appflowy-mcp: Instructions file for Codex

AGENTS.md

Guidance for agents (and humans) working on appflowy-mcp.

Project layout

• src/appflowy_mcp/ — the package.
  • config.py — settings + token/scope parsing from env and config files.
  • appflowy.py — async AppFlowy REST/collab client.
  • access.py — token-scoped access control over workspaces and page subtrees.
  • blocks.py — Yjs/CRDT document decoding and block editing helpers.
  • server.py — FastMCP tools + entrypoint.
• tests/ — the test suite (one file per source module).

Commands

uv sync            # install runtime + dev dependencies
uv run pytest      # run all tests with the coverage gate
uv run ruff check  # lint

Definition of Done

A change is done only when all of the following hold:

1. 100% test coverage. Line and branch coverage of appflowy_mcp must be 100%. This is enforced by --cov-fail-under=100 in pyproject.toml; never lower it. New code ships with the tests that cover it. Genuinely unreachable lines (optional-import fallbacks, defensive raises after exhaustive loops) are excluded with an explicit # pragma: no cover and a one-line reason — not by relaxing the threshold.

2. One test = one small piece of behaviour. Each test exercises a single function or branch and asserts one thing. Do not bundle unrelated assertions into a "kitchen sink" test. Prefer many small tests over a few large ones.

3. Clear test names. A test's name states what it verifies, in the form test_<unit>_<behaviour> — e.g. test_scope_parse_empty_raises, test_request_reauthenticates_once_on_401. Reading the name alone should tell you what broke when it fails.

4. No superfluous comments. Tests should read as self-explanatory. Comments are only for non-obvious setup (e.g. why a CRDT document is shaped a certain way), never to restate what the code plainly does.

5. Lint passes. uv run ruff check is clean.

6. The pipeline gates on tests. The Docker image build needs: test (.github/workflows/docker.yml); a failing test or a coverage drop must block the image from being built. Do not work around this gate.