Long Run Hybrid Coach MCP Server

Long Run Hybrid Coach

繁體中文 · English · 简体中文

Long Run Hybrid Coach 是一個非官方、Intervals-first、device-agnostic 的個人化 hybrid training coach。它維護同一份 28 天方向與本週跑步＋重訓課表，讀取可信的實際完成 evidence 持續複盤，並可在你確認後把課表送到 Intervals.icu 日曆。

Garmin 不是使用前提。 Garmin 是目前第一條做過實機 dogfood 的下游裝置路徑；Apple Watch、COROS、Polar、Suunto、Wahoo、其他 app／手錶，甚至沒有手錶，都可以走同一個 Coach。差異在於有多少可信 evidence 能進到訓練迴圈，以及 Intervals 後面的裝置同步路徑是否已驗證。

一般使用者優先選 Hosted MCP： https://mcp.paceandstaystrong.com/mcp。你需要一個 Intervals.icu 帳號，但不需要自己建立 Intervals OAuth App，也不需要自己維運 gateway。

---

Quick Start：Hosted MCP

使用前需要什麼？

1. 一個 Intervals.icu 帳號。
2. 一個能連 remote MCP、而且能提供本產品需要動作的 AI client。
3. 選配：已經會把活動同步進 Intervals.icu 的手錶或訓練 app。

沒有 Garmin 也可以使用。沒有自動 recovery evidence 時，Coach 會把缺少的資料視為 unknown，而不是 0。

1. 連上 Hosted Coach

MCP endpoint：

https://mcp.paceandstaystrong.com/mcp

• claude.ai / Claude Desktop：Settings → Connectors → Add custom connector → 貼上 endpoint。這條路徑已做過 production OAuth、coaching turn 與 Intervals delivery 的完整驗證。
• ChatGPT：完整 MCP（包含 write／modify actions）目前依 OpenAI 官方說明提供給 ChatGPT Business、Enterprise 與 Edu 的網頁版 beta；Pro 的 custom MCP 目前只有 read/fetch，不能完成本 Coach 的 plan write／delivery 全流程。若你的 workspace 支援完整 MCP，在 Apps／developer mode 建立 custom app 並指向上面的 remote endpoint。最新方案限制請以 OpenAI 官方說明 為準。
• OpenClaw：用 openclaw mcp add 指到同一個 endpoint，並加上 --auth oauth；一個 instance 若不只一個人用，要把 OAuth identity 設成 per-requester，否則所有人會連到同一個 Intervals 帳號。設定見 entrypoints/openclaw/。
• 其他 MCP client：把同一個 URL 設成 remote Streamable HTTP MCP server；實際是否能跑完整流程取決於該 client 是否支援本產品需要的 MCP/OAuth 行為。

逐入口「已完整實機驗證」或「已封裝、等待真實連線驗證」的狀態，以 entrypoints/ 為準。

2. 授權 Intervals.icu

第一次連線時，瀏覽器會開 Intervals.icu 的同意頁。登入你自己的 Intervals.icu 帳號並授權 Coach 需要的能力：

• ACTIVITY:READ：讀已完成訓練。
• WELLNESS:READ：讀 Intervals 可提供的 wellness evidence。
• CALENDAR:WRITE：讀／寫訓練日曆，讓確認過的課表可以交付並 read-back 驗證。
• SETTINGS:WRITE：讀設定；只有在已確認的 delivery 流程真的需要時，才補上缺少且有 evidence 支持的 running threshold setting。

Intervals 的同意頁會把權限分開。少勾一項時，依賴那項權限的能力會明確失敗；重新連線並補上權限即可。不要把 Intervals 密碼、API key 或 token 貼進對話。

3. 直接問正常的教練問題

不用先填問卷，例如：

讀我最近的訓練，告訴我這週該怎麼練。

或：

我想提升 VO2max，又不想掉力量，幫我排第一個 28 天方向。

Coach 會先讀已經存在的 evidence，再只問真正會改變決策的缺口，例如本週可練日、器材、或 provider 不可能知道的重訓 baseline。

4. 先看 28 天 preview，再確認計畫

第一次建立計畫時會先看到：

• 本週：精確、可執行、可交付的 session。
• 後三週：方向性 outlook，不假裝現在就知道所有細節。

你確認那份 preview 後，計畫才會寫入。之後的每週改動也是同一條體驗：

before / after preview → 一次確認 → apply。

5. 要送進日曆時，再做 delivery 確認

交付是另一個獨立確認：

delivery preview → 一次確認 → 寫入 Intervals.icu → read-back 驗證。

