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

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 for a stdio MCP configuration.

Run Manually

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:

python -m stats_query_mcp.demo

Or, after installing the package:

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:

python -m stats_query_mcp.demo --stdio

You can override the defaults:

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