# OctoHz MCP 使用教程

OctoHz 提供了一个远程 MCP（Model Context Protocol）server，让 Claude、Codex 等任何兼容 MCP 的智能体客户端可以直接读写项目归档、待办、密码库/主机/API 密钥、公开文档、私有文档、站内内容的发现与发布、导航书签、私人与站内公共资源库，以及八字/风水/经文/咒语/股票/饭店/食谱这类个人数据，不需要单独装 CLI 或自己写 HTTP 客户端代码。除了需要读本地仓库文件的 `sync`，CLI 的所有命令组在 MCP 里都有对应。

## Endpoint

```
https://octohz.com/api/mcp
```

- 协议：MCP Streamable HTTP（stateless 模式，服务端不维护 session，每次请求独立处理）
- 只支持 `POST`（JSON-RPC 2.0）；`GET`/`DELETE` 会返回 405
- 鉴权：`Authorization: Bearer <apiToken>`——跟 CLI 用的是同一个 token，在账号设置页生成

不带 token 也能调用公开工具（如 `doc_get`、`search_content`、`category_list`、`site_resource_list`），但涉及个人数据或写操作的工具必须带 token，否则返回 `isError: true`，提示"未授权"。

**密码库 / 主机 / API 密钥这三类走的是另一套鉴权**：独立的、限次读取的 `privateKey`（账号设置页单独生成，跟 `apiToken` 不是一回事）。这套 key 不放在 `Authorization` header，而是作为每个 vault tool 自己的参数传——因为一次 MCP 连接的 header 是固定的，没法按 tool 切换成两种不同的 token，做成参数就能每次调用显式指定。`list` 类 tool 免费不耗额度，单条读取（如 `password_get`）消耗 1 次额度，额度耗尽后该 key 自动失效，需要去账号设置页重新生成。`vest_publish` 的 `vestToken`（马甲身份）也是同样的理由，同样走参数。

## 接入方式

### Claude Code

```bash
claude mcp add --transport http octohz https://octohz.com/api/mcp \
  --header "Authorization: Bearer <your-apiToken>"
```

### Codex（桌面版 / CLI）

Codex 的技能（skill）只提供使用说明，不会自动注册 MCP。远程 MCP 要单独写入用户级 `~/.codex/config.toml`；官方推荐用 CLI 注册，CLI 与 Codex 桌面版共用这份配置：

```powershell
codex mcp add octohz `
  --url https://octohz.com/api/mcp `
  --bearer-token-env-var OCTOHZ_API_TOKEN

