Gera Data MCP server (@gera-services/mcp-gera-data)

Let any AI agent — Claude, ChatGPT-with-tools, Cursor, or any Model Context Protocol client — discover and query Gera's 30 attested open datasets, each with a cryptographically signed provenance attestation so a returned value can be cited and proven to come from a real, named, public-domain / OGL / CC-BY source, unaltered.

It is the agent-facing distribution surface for the Gera Data API (a model-B, AI-discoverability play): the same verified UK + US government / open data the API serves, exposed as MCP tools that run fully offline — the data is a committed on-disk snapshot, no backend, no network, no auth.

A Gera Systems product · gera.services

Tools

| Tool | What it does | |---|---| | list_datasets | Catalog of all datasets: id, title, source, source URL, licence, attribution, as-of period, row count, coverage, and the queryable column schema. Optional country filter (UK / US / all). Call this first. | | get_dataset | One dataset's full metadata (title, description, coverage, provenance, column schema, row count) + a compact attestation summary (content hash + key id). No rows. | | query_dataset | Verified rows with optional single-column filter, sort, and pagination — same semantics as the Data API. Number columns filter by exact match, string columns by case-insensitive substring. Returns the page + total / totalPages + dataset version + a ready-to-use cite_as string. Default page_size 50, max 500. | | get_attestation | The full signed Gera Vouch attestation for a dataset version: the claim (id, version, row count, SHA-256 content hash over the rows, source, licence, attribution, as-of, issuer), an Ed25519 signature, the public key, and the verification recipe. A proof-of-provenance receipt. | | get_vouch_public_key | The Ed25519 public key + recipe to verify any attestation — the same key the Gera Data API and the Gera Verify MCP publish. |

Every response carries the source attribution and a licence note. Missing / unknown datasets return a typed error listing the valid ids — the tools never fabricate a value.

Example agent flow

1. list_datasets({ country: "UK" }) → find uk-council-tax.
2. query_dataset({ id: "uk-council-tax", filter_column: "authority", filter_value: "Westminster", sort_by: "bandD", sort_dir: "asc" }) → the rows, with cite_as.
3. get_attestation({ id: "uk-council-tax" }) → the signed receipt; verify the Ed25519 signature against get_vouch_public_key and re-derive content_sha256 from the rows to prove the values were not altered.

Datasets exposed (30)

Snapshot of the Gera Data API registry — 19 UK + 11 US, 6,366 rows total.

UK (Open Government Licence v3.0, except Bank of England policy-rate data which is public-domain factual): council tax · benefits rates · childcare support · NHS charges · fuel prices · business rates · EV home-charging rate · road safety · EPC efficiency · food prices · food recalls · inflation (CPI) · interest rates · driving test · graduate salaries · student finance · NHS waits · farming stats · product recalls.

US (US-federal public domain — BLS, HUD, CMS, DoE, EIA, NHTSA, USDA, CPSC, FDA): salaries · rents · drug prices · college salaries · energy prices · gas prices · crash stats · farm stats · inflation · product recalls · food recalls.

Licensing. Every dataset is public-domain (US federal), Open Government Licence v3.0 (UK), or CC-BY — free to reuse with attribution. Each tool response returns the exact attribution string for the data it surfaces; reproduce it when you cite a value. Values are copied verbatim from the named source; any in-repo transform is recorded in the dataset's derivationNotes.

The authoritative list is whatever list_datasets returns at runtime; the catalog grows as the Data API registry does (see "Updating the snapshot").

Run it

Requires Node ≥ 20.

# from packages/mcp-gera-data
npm install          # @modelcontextprotocol/sdk + zod (already in the monorepo)
npm run build:data   # regenerate src/data/datasets.json from the Data API registry
npm run build        # tsc --noCheck + copy the snapshot into dist/
npm run smoke        # optional: in-process sanity check

# stdio (local MCP clients)
npm start            # = node bin/cli.js

# hosted (Streamable HTTP / SSE) — for remote clients & ChatGPT Apps
npm run start:http   # listens on PORT (default 3401) at POST /mcp; GET /health

Register with an MCP client (stdio)

Claude Desktop / Cursor mcpServers config:

{
  "mcpServers": {
    "gera-data": {
      "command": "npx",
      "args": ["-y", "@gera-services/mcp-gera-data"]
    }
  }
}

Hosted endpoint

The HTTP transport is stateless and ready to host behind a container (intended public endpoint: https://data.gera.services/mcp). GET /health is exempt from any bot-blocking (Lesson 5).

How the data is wired (no hand-copied rows)

The single source of truth is the Gera Data API registry at services/data-api/src/datasets/data/registry.ts. Rather than duplicate ~6,000 rows by hand, npm run build:data (scripts/build-data.mjs):

1. compiles only the Data API data/ folder (pure data + types, no NestJS) to a temp dir,
2. requires the compiled registry to read the live DATASETS array,
3. writes the full array to src/data/datasets.json (the committed snapshot).

The server loads that JSON snapshot at runtime, so the package is self-contained and builds in isolation. The query layer (src/data.ts) and attestation layer (src/attest.ts + src/sign.ts) are faithful mirrors of the Data API's datasets.service.ts / attestation.service.ts / common/vouch/gera-vouch.ts, so the MCP returns the same answers and issues byte-identical attestations that verify against the same Gera public key.

Updating the snapshot

When the Data API adds/changes datasets, re-run npm run build:data && npm run build. No tool code changes are needed — the tools are generic over the registry.

Build note (Lesson 11)

npm run build uses tsc --noCheck (the MCP SDK's recursive types can exhaust the V8 heap under a full type-check). npm run type-check (tsc --noEmit) runs the strict check separately and passes clean.

Honesty contract

A Gera Vouch signature proves Gera attested that this dataset version had this content hash, from this source, under this licence, as of issuance — nothing more. It is not a warranty of fitness for any purpose. Values are verbatim from the named public source; verify the signature and recompute the content hash yourself before relying on it.

Registering on MCP catalogs

server.json is the MCP server registry manifest (services.gera/mcp-gera-data, stdio, npm package @gera-services/mcp-gera-data). Follow-ups before public registration:

• Publish @gera-services/mcp-gera-data to npm (mirror mcp-gera-verify's PUBLISH.md flow).
• Submit server.json to the MCP registry and list it in the Gera AI-channel directories alongside the Gera Verify MCP.
• (Optional) Stand up the hosted HTTP endpoint at data.gera.services/mcp for ChatGPT Apps / remote clients — founder-gated (hosting cost).