FCoP MCP
September 14, 2026 · View on GitHub
Current package pair: 4.0.3, with 49 tools / 12 resources / 4 templates.
The three Branch tools introduced in 4.0.1 remain available; all signatures
are unchanged. MCP requires fcop>=4.0.3,<4.1.0 and uses the declared
package compatibility pairs.
fcop tools --json reads the public offline fcop_mcp.catalog.get_tool_catalog()
from the same declarations used by MCP registration. It neither starts MCP nor
performs work. With only Core installed it reports MCP as unavailable.
CLI reference / 中文参考.
4.0.1 新增 Branch 创建、只读家族检查及原子合并；原 reopen_task 和旧入口保留。
全部锁、幂等收据、REVIEW 追加与恢复由 Core 实现，MCP 只转换参数。
未就绪摘要允许 null，同时返回 merge_ready=false 和结构化原因；merge 不接受 null。
详见 Branch merge contract / 中文合同。
| Capability / 能力 | Public MCP entry / 入口 | v4 behavior / 行为 |
|---|---|---|
| Workspace | init_solo, init_project | Explicit protocol_version="4.0"; returns workspace_id; no legacy rules redeployment |
| TASK / Branch | create_task, write_task | workspace_id, durable operation_id; optional branch_of |
| T2 / T3 | claim_task, submit_task | inbox → active; active → review with current REPORT head |
| T4 / T5 | approve_task, reject_task | review → done / active; edge-specific REVIEW, REPORT and single-use authorization |
| T6 | reopen_task | done → active; separate reopen REVIEW and authorization; new attempt |
| T7 | archive_task | done → archive; Root with Branches also needs current digest and convergence REVIEW |
| REPORT | write_report, list_reports, read_report | current attempt_id; immutable append; head_only query; is_head/head_ref/head_digest |
| Authorization | write_review, mark_human_approved | append authorized facts; trusted evaluator registered at server initialization, never supplied in a tool request |
| Family | inspect_task(include_family_digest=true) | canonical family_digest, not a client-computed substitute |
| Convergence | write_review(review_kind="convergence") | family_digest and references to Branch REPORT heads; does not move a TASK |
| Rule discovery | resources/list, resources/templates/list, resources/read | version-selected read-only representations; discovery ≠ adoption ≠ Runtime consumption |
| Legacy deployment | redeploy_rules, deploy_role_templates | supported Legacy versions only; v4 rejects without Host writes; no automatic migration |
| Errors / retry | relevant write calls | structured code; same operation_id exact retry; different digest OPERATION_ID_CONFLICT; zero effects on rejection |
reopen_task(task_id, review_ref, authorization_ref, profile_ref, actor, lang="")
requests only T6. It does not accept operation_id, evaluator or an arbitrary edge.
finish_task and the four history tools reject v4; close_issue and a generic
transition tool are not added. Listing tools is not a promise that every old
operation applies to every workspace version.
并发不是独立工具：相关写入共享原子性、family lock 线性化、持久幂等、 精确重试、冲突拒绝、零副作用和恢复合同。MCP 不拥有第二套恢复状态机， 不增加公共 recovery MCP 工具；Core 恢复面与已提交请求重试须明确区分。
Versioned resources / 版本化只读资源
The installed adapter exposes 12 concrete resources and 4 templates.
Use discovery, not hard-coded old counts. fcop://protocol keeps Markdown
for v3; for v4, Core returns {path, revision, sha256} and MCP projects this
identity deterministically as Markdown, without rereading or interpreting the spec.
fcop://guidance/{assembly}/{language} is versioned guidance. Templates are
read-only views, not envelope generators or authorization issuers.
Real Branch loop / 真实 Branch 闭环
create_task(branch_of=...)
inspect_task(include_family_digest=true)
write_report(attempt_id=...)
write_review(review_kind="convergence", family_digest=..., references=...)
archive_task(review_ref=..., family_digest=...)
This is a parameter map; a real call must also supply the workspace, subject,
current attempt and transition evidence required by its tool schema.
Public stdio client exercises a
sequential TASK, Root plus two Branches, both completions, convergence, Root T7,
two processes racing on one operation ID, restart, exact retry and conflict
zero-effects. The client never imports fcop or fcop_mcp.
Trusted startup uses a demo-only
evaluator, not production issuer verification.
Candidate installation · MCP adapter reference · English README · 中文 README.
Historical 3.x reference / 以下仅为历史 3.x 工具说明
The following tables describe the released legacy interface, not the v4 contract. Counts, migration instructions and binding conventions below apply only to their stated legacy versions. 上方 v4 能力表不更改下面的历史语义。
总览
工具（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 | Legacy v1–v3 only / ADMIN-only。仅维护显式 Legacy 工作区；v4 无论 force/archive 都返回 toolkit:OPERATION_NOT_IMPLEMENTED，零写入。不是 4.x 安装或升级步骤；v4 通过包内及 MCP rules/protocol/guidance resources 获取规则。 | 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 校验。