cma-mcp

The Model Context Protocol layer for cma, an executable compound practice loop: capture failures, surface them at the moment of action, track decisions and rejections, and check whether warnings actually prevented repeats.

cma-mcp wraps the canonical cma command-line tool and exposes its seven primitives to MCP-compatible AI clients. It does not reimplement the loop; it shells out to the cma binary, so it never diverges from the reference implementation.

Status

pip install cma-mcp installs the latest release from PyPI. The release history is in CHANGELOG.md.

What this is

Most MCP servers expose new capability. cma-mcp exposes an existing capability (bash cma's seven primitives) to a wider set of environments: Claude Desktop, Cursor, Cline, Continue.dev, and any other MCP-compatible client. The contribution is reach. Drift is the named enemy: cma-mcp invokes the canonical bash cma binary as a subprocess for every captured action, so cma-mcp picks up cma's evolution automatically and never diverges from the 1.0 reference implementation.

Quickstart

cma-mcp shells out to the cma command-line tool, so that binary must be installed and on your PATH first. Confirm it:

cma --help

Then install cma-mcp:

pip install cma-mcp

The cma-mcp console script lands on PATH after install. Confirm:

cma-mcp --version

Point your MCP client at the installed entry point. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "cma": {
      "command": "cma-mcp"
    }
  }
}

Restart the client. Then in any conversation: "Record a miss: I claimed verified without testing the cross-tenant write path", or "What active rejections do I have?", or "What does cma stats show for prevention/miss ratio over the last 30 days?"

For Cursor, Cline, Continue.dev, and other MCP-compatible clients, the same pattern applies (point the client at the cma-mcp command; the stdio handshake runs).

What it exposes

Seven tools mirroring bash cma's seven primitives:

Four resources for read-only context:

Protocol

cma-mcp speaks the current Model Context Protocol and negotiates the revision with each client: it echoes the revision the client requests when it supports it (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) and otherwise offers its newest. Transport is stdio.

Three-section payload

Every tool response and resource read returns a JSON payload with three top-level sections:

{
  "analysis":       { ... data and stdout },
  "agent_guidance": { what to tell the user, how to cite },
  "provenance":     { server_version, protocol_version, license, cost_usd: 0.0, ... }
}

Tool calls also return this payload as structuredContent (validated against each tool's outputSchema) for MCP clients on protocol 2025-06-18 or newer, alongside the text form older clients read.

The agent_guidance and provenance sections exist because an agent passing cma-mcp output to a user without attribution would strip the reproducibility that makes the loop's evidence worth citing. Surfacing "how to cite faithfully" inside the payload is the structure that carries that integrity forward. Adversarial tests in tests/test_payload_determinism.py pin the structure.

Approach

Subprocess over reimplementation. cma-mcp invokes bash cma as a subprocess for every captured action. cma-mcp does not reimplement cma's seven primitives in Python; that is a deliberate subprocess-over-reimplementation decision.

Methodology-agnostic substrate. cma stores --fm (failure mode) as an opaque string. cma-mcp does not bundle any methodology's failure-mode catalog. You tag captures with your methodology's own vocabulary by passing the tag through; for autoclassification, set CMA_FM_CLASSIFIER per cma's plugin convention.

No external runtime dependencies. cma-mcp implements MCP directly in-repo using JSON-RPC 2.0 over stdio. No third-party MCP SDK; no pip-installed runtime requirements beyond the Python standard library. (Test-time deps: pytest.)

Platform support

Linux and macOS native. On Windows, run cma-mcp under WSL because cma-mcp shells out to the bash cma binary. Routing every tool call through the same canonical binary on every platform is how cma-mcp avoids drift; a parallel Python implementation would require keeping two surface definitions in sync forever. If you run an MCP-compatible AI client on Windows, you likely already have WSL available.

Install fingerprint

cma-mcp --version

Emits a one-line JSON fingerprint with server_version, protocol_version, git_sha (with +dirty flag if the working tree has uncommitted changes), cma_binary_version (probed from cma --version), python version, and script path. Lets you confirm the cma-mcp install configured in your MCP client is the expected one.

Offline sanity check

cma-mcp --test

Prints the full three-section payload for a cma_stats (default view) call against your ~/.cma/ data. Useful to verify pipeline wiring and that the cma binary is reachable.

Documentation

In the repository:

• CHANGELOG.md: cma-mcp release history
• docs/MCP_SERVER.md: protocol reference
• docs/ARCHITECTURE.md: module layout, data flow, contracts
• docs/FAQ.md: conceptual questions, install gotchas, cross-client config
• docs/TROUBLESHOOTING.md: symptoms and fixes

The installed wheel carries LICENSE and NOTICE in its dist-info metadata (Apache-2.0 attribution); the docs above live in the source repository.

Running tests

From this directory:

pip install -e .[test]
python3 -m pytest -q

The suite covers MCP protocol conformance, three-section payload determinism, JSONL parsing tolerance, and subprocess-wrapper isolation (argv-array discipline, timeout discipline). Tests that require the bash cma binary skip when it is not on PATH.

Issues

Bug reports, feature requests, and security reports: hello@clarethium.com.