Pin the project root for this MCP session.

Useful when the MCP process was spawned with the wrong working directory — typical symptom: unbound_report shows a project path like C:\Users\<you> instead of the workspace you actually opened in Cursor. Calling this tool once re-binds every subsequent tool call to the given directory, without editing mcp.json or restarting Cursor.

Safe to call while UNBOUND — re-pointing at a directory is not a role-claim and writes nothing. It only mutates in-process state.

Initialize an FCoP project with a bundled preset team.

Since 3.0.2 a fresh init produces the v3 topology (per spec §1.1): fcop/_lifecycle/{inbox,active,review,done,archive}/ plus the retained v2 buckets reports/ / issues/ / shared/. The superseded v2 buckets tasks/ and log/ are no longer created on fresh init (use python -m fcop migrate --to-v3 to upgrade an existing v2 project).

Writes fcop/fcop.json, deposits LETTER-TO-ADMIN.md under fcop/, creates the workspace/ cage with a starter README (per Rule 7.5), deploys the team's three-layer docs to fcop/shared/ (TEAM-README / TEAM-ROLES / TEAM-OPERATING-RULES + roles/{ROLE}.md, both zh and en), and (per ADR-0006) deploys the bundled protocol rules to four locations so any agent host sees them: .cursor/rules/fcop-rules.mdc, .cursor/rules/fcop-protocol.mdc, AGENTS.md, and CLAUDE.md. Existing copies are archived to .fcop/migrations/<timestamp>/ before being overwritten.

Initialize an FCoP project in Solo mode (one AI, no dispatch).

Solo mode is for projects where a single agent works directly with ADMIN. Rule 0.b still applies: the agent uses files to split itself into proposer and reviewer, even though there is no second role.

Since 3.0.2 fresh init produces the v3 topology (per spec §1.1): fcop/_lifecycle/{inbox,active,review,done,archive}/ plus retained reports/ / issues/ / shared/. Superseded v2 buckets (tasks/, log/) are no longer created on fresh init.

