abs-mcp 0.1.0__tar.gz

abs_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --extra dev
+      - name: Install package
+        run: uv pip install -e .
+      - name: Run unit tests
+        run: uv run pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Verify wheel installs cleanly
+        run: |
+          uv run --isolated --with ./dist/*.whl python -c \
+            "import abs_mcp.server as s; assert len(s.list_curated()) == 5; print('OK')"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

abs_mcp-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.swp
+.DS_Store
+.env
+
+# Inspection-only DSDs (regenerate with: curl -H "Accept: application/vnd.sdmx.structure+xml;version=2.1" https://data.api.abs.gov.au/rest/datastructure/ABS/<ID>?references=all)
+tests/fixtures/ABS_ANNUAL_ERP_ASGS2021_dsd.xml
+tests/fixtures/BA_GCCSA_dsd.xml
+tests/fixtures/CPI_dsd.xml
+tests/fixtures/JV_dsd.xml
+tests/fixtures/LEND_HOUSING_dsd.xml
+tests/fixtures/WPI_dsd.xml

abs_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-05-11)
+
+Initial release.
+
+- 5 MCP tools: `search_datasets`, `describe_dataset`, `get_data`, `latest`, `list_curated`
+- Hand-curated plain-English mappings for 5 dataflows: `LF` (Labour Force), `CPI` (Consumer Price Index), `ABS_ANNUAL_ERP_ASGS2021` (Estimated Resident Population), `BA_GCCSA` (Building Approvals), `LEND_HOUSING` (Lending Indicators - Housing)
+- Non-curated dataflows still queryable via raw SDMX dimension IDs and codes
+- SQLite-backed cache with per-kind TTL: catalogue 24 h, codelists 7 d, data 1 h, latest 15 min
+- Response shapes: `records` (default), `series`, `csv`
+- 50 tests (35 unit + 7 live integration + 8 MCP-protocol)

abs_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harry Vass
+
+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.

abs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: abs-mcp
+Version: 0.1.0
+Summary: MCP server for the Australian Bureau of Statistics Data API. Hides SDMX behind plain-English tools, with curated mappings for Labour Force, CPI, ERP, Building Approvals, and Lending Indicators.
+Project-URL: Homepage, https://github.com/Bigred97/abs-mcp
+Project-URL: Issues, https://github.com/Bigred97/abs-mcp/issues
+Author: Harry Vass
+License: MIT
+License-File: LICENSE
+Keywords: abs,australia,claude,mcp,sdmx,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: fastmcp<4,>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rapidfuzz>=3.9
+Requires-Dist: sdmx1>=2.20
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# abs-mcp
+
+An MCP server that wraps the [Australian Bureau of Statistics Data API](https://data.api.abs.gov.au/) and hides SDMX behind plain-English tools. Ask Claude "What's the unemployment rate in NSW?" and get a real answer with a source link, instead of a wall of SDMX codes.
+
+Five tools, hand-curated mappings for Labour Force, CPI, Estimated Resident Population, Building Approvals, and Lending Indicators.
+
+## Install
+
+```bash
+# After publish:
+uvx abs-mcp
+
+# Local dev install:
+uv pip install -e .
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uvx",
+      "args": ["abs-mcp"]
+    }
+  }
+}
+```
+
+For a local checkout (before PyPI publish):
+
+```json
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/abs-mcp", "abs-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The `abs` server appears in the tools panel with five tools.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or workspace `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uvx",
+      "args": ["abs-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_datasets(query, limit=10)` | Fuzzy-search ABS dataflow names. Returns the top matches. |
+| `describe_dataset(dataset_id)` | Plain-English description of a dataflow's dimensions and values. |
+| `get_data(dataset_id, filters, start_period, end_period, format)` | Query a dataflow with filters. Returns clean records (default), grouped series, or CSV. |
+| `latest(dataset_id, filters)` | Just the most recent observation(s) — wraps `get_data` with `lastNObservations=1`. |
+| `list_curated()` | The five dataflow IDs that have hand-curated plain-English support. |
+
+## Curated dataflows
+
+For these five, `filters` accepts plain-English values (e.g. `"region": "nsw"` instead of `"REGION": "1"`):
+
+- **LF** — Labour Force, monthly: employment, unemployment, participation by state/sex
+- **CPI** — Consumer Price Index, quarterly inflation by capital city and category
+- **ABS_ANNUAL_ERP_ASGS2021** — Estimated Resident Population, annual by state and sub-state geography
+- **BA_GCCSA** — Building Approvals, monthly by state/capital region and building type
+- **LEND_HOUSING** — Lending Indicators, monthly housing finance commitments by purpose, lender, and state
+
+Any other ABS dataflow still works — pass raw SDMX dimension IDs and codes.
+
+## Worked examples
+
+**"What's the current unemployment rate in NSW?"**
+
+Claude calls:
+```
+latest(dataset_id="LF", filters={"region": "nsw", "measure": "unemployment_rate"})
+```
+
+Returns:
+```json
+{
+  "dataset_id": "LF",
+  "dataset_name": "Labour Force",
+  "query": {"region": "nsw", "measure": "unemployment_rate"},
+  "period": {"start": "2026-03", "end": "2026-03"},
+  "records": [
+    {
+      "period": "2026-03",
+      "value": 4.2,
+      "dimensions": {"measure": "Unemployment rate", "region": "New South Wales", "sex": "Persons"}
+    }
+  ],
+  "source": "Australian Bureau of Statistics",
+  "abs_url": "https://www.abs.gov.au/statistics/labour/employment-and-unemployment/labour-force-australia"
+}
+```
+
+**"Show me NSW housing approvals over the last two years"**
+
+```
+get_data(dataset_id="BA_GCCSA", filters={"region": "nsw", "measure": "dwelling_units"}, start_period="2024")
+```
+
+**"Compare quarterly CPI in Sydney vs Melbourne"**
+
+```
+get_data(dataset_id="CPI", filters={"region": ["sydney", "melbourne"], "measure": "change_year"}, start_period="2023")
+```
+
+## Period formats
+
+ABS uses different period formats per dataflow:
+- Monthly (LF, BA_GCCSA, LEND_HOUSING): `"2026-03"`
+- Quarterly (CPI): `"2024-Q1"`
+- Annual (ABS_ANNUAL_ERP_ASGS2021): `"2024"`
+
+Pass `start_period` / `end_period` in the matching format.
+
+## Development
+
+```bash
+git clone https://github.com/Bigred97/abs-mcp.git
+cd abs-mcp
+uv sync --extra dev
+uv pip install -e .
+
+# Unit tests (no network)
+uv run pytest
+
+# Live integration tests (hits real ABS API)
+uv run pytest -m live
+```
+
+The SQLite cache lives at `~/.abs-mcp/cache.db`. Catalogue refreshes every 24h, codelists every 7 days, data responses every hour, latest 15 minutes. Delete the file to force a refresh.
+
+## How it differs from existing ABS MCP servers
+
+The one existing community option (`seansoreilly/abs`) exposes a single `query_dataset` tool that passes raw SDMX through. This package offers semantic tools and curated mappings for the highest-value dataflows so an LLM can answer real questions without you needing to know what `M13.3.1599.20.1.M` means.
+
+## License
+
+MIT — Harry Vass, 2026.

abs_mcp-0.1.0/README.md

@@ -0,0 +1,156 @@
+# abs-mcp
+
+An MCP server that wraps the [Australian Bureau of Statistics Data API](https://data.api.abs.gov.au/) and hides SDMX behind plain-English tools. Ask Claude "What's the unemployment rate in NSW?" and get a real answer with a source link, instead of a wall of SDMX codes.
+
+Five tools, hand-curated mappings for Labour Force, CPI, Estimated Resident Population, Building Approvals, and Lending Indicators.
+
+## Install
+
+```bash
+# After publish:
+uvx abs-mcp
+
+# Local dev install:
+uv pip install -e .
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uvx",
+      "args": ["abs-mcp"]
+    }
+  }
+}
+```
+
+For a local checkout (before PyPI publish):
+
+```json
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/abs-mcp", "abs-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The `abs` server appears in the tools panel with five tools.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or workspace `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uvx",
+      "args": ["abs-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_datasets(query, limit=10)` | Fuzzy-search ABS dataflow names. Returns the top matches. |
+| `describe_dataset(dataset_id)` | Plain-English description of a dataflow's dimensions and values. |
+| `get_data(dataset_id, filters, start_period, end_period, format)` | Query a dataflow with filters. Returns clean records (default), grouped series, or CSV. |
+| `latest(dataset_id, filters)` | Just the most recent observation(s) — wraps `get_data` with `lastNObservations=1`. |
+| `list_curated()` | The five dataflow IDs that have hand-curated plain-English support. |
+
+## Curated dataflows
+
+For these five, `filters` accepts plain-English values (e.g. `"region": "nsw"` instead of `"REGION": "1"`):
+
+- **LF** — Labour Force, monthly: employment, unemployment, participation by state/sex
+- **CPI** — Consumer Price Index, quarterly inflation by capital city and category
+- **ABS_ANNUAL_ERP_ASGS2021** — Estimated Resident Population, annual by state and sub-state geography
+- **BA_GCCSA** — Building Approvals, monthly by state/capital region and building type
+- **LEND_HOUSING** — Lending Indicators, monthly housing finance commitments by purpose, lender, and state
+
+Any other ABS dataflow still works — pass raw SDMX dimension IDs and codes.
+
+## Worked examples
+
+**"What's the current unemployment rate in NSW?"**
+
+Claude calls:
+```
+latest(dataset_id="LF", filters={"region": "nsw", "measure": "unemployment_rate"})
+```
+
+Returns:
+```json
+{
+  "dataset_id": "LF",
+  "dataset_name": "Labour Force",
+  "query": {"region": "nsw", "measure": "unemployment_rate"},
+  "period": {"start": "2026-03", "end": "2026-03"},
+  "records": [
+    {
+      "period": "2026-03",
+      "value": 4.2,
+      "dimensions": {"measure": "Unemployment rate", "region": "New South Wales", "sex": "Persons"}
+    }
+  ],
+  "source": "Australian Bureau of Statistics",
+  "abs_url": "https://www.abs.gov.au/statistics/labour/employment-and-unemployment/labour-force-australia"
+}
+```
+
+**"Show me NSW housing approvals over the last two years"**
+
+```
+get_data(dataset_id="BA_GCCSA", filters={"region": "nsw", "measure": "dwelling_units"}, start_period="2024")
+```
+
+**"Compare quarterly CPI in Sydney vs Melbourne"**
+
+```
+get_data(dataset_id="CPI", filters={"region": ["sydney", "melbourne"], "measure": "change_year"}, start_period="2023")
+```
+
+## Period formats
+
+ABS uses different period formats per dataflow:
+- Monthly (LF, BA_GCCSA, LEND_HOUSING): `"2026-03"`
+- Quarterly (CPI): `"2024-Q1"`
+- Annual (ABS_ANNUAL_ERP_ASGS2021): `"2024"`
+
+Pass `start_period` / `end_period` in the matching format.
+
+## Development
+
+```bash
+git clone https://github.com/Bigred97/abs-mcp.git
+cd abs-mcp
+uv sync --extra dev
+uv pip install -e .
+
+# Unit tests (no network)
+uv run pytest
+
+# Live integration tests (hits real ABS API)
+uv run pytest -m live
+```
+
+The SQLite cache lives at `~/.abs-mcp/cache.db`. Catalogue refreshes every 24h, codelists every 7 days, data responses every hour, latest 15 minutes. Delete the file to force a refresh.
+
+## How it differs from existing ABS MCP servers
+
+The one existing community option (`seansoreilly/abs`) exposes a single `query_dataset` tool that passes raw SDMX through. This package offers semantic tools and curated mappings for the highest-value dataflows so an LLM can answer real questions without you needing to know what `M13.3.1599.20.1.M` means.
+
+## License
+
+MIT — Harry Vass, 2026.

abs_mcp-0.1.0/examples/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "abs": {
+      "command": "uvx",
+      "args": ["abs-mcp"]
+    }
+  }
+}

abs_mcp-0.1.0/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["Bigred97"]
+}

abs_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "abs-mcp"
+version = "0.1.0"
+description = "MCP server for the Australian Bureau of Statistics Data API. Hides SDMX behind plain-English tools, with curated mappings for Labour Force, CPI, ERP, Building Approvals, and Lending Indicators."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Harry Vass" }]
+keywords = ["mcp", "abs", "statistics", "australia", "sdmx", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "fastmcp>=2.0,<4",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "rapidfuzz>=3.9",
+    "pandas>=2.2,<3",
+    "sdmx1>=2.20",
+    "aiosqlite>=0.20",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[project.scripts]
+abs-mcp = "abs_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/Bigred97/abs-mcp"
+Issues = "https://github.com/Bigred97/abs-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/abs_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["live: hits the real ABS API"]
+addopts = "-m 'not live'"
+testpaths = ["tests"]
+pythonpath = ["src"]

abs_mcp-0.1.0/src/abs_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

abs_mcp-0.1.0/src/abs_mcp/cache.py

@@ -0,0 +1,87 @@
+"""SQLite-backed HTTP cache with per-read TTL.
+
+Single table; the same row can satisfy different TTL windows because TTL is
+evaluated at read time. The `kind` column lets us run targeted invalidation
+later without renaming.
+"""
+from __future__ import annotations
+
+import time
+from datetime import timedelta
+from pathlib import Path
+from typing import Literal
+
+import aiosqlite
+
+CacheKind = Literal["catalogue", "datastructure", "data", "latest"]
+
+DEFAULT_DB_PATH = Path.home() / ".abs-mcp" / "cache.db"
+
+TTL: dict[CacheKind, timedelta] = {
+    "catalogue": timedelta(hours=24),
+    "datastructure": timedelta(days=7),
+    "data": timedelta(hours=1),
+    "latest": timedelta(minutes=15),
+}
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS http_cache (
+    cache_key  TEXT PRIMARY KEY,
+    payload    BLOB NOT NULL,
+    cached_at  REAL NOT NULL,
+    kind       TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_kind_cached_at ON http_cache(kind, cached_at);
+"""
+
+
+class Cache:
+    def __init__(self, db_path: Path = DEFAULT_DB_PATH) -> None:
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialized = False
+
+    async def _ensure_init(self) -> None:
+        if self._initialized:
+            return
+        async with aiosqlite.connect(self.db_path) as conn:
+            await conn.execute("PRAGMA journal_mode=WAL")
+            await conn.executescript(_SCHEMA)
+            await conn.commit()
+        self._initialized = True
+
+    async def get(self, key: str, ttl: timedelta) -> bytes | None:
+        await self._ensure_init()
+        cutoff = time.time() - ttl.total_seconds()
+        async with aiosqlite.connect(self.db_path) as conn:
+            async with conn.execute(
+                "SELECT payload FROM http_cache WHERE cache_key = ? AND cached_at >= ?",
+                (key, cutoff),
+            ) as cur:
+                row = await cur.fetchone()
+        return row[0] if row else None
+
+    async def set(self, key: str, value: bytes, kind: CacheKind) -> None:
+        await self._ensure_init()
+        async with aiosqlite.connect(self.db_path) as conn:
+            await conn.execute(
+                """
+                INSERT INTO http_cache (cache_key, payload, cached_at, kind)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(cache_key) DO UPDATE SET
+                    payload = excluded.payload,
+                    cached_at = excluded.cached_at,
+                    kind = excluded.kind
+                """,
+                (key, value, time.time(), kind),
+            )
+            await conn.commit()
+
+    async def clear(self, kind: CacheKind | None = None) -> None:
+        await self._ensure_init()
+        async with aiosqlite.connect(self.db_path) as conn:
+            if kind:
+                await conn.execute("DELETE FROM http_cache WHERE kind = ?", (kind,))
+            else:
+                await conn.execute("DELETE FROM http_cache")
+            await conn.commit()