strava-mcp-server/docs/DESIGN_DECISIONS.md

Design Decisions - Strava MCP Server

This document records key architectural and design decisions made during the development of the Strava MCP Server. It serves as a guide for AI agents and developers to maintain consistency.

1. Date and Time Handling

Decision: Standardize on ISO 8601 (UTC) for all internal data exchange, tool inputs, and tool outputs. Date: 2026-05-12 Context: LLMs often struggle with ambiguous date formats (e.g., DD.MM.YYYY vs. MM/DD/YYYY). International users require a unified format. Implementation:

• All tools accept ISO 8601 strings (YYYY-MM-DDTHH:MM:SSZ) for date parameters.
• Tool outputs include a _date or similar field with the raw ISO 8601 string.
• A shared utility src/strava_mcp_server/utils.py handles parsing and formatting.
• Human Readability: While raw data is ISO 8601, markdown summaries presented to the user should use DD.MM.YYYY HH:MM for comfort, but the raw data for agent analysis must be standardized.

2. Authentication & Token Management

Decision: Automate token rotation and prioritize environment-based configuration. Context: Strava tokens expire every 6 hours. Manual refresh is tedious for automated use. Implementation:

• The server checks token expiration before every request.
• Tokens are automatically refreshed and updated in the environment/memory.
• Initial authentication is handled via a separate auth script or integrated OAuth flow.

3. Data Representation & MCP Annotations

Decision: Use dual-content outputs with audience-specific annotations and native MIME typing. Context: To provide a clean user experience while giving the LLM detailed data, we split tool results into two parts and use protocol-level typing. Implementation:

• User Facing: Markdown summaries annotated with audience=["user"] using TextContent.
• Assistant Facing: Raw JSON data provided as an EmbeddedResource with mimeType="application/json" and annotated with audience=["assistant"].
• This ensures the LLM explicitly knows the data format while allowing clients to optimize the user-facing UI.

4. Internationalization

Decision: Use metric units (meters, km, m/s) internally and provide clear conversion instructions to the LLM. Implementation:

• Strava API returns metric units.
• The LLM is instructed in main.py to convert these to human-friendly formats (km, km/h) based on user preference.