Beyond fcop.json and the canonical directories, this also deposits fcop/LETTER-TO-ADMIN.md (the user manual), creates the workspace/ cage with a starter README (per Rule 7.5), deploys the bundled solo three-layer docs (TEAM-README / TEAM-ROLES / TEAM-OPERATING-RULES + roles/ME.md, both zh and en) to docs/agents/shared/, and (per ADR-0006) drops the bundled protocol rules into .cursor/rules/*.mdc + AGENTS.md + CLAUDE.md. Existing copies are archived under .fcop/migrations/<timestamp>/ before being overwritten.

Create an FCoP project with a custom roster of roles.

Role codes can be anything — they become part of task filenames, e.g. TASK-20260423-001-BOSS-to-CODER.md. Use validate_team_config first to catch illegal role codes without writing anything.

Since 3.0.2 fresh init produces the v3 topology (per spec §1.1): fcop/_lifecycle/{inbox,active,review,done,archive}/ plus retained reports/ / issues/ / shared/. Superseded v2 buckets (tasks/, log/) are no longer created on fresh init.

Custom teams have no bundled three-layer docs, so fcop/shared/ is left empty (apart from the project's own shared/README.md). The recommended next step is to read the closest preset (fcop://teams/<closest-preset> — see the teams/_data/README.md "Custom teams" section) and hand-author your own TEAM-README.md / TEAM-ROLES.md / TEAM-OPERATING-RULES.md + roles/{ROLE}.md based on it.

The other init artifacts are deposited as usual: fcop/fcop.json, LETTER-TO-ADMIN.md, workspace/README.md, plus the protocol rule files at .cursor/rules/*.mdc + AGENTS.md + CLAUDE.md (existing copies archived under .fcop/migrations/).

Dry-run validation for a custom team config.

Use before create_custom_team to catch illegal role codes (Chinese characters, dashes, reserved names, duplicates) without writing anything to disk.

Create a new task file (v3: _lifecycle/inbox/; v2: fcop/tasks/).

The library assigns a filename of the form TASK-YYYYMMDD-NNN-{SENDER}-to-{RECIPIENT}.md and writes a FCoP-compliant YAML frontmatter + markdown body. In a v3 project the task is placed in _lifecycle/inbox/ so the recipient can claim_task it.

Read the full content of a task file.

List tasks, optionally filtered.

Validate a task file against FCoP grammar.

Catches deterministic violations that raw read_file + regex agents often miss: filename says to-DEV but frontmatter says recipient: QA, protocol field mistyped, required field missing, and so on.

Archive a completed task (move under docs/agents/log/).

The report file tied to this task, if any, is moved alongside so the archived pair stays together.

Move a closed task from _lifecycle/archive/ to the deep history archive.

The task and all its associated reports are moved together into history/YYYY-MM-DD/<task-stem>/, creating an immutable, date-sharded record. The date shard defaults to the UTC date when the task was marked done; you can override it via done_date.

Call :func:archive_task first to move the task from _lifecycle/done/ to _lifecycle/archive/ before calling this tool.

Migrate all tasks from _lifecycle/archive/ into the deep history archive.

This is a convenience migration tool. It iterates every task in _lifecycle/archive/ and calls :func:archive_to_history for each one, moving each task together with its associated reports into history/YYYY-MM-DD/<task-stem>/.

Useful when:

• A project is being upgraded and existing archived tasks need to be moved into the new date-sharded history structure.

• You have just finished a manual archiving session and want to flush everything from _lifecycle/archive/ into history/ in one step.

The history/ directory is created automatically if it does not yet exist.

Create a new task and place it in the inbox (v3) or tasks folder (v2).

This is the canonical FCoP v3 spec §8 L1 entry-point for task creation — functionally identical to :func:write_task but named to match the spec. In a v3 project the task lands in _lifecycle/inbox/ so the recipient can claim_task it.

List the deep history archive.

When date is supplied (YYYY-MM-DD) the tool lists every task entry stored under that date shard. When date is omitted it lists all available date shards (newest first).

Read a task from the deep history archive.

Searches history/ for the task matching task_id. Providing date restricts the search to that date shard (much faster).

Claim a task from inbox → active (v3 lifecycle).

Moves the task file from _lifecycle/inbox/ to _lifecycle/active/ and appends a claim_task transition event to the file's frontmatter. On v2 projects this is a no-op that returns an informational message.

Submit an active task for review: active → review (v3 lifecycle).

Moves the task file from _lifecycle/active/ to _lifecycle/review/ and appends a submit_task transition event. On v2 projects this is a no-op.

Finish an active task directly: active → done (v3 lifecycle).

Moves the task file from _lifecycle/active/ to _lifecycle/done/ without a review step. Use this for tasks that do not require ADMIN approval. On v2 projects this is a no-op.

Approve a task under review: review → done (v3 lifecycle).

Moves the task file from _lifecycle/review/ to _lifecycle/done/ and appends an approve_task event. Typically called by ADMIN after inspecting the work. On v2 projects this is a no-op.

Reject / recall a task under review: review → active (v3 lifecycle).

Moves the task file back from _lifecycle/review/ to _lifecycle/active/ so the agent can rework it. Appends a reject_task transition event. This is the FCoP v3 "撤回" (recall) mechanism — ADMIN sends the work back for revision without discarding it. On v2 projects this is a no-op.

Write a completion report for a task.

Creates REPORT-<task_id>-{REPORTER}-to-{RECIPIENT}.md under docs/agents/reports/. The task_id is the canonical reference back to the source task.

List reports, optionally filtered.

Read the full content of a report file.

File an issue under docs/agents/issues/.

Write a REVIEW file (governance-layer decision, per ADR-0017/0025).

List REVIEW files, optionally filtered.

Read the full content of a REVIEW file.

Record a human approval decision on a needs_human REVIEW file.

Closes the escalation loop opened by write_review(decision='needs_human'). Writes human_approval sub-structure into the REVIEW frontmatter and returns the updated review summary (per ADR-0026).

List issues, optionally filtered.

List bundled preset teams and their role rosters.

Useful before init_project to pick a template that fits the work. Each team ships with its own three-layer documentation (TEAM-README.md + TEAM-ROLES.md + TEAM-OPERATING-RULES.md) that gets deployed into docs/agents/shared/ during init_project.

Return a concise status snapshot of the current project.

Shows whether the project is initialized, which team / roster is loaded, how many open tasks / reports / issues are on disk, and the five most recent activity entries (sorted newest first).

Deploy the three-layer team documentation into shared/.

Writes TEAM-README.md (bilingual), TEAM-ROLES.md, TEAM-OPERATING-RULES.md, and per-role bios under docs/agents/shared/ (both zh and en variants).

When force=True (default) existing files are archived under .fcop/migrations/<timestamp>/shared/ before being overwritten, so the action is safely reversible. When force=False existing files are left untouched and reported as skipped.

Create a workspace subdirectory under workspace/<slug>/.

workspace/<slug>/ is FCoP's soft convention for the actual artifacts of a piece of work — code, scripts, data. Keeping those out of the project root prevents yesterday's mini-game from colliding with today's report generator.

Idempotent: calling twice with the same slug updates the title / description but never wipes files you already dropped in the folder.

List all workspace/<slug>/ subdirectories with their metadata.

Picks up both workspaces created by new_workspace (they have a .workspace.json marker) and directories created by hand (shown with just the slug). Use for the at-a-glance "what's inside this project" view.

Pressure valve for agents who disagree with the current FCoP protocol.

Writes a timestamped markdown file under .fcop/proposals/ that ADMIN can review later. This is the ONLY sanctioned way for an agent to push back on the rule files (fcop-rules.mdc / fcop-protocol.mdc). Agents MUST NOT edit the rule files themselves; those are ADMIN's source of truth.

Works before init_project / init_solo too — suggestions just land under the project root even if the project is not yet fully initialized.

FCoP Rule 0 — first tool call of every new session, also the general project-status report.

Returns one of two reports plus a versions block + optional drift warning (ADR-0006):

1. Initialization report when docs/agents/fcop.json is missing. Lists the detected project path + resolution source and the available init modes (Solo / preset teams / custom). Does NOT ask for a role assignment — there's no team yet.

2. UNBOUND report when the project is initialized but this session has no role. Shows project state and a role-assignment template for ADMIN to fill in.

In both cases the [Versions] block reports installed fcop-mcp / fcop versions plus the project-local vs packaged versions of the protocol rules. When the project's .cursor/rules/*.mdc is older than the wheel-bundled copy a drift warning is appended prompting ADMIN to run redeploy_rules(). Agents must NOT invoke redeploy themselves.

While UNBOUND (or uninitialized) the agent MUST NOT read task bodies, write any files (except via the explicit init tools), or claim a role from context clues.

.. note:: This tool replaced unbound_report in 0.6.3. The deprecated alias was removed in 0.7.0; existing system prompts and LETTER-TO-ADMIN.md references that still reference unbound_report must switch to fcop_report.

FCoP audit. Cross-reference git working tree + frontmatter against the FCoP ledger.

Two independent post-hoc audits, both new in 0.7.1 (fcop_protocol_version: 1.6.0):

1. Rule 0.a.1 drift — files in git status --porcelain that live outside docs/agents/{tasks,reports,issues,log}/ are by definition work performed without the task→do→report→archive cycle.

2. Rule 1 sub-agent role impersonation — any session_id that signed files under more than one role code. One session = one role binding for life; cross-role usage is direct evidence that a sub-agent self-claimed a role its parent session was not assigned.

This tool is detection, not prevention. It surfaces the evidence; the protocol-mandated response is for ADMIN to file an ISSUE-* and decide handoff / co-review / distinct-role per Rule 1, just as for the role_occupancy table in fcop_report().

Decomposes to filesystem operations:

• git status --porcelain -z from the project root.

• Walk every TASK-*.md / REPORT-*.md / ISSUE-*.md in docs/agents/{tasks,reports,issues} + docs/agents/log/*.

• Read frontmatter only; never task bodies.

协议体检工具（ADR-0032）。扫描项目，发现协议合规缺口，产出"体检即整改方案"报告。

与 fcop_check 的区别：

• fcop_check — 日常轻量自检（working-tree drift + session/role 冲突）

• fcop_audit — 一次性深度体检（协议合规度全量扫描 + 整改方案）

三个 scope：

• new : 新项目验收 — 协议文件是否完整部署

• upgrade : 版本升级后验收 — 规则版本 / 文档是否同步

• takeover : 老 non-fcop 项目首次引入 fcop — 全量合规扫描（含 6 类盲区）

• auto : 自动推断（推荐）

产出物：fcop/shared/INSPECTION-{date}-{NNN}-{scope}.md

报告含 Execution Block：每条违规附带可直接复制的整改命令、执行人、 Tier 优先级和回滚方式。

ADMIN-only. Re-deploy bundled FCoP protocol rules to the project.

Writes the wheel-bundled :file:fcop-rules.mdc / :file:fcop-protocol.mdc to four locations so any agent host the project runs under sees the same rules:

.. code-block:: text

<root>/.cursor/rules/fcop-rules.mdc       # Cursor IDE
<root>/.cursor/rules/fcop-protocol.mdc    # Cursor IDE
<root>/AGENTS.md                          # Codex / Cursor / Devin / generic
<root>/CLAUDE.md                          # Claude Code CLI

Run this after pip install -U fcop-mcp (or -U fcop) to refresh on-disk copies to the newly packaged versions. fcop_report() shows when this is needed via the version drift warning.

Per ADR-0006, agents must NOT invoke this tool themselves — only ADMIN does, explicitly.

Compare the installed fcop-mcp version to the latest on PyPI.

Prints the local version, the latest PyPI version (if reachable), and a one-line verdict. Does NOT install anything — call upgrade_fcop afterwards for that.

Return the install-method-specific command to upgrade fcop-mcp.

Does NOT run pip — MCP servers cannot safely upgrade themselves mid-process, and different install methods (pip in a venv, pipx, uvx) need different commands. This tool prints the right incantation for the user to run in their own shell.

FCoP governance audit. Read the append-only governance event log.

Returns recent tool-call intercept events recorded by the FCoPGovernanceMiddleware (ADR-0030-bis Layer 1). Use this to understand what actions agents have taken and their risk classification.

FCoP governance summary. Return aggregate statistics from the governance event log: total calls by risk level, most active tools, and any CRITICAL_TAG events that should be reconciled with Tasks and Reviews.

Use as a quick health check: CRITICAL_TAG events without corresponding Task + Review coverage are governance gaps that require ADMIN attention.

ADMIN Governance Alert Inbox. List governance alerts from fcop/alerts/.

Alerts are written automatically by fcop_check() when governance drift signals are detected (ADR-0031). Each alert is a structured ALERT-*.md file with severity (high/medium/low), type, and a summary of the governance gap.

This is the ADMIN's "red dot" — run this to see what governance gaps the system has surfaced, without needing to manually patrol logs.

ADMIN / Governance Observer only. Manually file a governance alert.

Use when you (as ADMIN or an authorized governance observer) detect a governance gap that automated scanning has not yet captured. Creates a new ALERT-*.md file in fcop/alerts/.