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"
      }
    }
  }
}

在 shell 中，chorus mcp call <tool> 命令可用同一份智能体凭据调用上述任意工具，适合脚本与一次性调用，且无需消耗模型 token。参见 chorus 命令行工具。

注意

MCP 传输会话与 Chorus 的智能体会话无关。智能体会话用于追踪蜂群模式下的子智能体，让你能看到它们的工作， 通过下文的会话工具创建与管理。

按项目过滤范围

跨多个项目工作的智能体，可以在 MCP 连接上发送范围请求头，把结果限定在 某些项目内：

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

chorus_get_my_assignments 按范围请求头过滤结果。不带请求头时覆盖可访问项目，同时设置时 X-Chorus-Project-Group 优先。chorus_checkin 不按这些请求头过滤：它的 activeProjects 分布不受过滤（也不是近期想法列表），请求头选中的项目只会额外加入它的 projectTeams。其他工具使用各自显式的范围参数，这些请求头不是通用项目访问过滤器。

{
  "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）

可见不等于有权操作。一个工具可能可见，却仍在执行时拒绝某项操作，例如任务的执行状态 转换要求调用者是该任务的负责人，与谁能看到这个工具无关。

项目访问权限

权限位决定智能体拥有哪些工具，项目访问权限决定它能在哪里使用这些工具。智能体以其所有者对每个 项目的访问权限行事（参阅控制谁能看到项目）；没有所有者的智能体只能 使用公开项目。每次调用都会同时执行这两项检查。

• 隐藏即不存在。所有者无权访问的私有项目，以及其中的每个想法、提案、文档、任务和评论，都不会 出现在列表和搜索结果中，并且返回的“未找到”错误与查询不存在的 ID 时完全相同。
• 角色过低即禁止。当所有者的角色过低时（例如查看者执行写操作，或编辑者在私有项目中执行仅限管理员的操作）， 调用会以禁止访问错误失败；读操作仍然可用。在所有者的角色改变之前，重试也无济于事。
• chorus_get_project 会报告项目的 visibility 以及调用者的 accessLevel （viewer、editor 或 admin）。
• chorus_admin_create_project 和 chorus_admin_create_project_group 接受 visibility （public 或 private）。所有者会成为所创建对象的管理员。在私有项目组中创建的项目是私有的。
• chorus_admin_update_project_group 可以更改项目组的 visibility，并一次管理一位显式项目组成员 （memberAction：add、update 或 remove，配合 userUuid 和 role）。 chorus_admin_move_project_to_group 用于移动项目或将其移出分组。更改项目组的 visibility 或移动项目时， 请先以 preview: true 调用该工具，获取访问权限变化和一个 confirmationToken，再携带该令牌重复同样 的更改。成员变更会直接生效，无需预览。
• 更改项目组的可见性或成员，要求所有者是项目组管理员。移动私有项目、移入或移出私有项目组，或会扩大任何人 访问权限的移动，需要管理员角色；其他移动需要编辑者角色。
• chorus_search_mentionables 接受可选的 entityType 和 entityUuid。从想法、提案、文档或任务中 发起提及时传入它们，就只会推荐能看到该实体的人。
• 项目成员以及已有项目的可见性在 Web 界面中管理；没有对应的 MCP 工具。

工具类别

类别	门控	涵盖内容
公共（Public）	无，始终可见	发现与读取（chorus_get_*、chorus_list_*、chorus_search*）、chorus_checkin、chorus_get_my_assignments、评论、细化回答、通知，以及 chorus_create_tasks 和 chorus_update_task。
会话（Session）	无，始终可见	面向蜂群模式子智能体的智能体会话生命周期：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_report 看起来像公共工具（它没有 pm_ 前缀）， 但它受 document:write 门控。只有持有该权限位的智能体才会看到它（pm_agent / admin_agent 预设，或添加了 document:write 自定义权限的开发者智能体）。不要把它当作 未门控的公共工具。

chorus_create_tasks 与 chorus_update_task 是真正的公共工具：任何智能体都可以编辑任务的字段、 依赖与验收标准，但只有任务负责人才能把任务转为 in_progress 或 to_verify。

高频工具

以下是具有代表性的一部分工具，附带输入、返回结构与所需权限。每个工具的完整契约，参见本页末尾的 说明。

chorus_checkin（公共）

概览最多包含 10 个项目，按各项目最近更新的活跃想法排序。每个已列项目的活跃想法计数不截断；完整跟踪列表请使用 chorus_get_my_assignments。

返回身份、所有者、有效权限、角色设定及 activeProjects：项目 UUID 对应名称和 activeIdeaCount。计数是未截断的活跃想法总数，不包含逐条想法或任务。最多返回五条近期未读通知并自动标为已读，notifications.unread 是标记后的剩余未读数。范围请求头不会缩小该分布。

projectTeams 把每个项目 UUID 映射到所有者在该项目上的智能体团队，没有团队时为 null。 它覆盖 activeProjects 中的项目，以及范围请求头选中的项目；没有所有者或没有 project:read 权限的智能体得到 {}。其他项目请使用 chorus_get_project_team。

{ checkinTime, agent: { uuid, name, permissions, persona, systemPrompt, owner },
  activeProjects: { <projectUuid>: { name, activeIdeaCount } },
  projectTeams: { <projectUuid>: ProjectTeam | null },
  notifications: { unread, recent[] } }

chorus_get_my_assignments（公共）

返回按项目分组的完整活跃想法/任务追踪器，遵循范围请求头。ideaTracker 包含逐条想法的派生状态及提案/任务计数；taskTracker 包含未进入终态的任务及验收进度。需要完整列表时使用它，而非 activeProjects。

{ ideaTracker: { <projectUuid>: { name, ideas[] } },
  taskTracker: { <projectUuid>: { name, tasks[] } } }

将快速任务关联到想法

快速任务（不带 proposalUuid 创建的任务）可以直接关联到同一项目中的一个想法。此后，想法的派生状态会把这个任务与已批准提案的任务一起计算。主题想法会被拒绝；一个任务也不能同时带有 proposalUuid 和 ideaUuid，提案任务通过提案归属到它的想法。关联不会改变想法存储的状态。

设置关联是公共的：chorus_create_tasks 和 chorus_update_task 不受权限限制（需要项目编辑者权限）。读取关联则受权限限制：chorus_list_tasks 和 chorus_get_task 需要 task:read，chorus_get_idea 需要 idea:read。

• chorus_create_tasks 在快速任务模式下接受可选的顶层 ideaUuid，把整批任务都关联到该想法。它与 proposalUuid 同时传入时会被拒绝；关联无效时整个调用被拒绝；把 ideaUuid 写在 tasks[] 的单个条目里会报校验错误。
• chorus_update_task 接受 ideaUuid: string | null：传想法 UUID 可设置或更改关联，传 null 清除关联，省略则保持不变。对提案任务会被拒绝。
• chorus_list_tasks 接受可选的 ideaUuid 筛选，只返回关联到该想法的快速任务。结果不包含该想法的提案任务，提案任务请用 proposalUuids 列出。
• chorus_get_task 及其他任务返回值都带 ideaUuid（未关联时为 null，提案任务始终为 null）。
• chorus_get_idea 返回服务端计算的 derivedStatus（todo、in_progress、human_conduct_required 或 done）和 badgeHint（例如 building、verify_work 或 done）。它与看板使用同一规则，基于已批准提案的任务加上关联的快速任务；主题则由其子想法汇总。

chorus_create_tasks  Input: { projectUuid, ideaUuid?, tasks[] }        // no proposalUuid
chorus_update_task   Input: { taskUuid, ideaUuid?: string | null, ... }
chorus_list_tasks    Input: { projectUuid, ideaUuid?, status?, priority?, proposalUuids?, page?, pageSize? }

chorus_claim_task（task:write）

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

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

chorus_submit_for_verify（task:write，仅负责人）

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

输入：{ taskUuid, summary? }
返回： { uuid, status: "to_verify" }

先用不带 status 的 chorus_report_work 汇报完成，再记录 chorus_report_criteria_self_check，然后用 chorus_get_task 回读并确认 in_progress，最后显式提交。先汇报 status: "to_verify" 会导致提交失败。误改后退回 in_progress 会清空开发侧与管理侧的验收标记及依据，提交前必须重做自检。不要重开已经正常提交的任务。参阅运行任务。

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?, kind?,
       acceptanceCriteriaItems: [{ description, required? }],  // 必需，非空
       dependsOnDraftUuids?[] }
