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."

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)

tool	touches data?	returns
`list_manifolds()`	no	id, name, description, measure count, universes
`describe_manifold(manifold_id)`	no	dimensions/levels, edges (+ lineage), universes (+ predicate), measure index
`describe_measure(manifold_id, measure)`	no	family triple, per-member anchors, dtype, v-anchor `{universe, grain}`, m-anchor, provenance
`query(manifold_id, frameql, universe?)`	yes	the wire contract (serve/disclose/clarify/refuse/error)
`explain(manifold_id, frameql, universe?)`	no (`fetches_delta: 0`)	the would-be outcome + disclosures

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.

Development Status
- 4 - Beta
License
- OSI Approved :: Apache Software License
Programming Language
- Python :: 3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

columna_server-0.8.0.tar.gz (750.1 kB view details)

Uploaded Jul 26, 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.

columna_server-0.8.0-py3-none-any.whl (736.1 kB view details)

Uploaded Jul 26, 2026 Python 3

File details

Details for the file columna_server-0.8.0.tar.gz.

File metadata

Download URL: columna_server-0.8.0.tar.gz
Upload date: Jul 26, 2026
Size: 750.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for columna_server-0.8.0.tar.gz
Algorithm	Hash digest
SHA256	`b8381eb7132e3397b494a254dea69d8a5d89ba69afcce699fe58a12ee3d9aba8`
MD5	`14decfd008d8a80b91b5b873f740aed8`
BLAKE2b-256	`641f89408dd8be983e083a9cc81793f81a7282a710f5d59f819671960d3665f7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for columna_server-0.8.0.tar.gz:

Publisher: publish.yml on datumwise/columna

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: columna_server-0.8.0.tar.gz
- Subject digest: b8381eb7132e3397b494a254dea69d8a5d89ba69afcce699fe58a12ee3d9aba8
- Sigstore transparency entry: 2256649077
- Sigstore integration time: Jul 26, 2026
Source repository:
- Permalink: datumwise/columna@b342bd39378aba9756c71854ab3f90a63f4d6e0a
- Branch / Tag: refs/tags/v0.13.0
- Owner: https://github.com/datumwise
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@b342bd39378aba9756c71854ab3f90a63f4d6e0a
- Trigger Event: release