@hitheo/mcp npm 包。任何兼容 MCP 的 IDE——Cursor、Claude Code、Warp、Windsurf、VS Code 等——都可以按需啓動它,並將 Theo 作為一組工具和資源來調用。
什麼是 MCP
Model Context Protocol 是一種開放標準,用於讓由 LLM 驅動的代理調用由獨立進程託管的工具、讀取其資源。宿主(你的 IDE 中的代理)通過 stdio 以 JSON-RPC 與服務器(@hitheo/mcp)通信,並接收一份帶類型的工具、資源和提示詞目錄。
具體來說,MCP 為你的 IDE 提供了三種基本組件:
@hitheo/mcp 做了什麼
@hitheo/mcp 是一個基於 stdio 的 MCP 服務器,它封裝了官方的 @hitheo/sdk,並將調用轉發到 Theo 的 REST API(https://www.hitheo.ai/api/v1/*)。它並不是一個獨立的 Theo 後端——而是一個輕量級本地適配器,使用你的 THEO_API_KEY 將 MCP 工具調用轉換為經過身份驗證的 API 調用。
這意味着你從 IDE 代理發起的每一次工具調用,都會經過與直接調用 API 完全相同的編排流水線(意圖識別 → 模型路由 → 技能 → 工具執行)。你已安裝的技能、自定義角色、項目工具——所有這些都會在 IDE 內同樣生效。
覆蓋範圍
該服務器目前提供:- 8 個工具:
theo_complete、theo_code、theo_research、theo_image、theo_document、theo_skill_list、theo_skill_install、theo_status。 - 3 個資源:
theo://models、theo://skills/installed、theo://health。 - 項目配置: 在倉庫根目錄中可選放置一個
theo.config.json,它會將persona、skills、tools、defaultMode、temperature和metadata注入到每一次工具調用中。
請求流程
有幾點不變量值得了解:- 服務器由 IDE 啓動,而不是由你啓動。IDE 會按需生成
npx -y @hitheo/mcp進程,並在工作區關閉時將其銷燬。 - 傳輸方式為 stdio。不存在任何入站網絡端口;該服務器只會向
https://www.hitheo.ai發出出站的 HTTPS 調用。 - 鑑權使用你的常規 API 密鑰。
THEO_API_KEY在啓動時讀取一次,並在之後的每次請求中複用。該密鑰永遠不會離開服務器進程,IDE 也永遠不會看到它。 theo.config.json在啓動時從當前工作目錄(即 IDE 的工作區根目錄)加載。默認情況下會忽略 JS/TS 變體——參見安全性。
與 SDK 和 REST API 的對比
三者最終都會調用同一個後端。MCP 只是讓 IDE 代理獲得帶類型工具的本地適配器而已。
冒煙測試:確認可用
你可以手動啓動服務器,以驗證安裝流程和你的 API 密鑰是否正常:THEO_API_KEY,打開一個 stdio MCP 傳輸通道,並靜默等待 JSON-RPC 消息。按 Ctrl+C 退出——保持靜默是預期行為,因為與它對話的是 IDE,而不是人類。
如果需要更完整的端到端檢查(同時驗證網絡路徑),請使用 CLI:
版本管理
@hitheo/mcp 遵循 Theo 其他包所使用的預 1.0 semver 策略:minor(次版本號)升級才是破壞性變更的信號(而非 major),這與 npm 的 ^ 操作符解析 0.x.y 的方式一致。MCP 服務器(當前為 0.3.0)將 @hitheo/sdk 固定為 ^0.4.0,因此 0.4.x 的 SDK 發佈會被自動拾取;而 0.5.0 的 SDK 發佈則需要升級 MCP 服務器。
自 0.1.4 起,每個已發佈的 tarball 都帶有已簽名的 npm 溯源信息(provenance)。安裝前請先驗證: