@hitheo/mcp 向你的 IDE 智能体暴露十四个工具。每个工具都封装了 @hitheo/sdk 上的一个方法,并最终调用 https://www.hitheo.ai/api/v1/* 上的某个 REST 端点。下面的模式定义是从 packages/mcp/src/tools.ts 中原样摘录的,因此你的 IDE 在其工具目录中看到的内容与这里记录的完全一致。
这些工具分为两组:执行类工具用于实际运行任务(theo_complete、theo_code 等),配置类工具则根据自然语言描述来构建和调整某个密钥的编排器(theo_setup_key、theo_set_guardrail 等)。每次配置变更都会立即保存,并在 /dashboard/orchestrator?key=… 的仪表盘画布上渲染出来。
工具永远不会看到你的 API 密钥——
@hitheo/mcp 在启动时从 THEO_API_KEY 读取一次密钥,并代表智能体对底层 HTTP 请求进行签名。智能体只能看到工具返回的文本/JSON。权限范围继承。 配置类工具会继承 MCP 服务器用于身份验证的那个密钥的权限范围。将服务器指向一个团队密钥,它创建的一切——新密钥(
theo_setup_key)、路由偏好和护栏策略(theo_set_routing / theo_set_guardrail)——都会归属于该团队、计入团队账单,并对每个成员可见。将其指向一个个人密钥,同样这些工具就会保持在个人范围内。你永远不需要显式传入权限范围,它会跟随密钥自动确定。工具目录
执行类
配置类(需要 billing 权限范围)
theo_complete
通过 Theo 的编排引擎运行一次 AI 补全。Theo 会自动识别意图、在 300 多个 AI 模型中选择最合适的引擎、注入领域技能、执行工具调用,并返回结果。适用于任何通用 AI 任务:写作、分析、规划、问答。
输入模式
当
theo.config.json 定义了 persona、skills、defaultMode 或 tools 时,这些值会被合并进请求——参见项目配置。
智能体调用示例
响应示例(已截断)
说明
- 输出末尾附带一行摘要,包含最终选定的模型、模式和费用,方便智能体了解请求是如何被路由的。
- 费用会在执行完成后进行核对,并反映到你账户的实际计费中。
theo_code
使用 Theo 生成代码。请求会被路由到 Theo Code 引擎,以获得业界领先的代码生成能力,并配有更大的输出预算。返回生成的代码及任何附件(完整文件、项目脚手架)。适用于以编写、生成或搭建代码为主的任务。
输入模式
智能体调用示例
Artifacts: 区块。
theo_research
针对某个主题运行深度研究。Theo 会规划 3–6 条聚焦的搜索查询、并行执行、去重来源,并综合出一份带引用的结构化报告。这是一个异步操作——MCP 服务器会持续轮询,直到底层任务完成(默认预算:120 秒,轮询间隔 3 秒),然后返回最终报告。
输入模式
智能体调用示例
失败处理
如果研究任务失败或超时,该工具会返回一段以Research failed: 开头的纯文本,便于智能体判断是否要用更窄的提示词重试。
theo_image
使用 Theo 生成图像。请求会被路由到 Theo Create 引擎,并具备自动的服务商回退能力。返回图像 URL。适用于徽标、插图、原型图、概念图等任何视觉内容。
输入模式
响应示例
theo_document
生成一份格式化文档。Theo 会创建文档,并返回一个位于 artifacts.hitheo.ai 上的下载链接。适用于报告、演示文稿、电子表格和数据导出。
输入模式
智能体调用示例
响应示例
theo_skill_list
列出可用的 Theo 技能。技能是打包好的领域知识与工具集合,用于扩展 Theo 的能力(类似 AI 的应用程序)。可按 installed(该账户上已启用)或 marketplace(可供安装)进行过滤。
输入模式
该工具返回一个格式化打印的技能记录 JSON 数组(
id、slug、name、description、version 等)。智能体通常会将其与 theo_skill_install 搭配使用。
theo_skill_install
从 Theo 市场安装一个技能。安装完成后,该技能的领域知识与工具会在每次补全时可用(包括之后每一次 theo_complete MCP 调用)。
输入模式
响应示例
theo_status
检查 Theo 的健康状态与引擎可用性。返回引擎状态、延迟以及基础设施健康情况。用于验证连接是否正常,或在 IDE 内部诊断问题。
输入模式
无参数。响应示例
Status: healthy,请在主机上运行 theo verify 进行排查。
theo_setup_key
一次调用即可创建一个新的 Theo API 密钥,并构建出一个已保存、可见的编排器——无需在画布上手动搭建。可通过三种方式之一指定方案(优先级:graph > routing > use_case):
use_case——单引擎预设。coding将某个代码引擎固定为确定性的直通后端(适合作为 Warp / Cursor 的即插即用后端);chat固定为快速引擎;raw由你自行选择引擎。routing——按模式绑定引擎。Theo 的分类器会将每个请求划分为某种模式,你可以为每种模式固定一个引擎。graph——一个完整的自定义编排器图{ enabled, nodes, edges },将按原样应用。
输入模式
智能体调用示例
响应示例(已截断)
theo_configure_key
重新规划一个已有密钥——选项与 theo_setup_key 相同(use_case / routing / graph,优先级相同)。变更会立即反映在仪表盘画布上。返回一个仪表盘链接。
输入模式
智能体调用示例
theo_add_skill
安装一个技能(如需,从市场安装),并将其挂接到某个密钥的允许列表上,使该密钥能够调用它。可选地限定到单一模式。该操作具有幂等性——重复添加同一个(技能, 模式)组合不会产生任何变化。
输入模式
智能体调用示例
No skill matches "…",以便智能体调用 theo_skill_list 后重试。
theo_assign_skill_to_node
将一个技能挂接到某个密钥编排器图中的一个或多个模型节点上,使该技能只作用于这些节点。目标节点可通过节点的id、标签、其所处理的模式,或其运行的引擎来匹配——技能会挂接到每一个匹配到的节点上。因此,如果查询中指定的引擎或模式被两个及以上节点共用,则会命中所有这些节点(例如 sonnet 会挂接到运行 anthropic/claude-sonnet-4.6 的每一个节点)。
要求该密钥已经拥有一个图。如果没有任何匹配,该工具会返回可用节点的列表。
输入模式
智能体调用示例
theo_set_guardrail
将一个 Gateway Guardrails 策略绑定到某个密钥。可以传入一个已有策略的名称/id,或一个预设名称(例如 PII-safe、Injection guard),由该模板创建策略并绑定。在拥有编排器图的密钥上,该策略会以一个护栏节点的形式加入画布:
- input 节点(位于 Entry 之后,或在限定范围时位于分类器之后)负责检查提示词;
- output 节点(位于模型之后)负责检查回复。
input / output / both)中推断,除非你显式传入 phase。传入 mode(某个模式或引擎名称)可将护栏限定到该分支——它会挂接到所有具有该模式/引擎的节点。对于没有图的密钥,该策略会在密钥级别绑定(按其规则同时检查两个阶段)。remove: true 会清除护栏;附加 phase 可仅移除输入或输出检查点。
输入模式
智能体调用示例
theo_set_routing
将一个 Routing Studio 偏好绑定到某个密钥——可以是一个已有的偏好(按名称/id),也可以直接内联创建规则(pattern 关键词/正则 → mode)。规则默认是累加的:新规则会追加到该密钥当前的路由上(并去重),因此再次请求添加第二条规则时,第一条规则仍会保留。传入 replace: true 可改为重置。对于拥有图的密钥,会插入一个单独的Router 节点(Entry → … → Router → Classifier),使规则真正生效并显示在画布上;如果某条规则的目标模式没有对应的引擎节点,则会触发一条警告。remove: true 会清除路由。
输入模式
智能体调用示例
参考
引擎(配置界面——此处有意展示真实引擎名称):arca-velox-5.1(快速)、arca-magnus-5.1(深度推理)、anthropic/claude-sonnet-4.6、anthropic/claude-opus-4.8、anthropic/claude-haiku-4.5、google/gemini-2.5-pro、openai/gpt-4.1,以及你自己的 custom:<providerId>:<model>。
模式: fast、think、code、research、roast、genui、data_extraction、vision、image、video。
护栏预设: 例如 PII-safe、Injection guard。若不匹配,该工具会列出所有可用的策略和预设。
