MCP Integration

MCP Integration：連接 AI 工具

FH6-HorizonTuner 提供 localhost、read-only 的 Streamable HTTP MCP endpoint。Rust backend / MCP Beta 已隨 v1.6.1 發布；PR #443 尚未合併，會補強既有 Rust MCP 與功能契約、加入 Rust Agent CLI，並移除剩餘 Python backend runtime。MCP 與 telemetry listener 共用同一個 backend process，因此 AI 查詢的是目前應用程式使用的 telemetry/session 資料邊界。

使用前條件

MCP 只有在以下條件同時成立時可用：

1. FH6-HorizonTuner 正在執行。
2. backend / sidecar 已 ready。
3. Settings → MCP Server 的 Enable MCP Server 已開啟。
4. 你使用的是目前實際 backend port 的 /mcp URL。

開發模式的預設 endpoint：

http://127.0.0.1:8001/mcp

Release Build 會先嘗試 8001；若被占用，會選擇動態 port。請從 Settings MCP card 複製 URL，或查詢資料目錄的 logs/web_port.txt。不要猜測 Release endpoint。

Codex

在 FH6-HorizonTuner 已啟動且 MCP 已開啟時，執行：

codex mcp add fh6-horizon-tuner --url http://127.0.0.1:8001/mcp
codex mcp list
codex mcp get fh6-horizon-tuner

如果 Release Build 使用動態 port，將上面的 URL 替換為 Settings MCP card 顯示的實際 URL。

Claude Desktop、Cursor 與其他 HTTP MCP client

對於使用 JSON 設定的客戶端，使用 Streamable HTTP URL：

{
  "mcpServers": {
    "fh6-horizon-tuner": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

不同客戶端的設定檔位置不同；請保留 url 指向 /mcp，不要改成 legacy SSE 路由或啟動第二個 MCP server。

可以查詢什麼

目前提供 26 個 read-only tools，分為：

類別	能查詢的內容
Live telemetry	最新 snapshot、cockpit、vehicle dynamics、tires、suspension
Race sessions	Session 清單、摘要、Lap 與降採樣 telemetry
Tuning captures	capture 清單、摘要、時間窗口與 baseline/candidate A/B comparison
Drag	Drag session 清單與加速分析
Cars	車輛搜尋、車輛 details、tuning capabilities
Tuning	constants/priors、saved presets、preset details、Road/Rally/Drift/Drag solver、telemetry handling diagnosis
System	app settings、HUD configuration、最近 logs

代表性的 tool 名稱包括：

get_live_telemetry_snapshot
get_driver_cockpit_telemetry
get_vehicle_dynamics_telemetry
get_tires_status_telemetry
get_suspension_telemetry
list_race_sessions
get_session_summary
query_session_telemetry
list_tuning_captures
get_capture_summary
query_capture_window
compare_captures
list_drag_sessions
get_drag_analysis
search_cars
get_car_details
get_car_tuning_capabilities
get_tuning_constants_and_priors
list_tuning_presets
get_tuning_preset
run_dev_tuning_solver
run_gearing_solver
diagnose_telemetry_handling
get_system_settings
get_hud_configurations
get_recent_logs

Resource URI 會提供 live telemetry、current settings/HUD、最近 race session、最近 tuning capture，以及車輛與 tuning preset 等可發現資料：

fh6://telemetry/live
fh6://settings/current
fh6://telemetry/session/{id}
fh6://capture/{id}
fh6://car/{id}
fh6://tuning/{car}/{save}

這些 URI 是 read-only 的資源發現/查詢入口；{id}、{car}、{save} 必須替換成目前已存在且由應用程式列出的資料，不應用來猜測或存取任意檔案。

不會做什麼

MCP：

• 不會修改遊戲。
• 不會控制車輛或輸入鍵盤/手把。
• 不會寫入調校值或自動套用建議。
• 不提供任意 SQL。
• 不建立第二個 UDP telemetry listener。
• 不提供連續 server-push 的未來 60Hz frame stream。

Live tool 是 point-in-time snapshot；要觀察後續資料，客戶端必須再次查詢。歷史與 capture time-series 則透過有界窗口與降採樣結果查詢。

安全邊界

這是本機整合介面。除非你已經設計並審查明確的存取控制，不要把 127.0.0.1 endpoint 反向代理或暴露到區域網路/公網。若不使用 AI 整合，保持 MCP 關閉即可。

常見問題

現象	先檢查
MCP unavailable	程式是否 running、backend 是否 ready、MCP 是否 enabled
Connection refused	URL 的 port 是否仍是實際 backend port
沒有 live telemetry	先看 Telemetry Dashboard 與 Troubleshooting
查不到 Session/capture	先確認已啟用相應錄製並且資料已保存
工具可連線但資料為空	目前沒有有效資料；不要把空結果理解為零值

English

The Rust backend and MCP Beta shipped in v1.6.1. PR #443 remains open and unreleased; it hardens the existing Rust MCP and feature contracts, adds the Rust Agent CLI, and retires the remaining Python backend runtime. The localhost, read-only Streamable HTTP /mcp endpoint provides 26 tools for telemetry, sessions, captures, drag analysis, car data, tuning solvers, settings, HUD configuration, and logs.

日本語

Rust backend / MCP Beta は v1.6.1 で公開済みです。PR #443 は未マージ・未リリースで、既存 Rust MCP と機能契約の補強、Rust Agent CLI の追加、残る Python backend runtime の廃止を行います。localhost read-only の Streamable HTTP /mcp endpoint から telemetry、Session、capture、Drag、車両情報、solver、Settings、HUD、log を参照できます。