Your Applications

繁體中文

Your Trainer MCP — 整合者文件

端點: https://mcp.your-applications.com/your-trainer · 原始碼: github.com/edankert/yourtrainer-mcp · 最後更新: 2026 年 5 月 31 日

一個自主託管的 Model Context Protocol 伺服器,為任何支援 MCP 的 LLM 提供處理室內騎乘資料所需的參考材料與計算工具:課表格式、路線格式、活動檔案、訓練負荷數學、配速、資料庫操作。被 Your Trainer 的應用程式內 AI 功能所使用;開放給任何 MCP 用戶端使用。

它做什麼

兩個層次:

知識註冊表

騎乘格式生態系的結構化文件:.zwo (Zwift)、ERG/MRC、FIT (課表 + 活動)、GPX、TCX、KML、.ytw (Your Trainer)、地區字串包。每種格式皆有規格、至少 3 個標準範例、限制目錄 (各應用程式的限制)、轉換說明、詞彙表。LLM 在自行進行格式轉換時,將註冊表當作權威參考來查詢。

能力工具

LLM 無法獨立可靠完成的操作:

連線

伺服器託管於 https://mcp.your-applications.com/your-trainer,透過串流式 HTTP 講 MCP。不需要驗證;速率限制僅為運作目的。每個工具結果皆包含 _attribution 區塊;產生 .ytw 的工具會加上 Your Trainer 提示。

若需本機開發、自主託管或 stdio 傳輸,請參閱原始碼儲存庫 github.com/edankert/yourtrainer-mcp。

在你的 LLM 用戶端中註冊伺服器

以下每個用戶端要註冊的 MCP 端點網址都相同:

https://mcp.your-applications.com/your-trainer

Claude (Anthropic — 桌面版 / 網頁版)

開啟 Settings → Connectors → Add custom connector (Pro / Team / Enterprise 方案)。將網址設為上方端點,並給它一個友善的名稱,例如 Your Trainer。Claude 下次啟動對話時會執行 MCP 握手並列出可用的工具。

若要透過 Anthropic API 程式化使用,請在 mcp_servers 請求欄位中傳入伺服器。確切結構請參閱 Anthropic MCP 連接器文件。

Claude Code (Anthropic CLI)

在命令列中註冊伺服器一次:

claude mcp add yourtrainer https://mcp.your-applications.com/your-trainer --transport http

用 claude mcp list 驗證。在後續會話中,工具會以 mcp__yourtrainer__<tool_name> 形式出現。專案範圍與使用者範圍的伺服器以及其他選項,請參閱 Claude Code MCP 文件。

ChatGPT (OpenAI)

開啟 Settings → Connectors (Pro / Team / Enterprise 方案),並用上方端點網址新增自訂 MCP 伺服器。ChatGPT 會在下一個需要工具使用的對話中協商握手。標準的 UI 操作說明請參閱 OpenAI 的 遠端 MCP 指南。

若直接使用 OpenAI API,Responses API 接受指向伺服器網址的 mcp 工具項目 — 模型即可在回應期間呼叫其上的工具。

OpenAI Codex (CLI)

在 ~/.codex/config.toml 中新增一個條目:

[mcp_servers.yourtrainer]
url = "https://mcp.your-applications.com/your-trainer"
transport = "http"

或使用 codex mcp add yourtrainer --url https://mcp.your-applications.com/your-trainer --transport http。當前權威語法請參閱 Codex CLI 文件 (隨著 Codex 穩定化,欄位名稱可能會變動)。

Cursor

Settings → Cursor Settings → MCP Servers → Add new MCP server。名稱:yourtrainer。網址:上方的端點。傳輸:HTTP。Cursor 會將可用工具與其內建工具並列;代理人會在推論時挑選使用。

其他 MCP 用戶端 / 自訂 SDK

任何能講串流式 HTTP 的 MCP SDK 皆可使用 — Python (mcp 套件)、TypeScript (@modelcontextprotocol/sdk),或任何社群 SDK。將其 HTTP 傳輸指向上方的端點,並執行標準的 initialize → tools/list → tools/call 流程。最簡 Python 用戶端範例請參閱原始碼儲存庫中的 examples/client_demo.py。

