Metadata-Version: 2.5
Name: fcop
Version: 4.0.5
Summary: FCoP protocol: official Python library — Project API, task/report/issue files, filename parsing, bundled rules. Uses PyYAML and jsonschema; not an MCP server.
Project-URL: Homepage, https://github.com/joinwell52-AI/FCoP
Project-URL: Repository, https://github.com/joinwell52-AI/FCoP
Project-URL: Issues, https://github.com/joinwell52-AI/FCoP/issues
Project-URL: Changelog, https://github.com/joinwell52-AI/FCoP/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/joinwell52-AI/FCoP/blob/main/docs/getting-started.en.md
Project-URL: MCP Tools Reference, https://github.com/joinwell52-AI/FCoP/blob/main/docs/mcp-tools.md
Author: FCoP Maintainers
License-Expression: MIT
License-File: LICENSE
Keywords: agent-coordination,agent-framework,fcop,file-based-protocol,llm-tools,multi-agent,protocol
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: jsonschema<5.0,>=4.0
Requires-Dist: pyyaml<7.0,>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# FCoP · Python Core

`fcop` is the official Python implementation of the **File-based Coordination
Protocol (FCoP)**. It records durable, reviewable coordination facts as UTF-8
Markdown documents with YAML front matter.

**Current version: 4.0.5.** This package is the protocol Core, Python API, and
local CLI. The optional [`fcop-mcp`](https://pypi.org/project/fcop-mcp/) package
is a thin adapter over this Core. Core remains the sole authority for protocol
facts, validation, state transitions, idempotency, locking, and recovery.

## Install

FCoP 4.0.5 supports Python 3.10–3.13.

```bash
python -m pip install "fcop==4.0.5"
```

Verify the installed distribution:

```bash
python -c "from importlib.metadata import version; from fcop import Project; print(version('fcop'), Project)"
```

## Base Protocol boundary

FCoP Core provides:

- Workspace identity and versioned protocol behavior.
- Four durable envelope types: TASK, REPORT, ISSUE, and REVIEW.
- Explicit lifecycle, attempt, relation, evidence, and authorization records.
- Branch families, explicit convergence, 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, Runtime, or network dependency.

Team models, Solo mode, ME or other fixed roles, seats, and Host sessions are
outside the Base Protocol. A Host, Profile, or Runtime may define such concepts,
but Core does not require them. Legacy compatibility is also a separate boundary
and does not redefine canonical 4.x behavior. FCoP Core can be used independently
of CodeFlowMu.

`init_workspace` and the matching Core workspace API initialize a pure FCoP v4
workspace. They do not create `AGENTS.md`, `CLAUDE.md`, Cursor rules, role files,
or session state.

## CLI — Setup, inspect, and diagnose

**CLI = Setup + Observe + Diagnose; MCP = Work.**

| Command | Purpose |
| --- | --- |
| `fcop init` | Initialize a pure FCoP workspace |
| `fcop status` | View workspace status |
| `fcop inspect` | Inspect TASK / REPORT / ISSUE / REVIEW |
| `fcop validate` | Validate protocol structure |
| `fcop tools` | Inspect the installed optional MCP catalog |
| `fcop doctor` | Diagnose installation, environment, and compatibility |
| `fcop version` | Show installed versions |
| `fcop spec` | Show specification and rule identity |
| `fcop migrate` | Explicitly plan or apply a legacy workspace migration |

Example:

```bash
python -m pip install fcop

fcop version
fcop doctor
fcop init --root ./my-project
fcop status --root ./my-project
fcop validate --root ./my-project

python -m pip install fcop-mcp
fcop tools
fcop tools merge_branches --json
```

Package installation does not initialize a repository, migrate a workspace,
deploy Host instructions, start an MCP server, or modify another application.
Canonical v4 workspace state belongs under `<project>/fcop/`.
`fcop doctor` does not access the network or modify Host configuration.

## Minimal Python example

```python
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"])
```

## Package boundary

| Package | Responsibility |
| --- | --- |
| `fcop` | Protocol Core, Python API, and setup/observe/diagnose CLI |
| `fcop-mcp` | Optional canonical MCP adapter exposing Core capabilities |

The 4.0.5 default MCP surface contains **25 Canonical MCP Tools** and **6
read-only Core Resources**. The
[MCP reference](https://github.com/joinwell52-AI/FCoP/blob/main/docs/mcp-tools.md)
is generated from its canonical manifest. Every entry from the historical
49-tool implementation surface has an explicit disposition in the
[4.0.5 migration guide](https://github.com/joinwell52-AI/FCoP/blob/main/docs/migration-4.0.5-mcp.md).

## 中文简介

FCoP 4.0.5 是 File-based Coordination Protocol 的官方 Python Core。
Core 是协议事实、校验和状态迁移的唯一权威；`fcop-mcp` 只是可选的薄适配层。
Base Protocol 不要求 Team、Solo、ME、seat 或 Host session，这些概念属于
Host、Profile 或 Runtime。Legacy compatibility 也不属于 canonical 4.x 路径。
`init_workspace` 初始化纯 FCoP v4 工作区，不生成 Host 指令或角色文件。
FCoP Core 可以脱离 CodeFlowMu 独立使用。

## Documentation

- [Repository](https://github.com/joinwell52-AI/FCoP)
- [Protocol introduction](https://github.com/joinwell52-AI/FCoP/blob/main/docs/getting-started.en.md)
- [中文协议入门](https://github.com/joinwell52-AI/FCoP/blob/main/docs/getting-started.md)
- [MCP tools reference](https://github.com/joinwell52-AI/FCoP/blob/main/docs/mcp-tools.md)
- [4.0.5 migration guide](https://github.com/joinwell52-AI/FCoP/blob/main/docs/migration-4.0.5-mcp.md)
- [Changelog](https://github.com/joinwell52-AI/FCoP/blob/main/CHANGELOG.md)

## License

MIT · [LICENSE](https://github.com/joinwell52-AI/FCoP/blob/main/LICENSE)
