columna-server

The Columna MCP server (ADR-032 D8): a library of Manifolds exposed to AI agents over MCP, with one contract — every tool returns the same outcome/disclosure structure the Python API returns. This is the wedge product: the first metrics MCP server that can say "it depends."

What ships here, typed honestly. The packaged demo (Cascadia) is hand-authored, carries no SOURCE_MANIFOLD, and is classified ENTRY_LEGACY by admission: it demonstrates serving and the four moods, not the governed path. The governed artifact is firstlight (columna_server/governed/firstlight/) — a governed publication, a compiled execution image and the lowering receipt that binds them, admitted ENTRY_GOVERNED and exercised by standing tests. And this package consumes governed publications rather than producing them: the author → ratify → publish third of the lifecycle is not here, and no public governed authoring surface is open (topology record §§17.2–17.3).

Run

pip install columna-core columna-server
columna-server demo --play                    # the packaged demo: clarify -> refuse -> disclose -> serve
columna-server demo                           # serve the packaged demo over MCP stdio (no path args)
columna-server mcp --manifolds <dir>          # serve your own manifolds dir over stdio
columna-server mcp --manifolds <dir> --http :8000   # streamable-http, gated by COLUMNA_MCP_TOKEN

# Natural-language agent (a true MCP client over the server); needs the [agent] extra + a key:
pip install "columna-server[agent]"
ANTHROPIC_API_KEY=... columna-server agent    # chat REPL over the packaged demo

The agent turns natural language into a proposed Frame-QL query, spawns the server over stdio, and lets the four moods drive the conversation — it never touches the engine in-process. The model proposes, the planner disposes, the human decides (clarifies are relayed, never auto-picked; every number comes verbatim from the wire). See demos/agent_transcript.md. Model via COLUMNA_AGENT_MODEL (default claude-opus-4-8).

Richer run. The packaged demo ships a small (~330 KB) warehouse. To run the same benchmark Manifold over the full 4.7 MB warehouse (299,934 transactions), point --manifolds at a directory whose data.toml warehouse path is the repo's packages/columna-core/demos/warehouse.

From source (contributors): git clone https://github.com/datumwise/columna && cd columna, then pip install -e packages/columna-core -e "packages/columna-server[test]" and pytest packages/columna-server -q.

<dir> holds <id>/manifold.cml + data.toml (connector type + data path). Manifolds are parsed and connected once at startup.

Tools (five, read-only — no SQL, no writes)

frameql is "<columns> @ <anchor>" (e.g. "rate: revenue / level.last @ store, day"); the envelope is parsed here and every expression is delegated to columna-core — one expression dialect.

The contract

Outcomes are data (the four moods), and disclosures are structured {code, materiality, severity, category, detail, remedy, source, rel_error} via columna_core.disclosure_wire — the same serialization every surface shares. Clarify alternatives are mechanically substitutable (a universe pin carries apply: {"universe": U}).

See demos/mcp_claude_desktop.md for a Claude Desktop config and a real clarify → answer transcript.