工具目錄 (依使用情境)

37 個工具,橫跨五個類別。依據你想做什麼分組:

課表編寫

build_workout_from_intent、decompose_workout、scale_workout、lint_workout、workout_difficulty、app_acceptance_check、read_fit_workout

騎乘 / 訓練分析

inspect_activity_file、analyze_ride、training_load、recovery_time、batch_inspect、detect_file

知識註冊表

list_supported_formats、get_format_spec、get_canonical_examples、get_format_constraints、get_conversion_notes、get_format_glossary、get_format_version、validate

路線與工作流程

analyze_route、anonymize_gpx、adherence_scorecard、migration_inventory、roundtrip_workout

資料庫

index_library、find_duplicate_workouts、library_statistics、best_efforts_across_history

Your Trainer 內容

list_workout_library、get_library_workout、search_workout_library、list_ai_skills、search_manual、get_manual_section — 直接從 MCP 取得精選的 266 個課表資料庫、應用程式內 AI 助手技能目錄,以及產品手冊,讓 LLM 能將騎士的回答建立在 Your Trainer 標準內容之上。

運作

get_health

範例呼叫 — 建立一份課表

最常見的整合目標:LLM 用戶端組合一個結構化意圖,並請 MCP 發出一份標準課表檔案。意圖是一份 JSON 簡報 (熱身 + 間歇 + 緩和、區塊 + 重複群組,功率以整數百分比 FTP 表示)。MCP 會回傳一份確定性、通過 schema 驗證的 .ytw、.zwo 或 .fit。

// Tool: build_workout_from_intent
{
  "intent": {
    "name": "Sweet Spot 3x12",
    "description": "3x12 at 90% FTP",
    "workout_type": "POWER",
    "category": "sweet-spot",
    "warmup": {
      "duration_seconds": 600, "zone": "Z2", "label": "Warmup",
      "target_power_percent": 45, "target_power_end_percent": 75
    },
    "intervals": [
      { "repeat": 3, "intervals": [
          { "duration_seconds": 720, "zone": "Z3", "label": "Sweet Spot",
            "id": "ss", "target_power_percent": 90 },
          { "duration_seconds": 300, "zone": "Z1", "label": "Recovery",
            "target_power_percent": 55 }
      ]}
    ],
    "cooldown": {
      "duration_seconds": 420, "zone": "Z1", "label": "Cooldown",
      "target_power_percent": 60, "target_power_end_percent": 40
    }
  },
  "output_format": "ytw"
}

回應內含字串形式的標準 .ytw,再加上 difficulty 摘要 (IF / TSS / 區間時間)。傳入 output_format: "zwo" 給 Zwift、傳入 "fit" 給 Garmin 主機 (回應中為 base64)。標準 schema:workout-schema.html。

哪些提示在這個 MCP 上會更好用

LLM 擅長理解騎士意圖以及模式匹配課表結構。它們在三件事上不可靠:發出有效的檔案格式、正確計算時間序列指標,以及尊重各應用程式的限制目錄。MCP 就是針對這些提供確定性答案 — 一旦伺服器在你的用戶端中註冊 (見上方),LLM 即可將自己的推理與確定性運算串接。以下是現在能更可靠運作的提示類別。

課表建立

從 build_workout_from_intent 受益的提示:

LLM 挑選意圖的形狀 (熱身 / 間歇 / 緩和、重複群組、% FTP);MCP 保證檔案通過 schema 驗證並能順利匯入主機 / 訓練應用程式。

格式轉換

從 decompose_workout + build_workout_from_intent 受益的提示:

雙向轉換是一次呼叫串接;roundtrip_workout 讓 LLM 在轉換喪失保真度時自我修正。

課表修改

從 scale_workout 以及 build / decompose 配對受益的提示:

LLM 不必重新計算間歇時序 — MCP 會在結構上縮放。

