# Statistics Query and Verification MCP

This repository contains a Python MCP server for answering questions about official statistics from a single user-supplied publication URL.

## Current Scaffold

- Scope-first flow: `check_query_scope(url, question)` is the intended first tool call
- Shared scope gate reused by retrieval tools before they return publication data
- HTML parsing for publication title, sections, and linked CSV/XLSX files
- CSV/XLSX loading helpers for tabular data retrieval

## Tool Surface

- `check_query_scope(url, question)`
- `get_publication_overview(url)`
- `get_publication_text(url, question, section_keyword=None)`
- `get_data_file(url, question, file_url, sheet_name=None, max_rows=100)`
- `search_publication(url, question, search_term, max_matches=20)`

## Local Setup

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .[dev]
```

## Run In VS Code

The workspace includes [.vscode/mcp.json](.vscode/mcp.json) for a stdio MCP configuration.

## Run Manually

```powershell
python -m stats_query_mcp.server
```

Set `STATS_QUERY_MCP_TRANSPORT` to `sse` or `streamable-http` when wiring a deployed transport.

## Demo Flow

Run the packaged demonstration against the ONS migration bulletin:

```powershell
python -m stats_query_mcp.demo
```

Or, after installing the package:

```powershell
stats-query-mcp-demo
```

The demo runs the full MCP flow in order:
- `check_query_scope`
- `get_publication_overview`
- `get_publication_text`
- `search_publication`
- `get_data_file`

It prints a small demonstration summary with the verified excerpt, source section, and an example data-table sample.

By default, the demo uses the registered MCP tool surface in-process so it is quick and reliable to run live. If you want the demo to go through a spawned stdio MCP server as well, use:

```powershell
python -m stats_query_mcp.demo --stdio
```

You can override the defaults:

```powershell
python -m stats_query_mcp.demo --question "What was long-term net migration in year ending December 2025?" --search-term "171,000"
```