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.2. 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.2,<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 Project API with no MCP, LLM, or network dependency.

CLI v1: Setup + Observe + Diagnose

FCoP 4.0.2 provides nine commands: init, status, inspect, validate, tools, doctor, version, spec, migrate. CLI = Setup + Observe + Diagnose; MCP = Work.

pip install fcop==4.0.2
fcop version
fcop doctor
fcop init
fcop status

Use --root <path> for workspace commands. The eight non-migration commands support --json; fcop --help discovers the full surface. Observe/diagnose commands never fix, repair, migrate, create work records or configure a Host. Only explicit init and migration --apply may write. Bare fcop retains its historical migration guidance and exit 1; use fcop --help for help.

Exit codes: 0 success/valid, 1 internal failure, 2 invalid data/input, 3 unavailable/unsupported. An absent optional MCP package is reported explicitly by tools; Core remains independently usable. doctor warns, not installs it.

CLI reference / 中文 CLI 参考.

For MCP work, install fcop-mcp==4.0.2 in the same environment and use its client configuration and verification guide. Point the client at that environment's Python with -m fcop_mcp and explicitly set FCOP_PROJECT_DIR; run fcop tools to inspect the installed Tool Catalog.

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.2。 fcop 是 FCoP 协议的 Python Core，负责工作区、TASK/REPORT/ISSUE/REVIEW、并发 Branch、显式收敛、原子合并、幂等与恢复。它不包含 MCP Server，也不会在安装时自动初始化、迁移或修改现有项目。需要在 Codex、Cursor、Claude Desktop 等 MCP Host 中调用时，请另外安装 fcop-mcp。

Documentation

License

MIT — LICENSE

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fcop-4.0.2.tar.gz (643.0 kB view details)

Uploaded Sep 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fcop-4.0.2-py3-none-any.whl (744.0 kB view details)

Uploaded Sep 11, 2026 Python 3

File details

Details for the file fcop-4.0.2.tar.gz.

File metadata

Download URL: fcop-4.0.2.tar.gz
Upload date: Sep 11, 2026
Size: 643.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.12.9

File hashes

Hashes for fcop-4.0.2.tar.gz
Algorithm	Hash digest
SHA256	`3b07943b248d7b84b231118a0173a6920fbde6775488a182568604b0f7c68f55`
MD5	`61e425d738fdc4bf62603c46d1ac8e9e`
BLAKE2b-256	`d297826c9d776a4d93b6212d461cc2ed8cc98a0c5e5ed3025c57b639fd4a6cfd`

See more details on using hashes here.

File details

Details for the file fcop-4.0.2-py3-none-any.whl.

File metadata

Download URL: fcop-4.0.2-py3-none-any.whl
Upload date: Sep 11, 2026
Size: 744.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.12.9

File hashes

Hashes for fcop-4.0.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`0b9f4020c3bf4f3fb423cd28133389294a730652e8f577f00b77439ae4e6c577`
MD5	`152f4ae36c5bc796910a4424bcacde41`
BLAKE2b-256	`8a972644fb5d1fa1e7a80cc609d2d31a7d0b0a3bdf685488fba202819bd375c3`