Pierre Fitness Platform MCP Server

openapi: 3.0.3 info: title: Pierre MCP Fitness API description: | Multi-tenant fitness data API platform that aggregates data across multiple providers through a unified MCP (Model Context Protocol) interface. ## What is MCP? Model Context Protocol (MCP) is an open standard for connecting AI assistants with external data sources and tools. This API provides 18 specialized fitness tools accessible via MCP protocol. ## Key Features - **Multi-Provider Support**: Strava, Fitbit integration - **AI-Ready**: Built specifically for LLM consumption - **Advanced Analytics**: Performance analysis and intelligence tools - **Weather Intelligence**: Weather data integration for activities - **Real-time Data**: Live activity synchronization ## Authentication Multiple authentication methods supported: - **JWT Tokens**: Bearer tokens for user authentication (24h expiration) - **API Keys**: Production keys for B2B integrations (prefix: `pk_live_` or `pk_trial_`) - **A2A Authentication**: Client credentials for agent-to-agent communication JWT tokens include user ID, email, permissions, and expiration claims. See the [Authentication Guide](/docs/AUTHENTICATION.md) for complete details. ## Getting Started Connect to the MCP server via WebSocket and authenticate with JWT tokens to access all 18 fitness tools. version: 1.0.0 contact: name: Pierre MCP API email: contact@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: http://localhost:8081 description: Local Development (HTTP API) - url: ws://localhost:8081 description: Local Development (MCP over WebSocket) - url: https://api.pierre-fitness.com description: Production API paths: /mcp: post: summary: MCP Protocol Endpoint description: | All fitness tools are accessible via MCP JSON-RPC protocol. Send MCP requests to this endpoint with proper authentication. security: - JWTAuth: [] - APIKeyAuth: [] requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/McpToolsListRequest' - $ref: '#/components/schemas/McpToolCallRequest' examples: list_tools: summary: List Available Tools value: jsonrpc: "2.0" method: "tools/list" id: 1 call_tool: summary: Execute Tool value: jsonrpc: "2.0" method: "tools/call" params: name: "get_activities" arguments: limit: 10 provider: "strava" id: 2 responses: '200': description: MCP Response content: application/json: schema: oneOf: - $ref: '#/components/schemas/McpToolsListResponse' - $ref: '#/components/schemas/McpToolCallResponse' # Authentication endpoints /api/auth/login: post: summary: User Login description: Authenticate user and receive JWT token requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email password: type: string minLength: 6 required: [email, password] responses: '200': description: Login successful content: application/json: schema: type: object properties: jwt_token: type: string description: JWT token for authentication user_id: type: string format: uuid email: type: string expires_at: type: string format: date-time /api/auth/register: post: summary: User Registration description: Register new user account requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email password: type: string minLength: 6 display_name: type: string required: [email, password, display_name] responses: '201': description: Registration successful content: application/json: schema: type: object properties: user_id: type: string format: uuid message: type: string example: "User registered. Awaiting admin approval." # A2A Protocol endpoints /a2a/clients: post: summary: Register A2A Client description: Register agent client for A2A protocol access security: - JWTAuth: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string capabilities: type: array items: type: string contact_email: type: string format: email required: [name, description] responses: '201': description: Client registered successfully content: application/json: schema: type: object properties: client_id: type: string client_secret: type: string api_key: type: string public_key: type: string private_key: type: string key_type: type: string example: "ed25519" /a2a/auth: post: summary: A2A Authentication description: Authenticate A2A client and receive session token requestBody: required: true content: application/json: schema: type: object properties: client_id: type: string client_secret: type: string scopes: type: array items: type: string enum: [read, write] required: [client_id, client_secret] responses: '200': description: Authentication successful content: application/json: schema: type: object properties: session_token: type: string expires_at: type: string format: date-time scopes: type: array items: type: string components: securitySchemes: JWTAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token obtained from /api/auth/login APIKeyAuth: type: apiKey in: header name: X-API-Key description: API key with pk_live_ or pk_trial_ prefix schemas: # MCP Protocol Schemas McpToolsListRequest: type: object properties: jsonrpc: type: string enum: ["2.0"] method: type: string enum: ["tools/list"] id: type: integer required: [jsonrpc, method, id] McpToolCallRequest: type: object properties: jsonrpc: type: string enum: ["2.0"] method: type: string enum: ["tools/call"] params: type: object properties: name: type: string enum: [ "get_activities", "get_athlete", "get_stats", "get_activity_intelligence", "analyze_activity", "calculate_metrics", "analyze_performance_trends", "compare_activities", "detect_patterns", "predict_performance", "generate_recommendations", "create_goal", "get_goals", "suggest_goals", "get_weather_for_activity", "connect_provider", "disconnect_provider", "get_connection_status" ] arguments: type: object required: [name] id: type: integer required: [jsonrpc, method, params, id] McpToolsListResponse: type: object properties: jsonrpc: type: string enum: ["2.0"] id: type: integer result: type: object properties: tools: type: array items: $ref: '#/components/schemas/McpTool' McpToolCallResponse: type: object properties: jsonrpc: type: string enum: ["2.0"] id: type: integer result: type: object properties: content: type: array items: type: object properties: type: type: string enum: ["text"] text: type: string McpTool: type: object properties: name: type: string description: Tool name description: type: string description: Tool description inputSchema: type: object description: JSON schema for tool parameters required: [name, description, inputSchema] # Fitness Data Schemas Activity: type: object properties: id: type: string description: Activity ID from provider name: type: string description: Activity name sport_type: type: string enum: [Run, Ride, Swim, Walk, Hike, Workout, WeightTraining, Yoga] start_date: type: string format: date-time distance_meters: type: number description: Distance in meters duration_seconds: type: integer description: Duration in seconds elevation_gain_meters: type: number description: Elevation gain in meters average_heartrate: type: number nullable: true max_heartrate: type: number nullable: true average_speed: type: number description: Average speed in m/s max_speed: type: number description: Maximum speed in m/s calories: type: integer nullable: true provider: type: string enum: [strava, fitbit] Athlete: type: object properties: id: type: string description: Athlete ID from provider first_name: type: string last_name: type: string profile_picture_url: type: string nullable: true city: type: string nullable: true state: type: string nullable: true country: type: string nullable: true sex: type: string enum: [M, F] nullable: true weight: type: number nullable: true description: Weight in kg provider: type: string enum: [strava, fitbit] Stats: type: object properties: total_activities: type: integer total_distance_meters: type: number total_elevation_gain_meters: type: number total_duration_seconds: type: integer average_speed: type: number description: Average speed in m/s recent_activities: type: array items: $ref: '#/components/schemas/Activity' provider: type: string enum: [strava, fitbit] Goal: type: object properties: id: type: string format: uuid title: type: string description: type: string target_value: type: number current_value: type: number unit: type: string target_date: type: string format: date created_at: type: string format: date-time status: type: string enum: [active, completed, paused, cancelled] WeatherData: type: object properties: temperature_celsius: type: number humidity_percent: type: number wind_speed_kmh: type: number wind_direction: type: string conditions: type: string visibility_km: type: number timestamp: type: string format: date-time Error: type: object properties: error: type: string description: Error type message: type: string description: Human readable error message details: type: object properties: error_code: type: string timestamp: type: string format: date-time request_id: type: string tags: - name: MCP Protocol description: Model Context Protocol endpoints for AI assistants - name: Authentication description: User authentication and registration - name: A2A Protocol description: Agent-to-Agent protocol for autonomous systems # Example MCP Tool Implementations x-mcp-tools: get_activities: description: "Fetch fitness activities with pagination support" parameters: limit: type: integer minimum: 1 maximum: 50 default: 10 description: "Maximum number of activities to return" provider: type: string enum: ["strava", "fitbit"] default: "strava" description: "Fitness provider to query" get_activity_intelligence: description: "AI-powered activity analysis with full context" parameters: activity_id: type: string description: "ID of the activity to analyze" required: true analysis_type: type: string enum: ["performance", "health", "training", "comprehensive"] default: "comprehensive" description: "Type of analysis to perform" get_weather_for_activity: description: "Get weather conditions for a specific activity" parameters: activity_id: type: string description: "Activity ID to get weather for" required: true units: type: string enum: ["metric", "imperial", "kelvin"] default: "metric" description: "Temperature units"