Pierre Fitness Platform
Pierre Fitness Platform connects AI assistants to fitness data from Strava, Garmin, Fitbit, WHOOP, COROS, and Terra (150+ wearables). Implements Model Context Protocol (MCP), A2A protocol, OAuth 2.0, and REST APIs for Claude, ChatGPT, and other AI assistants.
Intelligence System
Sports science-based fitness analysis including training load management, race predictions, sleep and recovery scoring, nutrition planning, and pattern detection.
See Intelligence Methodology and Nutrition Methodology for details.
Features
- MCP Protocol: JSON-RPC 2.0 for AI assistant integration
- A2A Protocol: Agent-to-agent communication
- OAuth 2.0 Server: RFC 7591 dynamic client registration
- 47 MCP Tools: Activities, goals, analysis, sleep, recovery, nutrition, recipes, configuration
- TypeScript SDK:
pierre-mcp-clientnpm package - Pluggable Providers: Compile-time provider selection
- TOON Format: Token-Oriented Object Notation output for ~40% LLM token reduction (spec)
Provider Support
| Provider | Feature Flag | Capabilities |
|---|---|---|
| Strava | provider-strava | Activities, Stats, Routes |
| Garmin | provider-garmin | Activities, Sleep, Health |
| WHOOP | provider-whoop | Sleep, Recovery, Strain |
| Fitbit | provider-fitbit | Activities, Sleep, Health |
| COROS | provider-coros | Activities, Sleep, Recovery |
| Terra | provider-terra | 150+ wearables, Activities, Sleep, Health |
| Synthetic | provider-synthetic | Development/Testing |
Build with specific providers:
cargo build --release # all providers
cargo build --release --no-default-features --features "sqlite,provider-strava" # strava only
See Pluggable Provider Architecture.
Modular Architecture
Pierre uses compile-time feature flags for modular deployments. Build only what you need.
Server Profiles
Pre-configured bundles for common deployment scenarios:
| Profile | Description | Binary Size |
|---|---|---|
server-full | All protocols, transports, clients (default) | ~50MB |
server-mcp-stdio | MCP protocol + stdio transport (desktop clients) | ~35MB |
server-mcp-bridge | MCP + A2A protocols, web transports | ~40MB |
server-mobile-backend | REST + MCP, mobile client routes | ~42MB |
server-saas-full | REST + MCP, web + admin clients | ~45MB |
# Build for desktop MCP clients (minimal)
cargo build --release --no-default-features --features "sqlite,server-mcp-stdio"
# Build for SaaS deployment
cargo build --release --no-default-features --features "postgresql,server-saas-full"
Feature Categories
| Category | Features | Description |
|---|---|---|
| Protocols | protocol-rest, protocol-mcp, protocol-a2a | API protocols |
| Transports | transport-http, transport-websocket, transport-sse, transport-stdio | Communication layers |
| Clients | client-web, client-admin, client-mobile | Route groups |
| Tools | tools-fitness-core, tools-wellness, tools-all | MCP tool categories |
See Build Configuration for detailed feature documentation.
What You Can Ask
- "Calculate my daily nutrition needs for marathon training"
- "Analyze my training load - do I need a recovery day?"
- "Compare my three longest runs this month"
- "Analyze this meal: 150g chicken, 200g rice, 100g broccoli"
- "What's my predicted marathon time based on recent runs?"
See Tools Reference for the 47 available MCP tools.
Quick Start
git clone https://github.com/Async-IO/pierre_mcp_server.git
cd pierre_mcp_server
cp .envrc.example .envrc # edit with your settings
direnv allow # or: source .envrc
./bin/setup-and-start.sh # complete setup: fresh DB, admin user, server start
Server starts on http://localhost:8081. See Getting Started for detailed setup.
MCP Client Configuration
Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"pierre-fitness": {
"command": "npx",
"args": ["-y", "pierre-mcp-client@next", "--server", "http://localhost:8081"]
}
}
}
The SDK handles OAuth 2.0 authentication automatically. See SDK Documentation.
Available MCP Tools
47 tools organized in 8 categories:
| Category | Tools | Description |
|---|---|---|
| Core Fitness | 6 | Activities, athlete profile, provider connections |
| Goals | 4 | Goal setting, suggestions, feasibility, progress |
| Analysis | 10 | Metrics, trends, patterns, predictions, recommendations |
| Sleep & Recovery | 5 | Sleep quality, recovery score, rest recommendations |
| Nutrition | 5 | BMR/TDEE, macros, USDA food search, meal analysis |
| Recipes | 7 | Training-aware meal planning and recipe storage |
| Configuration | 6 | User settings, training zones, profiles |
| Fitness Config | 4 | Fitness parameters, thresholds |
Full tool reference: docs/tools-reference.md
Server Management
./bin/setup-and-start.sh # complete setup: fresh DB, admin user, server start
./bin/start-server.sh # start backend only (loads .envrc)
./bin/stop-server.sh # stop backend
./bin/start-frontend.sh # start dashboard (http://localhost:5173)
Options for setup-and-start.sh:
--skip-fresh-start- preserve existing database--run-tests- run workflow tests after startup--admin-email EMAIL- custom admin email--admin-password PWD- custom admin password
User Portal Dashboard
Web-based dashboard for users and administrators at http://localhost:5173.
Features
- Role-Based Access: super_admin, admin, user roles with permission hierarchy
- User Registration: Self-registration with admin approval workflow
- API Key Management: Create, view, deactivate API keys
- MCP Tokens: Generate tokens for Claude Desktop and AI assistants
- Usage Analytics: Request patterns, tool usage charts
- Super Admin Impersonation: View dashboard as any user for support
User Roles
| Role | Capabilities |
|---|---|
| User | Own API keys, MCP tokens, analytics |
| Admin | + User approval, all users analytics |
| Super Admin | + Impersonation, admin tokens, system config |
First Admin Setup
cargo run --bin admin-setup -- create-admin-user \
--email admin@example.com \
--password SecurePassword123 \
--super-admin
See Frontend Documentation for detailed dashboard documentation.
Mobile App
React Native mobile app for iOS and Android with conversational AI interface.
Features
- AI Chat Interface: Conversational UI with markdown rendering and real-time streaming
- Fitness Provider Integration: Connect to Strava, Garmin, Fitbit, WHOOP, COROS via OAuth
- Activity Tracking: View and analyze your fitness activities
- Training Insights: Get AI-powered training recommendations
Quick Start
cd frontend-mobile
bun install
bun start # Start Expo development server
bun run ios # Run on iOS Simulator
See Mobile App README and Mobile Development Guide.
AI Coaches
Pierre includes an AI coaching system with 9 default coaching personas and support for user-created personalized coaches.
Default Coaches
The system includes 9 AI coaching personas across 5 categories:
| Category | Icon | Coaches |
|---|---|---|
| Training | 🏃 | Endurance Coach, Speed Coach |
| Nutrition | 🥗 | Sports Nutritionist, Hydration Specialist |
| Recovery | 😴 | Recovery Specialist, Sleep Coach |
| Recipes | 👨🍳 | Performance Chef, Meal Prep Expert |
| Analysis | 📊 | Data Analyst |
Default coaches are seeded automatically by ./bin/setup-and-start.sh and are visible to all users.
Personalized Coaches
Users can create their own AI coaches with custom:
- Name and personality
- System prompts and behavior
- Category assignment
- Avatar customization
User-created coaches appear in a "Personalized" section above system coaches and are private to each user.
Coach Seeder
To seed or refresh the default coaches:
cargo run --bin seed-coaches
This creates the 9 default AI coaching personas if they don't already exist.
Documentation
Reference
- Getting Started - installation, configuration, first run
- Architecture - system design, components, request flow
- Protocols - MCP, OAuth2, A2A, REST
- Authentication - JWT, API keys, OAuth2 flows
- Configuration - environment variables, algorithms
Development
- Development Guide - workflow, dashboard, testing
- Scripts Reference - 30+ development scripts
- CI/CD - GitHub Actions, pipelines
- Release Guide - releasing server and SDK to npm
- Contributing - code standards, PR workflow
Components
- SDK - TypeScript client for MCP integration
- Frontend - React dashboard
- Mobile - React Native mobile app
- Mobile Development - mobile dev setup guide
Methodology
- Intelligence - sports science formulas
- Nutrition - dietary calculations
Testing
cargo test # all tests
./scripts/lint-and-test.sh # full CI suite
./scripts/smoke-test.sh # quick validation (~3 min)
Development Workflow
Before Committing
# 1. Format code
cargo fmt
# 2. Architectural validation
./scripts/architectural-validation.sh
# 3. Clippy (strict mode)
cargo clippy --all-targets -- -D warnings -D clippy::all -D clippy::pedantic -D clippy::nursery
# 4. Run relevant tests
cargo test <test_pattern>
Before Pushing
# 1. Enable git hooks (once per clone)
git config core.hooksPath .githooks
# 2. Run validation (creates marker valid for 15 min)
./scripts/pre-push-validate.sh
# 3. Push (hook checks for valid marker)
git push
The pre-push hook blocks pushes without a valid marker. This decouples test execution from the push to avoid SSH timeout issues.
Contributing
See Contributing Guide.
License
Dual-licensed under Apache 2.0 or MIT.