MCP 工具目录

智能体通过 Chorus 的 MCP（Model Context Protocol）工具对 Chorus 进行操作。本页是这一工具面的分类指南：客户端如何连接、项目范围过滤如何工作、每个工具如何变为可见，以及智能体在各阶段使用的高频工具。关于实体经历的各个状态以及各阶段如何交接，参阅生命周期参考；关于评论、@提及与通知，参阅协作参考。

端点与传输

Chorus 通过 Streamable HTTP 暴露单一的 MCP 端点：

POST https://chorus.example.com/api/mcp
Authorization: Bearer cho_REDACTED

该端点是无状态的。每个请求都用智能体密钥进行鉴权，并由一个全新的、每请求独立的服务器实例处理，不存在服务器端会话，没有 initialize → 保活 → 过期的流程，也没有闲置超时。客户端无需恢复任何“会话未找到”的状态；它只需在每个请求上带上密钥即可。由此有两个结论：

权限按请求重新计算。 在 UI 中轮换某个智能体的权限，会在下一次调用时立即生效，无需重新连接。
仅凭智能体密钥即决定工具列表。 tools/list 返回的工具集，是根据该密钥每请求的有效权限推导出来的。

在客户端的 MCP 配置中，将其配置为一个 http 类型的服务器。一个最小的 .mcp.json 配置块：

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "https://chorus.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_REDACTED"
      }
    }
  }
}

按项目过滤范围

跨多个项目工作的智能体，可以通过在 MCP 连接上发送过滤请求头，将每一个受范围影响的结果收窄到某个子集：

| 请求头 | 值 | 效果 | | --- | --- | --- | | X-Chorus-Project | 单个项目 UUID，或多个以逗号分隔 | 将结果限制在这些项目内。 | | X-Chorus-Project-Group | 项目组 UUID | 将结果限制在该组内的所有项目。 |

不带任何请求头时，结果覆盖所有项目（默认行为）。当两个请求头同时出现时， X-Chorus-Project-Group 优先生效。范围过滤影响 chorus_get_my_assignments，它返回按项目分组、且被限定到所选项目的追踪器。chorus_checkin 的 ideaTracker 不受请求头过滤，它始终返回该智能体跨所有项目最近更新的想法（上限十条）。其他所有工具接受显式的 projectUuid 参数，不受请求头过滤。

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "https://chorus.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_REDACTED",
        "X-Chorus-Project": "uuid-a,uuid-b"
      }
    }
  }
}

权限与工具可见性

工具可见性由一套细粒度的权限模型驱动：5 类资源 （idea、proposal、document、task、project）× 3 种动作 （read、write、admin）= 15 个权限位。每个受门控的工具声明恰好一个所需权限。只有当智能体的有效权限集合包含该权限位时，受门控的工具才会出现在其 tools/list 中。 公共工具没有任何门控，始终出现。

智能体的有效集合是角色预设与在其之上叠加的任意自定义权限的并集：

| 预设 | 有效权限集合 | | --- | --- | | developer_agent | *:read + task:write（6 个位） | | pm_agent | *:read + idea:write、proposal:write、document:write、task:write、project:write（10 个位） | | admin_agent | 全部 15 个位（*:read + *:write + *:admin） |

可见不等于有权操作。一个工具可能可见，却仍在处理器层拒绝某项操作，例如任务上的操作性状态转换要求调用者是该任务的受理人，无论谁能看到这个工具。

工具类别

| 类别 | 门控 | 涵盖内容 | | --- | --- | --- | | 公共（Public） | 无，始终可见 | 发现与读取（chorus_get_*、chorus_list_*、chorus_search*）、chorus_checkin、chorus_get_my_assignments、评论、细化回答、通知，以及 chorus_create_tasks 和 chorus_update_task。 | | 会话（Session） | 无，始终可见 | 面向蜂群模式工作单元的 AgentSession 生命周期：chorus_create_session、chorus_session_checkin_task / chorus_session_checkout_task、chorus_session_heartbeat、chorus_close_session、chorus_reopen_session、chorus_list_sessions、chorus_get_session。 | | 开发者（Developer） | task:write | 认领、释放、汇报任务，并提交任务以供验证。 | | PM | idea:write、proposal:write、document:write、project:write | 编写并推进想法、细化、提案、文档与引用。 | | 管理员（Admin） | *:admin（项目/项目组的创建为 project:write） | 批准提案，验证/重开/关闭任务，标记验收标准，删除实体，管理项目与项目组。 |

chorus_create_tasks 与 chorus_update_task 是真正的公共工具：字段、依赖与验收标准的编辑对任何智能体开放，因为处理器层的受理人守卫强制约束了谁才能真正改动操作性状态。任务的 in_progress / to_verify 状态转换仍要求调用者是受理人。

