# joinwell52-AI/FCoP [Health: Active] **Category:** 🛠️ Other Tools and Integrations **Repository:** https://github.com/joinwell52-AI/FCoP **GitHub Stars:** 2 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/joinwell52-ai-fcop ## Description File-based Coordination Protocol: behavior governance layer for multi-agent teams. 45 MCP tools (writetask, writereport, writeissue, writereview, lifecycle claim/submit/approve…). Agents coordinate via structured Markdown files (\lifecycle/\) — no message broker, no database, just the filesystem. Official MCP Registry: io.github.joinwell52-AI/fcop (v3.2.5). pip install fcop-mcp ## Tools Capabilities this server exposes over MCP: - **set_project_dir** — 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\`` 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. - **init_project** — 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//`` before being overwritten. - **init_solo** — 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//`` before being overwritten. - **create_custom_team** — 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/`` — 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/``). - **validate_team_config** — 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. - **write_task** — Create a new task file (Cold Path dispatch or formal intake only). **Not Hot Path execution.** Use when ``ADMIN`` / ``leader`` assigns work, when Cold Path fan-out dispatches subtasks, or when you were explicitly told to land a formal task. Agents **must NOT** self-dispatch without an upstream requirement (Rule 0.a.2). Subtask linking: set ``thread_key`` for thread continuity; set ``parent`` to the upstream task ID (``parent:`` frontmatter — work derivation, distinct from ``references``). Do **not** emit ``parent_task_id`` as normative output (read-only legacy alias only). File ops: write ``TASK-*.md`` under ``_lifecycle/inbox/`` (v3) or ``fcop/tasks/`` (v2). Does **not** claim, finish, or archive. The library assigns a filename of the form ``TASK-YYYYMMDD-NNN-{SENDER}-to-{RECIPIENT}.md`` with FCoP-compliant YAML frontmatter + markdown body. In v3 the recipient ``claim_task``s from inbox. - **read_task** — Read the full content of a task file (Hot Path pre-flight). **Before executing** on an assigned or claimed task, call this **together with** ``inspect_task`` (Rules 0.a.1 / 0.a.2). Do not mutate the workspace or dispatch from chat/memory alone. File ops: ``cat`` the file under ``_lifecycle/{stage}/TASK-*.md``, legacy ``fcop/tasks/``, or ``fcop/log/`` when archived. - **list_tasks** — List tasks, optionally filtered. - **inspect_task** — Validate a task file against FCoP grammar (Hot Path pre-flight). Run **before executing** on a claimed/assigned task, alongside ``read_task``. Catches deterministic violations agents often miss (filename ``to-DEV`` vs frontmatter ``recipient: QA``, mistyped ``protocol``, missing required fields). ``PASS`` does **not** replace reading the task body for acceptance criteria. File ops: read filename + frontmatter and validate grammar only. - **archive_task** — Archive a task after governance acceptance (v3: ``_lifecycle/archive/``; v2: ``log/``). **Governance action (Rule 0.a.5).** **Not** Hot Path step 4 for executors. Default actor is ``leader`` or ``ADMIN`` after accepting the paired ``REPORT-*``. Executors must **not** call this unless the task body or ``ADMIN`` explicitly authorises archive-on-completion. **Authorization:** subtasks — direct upstream or governance runtime; main tasks — ``ADMIN`` or the main-task owner only. Archive **≠** business completion (Rule 0.a.3). Does **not** run automatically after ``write_report`` or ``finish_task``. File ops: ``mv`` task (+ matched reports via ``references``) to ``_lifecycle/archive/`` or ``fcop/log/``. - **archive_to_history** — Deep-history cold storage after governance archive (v3 only). Moves a task already in ``_lifecycle/archive/`` (or legacy ``log/``) into ``history/YYYY-MM-DD//`` with its reports — immutable, date-sharded retention. **Not** business acceptance and **not** a substitute for ``write_report`` or authorised ``archive_task``. Call ``archive_task`` first (v3: ``done/`` → ``archive/``). Main-task deep archive requires the same governance authorization as ``archive_task`` (Rule 0.a.5). File ops: ``mv _lifecycle/archive/TASK-* history/YYYY-MM-DD//``. - **bulk_archive_to_history** — 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//``. 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_task** — 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_history** — 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_history_task** — 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_task** — Claim a task: ``inbox`` → ``active`` (v3 Hot Path start). **Hot Path step 1 (v3):** call before executing on an inbox task. Always follow with ``read_task`` + ``inspect_task``. Does **not** read the task body, write a report, or imply business completion. File ops: ``mv _lifecycle/inbox/TASK-* _lifecycle/active/`` + append ``claim_task`` transition event to frontmatter. On v2 projects this is a no-op with an informational message. - **submit_task** — Submit for review: ``active`` → ``review`` (v3 lifecycle directory move). **Lifecycle only (Rule 0.a.3).** Does **not** replace ``write_report``, upstream acceptance, or authorised ``archive_task``. Pair with a ``REPORT-*`` before or after submit as your team's operating rules require — this tool alone does not close business work. File ops: ``mv _lifecycle/active/TASK-* _lifecycle/review/``. On v2 projects this is a no-op. - **finish_task** — Move lifecycle stage: ``active`` → ``done`` (v3 directory move only). This is a **lifecycle directory move** — it does **not** replace ``write_report``, upstream acceptance, or authorised ``archive_task`` (Rules 0.a.3, 0.a.5, 0.a.6). **Rule 0.a.6:** after reporting, **stop and wait** for review; do **not** chain ``finish_task`` in the same turn as ``write_report`` or treat it as "business complete". File ops: ``mv _lifecycle/active/TASK-* _lifecycle/done/``. On v2 projects this is a no-op. - **approve_task** — Approve lifecycle stage: ``review`` → ``done`` (v3 directory move). **Lifecycle approval ≠ business acceptance (Rule 0.a.3).** Typically ``ADMIN`` / reviewer after inspecting the paired ``REPORT-*``. Does **not** auto-call ``archive_task`` or mark blocked upstream work as externally delivered. File ops: ``mv _lifecycle/review/TASK-* _lifecycle/done/``. On v2 projects this is a no-op. - **reject_task** — Reject / recall: ``review`` → ``active`` (v3 rework loop). Returns the task to ``active/`` for revision after a ``REPORT-*`` or review finding (complements Rule 0.a.6 stop-and-wait). **Lifecycle only** — does not delete reports or auto-call ``archive_task``. File ops: ``mv _lifecycle/review/TASK-* _lifecycle/active/`` + append ``reject_task`` event. On v2 projects this is a no-op. - **write_report** — Write a completion report for a task. Creates ``REPORT--{REPORTER}-to-{RECIPIENT}.md`` under ``docs/agents/reports/`` (v3: co-located under ``_lifecycle/``). The ``task_id`` is the canonical reference back to the source task. **Stop signal (Rule 0.a.6):** after this call, wait for upstream review / rework — do not keep editing artefacts, dispatch unrelated work, or call ``archive_task`` unless explicitly authorised. Does **not** trigger ``finish_task``, ``approve_task``, or ``archive_task`` automatically. ``status=blocked`` still leaves the task open for upstream action. File ops: write ``REPORT-*.md`` under ``fcop/reports/`` or co-located ``_lifecycle/`` stage. - **list_reports** — List reports, optionally filtered. - **read_report** — Read the full content of a report file. - **write_issue** — File an issue under ``docs/agents/issues/``. - **write_review** — Write a REVIEW file (governance-layer decision, per ADR-0017/0025). - **list_reviews** — List REVIEW files, optionally filtered. - **read_review** — Read the full content of a REVIEW file. - **mark_human_approved** — 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** — List issues, optionally filtered. - **get_available_teams** — 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``. - **get_team_status** — 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_role_templates** — 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//shared/`` before being overwritten, so the action is safely reversible. When ``force=False`` existing files are left untouched and reported as skipped. - **new_workspace** — Create a workspace subdirectory under ``workspace//``. ``workspace//`` 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_workspaces** — List all ``workspace//`` 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. - **drop_suggestion** — 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_report** — **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. The initialized report includes the **3.2.5 collaboration cycle** (Rule 0.a.1–0.a.6): ``write_task`` → execute/dispatch → ``write_report`` → wait / authorised ``archive_task``. It does **not** deep-audit the project — use ``fcop_check`` (lightweight) or ``fcop_audit`` (deep) when ADMIN requests. .. 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_check** — **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 the FCoP ledger (``_lifecycle/`` or legacy ``docs/agents/{tasks,reports,issues,log}/``) are work performed without the task→execute/dispatch→report collaboration cycle. Missing ``archive_task`` on an open task is **not** drift by itself — executors default to **not** archiving (Rule 0.a.5). 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()``. **Not Hot Path auto-run:** do **not** invoke after every ``write_report`` by default. For one-shot deep compliance scans use ``fcop_audit`` instead (Rule 9.6). 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. - **fcop_audit** — **协议体检工具（ADR-0032）** — deep compliance scan, not Hot Path. 与 ``fcop_check`` 的区别： - ``fcop_check`` — 日常轻量自检（working-tree drift + session/role 冲突）； **不**在每次 ``write_report`` 后自动调用 - ``fcop_audit`` — 一次性深度体检（协议合规度全量扫描 + 整改方案）； **不**替代协作闭环，**不**等于业务验收或 ``archive_task`` **Not lifecycle closure:** passing audit does not archive tasks or accept reports. Execution Block commands are **suggestions** only. 三个 scope： - ``new`` : 新项目验收 — 协议文件是否完整部署 - ``upgrade`` : 版本升级后验收 — 规则版本 / 文档是否同步 - ``takeover`` : 老 non-fcop 项目首次引入 fcop — 全量合规扫描（含 6 类盲区） - ``auto`` : 自动推断（推荐） 产出物：``fcop/shared/INSPECTION-{date}-{NNN}-{scope}.md`` 报告含 **Execution Block**：每条违规附带可直接复制的整改命令、执行人、 Tier 优先级和回滚方式。 - **redeploy_rules** — **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 /.cursor/rules/fcop-rules.mdc # Cursor IDE /.cursor/rules/fcop-protocol.mdc # Cursor IDE /AGENTS.md # Codex / Cursor / Devin / generic /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. - **check_update** — 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. - **upgrade_fcop** — 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. - **list_governance_events** — **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. - **get_governance_summary** — **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. - **fcop_list_alerts** — **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. - **fcop_create_alert** — **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/. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "fcop": { "command": "uvx", "args": ["fcop-mcp"] } } ``` ## Documentation & README

