Setup Server Skill

CLAUDE: When this skill is invoked with /setup-server, run the setup script:

./bin/setup-and-start.sh --skip-fresh-start

For a completely fresh start (wipes database):

./bin/setup-and-start.sh

Purpose

Bootstraps the Pierre MCP Server with all required components: database, admin user, coaches, and optionally test users. Essential for development, testing, and iOS Simulator testing.

Usage

/setup-server

Synthetic Provider vs Strava (IMPORTANT)

CLAUDE: Default to synthetic provider. Ask if Strava is needed.

When to Use Synthetic Provider (DEFAULT)

• Most development and testing - no OAuth required
• iOS Simulator testing - works without external accounts
• UI/UX development - realistic data without API limits
• CI/CD pipelines - deterministic, reproducible tests

When Strava is Needed

Only use Strava when:

• Testing OAuth flow specifically
• Validating real Strava API integration
• User explicitly requests Strava data
• Testing webhook sync features

Set Provider in .envrc

# Default to synthetic (RECOMMENDED)
export PIERRE_DEFAULT_PROVIDER=synthetic

# Only if Strava OAuth testing needed
export PIERRE_DEFAULT_PROVIDER=strava

Default Test Credentials

CRITICAL: These are the default credentials from .envrc. Always use these for testing.

Admin User

Email:    [email protected]
Password: adminpass123

Regular Test User

Email:    [email protected]
Password: userpass123

Environment Variables (from .envrc)

export ADMIN_EMAIL="[email protected]"
export ADMIN_PASSWORD="adminpass123"
export OAUTH_DEFAULT_EMAIL="[email protected]"
export OAUTH_DEFAULT_PASSWORD="userpass123"

Admin Token (REQUIRED FOR USER MANAGEMENT)

CLAUDE: To create/approve users via admin API, you need an admin token.

Generate Admin Token

cargo run --bin pierre-cli -- token generate --service claude_test --expires-days 7

Use Admin Token in API Calls

# Store the token
export ADMIN_TOKEN="<token-from-above-command>"

# Use in curl requests
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8081/admin/users

Automatic Token Handling

The complete-user-workflow.sh script handles admin tokens automatically:

./scripts/complete-user-workflow.sh

This script:

1. Generates an admin token (or reuses existing)
2. Creates test user
3. Approves user with tenant
4. Saves all tokens to .workflow_test_env

After Running Workflow Script

# Load saved tokens
source .workflow_test_env

# Now you can use $ADMIN_TOKEN and $JWT_TOKEN
echo "Admin: $ADMIN_TOKEN"
echo "User JWT: $JWT_TOKEN"

Bootstrap Commands

Quick Start (skip database wipe)

./bin/setup-and-start.sh --skip-fresh-start

Fresh Start (wipes and recreates database)

./bin/setup-and-start.sh

Fresh Start with Workflow Tests

./bin/setup-and-start.sh --run-tests

What Setup Does

1. Database Setup - Creates/migrates SQLite database
2. Admin User - Creates [email protected] with adminpass123
3. Seed Coaches - Loads AI coaching personas
4. Start Server - Starts on port 8081
5. Health Check - Waits for server to be healthy

Note: Basic setup only runs seed-coaches. For full test data, run additional seeders below.

Data Seeders (IMPORTANT FOR TESTING)

CLAUDE: Before testing features, run the appropriate seeders to populate test data.

Available Seeders

Synthetic Activities Seeder (NEW - For Testing Without Strava)

CRITICAL: Use this seeder for testing without OAuth.

# Seed 100 activities for default test user
cargo run --bin seed-synthetic-activities

# Seed more activities
cargo run --bin seed-synthetic-activities -- --count 200

# Seed for specific user
cargo run --bin seed-synthetic-activities -- --email [email protected]

# Reset and reseed
cargo run --bin seed-synthetic-activities -- --reset --count 150

Sport types included: Run, Trail Run, Ride, Mountain Bike, Gravel Ride, Nordic Ski, Backcountry Ski, Alpine Ski, Swim, Hike, Walk, Weight Training, Yoga, Rowing, Kayaking, SUP, and more.

Run All Seeders (Full Test Setup)

Option A: Fresh database with ALL seeders (RECOMMENDED)

./bin/reset-dev-db.sh

This wipes the database and runs ALL seeders automatically.

Option B: Run seeders individually (existing database)

cargo run --bin seed-coaches
cargo run --bin seed-demo-data
cargo run --bin seed-mobility
cargo run --bin seed-social

When to Run Which Seeder

Complete User Workflow

After server is running, to create a test user with full access:

./scripts/complete-user-workflow.sh

This script:

1. Creates/gets admin token
2. Registers regular user ([email protected])
3. Approves user with tenant creation
4. Tests MCP access
5. Saves tokens to .workflow_test_env

iOS Simulator Testing

When testing the mobile app with iOS Simulator:

1. Reset Database with Full Test Data

./bin/reset-dev-db.sh

This creates a fresh database with ALL seeders (coaches, demo data, mobility, social).

2. Start Server

./bin/start-server.sh

3. Run User Workflow (creates test user)

./scripts/complete-user-workflow.sh

4. Login Credentials for Mobile App

Email:    [email protected]
Password: userpass123

5. Start Mobile App

cd frontend-mobile && bun start

Server Endpoints

Manual Server Control

Start Server Only

./bin/start-server.sh

Stop Server

./bin/stop-server.sh

Check Server Status

curl http://localhost:8081/health

Troubleshooting

Server won't start

# Kill any existing processes
pkill -f pierre-mcp-server

# Check port availability
lsof -i :8081

# Start fresh
./bin/setup-and-start.sh

Database errors

# Reset database completely
./bin/reset-dev-db.sh

Token expired

# Generate new admin token
cargo run --bin pierre-cli -- token generate --service test --expires-days 7

Missing .envrc

cp .envrc.example .envrc
direnv allow

Environment Files After Setup

After running complete-user-workflow.sh:

# Contains JWT tokens for API testing
source .workflow_test_env

# Use tokens in curl commands
curl -H "Authorization: Bearer $JWT_TOKEN" http://localhost:8081/mcp ...

Related Skills

• validate-frontend - Frontend validation
• validate-mobile - Mobile app validation
• create-worktree - Git worktree for feature branches