RunCoach

公開中: runcoach-ruby.vercel.app · MCPエンドポイント https://runcoach-ruby.vercel.app/mcp

ランナー自身のトレーニングデータ（計算されたトレーニング負荷、レースタイム予測、生成されたプラン）を、LLMが呼び出せるツールとして公開するMCPサーバーです。

ポイントは根拠（grounding）です。「今週は負荷を減らすべきですか？」とアシスタントに尋ねると、何もないところからもっともらしいコーチングアドバイスが返ってきます。RunCoachは同じ質問をアスリートの実際の記録されたアクティビティに基づいて解決し、回答にはその根拠となった具体的なランの情報が含まれます。

あなた: トレーニングの調子はどうですか？ハーフマラソンはどのくらいで走れそうですか？

Claude （analyze_training_statusを呼び出し、次にpredict_race_timeを呼び出す）: トレーニングは一貫しており、負荷は安定しています。過去28日間で17回のラン、週間走行距離46.8km、急性：慢性比1.00、3日以上の休養期間はありません。フィットネスは維持されており、構築されているわけではありません。これは目標と目標の間にある適切な状態であり、レースが近づいている場合は変更する価値があります。

ハーフマラソンについては：1:38:49、最も可能性の高い範囲は1:36:50から1:40:48です。これはあなた自身の距離/タイム曲線に基づいて、5K（21:30、7月8日）、10K（44:50、6月3日）、ハーフ（1:38:48、4月29日）の記録からフィッティングされています。疲労指数は1.059で、母集団平均の1.06に対して、距離が伸びてもペースを維持する能力は平均的です。1つのアクティビティは除外されました：7月28日の3kmランで、その距離の世界記録よりも速いペースで記録されており、ほぼ確実にGPSエラーです。

上記の数値はすべてnpm testのフィクスチャアスリートからの実際の出力であり、例示ではありません。正確な文字列はtest/readme.test.tsにあり、科学が進歩してREADMEが更新されない場合にテストが失敗します。すべてのツールは信頼度とその数値の導出方法の説明を返し、サーバーの指示はモデルにその両方を伝えるよう指示します。根拠なしに述べられた予測は、推測と区別がつきません。

ツール

Related MCP server: livetrack-mcp

数値の出典

RunCoachは何も再実装していません。すべての計算は@runman/coreを使用しています。これはフィクスチャテスト済みの科学パッケージであり、Runmanウェブアプリのバックエンドでもあります。Claudeに質問して対応するページを読み込むと、同じコードが同じデータベースに対して実行されます。

このパッケージはgitサブモジュールとしてここにベンダリングされており、RunCoachのテストはRunmanのテストと同じフィクスチャファイルをインポートしています。つまり、「このデータが何を生成すべきか」という定義が両方のリポジトリで1つになり、ずれることがありません。

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

説明に値する設計上の決定

ツールはアスリートIDを受け取りません。 APIキーは正確に1人のアスリートに解決され、そのIDがツールのコンテキストになります。モデルがアスリートIDを渡せるようにすると、アクティビティタイトルに注入されたプロンプトインストラクションがそれを要求する可能性があります。そしてここでのペイロードは誰かの個人健康データです。あるアスリートのキーが別のアスリートのデータを読み取れるという議論はまったくありません。テストでこれが維持されることを確認しています。

拒否は有効な回答です。 予測をサポートするデータがない場合、ツールはその旨を伝え、モデルに推定値を代用しないよう指示します。プラン生成も同様です。アスリートに最近のトレーニングがない場合、またはレースが3週間先の場合、推測されたベースラインに基づくプランを生成する代わりに、理由を添えて拒否します。モデルはデフォルトでギャップを埋めます。ツールの出力は積極的に反発する必要があります。

出力は散文（prose）であり、JSONではありません。 モデルはネストされたオブジェクトを読むよりも、文をより忠実に言い換えます。また、存在しないフィールドをでっち上げる可能性もはるかに低くなります。正確な数値は依然として文中に現れます。

各HTTPリクエストは独自のサーバーインスタンスを構築します。 サーバーレス環境で呼び出し間で1つのインスタンスを共有すると、ウォームコンテナ内で2人のアスリートのセッションが混在するリスクがあります。これは許容できない障害モードです。

デプロイ

HTTPトランスポートは単一のVercel関数です。認証はベアラートークンです。アスリートがRunmanプロフィールページから発行するAPIキーで、SHA-256ハッシュとしてのみ保存されます。

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

Vercelのエントリポイント（api/mcp.js）は、src/からTypeScriptをインポートするのではなく、dist/からコンパイルされたハンドラを再エクスポートするプレーンなJavaScriptであることに注意してください。Vercelは.ts関数をその場でコンパイルしますが、相対インポート指定子はそのまま残すため、.ts指定子がデプロイされたバンドルに残り、出荷されなかったファイルを探して実行時に失敗します。

デプロイ後、実際のMCPクライアントでエンドツーエンドを確認します：

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

これはClaudeとまったく同じようにネットワーク経由で接続します（ハンドシェイク、ツール発見、その後5つのツールそれぞれの呼び出し）。そして、回答が単に整形式であるだけでなく、根拠に基づいて返ってくることを確認します。

その後、任意の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

3つのレイヤーにわたる31のテスト：Runmanの共有フィクスチャセット（一貫したランナー、心拍数なしランナー、単一アクティビティ、空の履歴、GPSグリッチ履歴、散発的ランナー、復帰ランナー、ボリュームスパイク）に対するツールハンドラ、および実際のMCPクライアントを実際のサーバーに接続し、ツール発見、スキーマ検証、呼び出しを駆動するエンドツーエンドプロトコルテスト。3番目のレイヤーは、このREADMEで引用されている例の数値を固定します。

v1には含まれないもの

Garminソースのツール（回復、睡眠、HRV）は、上流のGarmin MCPサーバーへのプロキシを介して提供され、アスリートがアカウントをリンクしている場合にのみ利用可能です。意図的に分離可能であり、Garminを持たないアスリートは機能低下を経験しません。

ライセンス

MIT