setup-server

name	setup-server
description	Bootstrap Pierre server with database, admin user, coaches, and test users for development and testing
user-invocable	true

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:    [e-mail]
Password: adminpass123

Regular Test User

Email:    [e-mail]
Password: userpass123

Environment Variables (from .envrc)

export ADMIN_EMAIL="[e-mail]"
export ADMIN_PASSWORD="adminpass123"
export OAUTH_DEFAULT_EMAIL="[e-mail]"
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 [e-mail] 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 pierre-cli 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.

All seeders are consolidated under pierre-cli seed <domain> subcommands.

Available Seeders

Seeder	Command	What It Creates
Bootstrap	pierre-cli seed bootstrap	Admin + demo users (idempotent; requires ADMIN_PASSWORD)
Coaches	pierre-cli seed coaches	9 AI coaching personas (training, nutrition, recovery, mobility)
Demo Data	pierre-cli seed demo-data	Dashboard analytics, API keys, usage time-series data
Mobility	pierre-cli seed mobility	Stretching exercises, yoga poses, activity-muscle mappings
Social	pierre-cli seed social	Friend connections, shared insights, reactions, feed data
Synthetic Activities	pierre-cli seed synthetic-activities	100+ diverse activities (run, MTB, nordic ski, etc.)
LLM Usage	pierre-cli seed llm-usage	30 days of LLM call records for analytics dashboards
Insight Samples	pierre-cli seed insight-samples	Loads and validates insight sample markdown files (no DB writes)

Synthetic Activities Seeder (For Testing Without Strava)

CRITICAL: Use this seeder for testing without OAuth.

# Seed 100 activities for default test user
pierre-cli seed synthetic-activities

# Seed more activities
pierre-cli seed synthetic-activities --count 200

# Seed for specific user
pierre-cli seed synthetic-activities --email [e-mail]

# Reset and reseed
pierre-cli 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)

pierre-cli seed coaches
pierre-cli seed demo-data
pierre-cli seed mobility
pierre-cli seed social

When to Run Which Seeder

Testing This Feature	Required Seeders
Mobile app login	seed coaches (minimal)
Coach conversations	seed coaches
Activity list/analysis	seed synthetic-activities
Performance insights	seed synthetic-activities
Dashboard/Analytics	seed demo-data
Mobility/Stretching	seed mobility
Friends/Feed/Social	seed social + seed synthetic-activities
Full E2E testing	All seeders

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 ([e-mail])
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:    [e-mail]
Password: userpass123

5. Start Mobile App

cd frontend-mobile && bun start

Server Endpoints

Endpoint	Purpose
http://localhost:8081/health	Health check
http://localhost:8081/oauth2/login	Web login page
http://localhost:8081/oauth/token	OAuth token endpoint
http://localhost:8081/mcp	MCP protocol endpoint
http://localhost:8081/admin/*	Admin 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