zigmo

Your business data, explained by an ape. zigmo is a semantic-layer engine for business metrics, exposed as an MCP server. Ask in plain words — "which countries drive our revenue?" — and an AI agent answers with governed numbers, the share of the total, and the exact SQL behind them. No dashboard required.

zig is the zigzag every metric draws over time (and a nod to sigma); mo is the monkey. Pronounced zig-mo. Part of the nxape family.

flowchart LR
    A[Online Retail II<br/>1.07M public lines] -->|make data| B[(DuckDB<br/>star schema)]
    S[semantic/model.yaml<br/>metrics + dimensions] --> C[compiler]
    C --> G[guardrails]
    G --> B
    M[MCP server<br/>4 tools] --> C
    U[Claude / any MCP client] <--> M

Why

Dashboards answer the questions someone predicted. Letting an LLM write SQL answers any question, but each answer may define "revenue" differently, cost an unbounded scan, or open an injection hole. zigmo sits in between:

• One meaning per metric. gross_revenue, return_rate and friends are defined once in semantic/model.yaml. Every answer uses the same definition.

• Agents ask for names, not SQL. The compiler turns metrics, dimensions and filters into one parameterized query, joining only the tables it needs.

• Guardrails by default. Read-only connection, allowlists, a cost pre-flight, a timeout and an audit log of every call.

• Evals that prove it. 15 business questions checked against hand-written oracle queries in CI, plus an optional eval where Claude answers them through the MCP tools.

Related MCP server: governed-analytics-agent

Quickstart

Requires uv.

git clone https://github.com/unprimathe/zigmo && cd zigmo
make setup     # install
make data      # download the dataset (45 MB) and build data/zigmo.duckdb (~2 s)
make test      # 30 unit and guardrail tests
make evals     # 15 business questions vs. oracle queries

Connect it to Claude Code:

claude mcp add zigmo -- uv --directory "$PWD" run zigmo-server

or to Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "zigmo": { "command": "uv",
  "args": ["--directory", "/absolute/path/to/zigmo", "run", "zigmo-server"] } } }

Then ask: "What share of gross revenue do our top 3 countries have?"

Tools

All four are annotated read-only.

Example

query_metrics(metrics=["gross_revenue"], dimensions=["country"], limit=3, with_share=true)

The response also carries the SQL that produced it:

SELECT co.country AS country,
       SUM(f.amount) FILTER (WHERE NOT f.is_return) AS gross_revenue,
       CAST((SUM(f.amount) FILTER (WHERE NOT f.is_return)) AS DOUBLE)
         / NULLIF(SUM(SUM(f.amount) FILTER (WHERE NOT f.is_return)) OVER (), 0) AS gross_revenue_share
FROM fact_sales f
JOIN dim_country co ON co.country_key = f.country_key
GROUP BY ALL
ORDER BY gross_revenue DESC NULLS LAST
LIMIT 3

The semantic model

Star schema: fact_sales (one row per invoice line, 1,021,252 rows) with dim_date, dim_product, dim_customer and dim_country. How returns, guest checkouts and non-merchandise lines are handled is in ADR 3.

Why these guardrails

Each one has a test in tests/. Details in ADR 4.

Evals

• make evals — deterministic, runs in CI. Each question in evals/questions.yaml has a semantic request and an independent, hand-written oracle query; the results must match. Breaking a metric definition on purpose turns the run red (7/15), which is how we know the eval protects something.

• make evals-llm — Claude answers each question using only the MCP tools; a question passes when its last query returns the oracle's rows. Needs Anthropic credentials and costs money, so it is not in CI.

Layout

semantic/model.yaml        the semantic model
src/zigmo/ingest.py        download + clean + star schema
src/zigmo/semantic_layer.py  model loading and validation
src/zigmo/compiler.py      request -> parameterized SQL
src/zigmo/engine.py        guardrails, execution, audit
src/zigmo/server.py        MCP server
tests/                     unit and guardrail tests on a hand-checkable fixture
evals/                     deterministic and LLM evals
docs/adr/                  architecture decisions

Data

Online Retail II by Daqing Chen, UCI Machine Learning Repository, doi:10.24432/C5CG6D, licensed CC BY 4.0. The data is downloaded at build time and not redistributed here.

License

Code: MIT. Built by Roland Sencial at nxape.