> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服務器概覽

> Theo 如何通過 @hitheo/mcp 接入 Cursor、Claude Code、Warp、Windsurf、VS Code 以及任何其他兼容 MCP 的 IDE。

Theo 將其完整的編排引擎以本地 **Model Context Protocol（MCP）** 服務器的形式對外提供，併發布為 [`@hitheo/mcp`](https://www.npmjs.com/package/@hitheo/mcp) npm 包。任何兼容 MCP 的 IDE——Cursor、Claude Code、Warp、Windsurf、VS Code 等——都可以按需啓動它,並將 Theo 作為一組工具和資源來調用。

## 什麼是 MCP

[Model Context Protocol](https://modelcontextprotocol.io) 是一種開放標準,用於讓由 LLM 驅動的代理調用由獨立進程託管的工具、讀取其資源。宿主(你的 IDE 中的代理)通過 stdio 以 JSON-RPC 與服務器(`@hitheo/mcp`)通信,並接收一份帶類型的工具、資源和提示詞目錄。

具體來說,MCP 為你的 IDE 提供了三種基本組件:

| 基本組件 | 是什麼 | Theo 示例 |
| - | - | - |
| **工具(Tool)** | 一個帶有 JSON-Schema 輸入的可調用函數 | `theo_complete`、`theo_image` |
| **資源(Resource)** | 代理可以獲取以作為上下文的只讀 URL | `theo://models`、`theo://health` |
| **提示詞(Prompt)** | 可複用的提示詞模板 | *(目前 `@hitheo/mcp` 尚未提供)* |

## `@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`](/mcp/tools#theo_complete)、[`theo_code`](/mcp/tools#theo_code)、[`theo_research`](/mcp/tools#theo_research)、[`theo_image`](/mcp/tools#theo_image)、[`theo_document`](/mcp/tools#theo_document)、[`theo_skill_list`](/mcp/tools#theo_skill_list)、[`theo_skill_install`](/mcp/tools#theo_skill_install)、[`theo_status`](/mcp/tools#theo_status)。
* **3 個資源**: [`theo://models`](/mcp/resources#theo-models)、[`theo://skills/installed`](/mcp/resources#theo-skills-installed)、[`theo://health`](/mcp/resources#theo-health)。
* **項目配置**: 在倉庫根目錄中可選放置一個 [`theo.config.json`](/mcp/project-config),它會將 `persona`、`skills`、`tools`、`defaultMode`、`temperature` 和 `metadata` 注入到每一次工具調用中。

## 請求流程

```mermaid theme={null}
sequenceDiagram
    participant IDE as IDE Agent
    participant MCP as @hitheo/mcp (stdio)
    participant SDK as @hitheo/sdk
    participant API as api.hitheo.ai
    IDE->>MCP: tools/call theo_complete { prompt }
    MCP->>MCP: load theo.config.json (cwd)
    MCP->>SDK: client.complete({ prompt, persona, skills, ... })
    SDK->>API: POST /api/v1/completions
    API-->>SDK: { content, model, usage, ... }
    SDK-->>MCP: typed response
    MCP-->>IDE: text content (Theo's reply)
```

有幾點不變量值得了解:

1. **服務器由 IDE 啓動**,而不是由你啓動。IDE 會按需生成 `npx -y @hitheo/mcp` 進程,並在工作區關閉時將其銷燬。
2. **傳輸方式為 stdio**。不存在任何入站網絡端口;該服務器只會向 `https://www.hitheo.ai` 發出出站的 HTTPS 調用。
3. **鑑權使用你的常規 API 密鑰**。`THEO_API_KEY` 在啓動時讀取一次,並在之後的每次請求中複用。該密鑰永遠不會離開服務器進程,IDE 也永遠不會看到它。
4. **`theo.config.json` 在啓動時從當前工作目錄**(即 IDE 的工作區根目錄)加載。默認情況下會忽略 JS/TS 變體——參見[安全性](/mcp/security)。

## 與 SDK 和 REST API 的對比

| 使用場景 | 最佳選擇 |
| - | - |
| 在 IDE 代理內使用,無需編寫代碼 | **MCP**(`@hitheo/mcp`) |
| 你自己的 TypeScript/Node 應用或 worker | **SDK**([`@hitheo/sdk`](/sdk-reference/installation)) |
| 任何其他語言、CI、curl、webhook | **REST**([`/api/v1/*`](/api-reference/overview)) |

三者最終都會調用同一個後端。MCP 只是讓 IDE 代理獲得帶類型工具的本地適配器而已。

## 冒煙測試:確認可用

你可以手動啓動服務器,以驗證安裝流程和你的 API 密鑰是否正常:

```bash theme={null}
export THEO_API_KEY=theo_sk_...
npx -y @hitheo/mcp
```

該進程會從環境變量中讀取 `THEO_API_KEY`,打開一個 stdio MCP 傳輸通道,並靜默等待 JSON-RPC 消息。按 `Ctrl+C` 退出——保持靜默是預期行為,因為與它對話的是 IDE,而不是人類。

如果需要更完整的端到端檢查(同時驗證網絡路徑),請使用 [CLI](/cli-reference/overview):

```bash theme={null}
theo verify   # machine-readable JSON, exits non-zero on failure
theo status   # human-readable; probes both apex and www
```

如果兩者都通過,那麼在任何配置了相同密鑰的 IDE 中,MCP 都能正常工作。

## 版本管理

`@hitheo/mcp` 遵循 Theo 其他包所使用的[預 1.0 semver 策略](/changelog):**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)](/security/authentication#supply-chain-verifying-npm-packages)。安裝前請先驗證:

```bash theme={null}
npm audit signatures @hitheo/mcp
```

## 後續步驟

* **[安裝](/mcp/install)** — 在你的 IDE 中配置 MCP(自動檢測或按 IDE 分別配置)。
* **[工具](/mcp/tools)** — 每個工具的作用、模式(schema)、示例。
* **[資源](/mcp/resources)** — 你的代理可讀取的三個 `theo://` URI。
* **[項目配置](/mcp/project-config)** — 按倉庫固定角色、默認技能或內聯工具。
* **[故障排查](/mcp/troubleshooting)** — 常見配置失敗及修復方法。
* **[安全性](/mcp/security)** — 威脅模型與沙箱語義。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.