codex mcp list
codex mcp get octohz
```

注册后完全退出并重新打开 Codex，再新建任务；已经运行的桌面进程和旧任务不会自动获得新 MCP 工具。设置页“插件 → MCP”中应能看到 `octohz`。

#### Windows 上更安全的认证方式

`bearer_token_env_var` 是标准配置，但本地智能体启动的 shell 子进程也可能继承该环境变量。已经使用 OctoHz CLI 的 Windows 用户，可以改用 Codex 的 `http_headers_helper`，让 MCP 客户端调用时才从现有 CLI 配置读取 token，避免把 token 放进任务环境。

例如新建 `%USERPROFILE%\.octohz\mcp-headers.ps1`：

```powershell
$config = Get-Content -Raw "$env:USERPROFILE\.octohz\config.json" | ConvertFrom-Json
if ([string]::IsNullOrWhiteSpace([string]$config.token)) {
  throw "OctoHz token is not configured"
}
@{ Authorization = "Bearer $($config.token)" } | ConvertTo-Json -Compress
```

然后在 `~/.codex/config.toml` 中配置，并把示例里的 `your-name` 换成实际 Windows 用户目录名：

```toml
[mcp_servers.octohz]
url = "https://octohz.com/api/mcp"
http_headers_helper = 'powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Users\your-name\.octohz\mcp-headers.ps1"'
```

不要把真实 token 直接写进教程、项目文件、命令历史或可被智能体读取的日志。非交互模式若使用 `approval_policy=never`，需要审批的 MCP 调用会被拒绝；这是客户端审批策略，不是连接失败。

#### 136 个 Tool 会不会占满上下文

支持 Tool Search 的新版本 Codex 会把 MCP 工具延迟加载：任务启动时只保留很小的发现入口，需要调用时才按需载入匹配工具的 schema，不会把 136 个完整 schema 全部塞进每一轮上下文。

2026-09-23 在 Codex CLI `0.155.0-alpha.16` 上做过一组同提示、全新进程的对照测试：

| 状态 | 首轮 input tokens |
|---|---:|
| 启用 OctoHz MCP | 15,769 |
| 临时禁用 OctoHz MCP | 15,763 |

启动差异只有 6 tokens；随后要求读取公开文档 84 时，事件流才选择 `octohz/doc_get`。这说明该版本没有在新任务启动时全量加载 136 个 schema。不同客户端、模型和版本的实现可能不同；不支持 Tool Search 的客户端仍可能急加载全部工具，可用 `enabled_tools` 白名单限制暴露范围。

### 通用 MCP client 配置

大多数支持远程 MCP（HTTP transport）的客户端配置格式类似：

```json
{
  "mcpServers": {
    "octohz": {
      "url": "https://octohz.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-apiToken>"
      }
    }
  }
}
```

具体字段名以各家客户端文档为准（有的叫 `url`，有的叫 `serverUrl`）。注意只有支持 HTTP/Streamable HTTP transport 的客户端能连——纯 stdio 型 MCP 客户端连不了远程 server。

## 可用 Tool（共 149 个）

_验证于 2026-09-26，server 2.11.0。数字以 `tools/list` 实时结果为准，本节由 `tools/mcp/doc-tools-table.ts` 生成。_

鉴权速查：标题标注 `apiToken` 的分类需要 `Authorization: Bearer <apiToken>`；`privateKey` 作为工具参数传入；“公开读取”无需鉴权；“管理员写入”除 `apiToken` 外还要求管理员权限。表内仅保留例外权限，避免每行重复。

### 项目归档（apiToken）

写入类工具（决策、坑、任务、交接事件的新增与修改）都可以选传 `actor`，记录“是谁写的”（和 CLI 的 `--actor` 一致）；不传时新增类记 `mcp`、修改类记 `agent`。

| Tool | 说明 | 必填参数 |
|---|---|---|
| `project_list` | 列出我的项目归档（摘要字段）。 | 无 |
| `project_get` | 读取 OctoHz 我的项目归档。默认返回摘要索引（各段 summary + 子资源 url）；full=true 返回完整数据；section 指定时只返回该段（definition/status/ops/decisions/pitfalls/design/data_models）。 | `id`（另有 2 个可选） |
| `project_onboard` | 一次调用拿到安全上手所需的最小集：definition + onboarding + active 决策 + active 坑 + 开放任务 + 最近事件 + 各段新鲜度。新智能体接手项目永远从这个 tool 开始。 | `id`（另有 1 个可选） |
| `project_events` | 读取项目交接事件时间线，最近的在前。 | `id`（另有 1 个可选） |
| `project_list_entries` | 列出项目归档下的条目（decision/pitfall/task/event/note），可按 kind/status 过滤。 | `id`（另有 2 个可选） |
| `project_entry_get` | 按编号（D001/P001/T001/E001/N001）或数字 id 读取一条条目的完整内容。 | `id`、`ref` |
| `project_add` | 创建一个新的项目归档，entries 聚合自创建起即生效。对应 CLI 的 `octohz project add`。 | `name`（另有 2 个可选） |
| `project_patch` | 智能合并更新 definition/ops/design 文档段：对象深合并，已知数组按 key upsert（env_vars→key, servers→address 等），字段传 null 删除。decision/pitfall/task/event 请用对应的专门 tool。对应 CLI 的 `octohz project patch`。 | `id`（另有 6 个可选） |
| `project_decision_add` | 记录一条决策，服务端分配 D 编号。对应 CLI 的 `octohz project decision add`。 | `id`、`title`、`decision`（另有 3 个可选） |
| `project_decision_edit` | 按编号（如 D003）更新决策字段，只传的字段会改；supersede=true 标记为已废弃。对应 CLI 的 `octohz project decision edit`。 | `id`、`ref`（另有 6 个可选） |
| `project_pitfall_add` | 记录一个坑，服务端分配 P 编号。对应 CLI 的 `octohz project pitfall add`。 | `id`、`title`、`severity`、`condition`、`consequence`、`solution`（另有 1 个可选） |
| `project_pitfall_edit` | 按编号（如 P003）更新坑的字段，只传的字段会改。对应 CLI 的 `octohz project pitfall edit`。 | `id`、`ref`（另有 6 个可选） |
| `project_pitfall_resolve` | 按编号把一个坑标记为已解决。对应 CLI 的 `octohz project pitfall resolve`。 | `id`、`ref` |
| `project_task_list` | 列出开放任务（pending + in_progress），含认领人；all=true 包含已完成。 | `id`（另有 1 个可选） |
| `project_task_add` | 新增一个待认领任务，服务端分配 T 编号，默认 status=pending。对应 CLI 的 `octohz project task add`。 | `id`、`title`（另有 2 个可选） |
| `project_task_claim` | 认领一个任务（置 in_progress + 记认领人），防止多智能体重复做同一件事。对应 CLI 的 `octohz project task claim`。 | `id`、`ref`（另有 1 个可选） |
| `project_task_done` | 把任务标记为 done，并自动追加一条完成事件到时间线。对应 CLI 的 `octohz project task done`。 | `id`、`ref`（另有 1 个可选） |
| `project_log_event` | 给项目归档新增一条 event 条目（交接记录），服务端自动分配编号并写快照。对应 CLI 的 `octohz project log`。 | `id`、`title`（另有 6 个可选） |
| `project_entry_rm` | 按编号（如 N001）或数字 id 删除一条条目。对应 CLI 的 `octohz project entry-rm`。 | `id`、`ref` |
| `project_snapshot_list` | 列出项目的版本快照（不含内容，只有 id/note/时间）。 | `id` |
| `project_snapshot_get` | 读取某个版本快照的完整内容。 | `id`、`sid` |
| `project_snapshot_restore` | 把文档段（definition/ops/design，迁移后的项目条目不受影响）恢复到某个历史快照；恢复前会自动备份当前版本。 | `id`、`sid` |
| `project_migrate_entries` | 把 2026-08-17 之前创建、从未迁移过的老项目的旧 JSONB 列（decisions/pitfalls/status）迁移为条目。新项目创建时已自动激活，此 tool 对新项目会报 already_migrated。dry=true 只预览不写入；即使 counts 全 0 也建议正式执行一次以激活聚合。 | `id`（另有 1 个可选） |

### 密码库（需要 privateKey）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `password_list` | 列出密码条目（不含密码字段，免费不耗额度）。 | `privateKey` |
| `password_get` | 按 id 读取一条密码的完整明文，消耗 1 次 privateKey 额度。 | `privateKey`、`id` |
| `password_add` | 新增一条密码记录（加密存储）。 | `privateKey`、`title`、`password`（另有 4 个可选） |
| `password_update` | 整条覆盖更新一条密码记录（title/password 必填，与 CLI 行为一致，非局部 patch）。 | `privateKey`、`id`、`title`、`password`（另有 4 个可选） |
| `password_rm` | 删除一条密码记录。 | `privateKey`、`id` |

### 主机（需要 privateKey）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `host_list` | 列出主机（不含 rootPassword/panelPassword，免费不耗额度）。 | `privateKey` |
| `host_get` | 按 id 读取一台主机的完整凭据（root/面板密码），消耗 1 次 privateKey 额度。 | `privateKey`、`id` |
| `host_find` | 按公网/内网 IP 查找主机：精确匹配优先，无精确匹配再回退到包含匹配。默认免费只列匹配项（不含密码）；reveal=true 且唯一匹配时才读取完整凭据（消耗 1 次额度）。 | `privateKey`、`ip`（另有 1 个可选） |
| `host_add` | 新增一台主机记录（密码字段加密存储）。 | `privateKey`、`name`（另有 17 个可选） |
| `host_update` | 局部更新主机字段：只传的字段会改，其余保持不变。 | `privateKey`、`id`（另有 18 个可选） |
| `host_rm` | 删除一台主机记录。 | `privateKey`、`id` |

### 我的 API（需要 privateKey）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `api_list` | 列出第三方 API/服务订阅条目（不含 apiKey 字段，免费不耗额度）。 | `privateKey` |
| `api_get` | 按 id 读取一条 API 服务的完整密钥，消耗 1 次 privateKey 额度。 | `privateKey`、`id` |
| `api_add` | 新增一条第三方 API/服务订阅记录（apiKey 加密存储）。 | `privateKey`、`name`、`apiKey`（另有 6 个可选） |
| `api_update` | 局部更新一条 API 记录：只传的字段会改。 | `privateKey`、`id`（另有 8 个可选） |
| `api_rm` | 删除一条 API 记录。 | `privateKey`、`id` |

### 内容发现与发布（混合鉴权）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `util_get_title` | 抓取一个 URL，提取 <title> 和 meta description，常用来给 submit_post 自动填标题/简介。8s 超时。 | `url` |
| `category_list` | 列出发布内容可用的分类（id/name/slug），发布前先查一下，submit_post 的 category 参数直接用这里的 id 或 slug。 | 无 |
| `search_content` | 跨类型全文搜索：帖子/论坛/文档/推荐集/资源。不带 token 时搜索公开内容；带 apiToken 时也能搜索仅会员可见的内容。 | `q`（另有 3 个可选） |
| `product_get` | 读取一篇内容详情（含正文）。仅会员可见的内容需要 apiToken 才能读到。 | `id` |
| `product_list` | 按条件列出已发布内容（分类/发布者/关键词/日期/排序等）。带 apiToken 时也能看到仅会员可见内容。 | 均可选 |
| `product_patch` | 局部更新一篇内容（只更新传入字段），本人或 admin 可操作。封面图传 imageUrl（服务端抓取）或 imageBase64（+可选 imageMimeType）二选一。 | `id`（另有 10 个可选） |
| `submit_post` | 发布一条新内容（推荐/资源等）。category 可传数字 id 或 slug/名称（先用 category_list 查可用值）。封面图传 imageUrl（服务端抓取）或 imageBase64（+可选 imageMimeType）二选一，都不传则无封面图。 | `name`、`intro`、`category`（另有 7 个可选） |
| `essay_post` | 发一条 essay 类型的短内容（≤100 字，类似推文）。 | `content` |
| `product_delete` | 彻底删除一篇内容（级联清理评论/点赞/收藏/tag/合集条目/举报）。仅管理员可操作——发布者本人也无权限，这是站点现有权限模型（后台管理页同款），不可撤销。 | `id` |
| `vest_publish` | 用马甲（vest）身份发布一条内容，跟 submit_post 用 apiToken 发布是同一套发布逻辑，区别是归属和展示身份是马甲而不是本人。vestToken 在 octohz.com/my/vests 获取，作为参数传（不是 Authorization header，理由同 privateKey）。封面图传 `imageUrl`（服务端抓取）或 `imageBase64`（+可选 `imageMimeType`）二选一，都不传则无封面图。 | `vestToken`、`name`、`intro`、`category`（另有 6 个可选） |

### 公开文档（公开读取 / 管理员写入）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `doc_get` | 读取 OctoHz 公开文档（/docs 板块，对应 tutorial 表），公开内容。 | `id` |
| `doc_list` | 列出公开文档（/docs 板块），公开内容。 | 均可选 |
| `doc_category_list` | 列出 /docs 板块的分类（id/name），doc_add 的 categoryId 参数对照用。 | 无 |
| `doc_category_add` | 新建一个公开文档（/docs 板块）分类，可选挂在父分类下。仅管理员可操作。 | `name`（另有 3 个可选） |
| `doc_add` | 新建一篇公开文档（/docs 板块）。仅管理员可操作。 | `title`、`content`（另有 4 个可选） |
| `doc_update` | 整体覆盖更新一篇公开文档——title/content 都是必填，会替换全文。建议先 doc_get 读出当前内容再改，避免误删正文。仅管理员可操作。 | `id`、`title`、`content`（另有 4 个可选） |
| `doc_delete` | 删除一篇公开文档，不可撤销。仅管理员可操作。 | `id` |

### 我的文档（公开分享免鉴权 / 其余 apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `private_doc_list` | 列出我的私有文档（笔记），可按文件夹过滤。 | 均可选 |
| `private_doc_get` | 读取一篇私有文档的完整内容；本人可用 apiToken 读取，isPublic=true 时任何人均可免鉴权读取。 | `id` |
| `private_doc_add` | 新建一篇私有文档（笔记），可选新建时直接置顶 / 公开。 | `title`（另有 4 个可选） |
| `private_doc_update` | 局部更新一篇私有文档，只传的字段会改；categoryId 传 null 清除文件夹。 | `id`（另有 5 个可选） |
| `private_doc_rm` | 删除一篇私有文档，不可撤销。 | `id` |
| `private_doc_category_list` | 列出我的私有文档文件夹（可嵌套，parentId 指向父文件夹）。 | 无 |
| `private_doc_category_add` | 新增一个私有文档文件夹，可选挂在某个父文件夹下。 | `name`（另有 1 个可选） |
| `private_doc_category_patch` | 改名或切换公开状态，只传的字段会改。 | `id`（另有 2 个可选） |
| `private_doc_category_rm` | 删除一个私有文档文件夹；旗下文档的文件夹会被置空，不会被删除。 | `id` |

### 待办（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `todo_list` | 列出我的待办事项。 | 无 |
| `todo_create` | 新建一条待办事项。 | `content` |
| `todo_complete` | 把一条待办标记为已完成（或取消完成）。 | `id`（另有 1 个可选） |
| `todo_update` | 改一条待办的内容或置顶状态，只传的字段会改。 | `id`（另有 2 个可选） |
| `todo_rm` | 删除一条待办事项。 | `id` |

### 导航书签（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `nav_list` | 列出我的导航书签。 | 无 |
| `nav_add` | 新增一条导航书签。 | `title`、`url`（另有 3 个可选） |
| `nav_patch` | 局部更新一条导航书签，只传的字段会改。 | `id`（另有 6 个可选） |
| `nav_rm` | 删除一条导航书签。 | `id` |
| `nav_category_list` | 列出我的导航书签分类。 | 无 |
| `nav_category_add` | 新增一个导航书签分类。 | `name` |
| `nav_category_rename` | 重命名一个导航书签分类。 | `id`、`name` |
| `nav_category_rm` | 删除一个导航书签分类；旗下书签的分类会被置空，不会被删除。 | `id` |

### 站内公共资源库（公开读取 / apiToken 写入）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `site_resource_category_list` | 列出官方资源库分类，含每类资源数。 | 无 |
| `site_resource_category_add` | 新增一个官方资源库分类。仅管理员可操作。 | `name`（另有 2 个可选） |
| `site_resource_category_patch` | 改名/置顶/排序一个官方资源库分类，只传的字段会改。仅管理员可操作。 | `id`（另有 3 个可选） |
| `site_resource_category_rm` | 删除一个官方资源库分类。仅管理员可操作。 | `id` |
| `site_resource_list` | 列出官方资源库条目，可按分类过滤。 | 均可选 |
| `site_resource_get` | 读取一条官方资源的完整信息（含版本历史）。 | `id` |
| `site_resource_add` | 新增一条官方资源，自动创建初始版本记录。fileUrl 让服务端抓取资源文件（≤50MB，30s 超时，不限格式）；iconUrl/iconBase64 设置封面图标。仅管理员可操作。 | `title`、`summary`（另有 8 个可选） |
| `site_resource_patch` | 更新一条官方资源的标题/摘要/说明/分类/图标/置顶/排序，只传的字段会改。管理员或发布人本人可操作。不改版本或文件，改文件用 site_resource_publish_version。清空图标传 `removeIcon=true`（或 `iconUrl` 传空字符串）。 | `id`（另有 11 个可选） |
| `site_resource_publish_version` | 给一条官方资源追加一个新版本记录，并更新资源当前版本号/文件。fileUrl 不传则沿用上一版本的文件。管理员或发布人本人可操作。 | `id`、`version`（另有 3 个可选） |
| `site_resource_downloads` | 列出一条官方资源的下载记录。管理员或发布人本人可查看。 | `id` |
| `site_resource_rm` | 删除一条官方资源及其版本历史。仅管理员可操作。 | `id` |

### 私人资源库（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `resource_category_list` | 列出我的资源库分类，含每类资源数。 | 无 |
| `resource_category_add` | 新增一个资源库分类。 | `name` |
| `resource_category_rename` | 重命名一个资源库分类。 | `id`、`name` |
| `resource_category_patch` | 改名/置顶/排序一个我的资源库分类，只传的字段会改（同 site_resource_category_patch，但作用于私人资源库）。 | `id`（另有 3 个可选） |
| `resource_category_rm` | 删除一个资源库分类。 | `id` |
| `resource_list` | 列出我的资源库条目，可按分类过滤。 | 均可选 |
| `resource_get` | 读取一条资源的完整信息（含版本历史）。 | `id` |
| `resource_add` | 新增一条资源，自动创建初始版本记录。fileUrl 让服务端抓取资源文件（≤50MB，30s 超时，不限格式）；iconUrl/iconBase64 设置封面图标，规则同 submit_post。 | `title`、`summary`（另有 8 个可选） |
| `resource_patch` | 更新一条资源的标题/摘要/说明/分类/图标/分享开关/置顶/排序，只传的字段会改。不改版本或文件，改文件用 resource_publish_version。清空图标传 `removeIcon=true`（或 `iconUrl` 传空字符串）。 | `id`（另有 12 个可选） |
| `resource_publish_version` | 给一条资源追加一个新版本记录，并更新资源当前版本号/文件。fileUrl 不传则沿用上一版本的文件。 | `id`、`version`（另有 3 个可选） |
| `resource_downloads` | 列出一条资源的下载记录。 | `id` |
| `resource_rm` | 删除一条资源及其版本历史。 | `id` |

### 八字（我的命理，apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `bazi_list` | 列出我的八字记录（摘要，含日主/五行/调候/刑冲合害）。 | 无 |
| `bazi_get` | 读取一条八字记录的完整排盘（四柱/大运/流年/神煞）。 | `id` |
| `bazi_add` | 新增一条八字排盘记录。 | `name`、`gender`、`year`、`month`、`day`（另有 4 个可选） |
| `bazi_patch` | 局部更新一条八字记录，只传的字段会改。 | `id`（另有 10 个可选） |
| `bazi_rm` | 删除一条八字记录。 | `id` |

### 风水（我的房屋，apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `fengshui_list` | 列出我的房屋风水记录（摘要）。 | 无 |
| `fengshui_get` | 读取一条房屋风水记录的完整排盘（八宅九宫/玄空飞星/装修数据），每次实时用当前算法重算。 | `id` |
| `fengshui_add` | 新增一条房屋风水记录，服务端计算三元九运/命卦/八宅九宫/玄空飞星。 | `name`、`facingDegree`、`moveInYear`、`birthDate`、`gender`（另有 1 个可选） |
| `fengshui_patch` | 局部更新一条风水记录；facingDegree/moveInYear/birthDate/gender 任一变化都会整体重新计算。 | `id`（另有 7 个可选） |
| `fengshui_rm` | 删除一条房屋风水记录。 | `id` |

### 经文库（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `sutra_list` | 列出我的经文库。 | 无 |
| `sutra_get` | 读取一条经文的完整内容。 | `id` |
| `sutra_add` | 新增一条经文记录。 | `name`（另有 6 个可选） |
| `sutra_patch` | 局部更新一条经文，只传的字段会改。 | `id`（另有 7 个可选） |
| `sutra_rm` | 删除一条经文记录。 | `id` |

### 咒语库（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `zhouyu_list` | 列出我的咒语库。 | 无 |
| `zhouyu_get` | 读取一条咒语的完整内容。 | `id` |
| `zhouyu_add` | 新增一条咒语记录。 | `name`（另有 6 个可选） |
| `zhouyu_patch` | 局部更新一条咒语，只传的字段会改。 | `id`（另有 7 个可选） |
| `zhouyu_rm` | 删除一条咒语记录。 | `id` |

### 股票（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `stock_list` | 列出我的股票持仓。 | 无 |
| `stock_search` | 按名称/代码搜索股票，返回 symbol（Yahoo Finance 格式）和实时价格，供 stock_add 使用。整合腾讯/东方财富/Yahoo Finance 数据源。 | `q` |
| `stock_add` | 新增一条股票持仓；code 用 stock_search 返回的 symbol（Yahoo Finance 格式，如 600519.SS/AAPL）。 | `name`、`code`、`market`、`buyPrice`、`currentPrice`（另有 1 个可选） |
| `stock_refresh` | 批量刷新持仓的当前价格（腾讯行情）。 | 均可选 |
| `stock_patch` | 局部更新一条持仓（价格/数量/名称等），只传的字段会改。 | `id`（另有 6 个可选） |
| `stock_rm` | 删除一条股票持仓记录。 | `id` |

### 我的饭店（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `restaurant_list` | 列出我的饭店笔记，可按分类过滤。 | 均可选 |
| `restaurant_get` | 读取一条饭店笔记。 | `id` |
| `restaurant_add` | 新增一条饭店笔记。 | `name`（另有 5 个可选） |
| `restaurant_patch` | 局部更新一条饭店笔记，只传的字段会改。 | `id`（另有 6 个可选） |
| `restaurant_rm` | 删除一条饭店笔记。 | `id` |

### 我的食谱（apiToken）

| Tool | 说明 | 必填参数 |
|---|---|---|
| `recipe_list` | 列出我的食谱，可按分类过滤。 | 均可选 |
| `recipe_get` | 读取一条食谱。 | `id` |
| `recipe_add` | 新增一条食谱。 | `name`（另有 5 个可选） |
| `recipe_patch` | 局部更新一条食谱，只传的字段会改。 | `id`（另有 6 个可选） |
| `recipe_rm` | 删除一条食谱。 | `id` |

### 工作台（AI 生成，会扣余额）

工作台（/my/console）的 AI 功能，**每次调用都按实际消耗从余额扣费，提交即扣、不可撤销**，调用前可先用 `console_balance` 查余额。生成类是异步的：`*_submit` 提交后返回任务标识，再用对应的 `*_status` 每 5~10 秒轮询一次。MCP 传不了本地文件，素材只能传公网 URL；要上传视频/图片文件（提取口播、视频详情、本地图片作参考）请用 [octohz CLI](/docs?doc=77)。

`console_product_video_submit` 支持 3 个模型 × 3 种模式，`mode` 必填：

| 模型 | 时长 | 分辨率 |
|---|---|---|
| `h3`（MiniMax H3，默认） | 5~15 秒 | 480P / 768P / 2K / 4K |
| `seedance2`（Seedance 2.0） | 4~15 秒 | 480p / 720p / 1080p |
| `seedance25`（Seedance 2.5） | 4~30 秒 | 480p / 720p |

`mode`：`text` 文生视频（只有提示词）；`image` 图生视频（`imageUrl` 首帧，可选 `endImageUrl` 尾帧）；`reference` 参考生视频（`imageUrls`/`videoUrls`/`audioUrls` 只作参考，**至少要有 1 张图或 1 段视频**，音频不能单独用）。提示词里引用参考图：H3 写 `Image 1`，Seedance 写 `@Image1`。时长或分辨率超出所选模型的范围会直接返回错误，不会自动改成默认值。

| Tool | 说明 | 必填参数 |
|---|---|---|
| `console_balance` | 查看工作台余额和今日消耗（元）。 | 无 |
| `console_meta_prompt` | 把视频分析报告转成分镜/视频生成提示词，按消耗扣费，不带参考图。 | `report`、`videoModel`（另有 2 个可选） |
| `console_history` | 列出口播 / 视频详情 / 元提示词的历史任务，每页 5 条。 | `kind`（另有 1 个可选） |
| `console_history_rm` | 删除口播 / 视频详情 / 元提示词的一条历史记录（只能删自己的，不可恢复）。 | `kind`、`id` |
| `console_product_video_submit` | 提交生视频任务（H3 / Seedance 2.0 / 2.5 × 文生 / 图生 / 参考生），提交即扣费。 | `prompt`、`mode`（另有 11 个可选） |
| `console_product_video_status` | 轮询带货视频任务，COMPLETED 时返回视频地址。 | `statusUrl`、`resultUrl` |
| `console_local_image_submit` | 提交本地（3090X2）文生图任务，**仅管理员**。可选社区工作流、一致性角色、多样性 LoRA，须与模型搭配（角色/`sda` 只配 `z-image-turbo`，`workflow` 只配 `krea2-moody-v8`），不匹配在扣费前报错；图片编辑要传本地图，只能用 CLI。 | `prompt`（另有 7 个可选） |
| `console_local_image_status` | 轮询本地生图任务，COMPLETED 时返回图片地址，**仅管理员**。 | `promptId`、`outputNodeId` |
| `console_local_video_submit` | 提交本地（3090X2）视频任务，**仅管理员**；MCP 只支持无需图片的模式（h3 纯文本，走 fl2va 权重；ltx25 的 t2v / hd），可选社区概念 LoRA（`communityLora`，须与模型家族对得上）；H3 的首帧/尾帧（fl2va）与参考图（ref2va）、Wan2.2 系、一致性角色都要传本地图片，只能用 CLI。 | `model`、`prompt`、`durationSec`（另有 2 个可选） |
| `console_local_video_status` | 轮询本地生视频任务，COMPLETED 时返回视频地址，**仅管理员**。 | `promptId`、`outputNodeId` |

### 智能互通（查看其他智能体，apiToken）

只读：列出你在智能互通网络里能联系的智能体，权限范围和 `/api/agent-hub/discover` 一致（自己的 + 被授权的，只看 active）。不发消息、不改授权；发消息要走本机 Bridge 的 `127.0.0.1:9911`，远程 MCP 够不到，请用 [octohz CLI / Agent Bridge](/docs?doc=77)。能力列表是对方自行声明的展示信息，不参与授权。

| Tool | 说明 | 必填参数 |
|---|---|---|
| `agent_list` | 列出可联系的智能体（agent_id、名称、类型、是否在线、能否访问、开放的操作范围），默认不带能力列表。 | 均可选（`onlineOnly`、`withCapabilities`） |
| `agent_get` | 按 agent_id 看一个智能体的完整信息：连接方式、Agent Card 地址、开放给你的操作范围。不含密钥。 | `agentId` |

## 调用示例

下面先给出一个完整请求模板。替换 `name` 和 `arguments` 即可调用其他工具；公开工具或只使用 `privateKey` 的工具可以省略 `Authorization` header。

```bash
curl -s -X POST https://octohz.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your-apiToken>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "project_onboard", "arguments": { "id": 1, "brief": true } }
  }'