本產品能證明的最遠狀態是 intervals_accepted。Intervals 成功不等於課表已經在 Garmin、Apple Watch 或其他手錶上。 Intervals 後面的同步是外部 hop，要依裝置路徑各自驗證。

---

Intervals.icu 在這個產品裡做什麼？

Intervals.icu 是目前的 interoperability hub：它幫 Coach 接住不同裝置／app 的活動與 wellness evidence，也承接 Coach 確認後的日曆課表。它不是 Coach 的 PlanState source of truth。

手錶 / 訓練 app
      │
      ▼
 Intervals.icu ───── 已完成活動 + wellness evidence ─────► Coach
      ▲                                                   │
      │                                                   │
      └────────── 確認後的 calendar workout ◄────────────┘
      │
      ▼
Garmin / Apple Watch bridge / 其他下游同步

責任分工：

• Intervals.icu：整合外部訓練 evidence，並持有 provider calendar。
• Long Run Hybrid Coach：持有唯一 current PlanState、decision history、athlete-reported evidence、確認 binding 與 coaching workflow。
• 你的手錶／app：可以把活動帶進 Intervals，也可能接收 Intervals 往下送的 workout；但最後一哩是否成功，是獨立 compatibility evidence。

Intervals 裡一定要先有資料嗎？

只有帳號本身是必要條件。有活動／wellness 已同步進去，Coach 的自動 evidence 會比較完整；沒有的欄位保持 unknown，不會被當成 0，也不會因為少一個選配數值就把一般 coaching 擋掉。

裝置量不到或沒有同步的東西可以直接在對話裡講，例如：

• 重訓實際組數、重量與次數；
• 本週可練時間與器材限制；
• 體重／體脂；
• 沒帶錶的一場活動；
• 「最近很累」「睡不好」這種 subjective state；
• 你從手錶／app 實際看到的 sleep、HRV、resting HR、readiness 等 recovery reading。

Coach 不會把一句「我很累」偷偷翻成一個假的 readiness score。

---

Hosted MCP vs Local / Self-hosted MCP

實際會感覺到的差別只有一個：**hosted 你在手機上就能直接用；local 只有在跑 gateway 的那台電腦上能用。**下面其他每一行，都是這個差別的成本。

Hosted MCP 最短啟用流程

1. 在支援完整需求的 MCP client 新增 remote MCP app／connector。
2. URL 貼 https://mcp.paceandstaystrong.com/mcp。
3. 完成 client 的 OAuth 流程。
4. 瀏覽器到 Intervals.icu 同意授權。
5. 回到聊天後直接問第一個教練問題。

Hosted 服務會自己處理 dynamic client registration、PKCE、gateway token 與 per-athlete owner mapping；一般使用者不需要 owner id、athlete id、API key、Intervals client secret 或 server environment variable。

Local / Self-hosted MCP 怎麼跑？

Repo 使用 Python 3.11，產品本身是 stdlib-only，不需要先安裝一串 runtime Python package。

1. Clone repo。
2. 向 Intervals.icu 申請建立 OAuth application。 Intervals 目前的公開流程不是在 Settings 自助新增 app：依官方 OAuth 說明提供 app name、description、website、logo、privacy policy、redirect URI 與你的 Intervals ID；app 建立後才會出現在 Settings，從 Manage App 取得 client_id / secret。流程見 Intervals.icu OAuth support。
3. 在 Intervals app 裡註冊 gateway provider callback：<gateway-origin>/oauth/callback。本機 client 可以走 loopback；remote client 需要可達的 HTTPS／secure tunnel。
4. 設定 gateway 必要環境變數：

export GARMIN_COACH_LOOP_GATEWAY_STATE_ROOT="$HOME/.local/share/long-run-hybrid-coach-gateway"
export GARMIN_COACH_LOOP_TOKEN_HMAC_KEY="$(openssl rand -base64 32)"
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_ID="..."
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_SECRET="..."

1. 啟動：

python3 -m garmin_coach_loop.cli serve-gateway --host 127.0.0.1 --port 8422

1. 本機 MCP client 指到：

http://127.0.0.1:8422/mcp

如果要正式提供給 remote client，不要把 loopback 範例當 production runbook。Persistent volume、TLS、trusted client origin、single replica、release identity 與部署驗證見 docs/deploy-gateway.md。

Local CLI 不應該默默變成第二份 current plan

一個 athlete 應該只有一個 current writer。當本機設定 GARMIN_COACH_LOOP_GATEWAY_URL 指向 hosted coach 時，本機 store 寫入預設會被擋；只有明確加 --offline 才代表「我刻意在做另一份 local plan」。

