RunCoach

Live: runcoach-ruby.vercel.app · MCP 端点 https://runcoach-ruby.vercel.app/mcp

一个 MCP 服务器，将跑步者自身的训练数据——计算出的训练负荷、比赛时间预测、生成的计划——作为工具暴露给 LLM 调用。

关键点在于结合实际情况。问任何助手“我这周是否应该减量”，它都会凭空产生看似合理的教练建议。RunCoach 让同一个问题基于运动员实际记录的活动来解答，回答中会附带具体是哪次跑步得出的结论：

你： 我的训练情况如何？半马能跑多少？

Claude (调用 analyze_training_status，然后调用 predict_race_time)： 训练稳定且负荷平稳——过去 28 天共 17 次跑步，每周 46.8 公里，急性与慢性负荷比为 1.00，最长间隔不超过三天。目前是维持状态而非提升状态，这在两个目标之间是合适的，但如果你有比赛即将到来，则值得调整。

半马成绩：1:38:49，最可能在 1:36:50 到 1:40:48 之间。这是根据你自己的距离/时间曲线拟合得出的，参考了你的 5 公里（21:30，7 月 8 日）、10 公里（44:50，6 月 3 日）和半马（1:38:48，4 月 29 日）——你的疲劳指数为 1.059，而人群平均值为 1.06，因此随着距离增加，你的配速保持能力与典型水平相当。一次活动被排除：7 月 28 日记录的 3 公里配速快于该距离的世界纪录，几乎肯定是 GPS 误差。

以上每个数字都是 npm test 的固定运动员的实际输出，而非示例——确切字符串出现在 test/readme.test.ts 中，如果科学依据发生变化且 README 未随之更新，则测试会失败。每个工具都返回一个置信度以及其数字推导过程的解释，服务器的指令告诉模型两者都要传递。没有依据的预测与猜测无异。

工具

Related MCP server: livetrack-mcp

数字来源

RunCoach 没有重新实现任何东西。所有计算都来自 @runman/core，这是一个经过固定测试的科学包，也是 Runman 网页应用的后端。向 Claude 提问和加载相应页面运行的是相同的代码和相同的数据库。

该包作为 git 子模块集成在此，RunCoach 的测试导入 Runman 测试使用的相同固定文件——因此“这些数据应该产生什么结果”在两个仓库中只有一个定义，而不会出现两个定义逐渐偏离的情况。

git clone --recursive https://github.com/varun-gangadharan/runcoach
npm install
npm test          # 31 tests, no database or credentials required

值得解释的设计决策

工具不接受运动员 ID。 API 密钥解析为唯一一名运动员，该 ID 成为工具上下文。如果模型可以传递运动员 ID，则活动标题中的提示注入指令可能会要求它这样做——而这里的载荷是某人的个人健康数据。没有任何理由让一名运动员的密钥读取另一名运动员的数据。测试确保这一点始终成立。

拒绝是一个有效的答案。 当没有数据支持预测时，工具会说明情况 并 指示模型不要用估计值替代。计划生成也是如此：如果运动员没有近期训练，或者比赛距离只有三周，它会以理由拒绝，而不会基于猜测的基线生成计划。模型默认会填补空白；工具输出必须主动抵制。

输出是散文，而不是 JSON。 模型解释句子比读取嵌套对象更忠实，并且编造不存在字段的可能性要小得多。精确的数字仍然会出现——在句子内部。

每个 HTTP 请求都构建自己的服务器实例。 在无服务器环境中跨调用共享一个实例，有在热容器内交错两个运动员会话的风险。这不是可接受的失败模式。

部署

HTTP 传输是一个单一的 Vercel 函数。身份验证是 Bearer 令牌——运动员从 Runman 个人资料页面发出的 API 密钥，仅以 SHA-256 哈希存储。

vercel env add SUPABASE_URL
vercel env add SUPABASE_SERVICE_ROLE_KEY
vercel deploy --prod

注意，Vercel 入口点 (api/mcp.js) 是纯 JavaScript，重新导出 dist/ 中的编译后处理程序，而不是 TypeScript 导入 src/。Vercel 会就地编译 .ts 函数，但会保留相对导入说明符不变，因此 .ts 说明符会保留在部署的包中，并在运行时因找不到从未发布的文件而失败。

部署后，使用真实的 MCP 客户端进行端到端检查：

node --experimental-strip-types scripts/verify-deployment.ts \
  https://runcoach-ruby.vercel.app/mcp rc_live_...

该连接完全像 Claude 那样通过网络进行——握手、工具发现，然后调用五个工具中的每一个——并断言返回的答案是经过验证的，而不仅仅是格式良好的。

然后在任何 MCP 客户端中添加它：

{
  "mcpServers": {
    "runcoach": {
      "type": "http",
      "url": "https://runcoach-ruby.vercel.app/mcp",
      "headers": { "Authorization": "Bearer rc_live_..." }
    }
  }
}

通过 stdio 本地运行

用于在自己的机器上针对自己的数据使用：

{
  "mcpServers": {
    "runcoach": {
      "command": "node",
      "args": ["/absolute/path/to/runcoach/dist/stdio.js"],
      "env": {
        "SUPABASE_URL": "...",
        "SUPABASE_SERVICE_ROLE_KEY": "...",
        "RUNCOACH_API_KEY": "rc_live_..."
      }
    }
  }
}

stdio 服务器没有需要身份验证的请求——它作为客户端的子进程运行——因此运动员在启动时固定。这仅适用于运动员自己的机器，这就是为什么部署的传输改为每个请求执行一次的原因。

测试

npm test

31 个测试涵盖三个层次：针对 Runman 共享固定集（稳定跑步者、无心率跑步者、单一活动、空历史、GPS 故障历史、零散跑步者、回归跑步者、容量激增）的工具处理程序，以及一个端到端协议测试，该测试连接真实的 MCP 客户端和真实的服务器，并驱动其完成工具发现、模式验证和调用。第三层固定了本 README 中引用的示例数字。

不在 v1 中

通过代理上游 Garmin MCP 服务器获取的 Garmin 来源工具（恢复、睡眠、HRV），仅在运动员关联了账户后才可用。有意做成可分离的，因此没有 Garmin 的运动员不会看到任何功能降级。

许可证

MIT。