# open-parliament-mcp

A thin MCP connector to the UK Parliament's public APIs and the Members OData
endpoint. It exposes five generic tools rather than modelling endpoints; the
"how to use each source" knowledge lives in playbooks.

## Tools

- `list_apis` — list the available Parliament data sources.
- `describe_api(api, detail?, path?)` — show a source's endpoints (compact by
  default; `detail:"full"` for the raw spec; `path` to filter). For the OData
  source, lists collections / returns `$metadata`.
- `call_api(api, path, query?)` — GET an endpoint and return JSON. The host is
  fixed by the source id (allowlist); read-only.
- `list_playbooks` / `get_playbook(name)` — procedural advice.

## Running

```bash
npm install
npm run build
# stdio (Claude Desktop / Claude Code):
MCP_TRANSPORT=stdio node build/index.js
# streamable HTTP (default), port 3401:
node build/index.js
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `MCP_TRANSPORT` | `http` | `http` or `stdio`. |
| `PORT` | `3401` | HTTP port. |
| `CF_ACCESS_TEAM_DOMAIN`, `CF_ACCESS_AUD` | _(unset)_ | Enable Cloudflare Access origin verification. |
| `PLAYBOOKS_REPO` | `brynmrgn/open-parliament-mcp` | GitHub repo for live playbooks. |
| `PLAYBOOKS_REF` | `main` | Git ref for playbooks. |

Playbooks are fetched live from the `playbooks/` folder of `PLAYBOOKS_REPO`,
falling back to the copy bundled in the image when GitHub is unreachable.

## Deployment

See [`docs/deployment.md`](docs/deployment.md) for running the container
behind a Cloudflare Tunnel and gating it for Claude with Cloudflare Access
Managed OAuth.

## Data sources

UK Parliament public APIs (read-only, no key required). See `list_apis` for
the full set. This connector is unaffiliated with UK Parliament; cite results
against the originating API.