@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)。安装前请先验证: