Maia

Build 2 of the Hermes stack: the MCP server.

Exposes the sqlite datasets produced by zeus as MCP tools/resources, so an MCP client (e.g. Claude Desktop) can explore and query them. Transport is Streamable HTTP.

Install

Requires uv.

cd maia
uv sync

Usage

Generate data with zeus first (see ../zeus), then point maia at its output directory:

cd zeus && uv run zeus generate patient_history -n 500 --seed 42 -f sqlite
cd zeus && uv run zeus generate pharma_sales -n 20000 --seed 42 -f sqlite

cd maia && uv run maia serve --data-dir ../zeus/output --host 127.0.0.1 --port 8000

--data-dir defaults to $MAIA_DATA_DIR or ./output. It scans <data_dir>/<use_case>/<use_case>.db — each subdirectory with a .db file becomes a queryable "dataset" — and re-scans on every call, so newly generated datasets show up without restarting the server.

Tools

Tool	Purpose
list_datasets()	List datasets and their tables
list_tables(dataset)	Tables + row counts for a dataset
describe_table(dataset, table)	Columns (name + inferred type) + one sample row
get_table(dataset, table, limit=100, offset=0)	Paginated raw rows, no SQL needed
query(dataset, sql, limit=200)	Arbitrary read-only SQL (SELECT/WITH only)

Also one resource template, maia://{dataset}/schema, returning the full table/column listing for a dataset as JSON.

For example prompts and Claude Desktop configuration, see ../docs/client-setup.md.

All access is strictly read-only: the sqlite connection itself is opened in mode=ro, so writes fail at the DB layer even if query's SQL-prefix check were somehow bypassed.

Claude Desktop setup

Claude Desktop's claude_desktop_config.json launches MCP servers over stdio, so an HTTP server needs a bridge — mcp-remote does this:

{
  "mcpServers": {
    "maia": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Start maia serve first, then restart Claude Desktop to pick up the config. See ../docs/client-setup.md for details.

MCP Inspector

MCP Inspector connects directly to an MCP server over Streamable HTTP, with no client or bridge in between.

Start maia first:

cd maia
uv run maia serve --data-dir ../zeus/output --host 127.0.0.1 --port 8000

Then, in another terminal, launch Inspector against it. See ../docs/client-setup.md (Step 4) for the full walkthrough (interactive UI + scriptable CLI mode with examples).

Layout

maia/
├── pyproject.toml
├── src/maia/
│   ├── data.py      # dataset discovery + read-only sqlite access (no MCP dependency)
│   ├── server.py    # FastMCP instance: tools + resource
│   └── cli.py       # typer CLI: `maia serve`
└── tests/
    └── test_data.py