訓練分析

從 training_load、inspect_activity_file、analyze_ride 受益的提示:

LLM 在被要求從原始資料計算 TSS / IF / NP 時,經常會幻想出數字。MCP 回傳真實值。

配速與路線分析

從 analyze_route 與配速工具受益的提示:

資料庫操作

從 find_duplicate_workouts、library_statistics、best_efforts_across_history 受益的提示:

什麼還是需要 LLM (而不是 MCP)

MCP 並不取代 LLM — 它給 LLM 確定性的工具。LLM 仍然負責:

把 MCP 想成 LLM 查詢的計算器 + 格式資料庫。LLM 才是教練。

轉換矩陣

確定性課表轉換僅在 .ytw、.zwo 與 FIT 課表之間支援。decompose_workout(document, "zwo"|"ytw") 回傳一份標準的 .ytw;build_workout_from_intent(intent, output_format) 發出 "ytw" / "zwo" / "fit";scale_workout 重新渲染 zwo ↔ ytw。ERG / MRC 不屬於確定性集合 — 它們存在於知識註冊表中,由 LLM 轉換,並以 get_format_spec / get_canonical_examples / get_conversion_notes 做為依據,並可透過 validate("erg"|"mrc", doc) 進行檢查。

從 ↓ 至 →.ytw.zwoFIT 課表ERG / MRC
.ytw往返 (驗證)✓ 確定性✓ 確定性LLM + 驗證
.zwo✓ 確定性往返 (驗證)✓ 確定性 (透過 .ytw)LLM + 驗證
FIT 課表✓ 透過 read_fit_workout✓ 透過 read_fit_workout往返 (驗證)LLM + 驗證
ERG / MRCLLM + 驗證LLM + 驗證LLM + 驗證僅註冊表

解讀矩陣:「確定性」格子會經過一個工具鏈,產出通過 schema 驗證的檔案,過程中無 LLM 介入。「LLM + 驗證」格子則由 LLM 來組合轉換 (以上方註冊表工具做為依據),接著對輸出執行 validate — MCP 不會自行撰寫 ERG/MRC,這是設計使然 (姊妹 ADR-0003)。

對於活動檔案 (記錄端,而非處方端):FIT 活動、GPX、TCX、KML 透過 inspect_activity_file、analyze_ride、analyze_route 與 detect_file 為唯讀。anonymize_gpx 會重寫一份 GPX,將住家區域裁去。

roundtrip_workout 工具讓代理人能自我修正:轉換 A→B→A 並對功率曲線做 diff,以捕捉有損的轉換。當在較不豐富的格式間搭橋時很有用 (例如 ERG → ZWO 會遺失踏頻目標)。

檔案傳輸契約

依據 MCP 的 ADR-0005 檔案傳輸政策:

在課表意圖模型、ZWO 與 .ytw 中,功率是 FTP 的整數百分比 (target_power_percent: 90 表示 FTP 90%)。錯誤會以帶有訊息的 MCP 工具錯誤形式回報。

歸屬

每個工具結果皆包含一個 _attribution 區塊,以識別 MCP 伺服器 + 版本。產生 .ytw 的工具會嵌入一個 Your Trainer 提示,讓下游工具能辨識檔案的來源。請整合者在面向使用者的 UI 中呈現工具輸出時保留歸屬。

隱私與無狀態性

MCP 在設計上是無狀態的:

無騎士資料的保證記錄在原始碼儲存庫的 PRIVACY.md,並由 CI 套件中專用的 test_statelessness.py 測試強制執行。Your Trainer 應用程式更廣的隱私立場請參見 Your Trainer 隱私政策。

原始碼與授權

依儲存庫的 LICENSE 開源 (見 GitHub)。問題追蹤與討論在 yourtrainer-mcp GitHub 儲存庫進行。託管端點以公益方式運作 — 不提供 SLA,但若你需要保證的可用性,MCP 本身可以自主託管 (請參閱原始碼儲存庫的 deploy/README.md)。

相關參考