返回：更新后的 Proposal

提案校验与草稿类型

chorus_pm_add_task_draft 和 chorus_pm_update_task_draft 接受可选 kind：implementation、verification、docs 或 other。编辑后先调用 chorus_pm_validate_proposal，再调用 chorus_pm_submit_proposal；提交时服务器会再次校验。结果为 { valid, issues[] }，级别有 error、warning、info。只有错误才使 valid 为 false。

• E-DEP-UNKNOWN：依赖不在本提案的任务草稿内。
• E-DEP-SELF：依赖自身。
• E-DEP-CYCLE：依赖形成环。
• I-KIND：没有声明类型，无法检查实现覆盖。
• W-IMPL：有类型声明，但没有 implementation。仅为建议，应说明已有实现覆盖或纯文档范围，不要虚构工作。无依赖警告（W4）也只是建议。

可选的 Pi 检查只追踪本地回读/校验顺序，不是服务器授权。参阅评审提案。

chorus_admin_verify_task（task:admin）

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

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

智能体团队工具

这些工具让智能体读取并使用其所有者的个人智能体团队。团队不授予任何权限，也从不自行分配工作； 每次调用仍按智能体的权限和其所有者的项目访问权进行检查。智能体不能修改团队，也不能确认想法交接：绑定、按角色覆盖、 解除绑定和交接都在网页界面中完成。

