Pierre
HTTP-SSE连接AI助手与健身数据平台的MCP服务器
连接AI助手与健身数据平台的MCP服务器
Development Status: This project is under active development. APIs and features may change.
Pierre Fitness Platform connects AI assistants to fitness data from Strava, Garmin, and Fitbit. The platform implements the Model Context Protocol (MCP), A2A protocol, OAuth 2.0, and REST APIs for integration with Claude, ChatGPT, and other AI assistants.
The platform calculates fitness metrics using established sports science formulas:
See Intelligence and Analytics Methodology, Sleep and Recovery Methodology, and Nutrition Methodology for formulas, implementation details, and scientific references.
Pierre Fitness Platform runs as a single HTTP server on port 8081 (configurable). All protocols (MCP, OAuth 2.0, REST API) share the same port.
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ MCP Client Integration │
├──────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ stdio transport (subprocess-based) │
│ ┌─────────────────┐ stdio ┌─────────────────┐ HTTP+OAuth ┌──────────┐ │
│ │ MCP Client │ ◄─────────► │ Pierre SDK │ ◄─────────────► │ Pierre │ │
│ │ (Claude Desktop)│ │ Bridge │ │ Fitness │ │
│ └─────────────────┘ └─────────────────┘ │ Platform │ │
│ │ │ │
│ streamable http transport (server-based) │ │ │
│ ┌─────────────────┐ MCP-over-HTTP+OAuth │ │ │
│ │ MCP Client │ ◄──────────────────────────────────────────────► │ │ │
│ │ (HTTP-native) │ │ │ │
│ └─────────────────┘ └──────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────┘
stdio transport (via pierre-mcp-client npm package)
streamable http transport (direct http connection)
http://localhost:8081/mcpAI assistants query fitness data through natural language. The LLM determines which MCP tools to call and combines results.
| Natural Language Request | What Happens | Tools Used |
|---|---|---|
| "Calculate my daily nutrition needs for marathon training and suggest pre-workout meals" | Calculates BMR/TDEE based on user profile, determines macros for endurance goal, calculates nutrient timing, searches USDA database for suitable pre-workout foods | calculate_daily_nutrition, calculate_nutrient_timing, search_foods |
| "Get my last 10 activities and propose a week-long meal plan with protein targets based on my training load" | Retrieves recent activities, analyzes intensity and duration, calculates caloric expenditure, generates nutrition recommendations with macro breakdowns | get_activities, analyze_training_load, calculate_daily_nutrition |
| "Compare my three longest runs this month and identify areas for improvement" | Fetches top runs by distance, analyzes pace consistency, heart rate zones, elevation patterns, provides feedback | get_activities, compare_activities, analyze_performance_trends |
| "Analyze this meal: 150g chicken breast, 200g rice, 100g broccoli" | Looks up each food in USDA database, retrieves complete nutrient breakdown, calculates total macros and calories for the meal | analyze_meal_nutrition, get_food_details |
| "Check my training load for the last two weeks and tell me if I need a recovery day" | Calculates cumulative training stress, analyzes recovery metrics, provides rest recommendations | analyze_training_load, get_activities, generate_recommendations |
| "When's the best day this week for an outdoor run based on my typical schedule and weather conditions?" | Analyzes activity patterns, checks weather forecasts, recommends timing | detect_patterns, get_activities, weather integration |
git clone https://github.com/Async-IO/pierre_mcp_server.git cd pierre_mcp_server cargo build --release
.envrc (Recommended)Pierre Fitness Platform includes a .envrc file for environment configuration. Use direnv to automatically load environment variables:
# Install direnv (macOS) brew install direnv # Add to your shell profile (~/.zshrc or ~/.bashrc) eval "$(direnv hook zsh)" # or bash # Allow direnv for this directory cd pierre_mcp_server direnv allow
The .envrc file includes all required configuration with development defaults. Edit .envrc to customize settings for your environment.
Required Environment Variables:
export DATABASE_URL="sqlite:./data/pierre.db" export PIERRE_MASTER_ENCRYPTION_KEY="$(openssl rand -base64 32)"
Optional Environment Variables:
export HTTP_PORT=8081 # Server port (default: 8081) export RUST_LOG=info # Log level export JWT_EXPIRY_HOURS=24 # JWT token expiry export PIERRE_RSA_KEY_SIZE=4096 # RSA key size for JWT signing (default: 4096) # Fitness provider OAuth (for data integration) export STRAVA_CLIENT_ID=your_client_id export STRAVA_CLIENT_SECRET=your_client_secret export STRAVA_REDIRECT_URI=http://localhost:8081/api/oauth/callback/strava # local dev only # Garmin Connect OAuth (optional) export GARMIN_CLIENT_ID=your_consumer_key export GARMIN_CLIENT_SECRET=your_consumer_secret export GARMIN_REDIRECT_URI=http://localhost:8081/api/oauth/callback/garmin # local dev only # Production: Use HTTPS for callback URLs # export STRAVA_REDIRECT_URI=https://api.example.com/api/oauth/callback/strava # export GARMIN_REDIRECT_URI=https://api.example.com/api/oauth/callback/garmin # Weather data (optional) export OPENWEATHER_API_KEY=your_api_key # Cache configuration export CACHE_MAX_ENTRIES=10000 # Maximum cached entries (default: 10,000) export CACHE_CLEANUP_INTERVAL_SECS=300 # Cleanup interval in seconds (default: 300) # export REDIS_URL=redis://localhost:6379 # Redis cache (future support)
See src/constants/mod.rs:32-173 for all environment variables.
cargo run --bin pierre-mcp-server
The server will start on port 8081 and display available endpoints.
Create an admin user via REST API:
curl -X POST http://localhost:8081/admin/setup \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "password": "SecurePass123!", "display_name": "Admin" }'
Pierre Fitness Platform includes an SDK bridge for direct integration with MCP clients that only support stdin/out. The SDK handles OAuth 2.0 authentication automatically.
Option 1: Install from npm (Recommended)
npm install pierre-mcp-client@next
The SDK is published as a pre-release package (@next tag) during v0.x development.
Option 2: Build from source
The SDK is included in the sdk/ directory:
cd sdk npm install npm run build
Add Pierre to your MCP client configuration. For Claude Desktop:
Configuration File Location:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/claude/claude_desktop_config.jsonConfiguration (using npm package):
{ "mcpServers": { "pierre-fitness": { "command": "npx", "args": [ "-y", "pierre-mcp-client@next", "--server", "http://localhost:8081" ] } } }
Alternative (using local installation):
{ "mcpServers": { "pierre-fitness": { "command": "node", "args": [ "/absolute/path/to/pierre_mcp_server/sdk/dist/cli.js", "--server", "http://localhost:8081" ] } } }
Replace /absolute/path/to/ with your actual path for local installations.
When the MCP client starts, the SDK will:
No manual token management required.
mcp clients with streamable http transport support can connect directly to pierre without the sdk bridge.
mcp clients with streamable http transport connect directly to the mcp endpoint:
endpoint: http://localhost:8081/mcp (development)
endpoint: https://your-server.com/mcp (production)
streamable http connections use oauth 2.0 authorization code flow:
/.well-known/oauth-authorization-server/oauth2/register)/oauth2/authorize)/oauth2/token)Pierre Fitness Platform provides 30 tools through the MCP protocol. Tool definitions are in src/protocols/universal/tool_registry.rs:12-45.
| Tool | Description | Parameters |
|---|---|---|
get_activities | Get user activities from fitness providers | provider (optional), limit (optional) |
get_athlete | Get athlete profile information | None |
get_stats | Get athlete statistics and metrics | None |
analyze_activity | Analyze a specific activity with detailed insights | activity_id (required) |
get_activity_intelligence | Get AI-powered analysis for an activity | activity_id (required) |
get_connection_status | Check OAuth connection status for providers | None |
disconnect_provider | Disconnect from a fitness provider | provider (required) |
| Tool | Description | Parameters |
|---|---|---|
set_goal | Set a new fitness goal | goal_type, target_value (required) |
suggest_goals | Get AI-suggested goals based on activity history | None |
analyze_goal_feasibility | Analyze if a goal is achievable | goal_data (required) |
track_progress | Track progress toward goals | goal_id (required) |
| Tool | Description | Parameters |
|---|---|---|
calculate_metrics | Calculate custom fitness metrics | activity_id (required) |
analyze_performance_trends | Analyze performance trends over time | None |
compare_activities | Compare activities for performance analysis | activity_ids (required) |
detect_patterns | Detect patterns in activity data | None |
generate_recommendations | Generate personalized training recommendations | None |
calculate_fitness_score | Calculate overall fitness score | None |
predict_performance | Predict future performance based on training | None |
analyze_training_load | Analyze training load and recovery | None |
| Tool | Description | Parameters |
|---|---|---|
analyze_sleep_quality | Analyze sleep quality with NSF/AASM scoring | sleep_session (required) |
calculate_recovery_score | Calculate recovery readiness from TSB, sleep, HRV | tsb, sleep_quality, hrv_data (optional) |
track_sleep_trends | Track sleep patterns and trends over time | start_date, end_date (required) |
optimize_sleep_schedule | Get personalized sleep timing recommendations | preferences (optional) |
get_rest_day_recommendations | Get rest day recommendations based on recovery | tsb, recent_load, sleep_quality (optional) |
| Tool | Description | Parameters |
|---|---|---|
get_configuration_catalog | Get complete configuration catalog | None |
get_configuration_profiles | Get available configuration profiles | None |
get_user_configuration | Get current user configuration | None |
update_user_configuration | Update user configuration parameters | profile or parameters (required) |
calculate_personalized_zones | Calculate personalized training zones | None |
validate_configuration | Validate configuration parameters | parameters (required) |
Tool descriptions from src/protocols/universal/tool_registry.rs:114-162.
Pierre Fitness Platform supports agent-to-agent communication for autonomous AI systems. Implementation in src/a2a/.
A2A Features:
src/a2a/agent_card.rs)A2A Endpoints:
GET /a2a/status - Get A2A protocol statusGET /a2a/tools - Get available A2A toolsPOST /a2a/execute - Execute A2A toolGET /a2a/monitoring - Get A2A monitoring informationGET /a2a/client/tools - Get client-specific A2A toolsPOST /a2a/client/execute - Execute client A2A toolExample A2A Integration:
use pierre_mcp_server::a2a::A2AClientManager; #[tokio::main] async fn main() -> Result<()> { let client = A2AClientManager::new("https://pierre-server.com/a2a").await?; let response = client.send_message( "fitness-analyzer-agent", serde_json::json!({ "action": "analyze_performance", "user_id": "user-123", "timeframe": "last_30_days" }) ).await?; println!("Analysis: {}", response); Ok(()) }
Pierre Fitness Platform includes comprehensive test coverage with automated intelligence testing using synthetic data.
# Run all tests cargo test # Run specific test suites cargo test --test mcp_protocol_comprehensive_test cargo test --test mcp_multitenant_complete_test cargo test --test intelligence_tools_basic_test cargo test --test intelligence_tools_advanced_test # Run with output cargo test -- --nocapture # Lint and test (comprehensive validation) ./scripts/lint-and-test.sh
The platform includes 30+ integration tests covering all 8 intelligence tools without OAuth dependencies:
Test Categories:
get_athlete, get_activities, get_stats, compare_activitiescalculate_fitness_score, predict_performance, analyze_training_loadsuggest_goals, analyze_goal_feasibility, track_progressSynthetic Data Scenarios:
See tests/intelligence_tools_basic_test.rs and tests/intelligence_tools_advanced_test.rs for details.
Pierre Fitness Platform uses RS256 asymmetric signing for JWT tokens. Key size affects both security and performance:
Production (4096-bit keys - default):
Testing (2048-bit keys):
export PIERRE_RSA_KEY_SIZE=2048
Pierre Fitness Platform includes a shared test JWKS manager to eliminate RSA key generation overhead:
Shared Test JWKS Pattern (implemented in tests/common.rs:40-52):
use pierre_mcp_server_integrations::common; // Reuses shared JWKS manager across all tests (10x faster) let jwks_manager = common::get_shared_test_jwks();
Performance Impact:
E2E Tests: The SDK test suite (sdk/test/) automatically uses 2048-bit keys via PIERRE_RSA_KEY_SIZE=2048 in server startup configuration (sdk/test/helpers/server.js:82).
# Clean database and fresh server start ./scripts/fresh-start.sh cargo run --bin pierre-mcp-server & # Complete workflow test (admin + user + tenant + login + MCP) ./scripts/complete-user-workflow.sh # Load saved environment variables source .workflow_test_env echo "JWT Token: ${JWT_TOKEN:0:50}..."
A web dashboard is available for monitoring:
cd frontend npm install && npm run dev
Access at http://localhost:5173 for:
See frontend/README.md for details.
Complete documentation is in the docs/ directory:
Installation guide for MCP clients:
Pierre Fitness Platform uses validation scripts to maintain code quality and prevent common issues:
Pre-commit Validation:
scripts/validation-patterns.tomlRun validation:
./scripts/lint-and-test.sh
Install git hooks:
./scripts/install-hooks.sh
git checkout -b feature/new-feature)./scripts/lint-and-test.sh)git commit -m 'feat: add new feature')git push origin feature/new-feature)This project is dual-licensed:
You may choose either license.