ausecon-mcp-server 0.5.0__tar.gz

ausecon_mcp_server-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.12']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify public repository hygiene
+        shell: bash
+        run: |
+          test -f LICENSE
+          if rg -n "rba_abs_mcp|<your-repo-url>" README.md examples pyproject.toml; then
+            echo "Found stale public references"
+            exit 1
+          fi
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }} --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Test
+        run: uv run pytest

ausecon_mcp_server-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ausecon_mcp_server-0.5.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+coverage.xml
+.coverage
+ausecon-mcp-server-future-releases.png
+.DS_Store

ausecon_mcp_server-0.5.0/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync --python 3.12
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_catalogue.py
+
+# Run a single test by name
+uv run pytest tests/test_catalogue.py::test_search_catalogue_prefers_high_value_alias_matches
+
+# Lint and format
+uv run ruff check src tests
+uv run ruff format src tests
+
+# Run the MCP server (stdio mode)
+uv run ausecon-mcp-server
+```
+
+## Architecture
+
+This is a **FastMCP server** that wraps ABS (Australian Bureau of Statistics) and RBA (Reserve Bank of Australia) data APIs. The design is intentionally thin on the MCP surface and delegates all logic to internal layers.
+
+### Layer structure
+
+```
+server.py          → FastMCP tool definitions, AuseconService orchestrator
+providers/         → Async httpx clients for each source (ABS, RBA), TTLCache wrappers
+parsers/           → Pure functions: raw HTTP response text → normalised dicts
+catalogue/         → Static curated dicts (abs.py, rba.py) + search.py ranking logic
+models.py          → SeriesDescriptor and Observation dataclasses; shared to_dict() helpers
+cache.py           → In-memory TTLCache (monotonic clock, per-instance, no persistence)
+```
+
+### Data flow
+
+1. MCP tool call → `AuseconService` method
+2. `AuseconService` → `ABSProvider` or `RBAProvider` (checks TTLCache first)
+3. Provider → httpx GET → raw CSV or XML response
+4. Parser (`parse_abs_csv`, `parse_rba_csv`, `parse_abs_structure`) → `{metadata, series, observations}` dict
+5. Optional post-fetch filtering (`_slice_observations`, `_filter_rba_payload`) for `last_n`, date ranges, series IDs
+6. Result cached and returned as dict (not model instances)
+
+### ABS vs RBA differences
+
+- **ABS** uses SDMX REST (`data.api.abs.gov.au/rest`): structure endpoint returns XML, data endpoint returns CSV with `format=csvfile`.
+- **RBA** serves static CSVs at `rba.gov.au/statistics/tables/csv/{table_id}-data.csv`; all filtering is done client-side after download.
+
+### Tool injection pattern
+
+`build_server()` in `server.py` creates the FastMCP instance and registers all tools as closures over an `AuseconService`. Tests inject mock providers directly into `AuseconService`, which is then passed to `build_server()`.
+
+### Catalogue search scoring
+
+`search_catalogue` in `catalogue/search.py` ranks entries by weighted keyword matching: exact alias match (+120) > exact name match (+100) > substring in name (+45) > substring in description (+25) > alias term overlap (+20 per term). Source filtering (`source="abs"` or `"rba"`) is applied before scoring.
+
+### Response shape
+
+All retrieval tools return `{metadata: {...}, series: [...], observations: [...]}`. Provenance fields (`retrieval_url`, `truncated`, `updated_after`) are added to `metadata` after parsing.
+
+## Key conventions
+
+- All provider methods are `async`; `list_tables` on `RBAProvider` is the only sync exception (no I/O).
+- `asyncio_mode = "auto"` is set in `pyproject.toml` — no `@pytest.mark.asyncio` decorator needed.
+- Tests use `respx` for HTTP mocking and fixture files in `tests/fixtures/`.
+- Ruff target is Python 3.10 with `E, F, I, B, UP` rules and line length 100.

ausecon_mcp_server-0.5.0/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to `ausecon-mcp-server` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-04-17
+
+Semantic-defaults and release-readiness release. Curated
+`get_economic_series` concepts now resolve to concrete series by default, and
+the public onboarding docs now cover the main local MCP clients.
+
+### Changed
+- `cash_rate_target`, `headline_cpi`, `trimmed_mean_inflation`, and
+  `gdp_growth` now resolve to narrowed default series instead of broad ABS
+  datasets or RBA tables.
+- Curated catalogue entries for `CPI`, `ANA_AGG`, `a2`, and `g1` now include
+  populated default semantic variants used by the resolver.
+- `README.md` now documents the actual `get_economic_series` inputs and
+  provides self-serve local setup instructions for Claude Desktop, Claude Code,
+  and Codex.
+
+### Fixed
+- ABS structure parsing now handles the current SDMX structure shape where
+  dimension metadata is nested under `ConceptIdentity` / `LocalRepresentation`
+  and includes `TimeDimension` entries.
+- ABS CSV parsing now handles current upstream column names such as
+  `TIME_PERIOD`, `UNIT_MEASURE`, `UNIT_MULT`, and `OBS_STATUS`, rather than
+  only the older labelled column variants.
+- Repository hygiene and behavioural tests now pin the `v0.5.0` semantic
+  shortcut contract and public onboarding text.
+
+## [0.4.0] - 2026-04-17
+
+Semantic resolver release. `get_economic_series` accepts variant / geography /
+frequency and dispatches to narrowed ABS or RBA retrievals.
+
+### Added
+- `ausecon_mcp.catalogue.resolver` module exposing `resolve()`, `build_abs_key()`,
+  `ResolvedQuery`, and the `CURATED_SHORTCUTS` map (replaces the removed
+  `CURATED_SERIES` dict on `server`).
+- ABS SDMX key construction that orders dimensions by `position`, composes from
+  literal dot-keys or `DIM=code;DIM=code` variant fragments, and validates each
+  emitted code against the live codelist.
+- RBA variant resolution returns the variant's `rba_series_ids` as the
+  `get_rba_table` filter.
+- `tests/test_resolver.py` — 19 unit tests covering unknown/ambiguous concepts,
+  unknown/unpopulated variants, frequency/geography validation, key composition,
+  and codelist mismatches.
+- First populated variant: `g1.headline` → `["GCPIAG"]`. Additional variants are
+  populated progressively as `scripts/dump_variant_candidates.py` output is
+  reviewed.
+
+### Changed
+- `get_economic_series` no longer rejects `variant` / `geography` / `frequency`;
+  it routes through the new resolver. Unknown values raise actionable errors
+  listing what is available.
+- When a curated shortcut has no variant supplied and no explicit variant is
+  declared, the response is identical to v0.3.2 (whole dataset or whole table).
+
+### Removed
+- `CURATED_SERIES` dict and `_unsupported_semantic_options` helper from
+  `server.py`.
+
+## [0.3.2] - 2026-04-17
+
+Bridge release between the v0.3.x discovery work and the upcoming v0.4.0 semantic
+resolver. No tool-surface changes.
+
+### Added
+- `CHANGELOG.md` seeded from git history. Earlier releases are reconstructed from
+  commit history and the README version notes.
+- `scripts/dump_variant_candidates.py` — dev-only helper that fetches each curated
+  RBA table and ABS dataflow structure, then writes a reviewable reference doc at
+  `docs/variant_candidates.md`. Used to hand-populate `variants[*].abs_key` and
+  `variants[*].rba_series_ids` in preparation for the v0.4.0 resolver.
+
+### Changed
+- `get_economic_series` now raises a version-neutral message when `variant`,
+  `geography`, or `frequency` are supplied. The previous message referenced
+  `v0.3.0` even in v0.3.1.
+
+## [0.3.1] - 2026-04-16
+
+### Fixed
+- Support Python 3.10 by depending on `tomli` for pre-3.11 interpreters.
+- Allow `pytest >= 9`.
+
+### Changed
+- README now displays a release badge.
+
+## [0.3.0] - 2026-04-14
+
+Discovery release. Same six-tool surface, materially expanded catalogue and
+deterministic search ranking.
+
+### Added
+- Expanded ABS catalogue to ~30 curated dataflows across prices, labour, national
+  accounts, activity, housing & construction, external sector, credit & finance,
+  and demographics.
+- Expanded RBA catalogue to ~30 active tables (plus `discontinued: True` tagging
+  where applicable) across monetary policy, payments, money & credit, interest
+  rates, exchange rates, inflation, output & labour, external sector, and
+  household finance.
+- `search_datasets` uses deterministic tiered scoring: exact id > exact alias >
+  exact name > full-term match > partial-term match > description match.
+- Catalogue entries declare resolver schema fields (`frequencies`, `geographies`,
+  `variants`) that stay inert until the v0.4.0 resolver consumes them.
+- Catalogue-coverage and search-ranking tests in `tests/test_catalogue.py`.
+
+## [0.2.0] - 2026-04-12
+
+Hardening release.
+
+### Added
+- `validation.py` — input validation for dataflow IDs, keys, ABS periods, ISO
+  dates, positive integers, series IDs, categories, and `updated_after`
+  timestamps. Applied at every tool boundary.
+- `providers/_retry.py` — exponential backoff (0.1s → 0.2s → 0.4s, 3 attempts)
+  with 4xx-no-retry / 5xx-retry / timeout-retry behaviour.
+- Provider-level error wrapping: `AuseconParseError` for malformed upstream
+  payloads, `AuseconUpstreamError` for HTTP failures.
+- Per-provider TTLCache (3600s default) for raw upstream payloads.
+- Support for ABS `a2` event-style tables.
+
+## [0.1.0] - 2026-04-12
+
+Initial public release.
+
+### Added
+- FastMCP server exposing six tools (`search_datasets`, `get_abs_data`,
+  `get_abs_dataset_structure`, `get_rba_table`, `list_rba_tables`,
+  `get_economic_series`).
+- Async httpx providers for ABS SDMX REST and RBA statistical CSVs.
+- Pure-function parsers for ABS SDMX CSV, ABS structure XML, and RBA CSVs.
+- Initial curated catalogues for ABS and RBA, plus a four-concept
+  `CURATED_SERIES` semantic shortcut map.
+
+[0.5.0]: https://github.com/AnthonyPuggs/ausecon-mcp-server/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/AnthonyPuggs/ausecon-mcp-server/compare/v0.3.2...v0.4.0
+[0.3.2]: https://github.com/AnthonyPuggs/ausecon-mcp-server/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/AnthonyPuggs/ausecon-mcp-server/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/AnthonyPuggs/ausecon-mcp-server/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/AnthonyPuggs/ausecon-mcp-server/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/AnthonyPuggs/ausecon-mcp-server/releases/tag/v0.1.0

ausecon_mcp_server-0.5.0/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync --python 3.12
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_catalogue.py
+
+# Run a single test by name
+uv run pytest tests/test_catalogue.py::test_search_catalogue_prefers_high_value_alias_matches
+
+# Lint and format
+uv run ruff check src tests
+uv run ruff format src tests
+
+# Run the MCP server (stdio mode)
+uv run ausecon-mcp-server
+```
+
+## Architecture
+
+This is a **FastMCP server** that wraps ABS (Australian Bureau of Statistics) and RBA (Reserve Bank of Australia) data APIs. The design is intentionally thin on the MCP surface and delegates all logic to internal layers.
+
+### Layer structure
+
+```
+server.py          → FastMCP tool definitions, AuseconService orchestrator
+providers/         → Async httpx clients for each source (ABS, RBA), TTLCache wrappers
+parsers/           → Pure functions: raw HTTP response text → normalised dicts
+catalogue/         → Static curated dicts (abs.py, rba.py) + search.py ranking logic
+models.py          → SeriesDescriptor and Observation dataclasses; shared to_dict() helpers
+cache.py           → In-memory TTLCache (monotonic clock, per-instance, no persistence)
+```
+
+### Data flow
+
+1. MCP tool call → `AuseconService` method
+2. `AuseconService` → `ABSProvider` or `RBAProvider` (checks TTLCache first)
+3. Provider → httpx GET → raw CSV or XML response
+4. Parser (`parse_abs_csv`, `parse_rba_csv`, `parse_abs_structure`) → `{metadata, series, observations}` dict
+5. Optional post-fetch filtering (`_slice_observations`, `_filter_rba_payload`) for `last_n`, date ranges, series IDs
+6. Result cached and returned as dict (not model instances)
+
+### ABS vs RBA differences
+
+- **ABS** uses SDMX REST (`data.api.abs.gov.au/rest`): structure endpoint returns XML, data endpoint returns CSV with `format=csvfile`.
+- **RBA** serves static CSVs at `rba.gov.au/statistics/tables/csv/{table_id}-data.csv`; all filtering is done client-side after download.
+
+### Tool injection pattern
+
+`build_server()` in `server.py` creates the FastMCP instance and registers all tools as closures over an `AuseconService`. Tests inject mock providers directly into `AuseconService`, which is then passed to `build_server()`.
+
+### Catalogue search scoring
+
+`search_catalogue` in `catalogue/search.py` ranks entries by weighted keyword matching: exact alias match (+120) > exact name match (+100) > substring in name (+45) > substring in description (+25) > alias term overlap (+20 per term). Source filtering (`source="abs"` or `"rba"`) is applied before scoring.
+
+### Response shape
+
+All retrieval tools return `{metadata: {...}, series: [...], observations: [...]}`. Provenance fields (`retrieval_url`, `truncated`, `updated_after`) are added to `metadata` after parsing.
+
+## Key conventions
+
+- All provider methods are `async`; `list_tables` on `RBAProvider` is the only sync exception (no I/O).
+- `asyncio_mode = "auto"` is set in `pyproject.toml` — no `@pytest.mark.asyncio` decorator needed.
+- Tests use `respx` for HTTP mocking and fixture files in `tests/fixtures/`.
+- Ruff target is Python 3.10 with `E, F, I, B, UP` rules and line length 100.

ausecon_mcp_server-0.5.0/LICENSE

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