FCoP — Python Core
fcop is the official Python implementation of the File-based Coordination
Protocol (FCoP). It gives agents and automation a durable, reviewable way to
coordinate work through UTF-8 Markdown files with YAML front matter.
This package is the protocol Core, Python API and thin CLI. The optional MCP adapter is
published separately as fcop-mcp.
FCoP 4.0 is Stable, Implemented and Released. The current package release
is 4.0.3. The optional adapter provides 49 Tools / 12 Resources /
4 Templates, including the official create_branch, inspect_family, and
merge_branches tools.
Install
FCoP 4.0 supports Python 3.10–3.13.
python -m pip install --upgrade "fcop>=4.0.3,<4.1.0"
Verify the installed distribution:
python -c "from importlib.metadata import version; from fcop import Project; print(version('fcop'), Project)"
What Core provides
- Workspace identity and versioned protocol behavior.
- Four durable envelope types: TASK, REPORT, ISSUE, and REVIEW.
- Explicit lifecycle, attempt, relation, and authorization records.
- Branch families for parallel work without overwriting the Root task.
- Explicit convergence with family inspection and atomic Branch merge.
- Durable idempotency, cross-process locking, and crash-safe recovery.
- Version-selected protocol rules and schemas.
- A typed Python
ProjectAPI with no MCP, LLM, or network dependency.
CLI — Local Setup, Inspect & Diagnose
CLI = Setup + Observe + Diagnose; MCP = Work.
| Command | Purpose |
|---|---|
fcop init |
Initialize an FCoP workspace |
fcop status |
View workspace status |
fcop inspect |
Inspect TASK / REPORT / ISSUE / REVIEW |
fcop validate |
Validate protocol structure |
fcop tools |
Inspect the installed MCP Tool Catalog |
fcop doctor |
Diagnose installation, environment and compatibility |
fcop version |
Show installed versions |
fcop spec |
Show specification / rule identity |
fcop migrate |
Explicitly migrate a legacy workspace; inspect the plan before apply |
Install & Verify
In an activated Python 3.10+ environment:
python -m pip install fcop
fcop version
fcop doctor
fcop init --root ./my-project
fcop status --root ./my-project
fcop validate --root ./my-project
For the optional MCP Tool Catalog:
python -m pip install fcop-mcp
fcop tools
fcop tools merge_branches --json
Once installed, the CLI can initialize, inspect, validate and diagnose locally and offline.
doctor does not access the network or modify Host configuration. Package installation itself may need a package index; offline installation requires locally available packages.
The CLI does not perform create_task, approval, Branch, merge or authorization work operations; use MCP or the Python API for those.
Installing fcop does not create Host instruction files. Normal v4 workspace state belongs in <project>/fcop/, never in project-root AGENTS.md, CLAUDE.md or Cursor rules.
Existing atomic initialization staging and failed-initialization evidence are preserved; customer files are never cleaned up automatically.
migrate is a separate explicit legacy operation, not an automatic package-upgrade step.
tools requires the optional MCP package and never starts a server or installs it automatically.
Minimal Python example
from pathlib import Path
from fcop import Project
project = Project(Path("/absolute/path/to/repository"))
workspace = project.create_workspace(protocol_version="4.0")
print(workspace["workspace_id"])
Installing the package does not initialize a repository, migrate an existing workspace, deploy rules, start an MCP server, or modify another application.
Branch and merge
Parallel work is represented as a Root TASK with Branch TASKs. Agents produce REPORTs on their assigned Branches; a PM or coordinating agent inspects the family and supplies the convergence decision. Core verifies the referenced heads and family digest, then records the merge as one durable REVIEW.
See the Branch merge contract and example or the Chinese version.
Package boundary
| Package | Responsibility |
|---|---|
fcop |
Protocol Core, Python API and setup/observe/diagnose CLI; no MCP dependency |
fcop-mcp |
Optional MCP stdio adapter exposing Core capabilities to MCP clients |
FCoP is not a task scheduler, agent runtime, LLM SDK, database, or automatic merge-decision engine. It records and validates coordination decisions made by the participating agents or humans.
中文简介
FCoP 4.0 已正式稳定发布，当前包版本为 4.0.3。
fcop 是 FCoP 协议的 Python Core，负责工作区、TASK/REPORT/ISSUE/REVIEW、
并发 Branch、显式收敛、原子合并、幂等与恢复。它不包含 MCP Server，也不会在
安装时自动初始化、迁移或修改现有项目。需要在 Codex、Cursor、Claude Desktop
等 MCP Host 中调用时，请另外安装 fcop-mcp。
Documentation
- Repository
- Protocol introduction
- 中文协议介绍
- Branch merge
- MCP tools reference
- Changelog
- Historical migrations
License
MIT — LICENSE
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file fcop-4.0.3.tar.gz.
File metadata
- Download URL: fcop-4.0.3.tar.gz
- Upload date:
- Size: 628.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2323147d5d740cc671f9a8219826b642bb37d997e02059819033c3842d1378db
|
|
| MD5 |
2b387da4ffeae0bc222d9aca3ccbc21e
|
|
| BLAKE2b-256 |
736bb4ba837dbeb509ff0d9620bfa2870f9e44a61588c95c25fe2c83e573e3db
|
File details
Details for the file fcop-4.0.3-py3-none-any.whl.
File metadata
- Download URL: fcop-4.0.3-py3-none-any.whl
- Upload date:
- Size: 721.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a974ff981cb829ab2af2ceb1b5fa82c275ffe7c8492a0642c215c3817bff244d
|
|
| MD5 |
0fa01b8a0d5dc882e3990fb16a4ea5dd
|
|
| BLAKE2b-256 |
ce5620189aea73eb2617bd38dfa76b21e9e9093db7546f88c04ddf7adcef4abc
|