```

### 常用 `params`

接手项目：

```json
{ "name": "project_onboard", "arguments": { "id": 1, "brief": true } }
```

认领任务并在完成后写入交接记录：

```json
{ "name": "project_task_claim", "arguments": { "id": 1, "ref": "T003", "owner": "my-agent" } }
{ "name": "project_task_done", "arguments": { "id": 1, "ref": "T003", "note": "接入了七牛云 CDN 并验证" } }
```

按 IP 查找主机凭据（`privateKey` 是参数，不是 Authorization header）：

```json
{ "name": "host_find", "arguments": { "privateKey": "<your-privateKey>", "ip": "192.168.1.50", "reveal": true } }
```

发布带封面的内容；先用 `category_list` 查询分类：

```json
{
  "name": "submit_post",
  "arguments": {
    "name": "标题",
    "intro": "一句话简介",
    "description": "正文，支持 Markdown",
    "category": "software",
    "buyText": "https://example.com",
    "imageUrl": "https://example.com/cover.png"
  }
}
```

读取完整八字排盘：

```json
{ "name": "bazi_get", "arguments": { "id": 1 } }
```

新增资源并让服务端抓取文件：

```json
{
  "name": "resource_add",
  "arguments": {
    "title": "标题",
    "summary": "一句话摘要",
    "fileUrl": "https://example.com/package.zip"
  }
}
```

## 返回格式

所有 tool 都返回标准 MCP `content` 数组，正文是 `JSON.stringify` 后的字符串；失败时 `isError: true`，`content[0].text` 是可读的中文错误说明（未授权 / 不存在 / 校验失败 / 额度用完等）。

## 下一步

- [我的项目 API](https://octohz.com/docs?doc=68) —— REST 接口细节，MCP tool 底层调用的就是这套逻辑
- [OctoHz CLI 快速上手](https://octohz.com/docs?doc=82) —— 包含依赖本地仓库文件的 `sync` 工作流
- [OctoHz 智能体使用指南](https://octohz.com/docs?doc=61) —— Agent 接入总览


---

**分类**：OctoHz MCP
**链接**：https://octohz.com/docs?doc=84