> ## 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.