Rusty Intervals MCP

意图驱动、令牌高效间隔.icu MCP服务器

高性能 用于Intervals.icu的Rust MCP服务器 围绕一个想法设计：LLM应该与 小型、语义丰富的辅导界面，而不是一堆原始的端点包装器。

公共合同： 8个高级意图+1个资源\ 内部执行层： 与Intervals.icu保持一致的动态OpenAPI运行时\ 设计目标： 尊重代理的上下文窗口，并返回决策就绪的指导上下文

目录

• 为什么这个项目存在
• 是什么让它与众不同
• 公共MCP表面
• 建筑概览
• 为什么它具有令牌效率
• 快速开始
• VS代码/副本设置
• Claude桌面设置
• 示例提问
• 确定性教练分析
• 可观察性和指标
• 运行时配置
• 发展
• 文档地图
• 许可证
• 免责声明

为什么这个项目存在

该项目最初的基础很牢固：根据实时Intervals.icu OpenAPI规范动态构建工具行为，这样MCP服务器就不会随着上游API的发展而漂移。

这解决了 维护 问题。

它做到了 不 解决 代理用户体验 问题。

每个API端点暴露一个工具会产生精确的故障模式，现代MCP设计试图避免：

• 加载到上下文中的工具太多
• 暴露给模型的API低级细节过多
• LLM承受了过多的多步骤编排负担
• 工具选择错误、参数无效和令牌浪费的可能性更大

这个项目现在采取了不同的方法：

• 保持 动态OpenAPI层 内部，它属于哪里
• 暴露a 能力级意图面 LLM
• 返回 结构化、指导驱动的输出 而不是原始有效载荷
• 在服务器上计算重要的辅导指标，而不是在模型的头脑中计算

换言之： 引擎盖下充满活力，在边界处精心策划.

是什么让它与众不同

1.意图驱动的公共接口

LLM看到 8个高级意图 例如 analyze_training 或 modify_training，而不是几十个端点形状的工具。

2.内部保留动态OpenAPI运行时

这不是一个过时的手工维护包装。服务器仍然动态加载Intervals.icu OpenAPI规范，并将其用作意图编排背后的执行层。

3.默认令牌效率

响应是为LLM设计的：

• 结构紧凑
• 预过滤
• 预聚合
• 指导丰富

4.确定性教练分析

只读教练意图使用确定性管道来计算指标，如准备状态、ACWR上下文、单调性、应变、疲劳指数、应力耐受性、耐久性指数、恢复解释和流导出的执行信号。

5.更安全的突变流程

突变意图是为代理人设计的：

• 业务标识符而不是不透明的系统优先流
• dry_run 风险变更预览
• idempotency_token 支持安全重试

6.防锈第一操作剖面

• 单个二进制
• 快速启动
• 强型安全
• 非常适合本地MCP、容器和远程HTTP部署

公共MCP表面

公共MCP合同有意保持小规模和稳定。

意图

资源

公共合同规则

• 名称以结果为导向，不是面向端点的。
• 论点被扁平化 因此，代理不必发明嵌套结构。
• 成功的意图结果使用结构化的MCP输出 通过 structuredContent.
• Intent工具调用避免将相同的有效负载复制到文本中 content，减少代币浪费。
• 错误和部分状态由制导驱动，因此模型被告知下一步要做什么。

建筑概览

LLM Host (VS Code / Claude / Cursor / other MCP client)
            |
            | calls one high-level intent
            v
  +-----------------------------+
  | Intent Layer                |
  | 8 public coaching intents   |
  +-----------------------------+
            |
            v
  +-----------------------------+
  | Intent Router               |
  | validation + idempotency    |
  | orchestration + rendering   |
  +-----------------------------+
            |
            v
  +-----------------------------+
  | Internal Execution Layer    |
  | dynamic OpenAPI runtime     |
  | Intervals client            |
  +-----------------------------+
            |
            v
        Intervals.icu API

分层哲学

此README将该项目描述为 能力级别MCP服务器:

• LLM与 目标
• 服务器处理 编排
• OpenAPI运行时仍然是 内部产品/组件层