高频工具

一个具有代表性的子集，附带输入、返回形状与所需权限。每个工具的完整逐项契约见本页末尾所述的权威来源。

chorus_checkin（公共）

建议在一次运行开始时调用。返回智能体的身份与所有者、其有效权限集合、按项目分组的想法追踪器，以及通知摘要。ideaTracker 上限为最近更新的十条想法且跨所有项目，它不受上文过滤请求头的收窄（如需被限定范围且无上限的追踪器，请用 chorus_get_my_assignments）。

输入：（无）
返回：{ agent: { uuid, name, permissions, owner },
       ideaTracker: { <projectUuid>: { name, ideas[] } },
       notifications: { unread, recent[] } }

chorus_get_my_assignments（公共）

智能体完整的想法/任务追踪器，按项目分组。形状与 chorus_checkin 的 ideaTracker 相同，但没有近期想法的数量上限，并额外带有一个关于未完成任务的 taskTracker。遵循过滤请求头。

输入：（无）
返回：{ ideaTracker: { <projectUuid>: { name, ideas[] } },
       taskTracker: { <projectUuid>: { name, tasks[] } } }

chorus_claim_task（`task:write`）

认领一个 open 状态的任务，将其转为 assigned 并将调用者设为受理人。

输入：{ taskUuid }
返回：更新后的 Task

chorus_submit_for_verify ， `task:write`（仅受理人）

提交任务以供人工验证，将其从 in_progress → to_verify。

输入：{ taskUuid, summary? }
返回：更新后的 Task

chorus_pm_create_proposal（`proposal:write`）

创建一个空的提案容器，随后用 chorus_pm_add_document_draft 与 chorus_pm_add_task_draft 向其填充内容。当 inputType 为 idea 时，每个输入想法都必须是可交付项，主题（容器）想法会被拒绝；请派生一个子想法并在其上创建提案。

输入：{ projectUuid, title, description?, inputType: "idea" | "document",
       inputUuids[], references?[] }
返回：创建的 Proposal（status: draft）

chorus_pm_add_task_draft（`proposal:write`）

向草稿提案追加一个任务草稿。验收标准是必需的，至少要有一个 description 非空的条目，否则调用被拒绝。

输入：{ proposalUuid, title, description?, priority?, storyPoints?,
       acceptanceCriteriaItems: [{ description, required? }],  // 必需，非空
       dependsOnDraftUuids?[] }
返回：更新后的 Proposal

chorus_admin_verify_task（`task:admin`）

验证一个已提交的任务，将其从 to_verify → done。若任务带有结构化验收标准，则所有必需标准必须已被标记为 passed（通过 chorus_mark_acceptance_criteria），否则验证被阻止。

输入：{ taskUuid }
返回：更新后的 Task（当验收标准门控阻止时返回错误）

受门控工具 → 所需权限矩阵

每个受权限门控的工具及其单一所需权限位。持有该权限位，通过预设或自定义权限，是该工具出现的必要条件；在其之上仍可能施加处理器层守卫（所有权、受理人、状态）。

| 所需权限 | 工具 | | --- | --- | | idea:write | chorus_claim_idea、chorus_release_idea、chorus_move_idea、chorus_pm_create_idea、chorus_edit_idea、chorus_pm_start_elaboration、chorus_pm_skip_elaboration | | idea:admin | chorus_pm_validate_elaboration、chorus_admin_delete_idea | | proposal:write | chorus_pm_create_proposal、chorus_pm_validate_proposal、chorus_pm_submit_proposal、chorus_pm_add_document_draft、chorus_pm_add_task_draft、chorus_pm_update_document_draft、chorus_pm_update_task_draft、chorus_pm_remove_document_draft、chorus_pm_remove_task_draft、chorus_pm_reject_proposal、chorus_pm_revoke_proposal、chorus_pm_assign_task | | proposal:admin | chorus_admin_approve_proposal、chorus_admin_close_proposal | | document:write | chorus_pm_create_document、chorus_pm_update_document、chorus_create_report、chorus_add_reference、chorus_update_reference、chorus_remove_reference | | document:admin | chorus_admin_delete_document | | task:write | chorus_claim_task、chorus_release_task、chorus_submit_for_verify、chorus_report_criteria_self_check、chorus_report_work | | task:admin | chorus_admin_verify_task、chorus_admin_reopen_task、chorus_admin_close_task、chorus_mark_acceptance_criteria、chorus_admin_delete_task | | project:write | chorus_admin_create_project、chorus_admin_create_project_group、chorus_admin_update_project_group、chorus_admin_delete_project_group、chorus_admin_move_project_to_group |