# Maia

Build 2 of the Hermes stack: the **MCP server**.

Exposes the sqlite datasets produced by [zeus](../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](https://docs.astral.sh/uv/).

```bash
cd maia
uv sync
```

## Usage

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

```bash
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`](../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`](https://www.npmjs.com/package/mcp-remote)
does this:

```json
{
  "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`](../docs/client-setup.md) for details.

## MCP Inspector

[MCP Inspector](https://github.com/modelcontextprotocol/inspector) connects
directly to an MCP server over Streamable HTTP, with no client or bridge in
between.

Start maia first:

```bash
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`](../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
```