这种分离是当前架构背后的核心设计决策。

为什么它具有令牌效率

此服务器旨在减少两者 静态工具元数据成本 和 动态响应成本.

刀具表面更小

服务器没有用端点形状的工具淹没模型，而是只暴露了在实际指导工作流程中最重要的意图表面。

紧凑型输出

响应是为了可操作性而形成的：

• 先总结后详述
• 原始JSON之前的决策就绪指标
• markdown表和结构化内容，而不是模式转储
• 只有在改变决定时才进行选择性富集

服务器端计算

服务器自己计算重要的指标和解释，包括以下部分：

• 准备情况
• 疲劳和载荷指导（疲劳指数、应力容限、耐久性指数）
• 流感知执行信号
• 培训期总结

这使模型专注于对结果进行推理，而不是重建结果。

指导驱动的后续行动

意向响应包括 suggestions 和 next_actions 因此，主机模型知道如何在不调用试错工具的情况下继续。

快速开始

先决条件

• 锈蚀1.94+ 货物，或
• 码头工人

获取您的Intervals.icu证书

1. 打开
2. 滚动到 开发者 部分
3. 创建API密钥
4. 复制API密钥
5. 从您的个人资料URL中记录您的运动员ID（格式： i123456)

安装并运行MCP服务器

服务器同时支持这两种功能 工作室 （适用于本地MCP客户）以及 超文本传输协议 （对于远程客户端）通过 MCP_TRANSPORT 环境变量。

git clone https://github.com/like-a-freedom/rusty-intervals-mcp.git
cd rusty-intervals-mcp

cp .env.example .env
# edit .env and set:
# INTERVALS_ICU_API_KEY=your_api_key_here
# INTERVALS_ICU_ATHLETE_ID=i123456

cargo install --locked --path crates/intervals_icu_mcp

STDIO模式（默认）

对于本地MCP客户端，如VS Code Copilot或Claude Desktop：

export INTERVALS_ICU_API_KEY=your_api_key_here
export INTERVALS_ICU_ATHLETE_ID=i123456
export MCP_TRANSPORT=stdio  # optional: stdio is the default
intervals_icu_mcp

HTTP模式

对于远程MCP客户端或作为服务运行时：

# Generate secret for JWT authentication
export JWT_MASTER_KEY=$(openssl rand -hex 64)

export INTERVALS_ICU_API_KEY=your_api_key_here
export INTERVALS_ICU_ATHLETE_ID=i123456
export MCP_TRANSPORT=http
export MCP_HTTP_ADDRESS=127.0.0.1:3000  # optional: default is 127.0.0.1:3000
export MAX_HTTP_BODY_SIZE=4194304        # optional: 4 MiB request limit
export REQUEST_TIMEOUT_SECONDS=30        # optional: per-request timeout
export IDLE_TIMEOUT_SECONDS=60           # optional: idle connection timeout
intervals_icu_mcp

MCP端点位于 http:///mcp.

通过以下方式进行身份验证 /auth

将Intervals.icu API密钥交换为JWT：

curl -s -X POST http://127.0.0.1:3000/auth \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key_here", "athlete_id": "i123456"}'

答复：

{
  "token": "",
  "expires_in": 7776000,
  "athlete_id": "i123456"
}

使用返回的 token 在后续请求中 /mcp:

curl -s http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer "

当前HTTP安全/运行时注意事项：

• /auth 针对暴力保护单独进行速率限制（1请求/秒，突发大小3）。
• /mcp 在端点/对等IP层应用速率限制。
• HTTP模式需要 JWT_MASTER_KEY 用于JWT签名和加密。
• 容器部署旨在 HTTP流式MCP.STDIO用于本地子进程集成，通常不受益于Docker。
• HTTP服务器也支持 REQUEST_TIMEOUT_SECONDS, IDLE_TIMEOUT_SECONDS，以及 JWT_TTL_SECONDS 用于运行时调优。

使用以下方式生成密钥：

export JWT_MASTER_KEY=$(openssl rand -hex 64)

令牌寿命

• 默认值：90天（7776000秒）
• 可通过以下方式配置 JWT_TTL_SECONDS