已經有本機 state 的人可以搬到 hosted，完整流程見 docs/ops/migrate-local-store-to-hosted.md。

---

現在可以做什麼？

目前產品能力包括：

• 維護一份 28 天方向：本週精確 session ＋ 後三週 outlook。
• 讀 Intervals activity／wellness／calendar evidence，並把可信的 planned → actual 自動 reconciliation 回 current plan。
• 在同一份週計畫裡同時處理跑步與重訓。
• 記錄 athlete-reported profile、availability、long-term goal、training preference、實際重訓、體重／體脂、裝置沒錄到的活動，以及 subjective state。
• startCoachSession 接收本次 request 的 recovery readings；Hosted 不需要也不會去讀你的本機 health database。
• 匯入支援的歷史 evidence，包括支援格式的 CSV、Apple Health XML 內容，以及透過 binary import path 處理的 FIT payload；同檔與同活動會做 deterministic 去重，判斷不了才問使用者。
• Session 可帶 coach_note，讓教練的重點文字一起進 Intervals event，而不是偷偷長出第二套 workout grammar。
• 每週複盤「實際練了什麼、是否有進步證據、下一步是什麼」，而不是把「課表做完」直接當成 fitness 已提升。
• 計畫變更先 preview，再確認後 apply。
• 日曆交付先 preview，再確認；支援安全 retry、replace 與 withdraw product-owned event。
• 在對話裡直接匯出或兩段式永久刪除本產品持有的 owner data。

重要邊界

• startCoachSession 會做 deterministic reconciliation，可能寫入新的 PlanState version；如果只要完全無 side effect 的 stored state，用 getCoachState，它才是 read-only 路徑。
• athlete-reported activity 是 evidence，但不會被偷偷升格成 provider-backed actual completion。
• recovery 數字只接受真的觀察值；模型不可以從文字自己猜一個數字。
• 本產品不做醫療診斷。
• Delivery 證據只到 Intervals read-back，不會聲稱已經到手錶。

---

資料、匯出與刪除

Hosted 端保存維持同一個 owner 計畫所必要的產品狀態：PlanState version chain、decision／receipt、athlete-reported evidence、identity mapping，以及未收斂 delivery bookkeeping。

匯出時刻意不包含：OAuth credential 的 keyed fingerprint、provider raw payload／GPS track，以及 internal owner id。Fingerprint 是單向 bookkeeping；raw GPS／活動檔應由 provider 提供；owner id 是內部 storage locator。

刪除產品資料也有三個明確邊界，這三件不在本產品能刪的範圍：

• 已經寫進 Intervals.icu 日曆 的 workout；
• 你在 Intervals.icu Settings 給出的 provider 授權；
• 不含 plan、健康或 identity 內容的最小化平台營運紀錄。

完整生命週期見 docs/account-lifecycle.md，公開隱私政策在 paceandstaystrong.com/privacy.html。

---

目前限制

• Coach 不直接登入 Apple Health、Garmin Connect 或其他裝置帳號；主要自動 evidence 路徑目前仍是 Intervals.icu。
• Hosted 不會永久保存每次 request 傳入的 raw recovery upload；下一次需要就再傳當下 evidence。
• 本產品不觀察 Intervals 之後的每一個裝置同步 hop，因此不會把 intervals_accepted 說成「已經在手錶上」。
• Local self-hosting 是 operator／developer 路徑；一般使用者應優先 Hosted MCP。
• 裝置相容性是逐路徑 evidence，不因 Garmin 已驗證就推論其他裝置一定相同。

---

產品 surface 與技術文件

目前 release 對外有 22 個 MCP tool、2 個 prompt、30 個 CLI 指令、3 份 JSON Schema contract、5 張 identity 表。這些數量由測試從真實程式碼推導，避免 README 自己走鐘。

• 穩定使用者故事：docs/user-story.md
• 資料來源與欄位邊界：docs/data-sources.md
• 入口與平台設定：entrypoints/
• MCP protocol、OAuth 與 tool 行為：entrypoints/mcp/README.md
• Hosted gateway 部署：docs/deploy-gateway.md
• 帳號生命週期：docs/account-lifecycle.md
• 公開上架／reviewer 材料：docs/distribution/
• Release inventory：docs/release-inventory.md
• Repository invariants 與驗證：AGENTS.md

Long Run Hybrid Coach 是獨立專案，與 Garmin、Intervals.icu、Apple 或其他裝置／平台供應商沒有隸屬、背書或贊助關係。程式碼以 MIT License 釋出。