statsmapped-mcp 0.1.0__tar.gz

statsmapped_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Triggers on creating a GitHub Release (developer's choice, 2026-09-20) -- draft a
+# release with a version tag and a line or two of notes, and this builds and publishes
+# automatically. Uses PyPI's Trusted Publishing (OIDC): no API token is stored as a
+# secret anywhere -- PyPI trusts this exact repo + workflow file + environment
+# combination directly, configured once on PyPI's own "Publishing" settings page.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Matches the "Environment name" field on PyPI's trusted-publisher form -- set that
+    # field to "pypi" too (or change both to match) when registering the publisher.
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing; no other permission needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

statsmapped_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+.env

statsmapped_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StatsMapped
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

statsmapped_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: statsmapped-mcp
+Version: 0.1.0
+Summary: MCP server exposing StatsMapped's public data API for Ireland and the UK (housing, crime, health, economy, social welfare, by county/local authority) as tools for AI agents.
+Project-URL: Homepage, https://statsmapped.com
+Project-URL: API docs, https://statsmapped.com/openapi.json
+Project-URL: Source, https://github.com/ActiveGuy/statsmapped-mcp
+Author-email: StatsMapped <feedback@statsmapped.com>
+License: MIT
+License-File: LICENSE
+Keywords: ireland,mcp,model-context-protocol,open-data,statistics,uk,united-kingdom
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0.0
+Description-Content-Type: text/markdown
+
+# statsmapped-mcp
+
+An [MCP](https://modelcontextprotocol.io) server exposing [StatsMapped](https://statsmapped.com)'s
+public API as tools for AI agents (Claude Desktop, Cursor, and any other MCP client).
+
+StatsMapped tracks public data for Ireland (by county) and the UK (by local authority) — housing,
+crime, health, the economy and social welfare — from official publishers (CSO, PSRA, Central Bank
+of Ireland, DHLGH, NTPF, the Office of Government Procurement, EU Publications Office for Ireland;
+ONS/HM Land Registry/Nomis/DfE/DfT for the UK), each figure carrying its own caveats. This
+package lets an agent query that data directly as tool calls instead of crawling and parsing
+web pages. Every tool below takes a `country` argument (`"ireland"` or `"united-kingdom"`,
+default `"ireland"`) — the two countries track genuinely different datasets and geography levels,
+so call `list_datasets`/`list_areas` for the country you actually want rather than assume
+Ireland's defaults apply.
+
+This is a thin client. It calls StatsMapped's already-public, unauthenticated HTTPS API
+(documented at [statsmapped.com/openapi.json](https://statsmapped.com/openapi.json)); no API key
+is needed for anything below. Runs on your own machine over stdio by default (the recommended way
+to use it today) -- see [Why stdio](#why-stdio-not-a-hosted-server-by-default) for a hosted
+`streamable-http` mode this package also supports, and the real tradeoff that comes with it.
+
+## Install
+
+Not yet published to PyPI. Once it is, install will be:
+
+```bash
+pip install statsmapped-mcp
+```
+
+## Configure
+
+Add to your MCP client's config (for Claude Desktop, `claude_desktop_config.json`; Cursor uses an
+equivalent `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "statsmapped": {
+      "command": "statsmapped-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+Every tool takes a `country` argument (`"ireland"` or `"united-kingdom"`, default `"ireland"`) —
+Ireland and the UK track different datasets and geography levels, so call `list_datasets`/
+`list_areas` for the country you want rather than assume Ireland's defaults apply.
+
+- **`list_datasets(country="ireland")`** — every stat StatsMapped tracks for one country, with its
+  key, label, and which geography levels it's published at. Start here.
+- **`list_areas(level="county", country="ireland")`** — every geography at one boundary level.
+  `level` defaults to Ireland's 26 counties; the UK's own primary level is `"lad"` (local
+  authority districts), not `"county"` — other levels exist per country too (Ireland's
+  `local_authority`/`garda_division` among them).
+- **`list_area_datasets(area_id, country="ireland")`** — every dataset available for one area
+  (e.g. `"county:kerry"` for Ireland, `"uk:lad:e09000033"` for the UK), with its latest figure
+  and year-on-year change. Caveats are projected to label + severity only, not full text — the
+  point is deciding which datasets matter before paying for the full detail on any one of them.
+- **`get_dataset_for_area(area_id, dataset, history_months=0, country="ireland")`** — full detail
+  on one dataset in one area: a written summary, full caveat text, and (optionally) recent
+  history.
+- **`rank_areas(stat_key, level="county", country="ireland")`** — every area at one level, ranked
+  by its latest figure for one stat, highest first.
+- **`list_comparisons(country="ireland")`** — every registered cross-dataset comparison pair for
+  one country (e.g. "median sale price vs new dwelling completions per 1,000 residents"). A
+  small, hand-curated set, not an arbitrary-pair engine.
+- **`get_comparison(pair_key, country="ireland")`** — full detail for one registered pair: each
+  axis's label/unit/publisher, the correlation stats (r, rho, a leave-one-out sensitivity range),
+  and caveats. `pair_key` comes from `list_comparisons(country=...)` for the same country.
+- **`check_comparability(stat_key_a, stat_key_b, country="ireland")`** — does StatsMapped have a
+  registered, hand-vetted comparison between these two stats? Registry-backed only — never
+  computes a fresh correlation for an arbitrary pair; `comparable: false` is a normal result for
+  most pairs, not an error.
+- **`explain_metric(stat_key, country="ireland")`** — definition, methodology and standing caveats
+  for one stat, never a current figure. Use this when the question is about what a metric means or
+  how it's measured, not about one area's value.
+
+## Why stdio, not a hosted server, by default
+
+StatsMapped runs on a single free-tier instance. A remote MCP endpoint hosted there would let an
+agent's own multi-area query pattern (calling the same tool once per area, in a loop) reproduce
+exactly the load pattern that has already caused timeouts on that instance under a large
+geography fan-out. Running over stdio means every call goes through your own network connection
+to the same public HTTPS API this package's tools call directly, with no shared bottleneck --
+each user's own machine makes the HTTP calls, so N users' traffic is naturally spread across N
+source IPs, not funnelled through one.
+
+`server.py` also supports a real hosted `streamable-http` mode (`MCP_TRANSPORT=streamable-http`)
+for a deployment that accepts that tradeoff -- StatsMapped's public API is itself rate-limited
+per source IP (600 requests/hour), but a hosted MCP endpoint proxies every remote user's calls
+through ONE shared egress IP, so all remote users of a hosted endpoint would share that one
+bucket rather than each getting their own. A StatsMapped-hosted endpoint is live at `https://mcp.statsmapped.com`
+(Streamable HTTP) -- confirmed responding correctly, no separate install needed for a client
+that speaks Streamable HTTP directly.
+
+## Development
+
+```bash
+pip install -e .
+python tests/test_client.py
+```
+
+The test suite runs against the real live API (`https://statsmapped.com` by default, or
+`STATSMAPPED_MCP_BASE_URL` if set) — read-only GETs only, nothing here writes any data or needs
+a key.
+
+## Releasing
+
+Publishing to PyPI happens automatically via `.github/workflows/publish.yml` on creating a
+GitHub Release — no API token is stored anywhere. It uses
+[PyPI's Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): PyPI is told,
+once, to trust this exact repo + workflow file + GitHub environment (`pypi`) combination, via
+PyPI's own "Publishing" settings page under this project. To release: bump `version` in
+`pyproject.toml`, commit, then draft a GitHub Release with a matching tag (e.g. `v0.2.0`).
+
+## Licence
+
+MIT for this package. The underlying data keeps each publisher's own licence — see
+[statsmapped.com/ireland/sources](https://statsmapped.com/ireland/sources) for Ireland's own
+publisher/licence detail before reusing any figure outside of querying it through an agent (a UK
+equivalent page doesn't exist yet — check each UK tool response's own `caveats`/`sources` fields
+in the meantime).

statsmapped_mcp-0.1.0/README.md

@@ -0,0 +1,124 @@
+# statsmapped-mcp
+
+An [MCP](https://modelcontextprotocol.io) server exposing [StatsMapped](https://statsmapped.com)'s
+public API as tools for AI agents (Claude Desktop, Cursor, and any other MCP client).
+
+StatsMapped tracks public data for Ireland (by county) and the UK (by local authority) — housing,
+crime, health, the economy and social welfare — from official publishers (CSO, PSRA, Central Bank
+of Ireland, DHLGH, NTPF, the Office of Government Procurement, EU Publications Office for Ireland;
+ONS/HM Land Registry/Nomis/DfE/DfT for the UK), each figure carrying its own caveats. This
+package lets an agent query that data directly as tool calls instead of crawling and parsing
+web pages. Every tool below takes a `country` argument (`"ireland"` or `"united-kingdom"`,
+default `"ireland"`) — the two countries track genuinely different datasets and geography levels,
+so call `list_datasets`/`list_areas` for the country you actually want rather than assume
+Ireland's defaults apply.
+
+This is a thin client. It calls StatsMapped's already-public, unauthenticated HTTPS API
+(documented at [statsmapped.com/openapi.json](https://statsmapped.com/openapi.json)); no API key
+is needed for anything below. Runs on your own machine over stdio by default (the recommended way
+to use it today) -- see [Why stdio](#why-stdio-not-a-hosted-server-by-default) for a hosted
+`streamable-http` mode this package also supports, and the real tradeoff that comes with it.
+
+## Install
+
+Not yet published to PyPI. Once it is, install will be:
+
+```bash
+pip install statsmapped-mcp
+```
+
+## Configure
+
+Add to your MCP client's config (for Claude Desktop, `claude_desktop_config.json`; Cursor uses an
+equivalent `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "statsmapped": {
+      "command": "statsmapped-mcp"
+    }
+  }
+}
+```
+
+## Tools
+
+Every tool takes a `country` argument (`"ireland"` or `"united-kingdom"`, default `"ireland"`) —
+Ireland and the UK track different datasets and geography levels, so call `list_datasets`/
+`list_areas` for the country you want rather than assume Ireland's defaults apply.
+
+- **`list_datasets(country="ireland")`** — every stat StatsMapped tracks for one country, with its
+  key, label, and which geography levels it's published at. Start here.
+- **`list_areas(level="county", country="ireland")`** — every geography at one boundary level.
+  `level` defaults to Ireland's 26 counties; the UK's own primary level is `"lad"` (local
+  authority districts), not `"county"` — other levels exist per country too (Ireland's
+  `local_authority`/`garda_division` among them).
+- **`list_area_datasets(area_id, country="ireland")`** — every dataset available for one area
+  (e.g. `"county:kerry"` for Ireland, `"uk:lad:e09000033"` for the UK), with its latest figure
+  and year-on-year change. Caveats are projected to label + severity only, not full text — the
+  point is deciding which datasets matter before paying for the full detail on any one of them.
+- **`get_dataset_for_area(area_id, dataset, history_months=0, country="ireland")`** — full detail
+  on one dataset in one area: a written summary, full caveat text, and (optionally) recent
+  history.
+- **`rank_areas(stat_key, level="county", country="ireland")`** — every area at one level, ranked
+  by its latest figure for one stat, highest first.
+- **`list_comparisons(country="ireland")`** — every registered cross-dataset comparison pair for
+  one country (e.g. "median sale price vs new dwelling completions per 1,000 residents"). A
+  small, hand-curated set, not an arbitrary-pair engine.
+- **`get_comparison(pair_key, country="ireland")`** — full detail for one registered pair: each
+  axis's label/unit/publisher, the correlation stats (r, rho, a leave-one-out sensitivity range),
+  and caveats. `pair_key` comes from `list_comparisons(country=...)` for the same country.
+- **`check_comparability(stat_key_a, stat_key_b, country="ireland")`** — does StatsMapped have a
+  registered, hand-vetted comparison between these two stats? Registry-backed only — never
+  computes a fresh correlation for an arbitrary pair; `comparable: false` is a normal result for
+  most pairs, not an error.
+- **`explain_metric(stat_key, country="ireland")`** — definition, methodology and standing caveats
+  for one stat, never a current figure. Use this when the question is about what a metric means or
+  how it's measured, not about one area's value.
+
+## Why stdio, not a hosted server, by default
+
+StatsMapped runs on a single free-tier instance. A remote MCP endpoint hosted there would let an
+agent's own multi-area query pattern (calling the same tool once per area, in a loop) reproduce
+exactly the load pattern that has already caused timeouts on that instance under a large
+geography fan-out. Running over stdio means every call goes through your own network connection
+to the same public HTTPS API this package's tools call directly, with no shared bottleneck --
+each user's own machine makes the HTTP calls, so N users' traffic is naturally spread across N
+source IPs, not funnelled through one.
+
+`server.py` also supports a real hosted `streamable-http` mode (`MCP_TRANSPORT=streamable-http`)
+for a deployment that accepts that tradeoff -- StatsMapped's public API is itself rate-limited
+per source IP (600 requests/hour), but a hosted MCP endpoint proxies every remote user's calls
+through ONE shared egress IP, so all remote users of a hosted endpoint would share that one
+bucket rather than each getting their own. A StatsMapped-hosted endpoint is live at `https://mcp.statsmapped.com`
+(Streamable HTTP) -- confirmed responding correctly, no separate install needed for a client
+that speaks Streamable HTTP directly.
+
+## Development
+
+```bash
+pip install -e .
+python tests/test_client.py
+```
+
+The test suite runs against the real live API (`https://statsmapped.com` by default, or
+`STATSMAPPED_MCP_BASE_URL` if set) — read-only GETs only, nothing here writes any data or needs
+a key.
+
+## Releasing
+
+Publishing to PyPI happens automatically via `.github/workflows/publish.yml` on creating a
+GitHub Release — no API token is stored anywhere. It uses
+[PyPI's Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): PyPI is told,
+once, to trust this exact repo + workflow file + GitHub environment (`pypi`) combination, via
+PyPI's own "Publishing" settings page under this project. To release: bump `version` in
+`pyproject.toml`, commit, then draft a GitHub Release with a matching tag (e.g. `v0.2.0`).
+
+## Licence
+
+MIT for this package. The underlying data keeps each publisher's own licence — see
+[statsmapped.com/ireland/sources](https://statsmapped.com/ireland/sources) for Ireland's own
+publisher/licence detail before reusing any figure outside of querying it through an agent (a UK
+equivalent page doesn't exist yet — check each UK tool response's own `caveats`/`sources` fields
+in the meantime).

statsmapped_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "statsmapped-mcp"
+version = "0.1.0"
+description = "MCP server exposing StatsMapped's public data API for Ireland and the UK (housing, crime, health, economy, social welfare, by county/local authority) as tools for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "StatsMapped", email = "feedback@statsmapped.com" }]
+keywords = ["mcp", "model-context-protocol", "ireland", "united-kingdom", "uk", "open-data", "statistics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    # server.py imports mcp.server.mcpserver.MCPServer, which only exists in mcp 2.x
+    # (FastMCP was renamed to MCPServer there) -- 1.2.0 would install and fail at import time.
+    # Upper-bounded at <3: this dependency has already broken its own public API once
+    # (the FastMCP -> MCPServer rename between majors), and an unbounded pin means a
+    # future mcp 3.x silently breaks every `pip install statsmapped-mcp` done after it
+    # lands, on a package with no maintainer actively watching for that (api-product-
+    # consultant, 2026-09-19).
+    "mcp>=2.0.0,<3",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://statsmapped.com"
+"API docs" = "https://statsmapped.com/openapi.json"
+Source = "https://github.com/ActiveGuy/statsmapped-mcp"
+
+[project.scripts]
+statsmapped-mcp = "statsmapped_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/statsmapped_mcp"]

statsmapped_mcp-0.1.0/src/statsmapped_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""statsmapped-mcp: an MCP server exposing StatsMapped's public API as tools."""
+
+__version__ = "0.1.0"

statsmapped_mcp-0.1.0/src/statsmapped_mcp/client.py

@@ -0,0 +1,348 @@
+"""
+Pure HTTP-calling and response-shaping logic for the 7 MCP tools, kept separate
+from `server.py`'s MCP/decorator wiring so it can be unit-tested as plain
+functions (no MCP runtime needed) -- same "logic separate from framework
+plumbing" split the parent StatsMapped project itself uses throughout
+`databeat/api.py`.
+
+Talks ONLY to StatsMapped's already-public, unauthenticated HTTPS API
+(https://statsmapped.com/api/v1/*, documented at /openapi.json) -- this package
+has no access to and no dependency on the StatsMapped repository's own database,
+source code, or internals. It is a thin client an AI agent runs on the user's
+own machine (stdio transport), calling the same API the site's own front end
+does.
+
+BASE_URL is overridable via the STATSMAPPED_MCP_BASE_URL environment variable --
+mainly so this package's own tests can point at a local/staging instance rather
+than hammering production on every test run, and so a user who ever needs to
+point this at a different deployment (a future country, a self-hosted mirror)
+can do so without a code change.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+import httpx
+
+BASE_URL = os.environ.get("STATSMAPPED_MCP_BASE_URL", "https://statsmapped.com")
+TIMEOUT_SECONDS = 20.0
+# Read from the installed package's own metadata rather than a hardcoded literal --
+# a hardcoded string duplicating pyproject.toml's version drifts on the first release
+# after this file stops being touched (api-product-consultant, 2026-09-19). Falls back
+# to "dev" for an editable/uninstalled checkout rather than raising.
+try:
+    _PKG_VERSION = version("statsmapped-mcp")
+except PackageNotFoundError:
+    _PKG_VERSION = "dev"
+USER_AGENT = f"statsmapped-mcp/{_PKG_VERSION} (+https://statsmapped.com)"
+
+# 2026-08-30 (developer question -> api-product-consultant): nothing in this package
+# told the calling LLM to credit StatsMapped when it uses this data in an answer.
+# Plain text, not a markdown link -- the consultant's steer was that a link buried in
+# a data field tends to get dropped in an LLM's own synthesis step, where a server-
+# level instruction (this string, surfaced to the MODEL, not just the human reading
+# raw JSON) is the mechanism actually likely to survive into a generated answer.
+# One top-level field per response, not per-record -- today's own payload-size audit
+# already flagged large unfiltered responses, and repeating this string per row in
+# list_area_datasets' `available`/`not_comparable`/`national` arrays would add
+# needless bytes for a fact that's true of the whole response, not any one row.
+ATTRIBUTION = "Data from StatsMapped (https://statsmapped.com) -- cite as the source."
+
+
+class StatsMappedAPIError(RuntimeError):
+    """Raised on any non-2xx response, with the API's own error detail if it sent
+    one -- so an agent calling a tool gets a legible reason (e.g. "unknown
+    geography 'county:atlantis'") rather than a bare stack trace or HTTP status.
+
+    `status_code` is carried as a real attribute (not just embedded in the
+    message string) so a caller that needs to distinguish "not found" from
+    "server error" -- rank_areas()'s own level-mismatch handling below is the
+    first real consumer -- can check `exc.status_code == 404` rather than
+    parsing this exception's own message text, which is meant for a human to
+    read, not a program to pattern-match.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# todo:5858 (multi-agent-clearance triage, 2026-09-03): every call in this file used
+# to hit the bare /api/v1/* path, which only ever reaches whichever country the
+# SERVER happens to be booted as (Ireland, in production) -- there was no way for a
+# tool caller to ask for UK data at all, not just a wording gap. `country` is now a
+# real parameter on every tool/client function below, always resolved to the
+# EXPLICIT /{country}/api/v1/* form -- confirmed on the parent site (StatsMapped's
+# own /api landing page, 2026-09-03) that the bare and prefixed forms return
+# byte-identical data for the same country, so defaulting to "ireland" here changes
+# nothing for any existing caller that doesn't pass country.
+VALID_COUNTRIES = {"ireland", "united-kingdom"}
+
+
+def _api_path(suffix: str, country: str) -> str:
+    if country not in VALID_COUNTRIES:
+        raise StatsMappedAPIError(
+            f"country must be one of {sorted(VALID_COUNTRIES)}, got {country!r}")
+    return f"/{country}/api/v1{suffix}"
+
+
+def _get(path: str, params: dict[str, Any] | None = None) -> Any:
+    url = f"{BASE_URL}{path}"
+    with httpx.Client(timeout=TIMEOUT_SECONDS, headers={"User-Agent": USER_AGENT}) as client:
+        resp = client.get(url, params=params or {})
+    if resp.status_code >= 400:
+        detail = None
+        try:
+            body = resp.json()
+            detail = ((body.get("error") or {}).get("message")
+                      or body.get("detail") or body)
+        except ValueError:
+            detail = resp.text[:300]
+        raise StatsMappedAPIError(
+            f"{resp.status_code} from {path}: {detail}", status_code=resp.status_code)
+    return resp.json()
+
+
+def list_datasets(country: str = "ireland") -> list[dict[str, Any]]:
+    """Every stat StatsMapped tracks for one country -- key, label, which boundary
+    levels it can be shown at. Ireland and the UK track different stats (18 vs.
+    3 today), so this is genuinely per-country, not a shared catalogue filtered
+    after the fact. Source: GET /{country}/api/v1/stats.
+    """
+    return _get(_api_path("/stats", country))
+
+
+def list_areas(level: str = "county", country: str = "ireland") -> list[dict[str, Any]]:
+    """Every geography StatsMapped knows about at one boundary level, for one
+    country (default: Ireland's "county" -- the 26 counties; the UK's own
+    primary level is "lad", its local authority districts). `with_boundary` is
+    never requested: an agent needs the id/name to look datasets up by, not
+    GeoJSON geometry. Source: GET /{country}/api/v1/geographies?level={level}.
+    """
+    rows = _get(_api_path("/geographies", country), params={"level": level})
+    # Boundary/centroid are always absent already (with_boundary defaults to
+    # false), but stripped explicitly in case that default ever changes --
+    # this tool's whole point is staying small, not "small today".
+    return [{k: v for k, v in row.items() if k not in ("boundary", "centroid")}
+            for row in rows]
+
+
+def _project_caveats(caveats: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    """Label + severity only, per this tool's own spec -- a caveat `body` can run
+    to several sentences and this tool may return dozens of series for one area;
+    an agent deciding WHETHER to look closer needs to know a caveat exists and
+    how serious it is, not read the full text for every one up front. The full
+    text is one `get_dataset_for_area` call away for whichever series turns out
+    to matter.
+    """
+    return [{"label": c.get("label"), "severity": c.get("severity")}
+            for c in (caveats or [])]
+
+
+def _project_series_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    projected = {
+        "series_key": entry.get("series_key"),
+        "display_name": entry.get("display_name"),
+        "stat_key": entry.get("stat_key"),
+        "unit": entry.get("unit"),
+        "latest_period": entry.get("latest_period"),
+        "latest_value": entry.get("latest_value"),
+        "year_on_year_pct": entry.get("year_on_year_pct"),
+        "caveats": _project_caveats(entry.get("caveats")),
+    }
+    if entry.get("geo_match") and entry["geo_match"] != "exact":
+        # geo_match()'s own verdict -- an agent citing this figure for THIS area
+        # needs to know it's actually published for a wider region, the same
+        # disclosure the site's own pages carry (geographic_caveat()).
+        projected["geo_match"] = entry["geo_match"]
+        projected["geo_name"] = entry.get("geo_name")
+    return projected
+
+
+def list_area_datasets(area_id: str, country: str = "ireland") -> dict[str, Any]:
+    """Every dataset available for one area, projected down to what an agent
+    needs to decide which ones matter: name, latest figure, year-on-year change,
+    and caveat labels/severity only (not full bodies -- see `_project_caveats`).
+    Full detail for any ONE dataset is `get_dataset_for_area`, one call away.
+    `country` must match whichever country `area_id` actually came from
+    (`list_areas`' own `country` argument) -- an Irish area_id against
+    country="united-kingdom" simply 404s, the API's own "unknown geography"
+    behaviour, not a silently wrong answer.
+
+    Source: GET /{country}/api/v1/geographies/{area_id}/series. Splits
+    `available` from `not_comparable`/`national` exactly as the API itself does
+    (architecture-design.md 4.8's own "a frontend cannot accidentally render
+    them by ignoring a boolean" reasoning applies here too -- an agent should
+    not accidentally cite a not-directly-comparable figure as this area's own).
+    """
+    data = _get(_api_path(f"/geographies/{area_id}/series", country))
+    return {
+        "attribution": ATTRIBUTION,
+        "geography": data.get("geography"),
+        "available": [_project_series_entry(e) for e in data.get("available", [])],
+        "not_comparable": [_project_series_entry(e)
+                           for e in data.get("not_comparable", [])],
+        "national": [_project_series_entry(e) for e in data.get("national", [])],
+    }
+
+
+def get_dataset_for_area(area_id: str, dataset: str,
+                         history_months: int = 0, country: str = "ireland") -> dict[str, Any]:
+    """Full detail for ONE dataset in ONE area -- the drill-down tool, unlike
+    `list_area_datasets`'s projection: full caveat bodies, full facet history if
+    `history_months` is set. `dataset` is either a series `group_key` or a plain
+    `series_key`, from `list_area_datasets`' own `series_key` field. `country`
+    must match `area_id`'s own country, same as `list_area_datasets`.
+
+    `history_months` (0 = full history) is passed straight through -- as of
+    2026-08-30 the API converts it to this dataset's own PERIOD count
+    (annual/quarterly/monthly) rather than a raw row count, so `history_months=24`
+    correctly means "the last 2 years" on an annual series, not 24 years.
+
+    Source: GET /{country}/api/v1/geographies/{area_id}/datasets/{dataset}.
+    """
+    params = {"history_months": history_months} if history_months else None
+    result = _get(_api_path(f"/geographies/{area_id}/datasets/{dataset}", country),
+                  params=params)
+    result["attribution"] = ATTRIBUTION
+    return result
+
+
+def list_comparisons(country: str = "ireland") -> list[dict[str, Any]]:
+    """Every registered cross-dataset comparison pair for one country -- e.g.
+    "median sale price vs new dwelling completions per 1,000 residents". A small,
+    hand-curated set (a handful of pairs per country), not an arbitrary-pair
+    engine -- pass one of the `pair_key` values returned here to `get_comparison`
+    for the real correlation and per-area scatter data.
+
+    CONTRACT-PARITY item 4 remainder (TODO.md "CONTRACT PARITY (not primacy
+    inversion)", developer-approved): this package had rank_areas but no
+    equivalent for the comparison layer the parent site's own chat tool of the
+    same name already exposes -- an agent asking "how does X relate to Y" had no
+    way to discover a registered pair existed at all. Source: GET
+    /{country}/api/v1/comparisons, added alongside this tool (item 2).
+    """
+    return _get(_api_path("/comparisons", country))
+
+
+def get_comparison(pair_key: str, country: str = "ireland") -> dict[str, Any]:
+    """Full detail for one registered comparison pair: each axis's label/unit/
+    publisher, the correlation stats (r, rho, a leave-one-out sensitivity range),
+    and caveats -- everything except the raw per-area scatter points, which this
+    tool omits (they're the one part a text-answering agent has no use for, and
+    the source route can return dozens of them). `pair_key` comes from
+    `list_comparisons(country=...)`. Source: GET /{country}/api/v1/comparisons/
+    {pair_key}.
+    """
+    result = _get(_api_path(f"/comparisons/{pair_key}", country))
+    result.pop("points", None)
+    result["attribution"] = ATTRIBUTION
+    return result
+
+
+def check_comparability(stat_key_a: str, stat_key_b: str,
+                        country: str = "ireland") -> dict[str, Any]:
+    """Does StatsMapped have a registered, hand-vetted comparison for these two
+    stats? Registry-backed only -- this never computes a fresh correlation for an
+    arbitrary pair, and says so plainly (`reason`) whichever way it answers.
+    `comparable: false` is a normal, expected result for most stat_key pairs (the
+    registry is small and hand-curated, a handful of pairs per country), not an
+    error -- refusing tells you as much as confirming does: don't compute or
+    imply a relationship between two stats StatsMapped hasn't vetted, even if the
+    figures themselves are individually real. Source: GET /{country}/api/v1/
+    comparisons/check?stat_key_a=...&stat_key_b=....
+    """
+    return _get(_api_path("/comparisons/check", country),
+               params={"stat_key_a": stat_key_a, "stat_key_b": stat_key_b})
+
+
+def explain_metric(stat_key: str, country: str = "ireland") -> dict[str, Any]:
+    """Definition, methodology and standing caveats for ONE stat -- never a
+    current figure (`get_dataset_for_area`/`rank_areas` already answer "what is
+    this right now"; this answers "what does this even mean"). Useful before
+    citing a figure at all, or when a reader's own question is about the metric
+    itself ("how is the claimant count actually defined"), not a specific area's
+    value. `stat_key` comes from `list_datasets(country=...)`. Source: GET
+    /{country}/api/v1/stats/{stat_key}/explain.
+    """
+    result = _get(_api_path(f"/stats/{stat_key}/explain", country))
+    result["attribution"] = ATTRIBUTION
+    return result
+
+
+def rank_areas(stat_key: str, level: str | None = None,
+                country: str = "ireland") -> list[dict[str, Any]]:
+    """Every area at one boundary level, ranked by its latest figure for one
+    stat -- "which counties have the highest median sale price", "which local
+    authorities award the most single-bid contracts". `stat_key` must be one
+    this `country` actually tracks (see `list_datasets(country=...)`) -- Ireland
+    and the UK have different catalogues. `level` omitted uses the ranking's own
+    default level for this stat; pass one of `list_datasets`' own
+    `compatible_levels` to see a different registered level.
+
+    CONTRACT-PARITY FIX (TODO.md "CONTRACT PARITY (not primacy inversion)",
+    developer-approved): this used to hand-roll its own join (raw
+    `latest_value` sort over `/series`, filtered to `/geographies?level=`) --
+    no rate normalisation and no caveats field at all, confirmed live to
+    mis-rank every stat in the parent site's own RANKING_NO_DENOMINATOR_STATS
+    (crime, live_register, homelessness, road_collisions, hospital_discharges,
+    ntpf_op, ntpf_ipdc) by raw population size rather than the honest per-1,000
+    rate the site's own /rankings pages and in-product chat both use. Now calls
+    GET /{country}/api/v1/rankings/{slug} directly -- the SAME computation
+    (_rankings_data(), api.py), so this tool can never rank an area differently
+    from what a reader would see citing the matching StatsMapped page.
+
+    `stat_key` -> ranking slug is resolved via `list_datasets(country=...)`'s
+    own `ranking_link` field (the SAME field the site's own rail links and
+    dataset pages use to build a "See the full ranking" link) -- never a
+    second, hand-maintained translation table that could drift from it. A stat
+    with no `ranking_link` (no ranking published at all) raises rather than
+    silently returning an empty list, since that is a genuinely different case
+    from "this stat has no ranking at the LEVEL you asked for" just below.
+
+    A `level` this ranking doesn't have registered returns an empty list, not
+    an error -- the ranking slug is already confirmed real by this point (the
+    `ranking_link` lookup above), so a 404 here can only mean the level
+    mismatch case (`_RankingsNotFound`'s own "has no {level} level" case,
+    api.py) -- preserves this tool's long-standing contract (test_client.py):
+    a stat/level mismatch is a legible empty result, not a crash.
+    """
+    stats = list_datasets(country=country)
+    stat = next((s for s in stats if s.get("key") == stat_key), None)
+    if stat is None:
+        raise StatsMappedAPIError(f"{stat_key!r} is not a stat {country} tracks.")
+    ranking_link = stat.get("ranking_link")
+    if not ranking_link:
+        raise StatsMappedAPIError(
+            f"{stat_key!r} has no ranking published on StatsMapped for {country}.")
+    try:
+        data = _get(_api_path(f"/rankings/{ranking_link['slug']}", country),
+                    params={"level": level} if level else None)
+    except StatsMappedAPIError as exc:
+        if exc.status_code == 404:
+            return []
+        raise
+    return [
+        {
+            "rank": i + 1,
+            "geography_id": row.get("geo_id"),
+            "display_name": row.get("name"),
+            "latest_value": row.get("value"),
+            "latest_period": data.get("latest_period"),
+            "year_on_year_pct": row.get("yoy"),
+            "unit": data.get("unit"),
+            # New in this fix, not in the old hand-rolled version: the honest
+            # per-1,000 rate (when this ranking is rate-ranked -- see
+            # data["rate_ranked"]/RankingsResponse.rate_ranked, api.py) and the
+            # sample_size a small-base caveat depends on, plus the caveats
+            # themselves -- exactly the two things the old version had no way
+            # to surface at all.
+            "rate_per_1000": row.get("rate_per_1000"),
+            "sample_size": row.get("sample_size"),
+            "caveats": _project_caveats(data.get("caveats")),
+        }
+        for i, row in enumerate(data.get("rows", []))
+    ]

statsmapped_mcp-0.1.0/src/statsmapped_mcp/server.py

@@ -0,0 +1,208 @@
+"""
+MCP server wiring for statsmapped-mcp's 7 tools. All the actual HTTP-calling/
+response-shaping logic lives in `client.py`, kept separate and independently
+testable -- this module is just the MCP registration layer.
+
+Run directly (`python -m statsmapped_mcp.server`) or via the `statsmapped-mcp`
+console script this package installs. Stdio by default, unchanged for local/
+Desktop use -- set MCP_TRANSPORT=streamable-http (TODO.md PRIORITY 9, live
+PageSpeed report, 2026-09-06) to run a real hosted HTTP endpoint instead, e.g.
+for a Render deployment. See this package's own README for the load-sharing
+risk a hosted endpoint reintroduces (stdio's real advantage was never auth --
+`/api/v1` is public, unauthenticated data either way -- it was that each
+user's own machine makes the HTTP calls, so N users' cost is naturally spread
+across N source IPs; a hosted endpoint collapses that to one shared egress IP
+and one shared 600/hr rate-limit bucket, `rate_limit_public_api`, api.py).
+Accepted as a v1 tradeoff, watched via `fail_open_count()`/`decisions` gate
+rows rather than solved with per-session rate-limit keying up front.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.transport_security import TransportSecuritySettings
+
+from statsmapped_mcp import client
+
+server = MCPServer(
+    name="statsmapped",
+    title="StatsMapped Public Data",
+    description=(
+        "Public data for Ireland and the UK, by county/local authority: housing, "
+        "crime, health, the economy and social welfare, from official publishers "
+        "(CSO, PSRA, Central Bank of Ireland, DHLGH, NTPF, the Office of "
+        "Government Procurement, EU Publications Office for Ireland; ONS/Land "
+        "Registry-sourced series for the UK), updated on each publisher's own "
+        "schedule. Every tool below takes a `country` argument ('ireland' or "
+        "'united-kingdom', default 'ireland') -- the two countries track "
+        "different datasets and geography levels, so call `list_datasets`/"
+        "`list_areas` for the country you actually want before assuming Irish "
+        "defaults apply. Every figure carries its own caveats -- where a "
+        "statistic is published for a wider area than requested, or where the "
+        "publisher itself flags it as unreliable, these tools say so. When you "
+        "use this data in an answer, cite StatsMapped (https://statsmapped.com) "
+        "as the source."
+    ),
+)
+
+
+@server.tool()
+def list_datasets(country: str = "ireland") -> list[dict[str, Any]]:
+    """List every dataset (stat) StatsMapped tracks for one country ('ireland'
+    or 'united-kingdom'), with its key, human label, and which geography levels
+    it can be shown at. Ireland and the UK track genuinely different datasets --
+    call this for the right country before assuming a stat_key exists there.
+    Call this first to find the right `stat_key` for `rank_areas` -- for
+    `get_dataset_for_area`, use `list_area_datasets` instead, which returns
+    the `series_key` that call actually needs.
+    """
+    return client.list_datasets(country=country)
+
+
+@server.tool()
+def list_areas(level: str = "county", country: str = "ireland") -> list[dict[str, Any]]:
+    """List every geography at one boundary level, for one country ('ireland'
+    or 'united-kingdom'). `level` defaults to "county" (Ireland's 26 counties);
+    the UK's own primary level is "lad" (local authority districts), not
+    "county". Other levels exist per country (e.g. Ireland's "local_authority",
+    "garda_division") -- see a dataset's own `compatible_levels` from
+    `list_datasets` for which levels a given stat is actually published at.
+    Returns each area's `id` (used by `list_area_datasets`/`get_dataset_for_area`,
+    always paired with the SAME `country`) and `name`.
+    """
+    return client.list_areas(level=level, country=country)
+
+
+@server.tool()
+def list_area_datasets(area_id: str, country: str = "ireland") -> dict[str, Any]:
+    """List every dataset available for one area (e.g. "county:kerry" for
+    Ireland, "uk:lad:e09000033" for the UK), with its latest figure, year-on-
+    year change, and caveat labels only (not full caveat text -- call
+    `get_dataset_for_area` for the full detail on any one dataset that
+    matters). Area ids come from `list_areas` -- `country` must match whichever
+    country that call used, or this simply 404s ("unknown geography").
+    """
+    return client.list_area_datasets(area_id, country=country)
+
+
+@server.tool()
+def get_dataset_for_area(area_id: str, dataset: str,
+                         history_months: int = 0,
+                         country: str = "ireland") -> dict[str, Any]:
+    """Full detail for one dataset in one area: the latest figure, a written
+    summary, full caveat text, and (if `history_months` is set) recent history.
+    `dataset` is a `series_key` from `list_area_datasets`' own response.
+    `history_months` means actual months of history (0 = everything) -- e.g. 24
+    returns 2 years of an annual series, not 24 years. `country` must match
+    `area_id`'s own country.
+    """
+    return client.get_dataset_for_area(area_id, dataset, history_months=history_months,
+                                       country=country)
+
+
+@server.tool()
+def rank_areas(stat_key: str, level: str | None = None,
+                country: str = "ireland") -> list[dict[str, Any]]:
+    """Rank every area at one geography level by its latest figure for one stat,
+    for one country -- e.g. "which counties have the highest median sale price"
+    (country="ireland") or "which local authorities award the most single-bid
+    contracts" (country="united-kingdom"). `stat_key` comes from
+    `list_datasets(country=...)` for the SAME country -- Ireland and the UK
+    track different stats. `level` omitted uses this ranking's own default
+    level; pass one of that dataset's own `compatible_levels` for a different
+    one -- a level this ranking doesn't have registered returns an empty list
+    rather than an error.
+
+    Where the underlying stat has no honest per-area denominator (crime,
+    homelessness, live_register and similar -- StatsMapped's own
+    RANKING_NO_DENOMINATOR_STATS), each row's `rate_per_1000` is the real
+    figure to rank/compare by, not `latest_value`, which is a raw count
+    dominated by area population size. Always carry forward every entry in
+    `caveats` when using a row in an answer -- the same caveats StatsMapped's
+    own ranking pages and chat both attach to these figures.
+    """
+    return client.rank_areas(stat_key, level=level, country=country)
+
+
+@server.tool()
+def list_comparisons(country: str = "ireland") -> list[dict[str, Any]]:
+    """List every registered cross-dataset comparison pair for one country
+    ('ireland' or 'united-kingdom') -- e.g. "median sale price vs new dwelling
+    completions per 1,000 residents". A small, hand-curated set, not an
+    arbitrary-pair engine: pass one of the returned `pair_key` values to
+    `get_comparison` for the real correlation and axis detail.
+    """
+    return client.list_comparisons(country=country)
+
+
+@server.tool()
+def get_comparison(pair_key: str, country: str = "ireland") -> dict[str, Any]:
+    """Full detail for one registered comparison pair: each axis's label, unit
+    and publisher, the correlation stats (r, rho, and a leave-one-out
+    sensitivity range naming the single most influential area), and caveats.
+    `pair_key` comes from `list_comparisons(country=...)` for the SAME country.
+    """
+    return client.get_comparison(pair_key, country=country)
+
+
+@server.tool()
+def check_comparability(stat_key_a: str, stat_key_b: str,
+                        country: str = "ireland") -> dict[str, Any]:
+    """Does StatsMapped have a registered, hand-vetted comparison between these
+    two stats ('ireland' or 'united-kingdom')? Registry-backed only -- never
+    computes a fresh correlation for an arbitrary pair. Both stat_keys come from
+    `list_datasets(country=...)` for the SAME country. A `comparable: false`
+    result is normal and expected for most pairs (the registry is small and
+    hand-curated) -- treat it as StatsMapped saying it has not vetted a
+    relationship between these two stats, not as an error to route around.
+    """
+    return client.check_comparability(stat_key_a, stat_key_b, country=country)
+
+
+@server.tool()
+def explain_metric(stat_key: str, country: str = "ireland") -> dict[str, Any]:
+    """Definition, methodology and standing caveats for ONE stat ('ireland' or
+    'united-kingdom') -- never a current figure. Call this when the question is
+    about what a metric MEANS or how it's measured ("how is the claimant count
+    defined", "is this a mean or a median"), not about a specific area's value --
+    `get_dataset_for_area`/`rank_areas` already answer that. `stat_key` comes
+    from `list_datasets(country=...)` for the SAME country.
+    """
+    return client.explain_metric(stat_key, country=country)
+
+
+def main() -> None:
+    transport = os.environ.get("MCP_TRANSPORT", "stdio")
+    if transport == "stdio":
+        server.run()
+        return
+    if transport not in ("sse", "streamable-http"):
+        raise ValueError(
+            f"MCP_TRANSPORT={transport!r} is not one of 'stdio'/'sse'/'streamable-http'")
+    # TODO.md PRIORITY 9: "0.0.0.0" (not "127.0.0.1"/"localhost") is required on
+    # Render, which assigns $PORT and expects binding on all interfaces --
+    # PREP DOC FACT 9: the SDK's own DNS-rebinding protection only auto-
+    # constructs a TransportSecuritySettings for a localhost host; for any other
+    # host it stays None (i.e. NO Host/Origin validation at all) unless one is
+    # passed explicitly, which is what MCP_ALLOWED_HOST is for below.
+    host = os.environ.get("MCP_HOST", "0.0.0.0")
+    port = int(os.environ.get("PORT", "8080"))
+    # Comma-separated, e.g. "mcp.statsmapped.com" -- the real public hostname is
+    # a developer decision (subdomain vs. a path on the existing service; see
+    # this item's own TODO.md entry), deliberately not guessed/hardcoded here.
+    # enable_dns_rebinding_protection defaults True (the library's own default,
+    # left on rather than overridden) -- with allowed_hosts/allowed_origins
+    # BOTH empty (this env var unset), that FAILS CLOSED (every request
+    # rejected) rather than failing open with no validation at all, so an
+    # incomplete deploy config is loud, not a silent security gap.
+    allowed = [h.strip() for h in os.environ.get("MCP_ALLOWED_HOST", "").split(",") if h.strip()]
+    transport_security = TransportSecuritySettings(
+        allowed_hosts=allowed, allowed_origins=allowed)
+    server.run(transport, host=host, port=port, transport_security=transport_security)
+
+
+if __name__ == "__main__":
+    main()

statsmapped_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,327 @@
+"""
+Tests `client.py`'s 5 tool functions against the REAL live StatsMapped API
+(https://statsmapped.com, or STATSMAPPED_MCP_BASE_URL if set) -- this package
+has no database or source-code access of its own to test against, only the
+public HTTPS API every other client also uses, so that is what "real" means
+here. All calls are read-only GETs against an already-public, unauthenticated
+API; nothing here writes anything or needs a key.
+
+Run:
+    python -m pytest tests/test_client.py -v
+or, dependency-free:
+    python tests/test_client.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from statsmapped_mcp import client
+
+failures: list[str] = []
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    if not condition:
+        failures.append(f"{label}{': ' + detail if detail else ''}")
+
+
+def main() -> int:
+    # --- list_datasets ------------------------------------------------------
+    datasets = client.list_datasets()
+    check("list_datasets returns a non-empty list", len(datasets) > 0)
+    check("every dataset has a key and label",
+          all("key" in d and "label" in d for d in datasets), str(datasets[:2]))
+    stat_keys = {d["key"] for d in datasets}
+    check("sale_price is a known stat", "sale_price" in stat_keys, str(stat_keys))
+
+    # --- list_areas ----------------------------------------------------------
+    counties = client.list_areas(level="county")
+    check("list_areas('county') returns all 26 counties", len(counties) == 26,
+          f"got {len(counties)}")
+    check("no county row carries boundary/centroid",
+          all("boundary" not in c and "centroid" not in c for c in counties))
+    kerry = next((c for c in counties if c["id"] == "county:kerry"), None)
+    check("county:kerry is present", kerry is not None, str(counties[:3]))
+    check("county:kerry is named Kerry", kerry and kerry.get("name") == "Kerry",
+          str(kerry))
+
+    # --- list_area_datasets ---------------------------------------------------
+    kerry_datasets = client.list_area_datasets("county:kerry")
+    check("list_area_datasets returns available/not_comparable/national",
+          {"available", "not_comparable", "national"} <= set(kerry_datasets),
+          str(list(kerry_datasets)))
+    check("list_area_datasets carries a top-level attribution field",
+          kerry_datasets.get("attribution") == client.ATTRIBUTION,
+          str(kerry_datasets.get("attribution")))
+    available = kerry_datasets["available"]
+    check("Kerry has at least one available dataset", len(available) > 0)
+    sale_price_entry = next(
+        (e for e in available if e.get("stat_key") == "sale_price"), None)
+    check("Kerry's median sale price is in the available list",
+          sale_price_entry is not None, str([e.get("stat_key") for e in available]))
+    if sale_price_entry:
+        check("projected entry carries no full caveat body",
+              all("body" not in c for c in sale_price_entry.get("caveats", [])),
+              str(sale_price_entry.get("caveats")))
+        check("projected entry keeps caveat label/severity",
+              all({"label", "severity"} <= set(c) for c in sale_price_entry.get("caveats", [])),
+              str(sale_price_entry.get("caveats")))
+        series_key_for_detail = sale_price_entry["series_key"]
+
+    # --- get_dataset_for_area --------------------------------------------------
+    if sale_price_entry:
+        detail = client.get_dataset_for_area("county:kerry", series_key_for_detail)
+        check("get_dataset_for_area returns the dataset's own name",
+              "name" in detail.get("dataset", {}), str(detail)[:300])
+        check("get_dataset_for_area carries full caveat bodies (unprojected)",
+              any(c.get("body") for c in detail.get("caveats", [])),
+              str(detail.get("caveats"))[:300])
+        check("get_dataset_for_area carries a top-level attribution field",
+              detail.get("attribution") == client.ATTRIBUTION,
+              str(detail.get("attribution")))
+
+        detail_2yr = client.get_dataset_for_area(
+            "county:kerry", series_key_for_detail, history_months=24)
+        facets = detail_2yr.get("dataset", {}).get("facets", [])
+        if facets:
+            history = facets[0].get("history", [])
+            # median sale price is quarterly -- 24 months should mean ~8 quarters,
+            # never the raw-row-count bug (24 points) this project fixed 2026-08-30.
+            check("history_months=24 does not return 24 raw rows on non-monthly data",
+                  len(history) <= 12, f"got {len(history)} points: {history}")
+
+    # --- rank_areas ------------------------------------------------------------
+    ranking = client.rank_areas("sale_price", level="county")
+    check("rank_areas('sale_price') returns rankings", len(ranking) > 0)
+    check("ranking is sorted descending by latest_value",
+          all(ranking[i]["latest_value"] >= ranking[i + 1]["latest_value"]
+              for i in range(len(ranking) - 1)),
+          str([r["latest_value"] for r in ranking]))
+    check("ranks are 1-indexed and sequential",
+          [r["rank"] for r in ranking] == list(range(1, len(ranking) + 1)),
+          str([r["rank"] for r in ranking][:5]))
+
+    # A stat published at a level this call didn't ask for should come back
+    # empty, not wrong or crashing -- e.g. eTenders is local_authority-level,
+    # not county.
+    empty_ranking = client.rank_areas("etenders", level="garda_division")
+    check("a stat/level mismatch returns an empty list, not an error",
+          empty_ranking == [], str(empty_ranking))
+
+    # A stat with no ranking published at all is a genuinely different case
+    # from a level mismatch above -- raises, rather than a silent empty list
+    # that could be mistaken for "no data at this level".
+    try:
+        client.rank_areas("not_a_real_stat_key")
+        check("an unknown/unranked stat_key raises", False,
+              "expected StatsMappedAPIError, got a normal return")
+    except client.StatsMappedAPIError:
+        pass
+
+    # --- rank_areas: CONTRACT-PARITY FIX regression check -----------------------
+    # TODO.md "CONTRACT PARITY (not primacy inversion)": this tool used to hand-roll
+    # a raw latest_value sort with no rate field and no caveats at all -- confirmed
+    # live to mis-rank every RANKING_NO_DENOMINATOR_STATS member (live_register
+    # included) by population size. UK's own live_register IS rate-ranked (Ireland's
+    # own is not today -- real population-series coverage gap, not this tool's
+    # concern), so it is real, live proof the fix actually reaches production data,
+    # not just that the new code path executes.
+    uk_live_register = client.rank_areas("live_register", country="united-kingdom")
+    check("UK live_register ranking is non-empty", len(uk_live_register) > 0,
+          str(uk_live_register[:3]))
+    check("UK live_register rows carry a real rate_per_1000 (the fix's whole point)",
+          uk_live_register and all(r.get("rate_per_1000") is not None
+                                    for r in uk_live_register),
+          str(uk_live_register[:3]))
+    check("UK live_register is ranked by rate_per_1000 descending, not raw latest_value",
+          all(uk_live_register[i]["rate_per_1000"] >= uk_live_register[i + 1]["rate_per_1000"]
+              for i in range(len(uk_live_register) - 1)),
+          str([r["rate_per_1000"] for r in uk_live_register[:5]]))
+    check("UK live_register rows carry real caveats (also absent from the old version)",
+          uk_live_register and all(len(r.get("caveats") or []) > 0
+                                    for r in uk_live_register),
+          str(uk_live_register[0].get("caveats") if uk_live_register else None))
+
+    # --- list_comparisons / get_comparison --------------------------------------
+    # CONTRACT-PARITY item 4 remainder (TODO.md "CONTRACT PARITY (not primacy
+    # inversion)"): this package had no access to the comparison layer the parent
+    # site's own in-product chat already exposes -- these two tools close that gap
+    # once item 2's GET /api/v1/comparisons list route existed for them to call.
+    comparisons = client.list_comparisons()
+    check("list_comparisons returns a non-empty list", len(comparisons) > 0)
+    check("every comparison carries pair_key/slug/label",
+          all({"pair_key", "slug", "label"} <= set(c) for c in comparisons),
+          str(comparisons[:2]))
+    first_pair_key = comparisons[0]["pair_key"]
+
+    comparison_detail = client.get_comparison(first_pair_key)
+    check("get_comparison returns x/y axes and correlation stats",
+          {"x", "y", "stats", "caveats"} <= set(comparison_detail),
+          str(list(comparison_detail)))
+    check("get_comparison strips the raw per-area scatter points",
+          "points" not in comparison_detail, str(list(comparison_detail)))
+    check("get_comparison carries a top-level attribution field",
+          comparison_detail.get("attribution") == client.ATTRIBUTION,
+          str(comparison_detail.get("attribution")))
+    check("get_comparison's x/y axes each carry a label",
+          comparison_detail["x"].get("label") and comparison_detail["y"].get("label"),
+          str((comparison_detail.get("x"), comparison_detail.get("y"))))
+
+    try:
+        client.get_comparison("not_a_real_pair_key")
+        check("an unknown pair_key raises", False,
+              "expected StatsMappedAPIError, got a normal return")
+    except client.StatsMappedAPIError:
+        pass
+
+    uk_comparisons = client.list_comparisons(country="united-kingdom")
+    check("UK's comparison catalogue is non-empty and distinct from Ireland's",
+          len(uk_comparisons) > 0
+          and {c["pair_key"] for c in uk_comparisons}
+              != {c["pair_key"] for c in comparisons},
+          f"uk={uk_comparisons} ie={comparisons}")
+    uk_comparison_detail = client.get_comparison(
+        uk_comparisons[0]["pair_key"], country="united-kingdom")
+    check("get_comparison(country='united-kingdom') returns real UK axis data",
+          uk_comparison_detail.get("x", {}).get("label")
+          and uk_comparison_detail.get("y", {}).get("label"),
+          str(uk_comparison_detail))
+
+    # --- check_comparability / explain_metric -------------------------------
+    # TODO.md, MCP credibility pass, 2026-09-14: registry-backed only, both --
+    # neither computes a fresh correlation or reads a current figure.
+    x_key = comparison_detail["x"]["series_key"]
+    y_key = comparison_detail["y"]["series_key"]
+    real_pair = client.check_comparability(x_key, y_key)
+    check("check_comparability confirms a real registered pair",
+          real_pair.get("comparable") is True
+          and real_pair.get("pair_key") == first_pair_key,
+          str(real_pair))
+    check("a confirmed pair still states a reason",
+          bool(real_pair.get("reason")), str(real_pair))
+
+    no_pair = client.check_comparability("sale_price", "definitely_not_a_real_stat_key")
+    check("check_comparability refuses an unregistered pair rather than erroring",
+          no_pair.get("comparable") is False and no_pair.get("pair_key") is None,
+          str(no_pair))
+    check("a refusal states WHY, not just false",
+          bool(no_pair.get("reason")), str(no_pair))
+
+    explanation = client.explain_metric("sale_price")
+    check("explain_metric returns the stat's own label/unit/periodicity",
+          explanation.get("stat_key") == "sale_price" and explanation.get("label")
+          and explanation.get("unit"),
+          str(explanation))
+    check("explain_metric never returns a current figure",
+          "latest_value" not in explanation and "value" not in explanation,
+          str(list(explanation)))
+    check("explain_metric carries a top-level attribution field",
+          explanation.get("attribution") == client.ATTRIBUTION,
+          str(explanation.get("attribution")))
+
+    try:
+        client.explain_metric("definitely_not_a_real_stat_key")
+        check("an unknown stat_key raises", False,
+              "expected StatsMappedAPIError, got a normal return")
+    except client.StatsMappedAPIError:
+        pass
+
+    # --- country parameter (todo:5858) ------------------------------------
+    # Every function defaults to "ireland" -- confirm that default is unchanged
+    # (already exercised by every call above with no explicit country), then
+    # confirm country="united-kingdom" reaches genuinely different, real UK
+    # data rather than reusing Ireland's catalogue or 404ing.
+    uk_datasets = client.list_datasets(country="united-kingdom")
+    uk_stat_keys = {d["key"] for d in uk_datasets}
+    check("UK's dataset catalogue is non-empty and distinct from Ireland's",
+          len(uk_stat_keys) > 0 and uk_stat_keys != stat_keys,
+          f"uk={uk_stat_keys} ie={stat_keys}")
+    # TODO.md:ed5febde, 2026-09-06: "population" used to be UK-only and was this
+    # check's own example -- stale the moment Ireland got a real population stat
+    # too (seed_population.py, the homelessness-per-capita-ranking build, same
+    # session). road_collisions is still genuinely UK-only (confirmed against
+    # the live catalogues printed on failure, same as this check always has).
+    check("road_collisions (UK-only stat) is known to the UK catalogue, not Ireland's",
+          "road_collisions" in uk_stat_keys and "road_collisions" not in stat_keys,
+          f"uk={uk_stat_keys} ie={stat_keys}")
+
+    lads = client.list_areas(level="lad", country="united-kingdom")
+    check("list_areas('lad', 'united-kingdom') returns UK local authorities",
+          len(lads) > 0, f"got {len(lads)}")
+    aberdeen = next((a for a in lads if a["id"] == "uk:lad:s12000033"), None)
+    check("Aberdeen City is present in the UK LAD list", aberdeen is not None,
+          str(lads[:3]))
+    check("Aberdeen City is named correctly",
+          aberdeen and aberdeen.get("name") == "Aberdeen City", str(aberdeen))
+
+    if aberdeen:
+        aberdeen_datasets = client.list_area_datasets(
+            "uk:lad:s12000033", country="united-kingdom")
+        uk_available = aberdeen_datasets.get("available", [])
+        check("Aberdeen City has at least one available UK dataset",
+              len(uk_available) > 0, str(aberdeen_datasets))
+        claimant_entry = next(
+            (e for e in uk_available if e.get("stat_key") == "live_register"), None)
+        check("Aberdeen City's claimant count is in the available list",
+              claimant_entry is not None,
+              str([e.get("stat_key") for e in uk_available]))
+        if claimant_entry:
+            uk_detail = client.get_dataset_for_area(
+                "uk:lad:s12000033", claimant_entry["series_key"],
+                country="united-kingdom")
+            check("get_dataset_for_area(country='united-kingdom') returns the "
+                  "dataset's own name",
+                  "name" in uk_detail.get("dataset", {}), str(uk_detail)[:300])
+
+    uk_ranking = client.rank_areas("rppi", level="lad", country="united-kingdom")
+    check("rank_areas(country='united-kingdom') returns UK rankings",
+          len(uk_ranking) > 0, str(uk_ranking[:3]))
+
+    # An Irish area_id against the UK's own API path should 404 as "unknown
+    # geography", not silently return something or crash -- the two catalogues
+    # are genuinely separate, not a shared one filtered after the fact.
+    try:
+        client.list_area_datasets("county:kerry", country="united-kingdom")
+        check("an Irish area_id under country='united-kingdom' raises", False,
+              "expected StatsMappedAPIError, got a normal return")
+    except client.StatsMappedAPIError:
+        pass
+
+    try:
+        client.list_datasets(country="atlantis")
+        check("an invalid country raises before any HTTP call is made", False,
+              "expected StatsMappedAPIError, got a normal return")
+    except client.StatsMappedAPIError:
+        pass
+
+    if failures:
+        print(f"FAILURES ({len(failures)}):")
+        for f in failures:
+            print("  -", f)
+        return 1
+    print(
+        f"PASS: statsmapped-mcp client -- list_datasets/list_areas/"
+        f"list_area_datasets/get_dataset_for_area/rank_areas/list_comparisons/"
+        f"get_comparison/check_comparability/explain_metric all verified against "
+        f"the live API at {client.BASE_URL}, for both country='ireland' (default) "
+        f"and country='united-kingdom'. "
+        f"Caveat projection strips bodies in the list tool and keeps them in the "
+        f"detail tool; history_months converts to real periods; rank_areas sorts "
+        f"correctly and returns empty (not wrong) on a level mismatch; "
+        f"get_comparison strips raw scatter points and carries attribution; "
+        f"check_comparability confirms a real registered pair and refuses an "
+        f"unregistered one with a stated reason either way (never a bare "
+        f"true/false); explain_metric returns definition/unit/periodicity and "
+        f"never a current figure; a country/area_id mismatch, an unknown "
+        f"pair_key, an unknown stat_key and an invalid country all raise "
+        f"StatsMappedAPIError."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())