fcop-mcp — MCP adapter for FCoP

mcp-name: io.github.joinwell52-AI/fcop

fcop-mcp exposes the official FCoP Python Core to Codex, Cursor, Claude Desktop, and other MCP clients. It is an optional adapter over the same protocol—not a second protocol implementation.

Current stable surface

FCoP 4.0 is Stable, Implemented and Released. Package version 4.0.2 provides:

49 tools
12 resources
4 resource templates
Python 3.10–3.13 support
Version-routed behavior for existing v3 and v4 workspaces

The original 46-tool surface remains available. The 4.0.1 Branch workflow adds:

Tool	Purpose
`create_branch`	Create a Branch TASK under a Root TASK for parallel work
`inspect_family`	Read the Root/Branch family, REPORT heads, readiness, and canonical family digest
`merge_branches`	Commit an explicit convergence decision through Core's atomic merge operation

Install

Install Core and the MCP adapter together in a dedicated virtual environment:

python -m pip install --upgrade \
  "fcop>=4.0.2,<4.1.0" \
  "fcop-mcp>=4.0.2,<4.1.0"

Verify both distributions:

python -c "from importlib.metadata import version; print('fcop', version('fcop')); print('fcop-mcp', version('fcop-mcp'))"
python -c "from fcop_mcp.server import mcp; print('fcop-mcp ready')"

fcop and fcop-mcp are released in lockstep within the same minor line. Do not mix incompatible minor versions.

Configure an MCP client

CLI = Setup + Observe + Diagnose; MCP = Work. Inspect this adapter's authoritative Tool Catalog without starting a server:

pip install fcop-mcp==4.0.2
fcop version
fcop doctor
fcop tools
fcop tools merge_branches --json

The public fcop_mcp.catalog.get_tool_catalog(name=None) query returns fresh, sorted name/disposition rows from disposition.TOOLS. It imports no MCP runtime, does not start a server and does not duplicate handler signatures. Unknown names raise KeyError. CLI Catalog, registry and real tools/list have equal sets; 4.0.2 does not add, remove or change any MCP work tool.

See the CLI reference.

A fixed virtual environment gives predictable startup and avoids importing a different editable fcop package from another project.

{
  "mcpServers": {
    "fcop": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "fcop_mcp"],
      "env": {
        "FCOP_PROJECT_DIR": "/absolute/path/to/repository"
      }
    }
  }
}

On Windows, command is the virtual environment's Scripts\\python.exe. Restart the MCP host after changing its configuration.

Installation only installs the packages. It does not initialize a workspace, migrate existing files, deploy rules, publish anything, or modify another application.

Parallel Branch workflow

create_branch → agents write REPORTs → inspect_family → merge_branches

A PM, coordinating agent, or authorized human supplies the convergence decision. FCoP does not invent that decision. Core validates the exact REPORT heads and family digest, uses a family-scoped cross-process lock, and records one durable REVIEW. An exact retry is idempotent; a conflict fails without partial writes.

Core owns validation, persistence, locking, and recovery. The MCP adapter validates the tool request and forwards it to the public Core API.

See the Branch merge contract and example or the Chinese version.

Authority and safety

Profile and evaluator authority must be adopted by the trusted application when the server starts. A role name, TASK field, Profile document, or tool argument does not grant authority by itself.

FCoP uses a local stdio transport by default. Relay support is an explicit optional extra and is never activated merely because a WebSocket dependency or environment variable is present.

Package boundary

Package	Responsibility
`fcop`	Protocol Core, filesystem model, validation, atomic persistence, and recovery
`fcop-mcp`	MCP tools and resources that call the Core API

You need fcop-mcp when an MCP client must operate FCoP through tools. Python applications using Project directly only need fcop.

中文简介

FCoP 4.0 已正式稳定发布，当前包版本为 4.0.2。 fcop-mcp 是 FCoP Core 的 MCP 适配层，当前提供 49 个 Tools、12 个 Resources 和 4 个 Templates。4.0.1 新增 create_branch、 inspect_family、merge_branches，让 MCP Host 能创建并发 Branch、检查 REPORT 家族并提交原子合并。合并判断由 PM、Agent 或人类给出，Core 负责校验、落盘、幂等和崩溃恢复。

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_mcp-4.0.2.tar.gz (107.2 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_mcp-4.0.2-py3-none-any.whl (116.0 kB view details)

Uploaded Sep 11, 2026 Python 3

File details

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

File metadata

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

File hashes

Hashes for fcop_mcp-4.0.2.tar.gz
Algorithm	Hash digest
SHA256	`39c4a06758f78ef9c0d5dff235cb7e00950e626e24531e269f00ca941c072122`
MD5	`2bc2f0d26e76ad5348c24ae3899e9bf6`
BLAKE2b-256	`c6013a0e9a30e2d88919ca79de8faf046b2a2115e0ab81625e617bf2e1378618`

See more details on using hashes here.

File details

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

File metadata

Download URL: fcop_mcp-4.0.2-py3-none-any.whl
Upload date: Sep 11, 2026
Size: 116.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_mcp-4.0.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a09e3227452a3d43ed00a5feb551145ca6c73e0588de2230b9ac50e2a954fbcc`
MD5	`e845b854917b1403e77b38a6c17da2d7`
BLAKE2b-256	`065f49280774a0112118df26eccce04d439f317a75fccf8a429d26cf450a55fa`