VS代码/副本设置

对于本地开发，最简单的VS Code MCP配置是：

{
  "mcpServers": {
    "intervals-icu": {
      "command": "cargo",
      "args": [
        "run",
        "--manifest-path",
        "/absolute/path/to/rusty_intervals_mcp/Cargo.toml",
        "-p",
        "intervals_icu_mcp",
        "--bin",
        "intervals_icu_mcp"
      ],
      "env": {
        "INTERVALS_ICU_API_KEY": "your_api_key_here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

重新启动VS Code后，尝试询问：

@intervals-icu Analyze yesterday's workout
@intervals-icu Build me a 12-week trail ultra plan
@intervals-icu How is my recovery this week?

Claude桌面设置

添加指向stdio二进制文件的本地MCP条目：

{
  "mcpServers": {
    "intervals-icu": {
      "command": "/ABSOLUTE/PATH/TO/intervals_icu_mcp",
      "env": {
        "INTERVALS_ICU_API_KEY": "your_api_key_here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

如果您不希望在MCP客户端配置中硬编码凭据，请使用环境文件和启动器脚本或shell包装器。

示例提问

使用此MCP服务器的最佳方式是请求 结果，而不是API机制。

规划

• “创建一个为期10周的半程马拉松训练”
• “下周大约有四个可用的培训日”
• “在我比赛后的一周内恢复”

锻炼和周期分析

• “分析昨天的极限训练”
• “总结我2月份的训练”
• “显示我周二会议的间隔见解”
• “本周晚些时候计划进行哪些锻炼？”

恢复和性能管理

• “过去7天我的恢复情况如何？”
• “我准备好迎接明天的挑战了吗？”
• “将本月与上月进行比较”

日历更改

• “将周六的长跑改为周日”
• “为周三创建45分钟的恢复运行”
• “在应用前预览下周删除的训练”

轮廓和齿轮

• “显示我当前的跑步阈值”
• “使用新的实验室阈值更新我的个人资料”
• “我的鞋子里还剩多少生命？”

确定性教练分析

只读教练层是有意的 确定性的.

它遵循以下流程：

Fetch → Audit → Compute → Interpret → Render

这在实践中意味着什么

• 服务器收集相关活动、健康、事件和配置文件上下文
• 它检查数据可用性和降级数据场景
• 它在Rust中计算度量和摘要
• 它用明确的规则解释这些指标
• 它为主机模型呈现紧凑、指导丰富的输出

它在哪里表现得最强烈

analyze_training

• 单次深潜训练
• 区间感知和流感知分析模式
• 计划锻炼和日历事件在时段窗口中的可见性
• 明确的数据可用性报告

assess_recovery

• 准备框架
• 个人基线感知HRV解释
• 恢复优先制导和红旗探测

analyze_race

• 赛后执行审查
• 康复远期随访指导
• 存在匹配日历事件时与计划行为的比较

为什么确定性很重要

• 可重复的 --相同的输入，相同的输出
• 可测试的 --规则可以进行单元和集成测试
• 可解释的 --警报有证据
• 令牌高效 --该模型接收解释，而不仅仅是原始数字

可观察性和指标

在HTTP模式下，服务器在以下位置公开Prometheus格式度量 /metrics这些提供了对上游API健康、MCP协议使用、授权生命周期和活动运动员跟踪的可见性。

端点

GET /metrics --以Prometheus文本格式返回指标。

通过以下方式进行可选身份验证 PROMETHEUS_METRICS_TOKEN env 是：

• 如果设置：请求必须包括 Authorization: Bearer 头球
• 如果未设置：端点是公共的（不需要身份验证）

关键指标组

Prometheus查询示例

# Upstream error rate
rate(intervals_icu_mcp_upstream_errors_total[5m]) / rate(intervals_icu_mcp_upstream_requests_total[5m])

# p95 tool latency
histogram_quantile(0.95, rate(intervals_icu_mcp_tool_duration_seconds_bucket[5m]))

# Active athletes
intervals_icu_mcp_active_athletes

配置

Grafana仪表板

这些指标的预构建Grafana仪表板可在以下网址获得：

• examples/grafana/intervals_icu_mcp_observability_dashboard.json

将其导入Grafana，绑定 DS_PROMETHEUS 数据源输入，并使用内置变量(Job, Instance, Path, Tool)从服务范围的健康状况向下钻到特定的路线或MCP工具。

为保护 /metrics 端点，使用与相同的承载令牌值配置Prometheus抓取作业 PROMETHEUS_METRICS_TOKEN.

vmagent抓取示例

VictoriaMetrics示例 vmagent 刮擦配置可在以下网址获得：

• examples/vmagent/intervals_icu_mcp_metrics.yml

该示例包括：

• 公众 /metrics 目标
• 受保护的 /metrics 目标使用 authorization.credentials_file

对于生产，首选 credentials_file 在内联承载令牌之上，这样秘密就不会出现在版本化配置之外。

有关完整的度量规范，请参阅 docs/OBSERVABILITY_SRS.md.

运行时配置

看 .env.example 标准环境布局。

所需的环境变量

常见的可选环境变量

OpenAPI运行时行为

如果 INTERVALS_ICU_OPENAPI_SPEC 是 取消设置，运行时：

1. 获取 ${INTERVALS_ICU_BASE_URL}/api/v1/docs
2. 动态构建内部注册表
3. 将缓存版本保存在内存中
4. 回落到 docs/intervals_icu_api.json 当远程加载不可用时

如果 INTERVALS_ICU_OPENAPI_SPEC 是 显式设置，该源变得权威，故障浮出水面，而不是默默地切换到不同的规范。

这使该项目两全其美：

• 实时兼容性 与上游API
• 稳定的本地回退 用于开发和测试

发展

此存储库是一个Cargo工作区，有两个主板条箱：

推荐的验证命令

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

有用的开发命令

# Client examples
cargo run -p intervals_icu_client --example basic_client
cargo run -p intervals_icu_client --example list_recent_activities

# MCP stdio mode (default)
cargo run -p intervals_icu_mcp

# MCP http mode
MCP_TRANSPORT=http cargo run -p intervals_icu_mcp

测试注意事项

代码库包括：

• 围绕意图处理程序和运行时行为的单元测试
• OpenAPI和MCP行为的模拟HTTP测试
• 跨工作区的集成测试
• 忽略选定上游兼容性案例的实时合同检查

Docker和远程部署

此存储库中的Docker打包用于 HTTP流式MCP 运输。对于本地STDIO客户端，如VS Code或Claude Desktop，直接运行二进制文件，而不是将其容器化。

构建容器

docker build -t rusty-intervals:latest .

使用环境变量在本地运行

HTTP模式

docker run --rm \
  -p 3000:3000 \
  -e INTERVALS_ICU_API_KEY=your_key \
  -e INTERVALS_ICU_ATHLETE_ID=i123456 \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_ADDRESS=0.0.0.0:3000 \
  -e JWT_MASTER_KEY=$(openssl rand -hex 64) \
  -e MAX_HTTP_BODY_SIZE=4194304 \
  rusty-intervals:latest

容器暴露：

• GET /health 用于活性检查
• POST /auth 将Intervals.icu凭据交换为JWT
• 可流式MCP /mcp
• GET /metrics Prometheus指标（仅限HTTP模式）

Docker Compose

docker-compose.yml 已针对HTTP模式进行了预配置。在shell中提供所需的机密和凭据，或 .env 文件，然后启动服务：

docker compose up -d

至少在启动前设置这些变量：

• INTERVALS_ICU_API_KEY
• INTERVALS_ICU_ATHLETE_ID
• JWT_MASTER_KEY

远程MCP客户端

如果您的MCP主机支持远程HTTP MCP服务器，请参阅 examples/mcp_remote.json 举个最小的例子。

对于生产部署：

• 将服务器置于TLS之后
• 在代理或网关上添加身份验证层
• 不要将未经身份验证的纯HTTP MCP端点直接暴露给公共互联网

许可证

麻省理工学院——见 LICENSE.

免责声明

本项目不隶属于Intervals.icu，也不由其认可或赞助。所有产品名称、徽标和品牌均为其各自所有者的财产。