FCoP MCP 工具清单（fcop-mcp 3.x）<!-- 45 tools
May 27, 2026 · View on GitHub
本页是
fcop-mcp暴露给 Cursor / Claude Desktop 等 MCP 客户端的工具索引。权威说明仍在源码 docstring（mcp/src/fcop_mcp/server.py）；本页是导航与速查，按类别分组。稳定承诺：整个
3.x周期工具「只增不改」。新增工具/参数允许；改名、删除、改语义不允许。
总览
工具（tools）共 45 个，按 Tier 分级：
| Tier | 含义 | 工具数 |
|---|---|---|
| L0 | 只读/查询，无写盘 | 若干 |
| L1 | 写盘操作，需绑定角色（binding_required） | 大多数 |
v3 新增（相对 v2/v1.x）：
- v3 任务生命周期（5 个）：
claim_task/submit_task/finish_task/approve_task/reject_task - 历史深档案（4 个）：
archive_to_history/bulk_archive_to_history/list_history/read_history_task - v3 spec 对齐（1 个）：
create_task（write_task的 v3 规范别名）
1. 起手式（每次新会话先调）
| 工具 | 何时调 | 关键参数 |
|---|---|---|
fcop_report | 每个新 MCP 会话的第一个调用（FCoP Rule 0）。返回项目状态；未初始化时给出三选一初始化建议；已初始化但本会话未认领角色时输出 UNBOUND 报告。报告头部含版本比对，漂移时提示 redeploy_rules。 | lang（zh/en） |
set_project_dir | MCP 把项目根定位错了，不改 mcp.json、不重启 Cursor 就能切换。 | path（绝对路径） |
fcop_check | 日常轻量自检：schema 合规、文件名一致性、frontmatter 完整性，含治理事件日志摘要。不写盘。 | lang |
2. 项目初始化（三选一）
| 工具 | 用途 | 关键参数 |
|---|---|---|
init_project | 用预设团队模板初始化：dev-team / media-team / mvp-team / qa-team。建立 fcop/ 五目录 + history/，写 fcop.json，部署三层文档。幂等。 | team（默认 dev-team）、lang |
init_solo | Solo 模式：单 AI 角色直接对 ADMIN，不做派发。 | role_code（默认 ME）、role_label、lang |
create_custom_team | 自定义角色初始化。强烈建议先 validate_team_config 干跑。 | team_name、roles（逗号分隔）、leader、lang |
validate_team_config | 不写盘地校验自定义团队配置。 | roles、leader |
get_available_teams | 列出仓库内置团队及其 leader / 成员。 | lang |
3. 任务创建与查询
任务文件命名：TASK-YYYYMMDD-NNN-{SENDER}-to-{RECIPIENT}.md
v3 项目任务落在 _lifecycle/ 各阶段目录；v2 项目落在 fcop/tasks/。
| 工具 | 用途 | 关键参数 |
|---|---|---|
create_task | v3 规范 §8 L1 入口：创建任务，v3 项目落入 _lifecycle/inbox/，v2 落入 fcop/tasks/。与 write_task 功能完全相同，命名符合 spec。 | sender、recipient、subject、body、priority（P0–P3）、thread_key、references、risk_level |
write_task | 同 create_task（v2 兼容名称，长期维护）。 | 同上 |
read_task | 读任务全文（含各阶段目录）。 | filename（文件名或 TASK-…-NNN） |
list_tasks | 按发件人 / 收件人 / 状态 / 日期过滤，带分页。 | sender、recipient、status、date、limit、offset |
inspect_task | 离线校验 schema 与「文件名↔frontmatter」一致性，不写盘。 | filename |
archive_task | 把 done/ 里的已完成任务（含同名报告）搬到 _lifecycle/archive/（v3）或 fcop/log/（v2）。 | task_id |
risk_level：high/irreversible的任务按 ADR-0024 应配套write_review(decision="needs_human")，由 ADMIN 用mark_human_approved闭合审批链。
4. v3 任务生命周期流转
仅 v3 项目有效；v2 项目调用这些工具会返回提示性 no-op 消息。
v3 任务在 _lifecycle/ 下按阶段流转：
inbox → active → review → done → archive → history/YYYY-MM-DD/<stem>/
↘ (直接完成，无需审核) ↗
| 工具 | 阶段流转 | 关键参数 |
|---|---|---|
claim_task | inbox → active：agent 领取任务，开始执行。 | task_id、actor（领取者角色码） |
submit_task | active → review：agent 提交工作，等待审核。 | task_id、actor |
finish_task | active → done：agent 直接完成（无需审核路径）。 | task_id、actor |
approve_task | review → done：ADMIN/治理角色审核通过。 | task_id、actor（默认 ADMIN）、note |
reject_task | review → active：ADMIN 打回重做，task 退回 active 阶段供修改。 | task_id、actor、note（建议写明原因） |
5. 报告流（reports/）
| 工具 | 用途 | 关键参数 |
|---|---|---|
write_report | 写完成报告，回到指定收件人（通常是 leader/PM）。 | task_id、reporter、recipient、body、status（done/in_progress/blocked）、priority |
list_reports | 过滤列出。 | reporter、task_id、status、limit、offset |
read_report | 读报告全文。 | filename（或对应 task_id） |
6. 问题流（issues/）
| 工具 | 用途 | 关键参数 |
|---|---|---|
write_issue | 上报问题：阻塞、规则不清、外部故障等。 | reporter、summary、body、severity（critical/high/medium/low，亦支持 P0–P3） |
list_issues | 过滤列出。 | reporter、severity、limit、offset |
7. 审核流（reviews/）
REVIEW 文件是治理层对制品的决策记录（ADR-0017）。
| 工具 | 用途 | 关键参数 |
|---|---|---|
write_review | 写一份 REVIEW（治理层决策）。 | reviewer_role、subject_type（task/report/role_switch/code_change）、subject_ref、decision（见下表）、rationale、required_changes（needs_changes 时必填）、reviewer_agent、body、subject_short |
list_reviews | 过滤列出，标注 [human_approval pending] / [human_approved]。 | reviewer_role、decision、subject_type、status（open/archived/all）、limit、offset |
read_review | 读 REVIEW 全文，含 human_approval 子结构展示。 | filename（文件名或 Review ID） |
mark_human_approved | 关闭 needs_human 升级回路（ADR-0026）。把 human_approval 事件写入已有 REVIEW frontmatter。approver 必须是 layer: admin 的角色。 | review_id、approver、decision（approve/reject）、channel、comment |
decision 枚举（5 值）：
| 值 | 含义 |
|---|---|
approved | 制品通过，可以继续 |
rejected | 制品被否决，不得继续 |
needs_changes | 需要修改（必须配 required_changes） |
abstained | 审核者回避 |
needs_human | agent 主动上升人工——REVIEW 停留 pending，ADMIN 需调 mark_human_approved 闭合 |
8. 历史深档案（history/）— v3 新增
仅 v3 项目有效。历史档案按日期分片存储在
history/YYYY-MM-DD/<task-stem>/，永不覆盖，适合长期回溯。
典型归档流程（v3）：
finish_task / approve_task
↓
_lifecycle/done/
↓ archive_task
_lifecycle/archive/
↓ archive_to_history（单个）或 bulk_archive_to_history（批量）
history/2026-05-22/TASK-20260522-001-ME-to-ADMIN/
├── TASK-20260522-001-ME-to-ADMIN.md
└── REPORT-20260522-001-ME-to-ADMIN.md
| 工具 | 用途 | 关键参数 |
|---|---|---|
archive_to_history | 把单个任务（及其关联报告）从 _lifecycle/archive/ 移入 history/YYYY-MM-DD/<stem>/。先调 archive_task，再调本工具。 | task_id、done_date（覆盖日期分片，默认使用任务自身 done_at） |
bulk_archive_to_history | 把 _lifecycle/archive/ 里所有任务批量迁入历史档案。一次性迁移利器，适合升级后批量整理旧归档。 | done_date（为所有任务统一覆盖日期，留空则各自读 done_at） |
list_history | 列出历史档案。不传 date 时列所有日期分片（最新在前）；传 date 时列该分片下所有任务。 | date（YYYY-MM-DD，可选） |
read_history_task | 从历史档案读取指定任务全文。传 date 可限定分片范围，速度更快。 | task_id、date（可选） |
9. 团队 / 共享文档 / 工作区
| 工具 | 用途 | 关键参数 |
|---|---|---|
get_team_status | 项目状态快照：初始化状态、团队/leader、open task/report/issue/review 数、最近活动。 | lang |
deploy_role_templates | 部署 / 刷新 fcop/shared/ 里的团队文档与角色档案。force=True 时先归档再覆盖。 | team、lang、force（默认 True） |
new_workspace | 在 workspace/<slug>/ 下建工作目录，不要把代码写到项目根。幂等。 | slug（^[a-z][a-z0-9-]*$、≤ 40）、title、description |
list_workspaces | 列出现有 workspace/<slug>/。 | lang |
10. 协议泄压阀
| 工具 | 用途 | 关键参数 |
|---|---|---|
drop_suggestion | 唯一让 agent 对协议提反对意见的合法通道：写一份带时间戳的 markdown 到 .fcop/proposals/。禁止自己改 fcop-rules.mdc。 | content、context |
11. 维护（自检与升级）
| 工具 | 用途 | 关键参数 |
|---|---|---|
check_update | 比对本地 fcop-mcp 与 PyPI 最新版（不写盘、不安装）。 | lang |
upgrade_fcop | 打印针对你的安装方式的升级命令。不自动跑 pip。 | lang |
redeploy_rules | ADMIN-only。把 wheel 里四份规则文件写到项目根；force=True 覆写，archive=True 先归档旧文件。何时调：fcop_report 显示版本漂移。 | force（默认 True）、archive（默认 True）、lang |
12. 治理事件审计
基于 ADR-0030-bis Layer 1 MCP Middleware。每个工具调用自动打
risk标签并写入fcop_events.jsonl。
| 工具 | 用途 | 关键参数 |
|---|---|---|
list_governance_events | 读取 fcop_events.jsonl，列出最近 N 条治理事件（tool / risk / tag / session_id / 时间戳）。 | last_n（默认 50）、risk（过滤）、tag（过滤） |
get_governance_summary | 汇总统计：总调用量 / 各风险层分布 / Top 10 工具 / CRITICAL_TAG 事件清单。 | 无 |
13. 治理告警（GAL — ADR-0031）
fcop_check()自动扫描治理漂移信号，命中则写入fcop/alerts/ALERT-*.md。
| 工具 | 用途 | 关键参数 |
|---|---|---|
fcop_list_alerts | 读取告警收件箱，支持按 status / severity 过滤。 | status（open/acknowledged/resolved）、severity、last_n（默认 20） |
fcop_create_alert | ADMIN / 治理观察者手动归档治理缺口。 | severity、alert_type、summary、suggestion |
告警类型：
| 类型 | 触发条件 | 严重度 |
|---|---|---|
critical_tool_unreviewed | 24h 内有 CRITICAL_TAG 工具调用，但无对应 Review 文件 | high |
missing_independent_verdict | 执行窗口 > 6h 无任何治理事件（Solo Blindspot，FCoP-Rule-G1） | high |
long_running_without_reconciliation | open Task 超 24h 未归档 | low |
FCoP-Rule-G1：write_report / fcop_report ∈ 执行域，不构成治理信号。只有 write_review / mark_human_approved / fcop_check 才算独立治理视角。
14. 协议体检（fcop_audit）
一次性深度体检；
fcop_check是日常轻量自检，二者互补。
| 工具 | 用途 | 关键参数 |
|---|---|---|
fcop_audit | 三场景协议体检，发现 6 类合规盲区，产出 INSPECTION 报告（含 Execution Block 整改建议）。 | scope（new/upgrade/takeover/auto，默认 auto）、output（file/stdout/both）、project_path |
三场景：
| 场景 | 触发条件 | 扫描内容 |
|---|---|---|
new | 新项目验收 | 协议文件是否完整部署 |
upgrade | 版本升级后验收 | 规则/文档版本是否同步 |
takeover | 老 non-fcop 项目首次引入 | 全量扫描（6 类盲区） |
附录：工具完整列表（45 个）
| # | 工具 | 分类 | Tier |
|---|---|---|---|
| 1 | fcop_report | 起手式 | L0 |
| 2 | set_project_dir | 起手式 | L1 |
| 3 | fcop_check | 起手式 | L0 |
| 4 | init_project | 初始化 | L1 |
| 5 | init_solo | 初始化 | L1 |
| 6 | create_custom_team | 初始化 | L1 |
| 7 | validate_team_config | 初始化 | L0 |
| 8 | get_available_teams | 初始化 | L0 |
| 9 | create_task | 任务 | L1 |
| 10 | write_task | 任务 | L1 |
| 11 | read_task | 任务 | L0 |
| 12 | list_tasks | 任务 | L0 |
| 13 | inspect_task | 任务 | L0 |
| 14 | archive_task | 任务 | L1 |
| 15 | claim_task | v3 生命周期 | L1 |
| 16 | submit_task | v3 生命周期 | L1 |
| 17 | finish_task | v3 生命周期 | L1 |
| 18 | approve_task | v3 生命周期 | L1 |
| 19 | reject_task | v3 生命周期 | L1 |
| 20 | write_report | 报告 | L1 |
| 21 | list_reports | 报告 | L0 |
| 22 | read_report | 报告 | L0 |
| 23 | write_issue | 问题 | L1 |
| 24 | list_issues | 问题 | L0 |
| 25 | write_review | 审核 | L1 |
| 26 | list_reviews | 审核 | L0 |
| 27 | read_review | 审核 | L0 |
| 28 | mark_human_approved | 审核 | L1 |
| 29 | archive_to_history | 历史档案 | L1 |
| 30 | bulk_archive_to_history | 历史档案 | L1 |
| 31 | list_history | 历史档案 | L0 |
| 32 | read_history_task | 历史档案 | L0 |
| 33 | get_team_status | 团队/工作区 | L0 |
| 34 | deploy_role_templates | 团队/工作区 | L1 |
| 35 | new_workspace | 团队/工作区 | L1 |
| 36 | list_workspaces | 团队/工作区 | L0 |
| 37 | drop_suggestion | 泄压阀 | L1 |
| 38 | check_update | 维护 | L0 |
| 39 | upgrade_fcop | 维护 | L0 |
| 40 | redeploy_rules | 维护 | L1 |
| 41 | list_governance_events | 治理审计 | L0 |
| 42 | get_governance_summary | 治理审计 | L0 |
| 43 | fcop_list_alerts | GAL | L0 |
| 44 | fcop_create_alert | GAL | L1 |
| 45 | fcop_audit | 体检 | L0 |
常见问题
项目根是怎么找到的？
set_project_dir → FCOP_PROJECT_DIR → 向上找 fcop/fcop.json / fcop-rules.mdc / fcop/tasks/ → 当前 cwd。
create_task vs write_task？
功能完全相同。create_task 是 FCoP v3 规范 §8 的命名；write_task 是 v1/v2 兼容名称。两者长期并存。
v3 生命周期工具在 v2 项目能用吗？
不能，但不会报错——会返回提示性 no-op 消息，说明当前是 v2 项目。
history/ 和 _lifecycle/archive/ 有什么区别？
_lifecycle/archive/ 是中间站（已完成但待深度归档）；history/ 是最终归宿（按日期分片，永久只读）。archive_to_history 负责把任务从前者迁移到后者。
risk_level=high 时必须 Review 吗？
协议层不强制阻塞，但 high / irreversible 的任务按 ADR-0024 应配套一个 write_review，且推荐 decision="needs_human" 由 ADMIN 用 mark_human_approved 闭合。
升级了 fcop-mcp 还要不要改 mcp.json？
3.x 内不必改——工具 shape 是只增不改的。改 mcp.json 仅当换了启动方式（uvx ↔ 固定 venv 的 python -m fcop_mcp）。
本页是导航索引，权威说明在源码 docstring；工具列表由 CI 对照 tool_surface.json 校验。