36 lines
2.4 KiB
Markdown
36 lines
2.4 KiB
Markdown
# 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.
|