FCoP architecture

# FCoP — File-based Coordination Protocol [English](https://github.com/joinwell52-AI/FCoP/blob/HEAD/README.md) · [简体中文](https://github.com/joinwell52-AI/FCoP/blob/HEAD/README.zh.md) **Keep agent work beyond the conversation.** Tasks, deliveries, issues and review decisions become durable files that people, tools and the next agent can inspect. A session can end without taking the work record with it.

fcop on PyPI: 4.0.2 fcop-mcp on PyPI: 4.0.2 MIT license

**[Ask AI to install](#ai-install) · [Manual reference](#manual-setup) · [Architecture series (中文)](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/README.md) · [Architecture](#architecture) · [Papers & citation](#research)** Agent work is persisted as TASK, REPORT, ISSUE and REVIEW files, then read by people, tools and another session. **Stable version: 4.0.2** — [4.0.2 release](https://github.com/joinwell52-AI/FCoP/releases/tag/v4.0.2). This repository contains the open protocol, the `fcop` Python implementation and the optional `fcop-mcp` adapter. Python 3.10+; no model API key is needed for the local example. ## Ask your AI to install FCoP Paste this into **Cursor Agent, Codex, or another coding agent with terminal and file access**. The agent handles setup and checks the result. ```text Install FCoP for the coding client and project I am using. Follow: https://github.com/joinwell52-AI/FCoP/blob/main/docs/ai-install.md Run the environment checks, installation, configuration and verification yourself. Preserve my existing configuration and project state. Report what actually works; ask me only for a missing client/project choice or a required approval/reload. ``` The [AI installation guide](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/ai-install.md) covers dependencies, client configuration and a real task check. If the client needs approval or a reload, the agent will identify that step. Manual Python/MCP instructions remain below for reference. ## Why put work outside the model? “I have finished” is a statement in a conversation. A teammate still needs to know **which assignment was attempted, what was delivered, who reviewed it and what remains unresolved**. Keeping those facts only in a chat makes a handoff depend on reconstructing that chat. FCoP gives formal work a shared representation: Markdown files with structured metadata, stable identities, explicit relationships and recorded state transitions. An agent can write them, a human can open them, and a script can validate them. The filesystem reference implementation needs no database or message broker. | Record | What it preserves | Why it matters | |---|---|---| | **TASK** | Assignment, participants and lifecycle | The next worker can locate the work and its current state. | | **REPORT** | Delivery claim and evidence for an attempt | “Submitted” remains distinguishable from “accepted.” | | **ISSUE** | A problem and its context | A blocker survives the session that discovered it. | | **REVIEW** | Review, acceptance or authorization facts | Decisions can be checked against the work and evidence they concern. | Persistence makes a claim inspectable; it does not make the claim true. FCoP checks protocol relationships and gates. Reviewers evaluate the substance of the delivered work, and the host Runtime supplies execution, scheduling and permissions.
Manual installation, Python/MCP examples and CLI reference (optional) ## CLI setup, observation and diagnosis; MCP work 4.0.2 provides nine top-level commands: `init`, `status`, `inspect`, `validate`, `tools`, `doctor`, `version`, `spec` and `migrate`. Except explicit initialization and migration apply, commands are read-only; the CLI does not provide task lifecycle write commands. ```sh fcop init --root ./demo-workspace --json fcop status --root ./demo-workspace --json fcop doctor --root ./demo-workspace --json fcop tools --json ``` The `fcop` package alone sets up and observes workspaces. `tools` needs the optional MCP package; when absent it returns a structured unavailable result, without starting a server or installing packages. [CLI reference](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/cli.md) · [中文命令参考](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/cli.zh.md). 4.0.1 introduced `create_branch`, `inspect_family` and `merge_branches`; 4.0.2 preserves all 49 tools and their signatures. Core owns atomic convergence, durable idempotency and recovery. Unfinished families return `family_digest: null`, `merge_ready: false` and structured reasons. The caller supplies the semantic conclusion. See the [Branch merge contract and example](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/branch-merge.md) / [中文合同](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/branch-merge.zh.md). ## Try it: create once, read from another client In an activated **Python 3.10+ virtual environment**, install the published library: ```sh python -m pip install "fcop==4.0.2" ``` Save this as `demo.py` and run `python demo.py`. It writes a real TASK, opens the workspace through a fresh `Project` instance, then retries the original request. ```python from pathlib import Path from tempfile import TemporaryDirectory from fcop import Project with TemporaryDirectory(prefix="fcop-demo-") as directory: root = Path(directory) / "workspace" project = Project(root) workspace = project.create_workspace(protocol_version="4.0") request = dict( workspace_id=workspace["workspace_id"], operation_id="demo-create-1", sender="ME", recipient="ME", subject="Inspect this handoff", body="Read the task and check the evidence before accepting delivery.", ) first = project.create_task(**request) next_client = Project(root) state = next_client.inspect_state(task_id=first["task_id"]) retry = next_client.create_task(**request) assert Path(state["path"]).is_file() assert retry["existing"] and retry["task_id"] == first["task_id"] print("State read from disk:", state["stage"]) print("Same task after retry:", retry["task_id"] == first["task_id"]) ``` ```text State read from disk: inbox Same task after retry: True ``` The example cleans up its temporary directory when it exits. Use your own project directory to retain the files. Retrying `create_task` with the same `operation_id` and normalized payload reuses its durable result; changing the payload is a conflict. This guarantee is specifically for task creation. **Continue with the [4.0 setup and version guide](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-4.0-progress.md)** for a lasting workspace, lifecycle operations and the authorization needed to complete a task. ## Give your agent the same operations through MCP The optional adapter exposes FCoP to an MCP-capable client over stdio. Install it in the same activated environment: ```sh python -m pip install "fcop==4.0.2" "fcop-mcp==4.0.2" ``` Add this entry to the client's MCP configuration. Replace both absolute paths; on Windows the command ends in `.venv/Scripts/fcop-mcp.exe`. ```json { "mcpServers": { "fcop": { "command": "/absolute/path/to/.venv/bin/fcop-mcp", "env": {"FCOP_PROJECT_DIR": "/absolute/path/to/new-workspace"} } } } ``` Once connected, initialize a **new** workspace with `init_solo(role_code="ME", protocol_version="4.0")`. Use its workspace identity when calling `create_task`, then inspect the TASK with `inspect_task(filename=task_id)`. Installing an MCP server alone does not initialize a workspace or start an agent team. **49 tools / 12 resources / 4 resource templates.** The adapter routes to the same Python Core. Default initialization has no trusted authorization Profile: creation, claim and submission are available, but acceptance, rejection, reopening and archival need an explicitly adopted Profile and an issuer evaluator registered by the trusted host. A role name typed into a request cannot supply that authority. [MCP tool reference](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/mcp-tools.md) · [Stable external Python example](https://github.com/joinwell52-AI/FCoP/blob/HEAD/tests/stable/third-party/python-only/app.py) · [Stable external MCP example](https://github.com/joinwell52-AI/FCoP/blob/HEAD/tests/stable/third-party/mcp-only/client.py). The full examples include an educational Profile; a real deployment must supply its own trust policy.
## From a delivery claim to an accepted result Each TASK follows an ordered lifecycle. In 4.0, entering `active` starts a new attempt, and submission links that attempt's REPORT. Acceptance then binds the review and authorization to the current evidence. FCoP 4.0 lifecycle: inbox, active, review, done and archive; authorized rejection and reopening return to a new active attempt. `active → done` is absent from 4.0. Reopening through `reopen_task` creates a new attempt for ordinary tasks as well as Branches. An old REPORT cannot satisfy a new attempt's submission gate. See the [complete lifecycle and C1–C8 contracts](https://github.com/joinwell52-AI/FCoP/blob/HEAD/spec/fcop-4.0-spec.md) · [中文规范](https://github.com/joinwell52-AI/FCoP/blob/HEAD/spec/fcop-4.0-spec.zh.md). ## Parallel work, with an explicit way to finish Multiple ordered workflows can advance concurrently. A Branch is an ordinary TASK linked to one Root by `branch_of`; sibling Branches keep their own attempts, reports and reviews. Your Runtime decides who runs them and when. Two sibling Branch tasks proceed independently through work, report and review; Root closure checks current evidence, convergence and archive authorization. Before a Root with Branches can be archived, FCoP checks completed Branches, their current REPORTs, a matching `family_digest`, a convergence REVIEW and separate Root archive authorization. A reopened Branch or changed REPORT invalidates stale convergence. Related writes share a short commit boundary; agents do not hold that lock while doing their work. This closes an evidence set; code integration remains the application's responsibility. ## A small protocol inside a larger agent system Another implementation should be able to preserve the same work semantics without copying a particular Python library, MCP tool list or product. | Layer | Responsibility | |---|---| | **Core** | C1–C8: identity, envelopes, lifecycle, relations, convergence, authorization, create idempotency and atomic recovery. | | **Specification** | Define the fields, state transitions, errors and observable behavior. | | **Conformance** | Check implementations against those contracts using fixtures, vectors and behavioral tests. | | **Toolkit** | Implement and expose the protocol; this repository supplies Python and the MCP adapter. | | **Profile** | Supply organizational policy and issuer authority; fixed PM/DEV/QA roles are not universal Core rules. | | **Runtime** | Run models and tools, manage sessions, schedule work and provide the user interface. | **Read the design explanation: [English](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/architecture.en.md) · [简体中文](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/architecture.zh.md).** It develops the reasoning behind files, separate delivery and acceptance, parallel work, and the boundaries between FCoP, MCP and a Runtime. **Architecture principles: five full essays in Chinese**, published September 10, 2026 and revised against 4.0: 1. [Work beyond the model context: why files?](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/01-work-beyond-context.zh.md) 2. [Extracting the minimal FCoP Core](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/02-minimal-core.zh.md) 3. [Separating Core, Specification, Toolkit, Profile and Runtime](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/03-architecture-layers.zh.md) 4. [Parallel work through ordered task lifecycles](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/04-parallel-work.zh.md) 5. [How FCoP, MCP, A2A and CodeFlowMu fit together](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/05-mcp-a2a-runtime.zh.md) [Series guide (中文)](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/README.md) · [All five essays (中文)](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-architecture-series/collected.zh.md) 4.0 also distributes **nine bilingual rule modules** with versioned manifests and `sequential`, `parallel` and `repository-development` assemblies. Adoption, deployment planning, receipts and rollback are explicit. Host projections use `reference` or `bounded_embed`; installing a package does not silently rewrite host rules. [Rule distribution contract](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-4.0/rule-distribution-contract.md) · [中文契约](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/fcop-4.0/rule-distribution-contract.zh.md). ## Papers, evidence and citation These resources are directly accessible; reading the essay collection is optional. | Resource | Read or cite | |---|---| | **Architecture whitepaper** | [English](https://github.com/joinwell52-AI/FCoP/blob/HEAD/essays/from-coordination-to-governance.en.md) · [中文](https://github.com/joinwell52-AI/FCoP/blob/HEAD/essays/from-coordination-to-governance.md) — historical research context | | **3.2.5 archive** | [Zenodo DOI 10.5281/zenodo.20457285](https://doi.org/10.5281/zenodo.20457285) · [OSF DOI 10.17605/OSF.IO/92NWM](https://doi.org/10.17605/OSF.IO/92NWM) | | **April 2026 research snapshot** | [Zenodo DOI 10.5281/zenodo.19886036](https://doi.org/10.5281/zenodo.19886036) · [Citation metadata](https://github.com/joinwell52-AI/FCoP/blob/HEAD/CITATION.cff) | | **17 field reports and design essays** | [Complete index](https://github.com/joinwell52-AI/FCoP/blob/HEAD/essays/README.md) · [中文目录](https://github.com/joinwell52-AI/FCoP/blob/HEAD/essays/README.zh.md), including original publication and evidence links | Choose the archive matching the version you studied. The historical DOIs above are not identifiers for 4.0.0; use the versioned release and specification when discussing current behavior. ## Three repositories, three entry points | Repository | Start here for | |---|---| | **[FCoP](https://github.com/joinwell52-AI/FCoP)** | **Flagship open-source project:** protocol, Python library and MCP server; use, implement or contribute to the coordination layer. | | **[joinwell52](https://github.com/joinwell52-AI/joinwell52)** | **Research and communication:** AI Agents, digital employees and engineering studies. | | **[CodeflowMu-Distribution](https://github.com/joinwell52-AI/CodeflowMu-Distribution)** | **Product experience:** packaged application and [downloads](https://github.com/joinwell52-AI/CodeflowMu-Distribution/releases); check its release notes for supported versions. | FCoP is independently usable under the [MIT license](https://github.com/joinwell52-AI/FCoP/blob/HEAD/LICENSE). The product distribution has its own licensing and release schedule. **Star FCoP to bookmark the protocol and its implementation.** To help it improve, share a reproducible integration issue, an example from your host, or a test of the protocol's public behavior through [Issues](https://github.com/joinwell52-AI/FCoP/issues) or a pull request. ## Versions and existing installations - **4.0.0:** [Release notes](https://github.com/joinwell52-AI/FCoP/blob/HEAD/docs/releases/4.0.0.md) · [Changelog](https://github.com/joinwell52-AI/FCoP/blob/HEAD/CHANGELOG.md) · [Architecture decisions](https://github.com/joinwell52-AI/FCoP/blob/HEAD/adr/README.md). Publication followed the recorded `FCOP_4_STABLE_RELEASE_READY` gate; users install the stable PyPI pair above. - **Release candidate: 4.0.0rc1** — retained as a [historical prerelease](https://github.com/joinwell52-AI/FCoP/releases/tag/v4.0.0rc1). - **3.x workspaces:** retain their original semantics until explicit migration. [Legacy specification EN](https://github.com/joinwell52-AI/FCoP/blob/HEAD/spec/fcop-v3-spec.md) · [ZH](https://github.com/joinwell52-AI/FCoP/blob/HEAD/spec/fcop-v3-spec.zh.md). `finish_task` and legacy history tools remain discoverable but reject v4 workspaces. - **Legacy installation prompts:** [EN](https://github.com/joinwell52-AI/FCoP/blob/HEAD/src/fcop/rules/_data/agent-install-prompt.en.md) · [ZH](https://github.com/joinwell52-AI/FCoP/blob/HEAD/src/fcop/rules/_data/agent-install-prompt.zh.md), also available at `fcop://prompt/install`. These are historical setup material; use the 4.0 guide above for the current version.