当想法的所有者（人）在为项目绑定团队之后，把它分配给自己的某个智能体时，或该智能体在由团队管理的想法下分配派生想法时， 该想法就由团队管理。该负责人统筹这个想法，不需要担任负责人角色。生命周期交接（提案提交或批准、任务提交验证）会通知统筹者， 统筹者每次被唤醒时都应重新读取该想法的团队上下文。

chorus_get_project_team（project:read）

读取调用方智能体的所有者在某个项目上的团队。至少需要该项目的查看者权限。所有者在该项目上没有团队，或智能体没有所有者时， 返回 { team: null }；永远不会返回其他用户的团队。

Input:  { projectUuid }
Return: { team: { projectUuid, templateUuid, templateName, frozen, revision,
                  overrides, roles: { product[], development[], review[], lead[] },
                  myRoles[], handoffWarning } | null }

每个角色成员都带有 agentUuid、agentName、eligible、missingPermissions[]、hasProjectAccess、online 和 activeCount。 离线成员仍可能满足资格。overrides 列出整个角色的替换；设为 [] 的角色是刻意留空的。frozen 表示模板已删除、保留了最后的成员。 myRoles 只列出调用方满足资格的角色。

chorus_get_idea_team_context（idea:read）

读取一个想法是否由团队管理，以及由谁统筹。state 为 active、paused（统筹者失去资格）或 unmanaged。 人用 Yolo 启动该想法时 yolo 为 true，它只决定提案批准是否需要人。routing（所有者、产品被委派者和团队角色） 只返回给团队所有者及其智能体。

Input:  { ideaUuid }
Return: { ideaUuid, managed, state, reason, orchestrator, yolo, routing }

chorus_recommend_team_agent（idea:read）

根据实时的资格、在线状态、负载和亲和性，为由团队管理的想法推荐一名 product、development 或 review 成员。 它不分配也不唤醒任何人。decision 为 recommended、lead_decision（候选不分上下，由统筹者在 candidates 中决定）、 manual（想法未由团队管理，或产品、开发工作没有可用成员）或 paused。

Input:  { ideaUuid, role: "product" | "development" | "review",
          taskUuid?, proposalUuid? }          // at most one target
Return: { decision, agentUuid, candidates[], reason }

对于 review，taskUuid 选择任务评审，proposalUuid 选择提案评审，两者都不传则是整个想法的评审。优先满足资格且在线的评审者， 其次是该目标最近一次结论的评审者，再次是最空闲的成员。没有人被排除在外。没有满足资格且在线的评审者时，它推荐统筹者本身， 由统筹者运行自己的评审子智能体，因此评审永远不会落到手动处理。

chorus_delegate_team_product（idea:write）

统筹者（或团队所有者）把细化和撰写提案委派给一名满足资格的产品成员，并 @提及它。被委派者可以开始细化，并创建和提交该想法的提案； 它不能认领、释放或重新分配该想法，也不能确认细化完成、批准或验证。重新分配想法会结束委派。

Input:  { ideaUuid, agentUuid }
Return: the updated Idea Team context

chorus_request_review（公共，需项目编辑者权限）

向一名评审者发送团队评审请求。Chorus 会在目标上发布一条评审请求评论，注明轮次、提及评审者，并说明结果交给谁： 通过时交给想法的统筹者，任务未通过时交给其开发者，提案未通过时交给产品被委派者，没有则交给统筹者。只有该评审者会被唤醒， 并在单独的评审对话中进行；对同一目标的再次评审会接续该对话。普通评论从不启动评审。评审者必须是另一个能访问该项目的智能体， 且想法（对于任务，还有该任务）必须有一个智能体负责人来接收结果；否则调用会被拒绝，不发布任何内容。如果评审者离线或无法被唤醒， 评审请求评论会被发布，但评审不会开始，调用返回错误；请在评审者在线后重试。

Input:  { targetType: "task" | "proposal" | "idea", targetUuid,
          reviewerUuid, round: 1-3, note? }
Return: { commentUuid, targetType, targetUuid, reviewerUuid, round, sessionId, turnUuid }

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

每个受权限门控的工具及其单一所需权限位。持有该权限位（通过预设或自定义权限）是该工具出现的 必要条件；工具执行时仍可能校验所有权、负责人或状态。

所需权限	工具
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、chorus_delegate_team_product
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

注意

权威、完整的工具列表，是运行中服务器自身的 tools/list 响应（每个工具的实时自描述）。 本页是对这套工具的分类指南，而非对每个工具逐字节的转录。当某个自描述与本页不一致时，以服务器为准。