ausecon-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Python 3.12 is recommended for local development. The package metadata and CI matrix support Python 3.10+.

# 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

# Run the eval benchmark (manual; needs ANTHROPIC_API_KEY; ~$10-15 per full run)
uv run --group evals python -m evals.run_eval --dry-run   # free: resolve ground truth only
uv run --group evals python -m evals.run_eval             # full three-arm run

# Regenerate the evaluation docs page after a run
# (first time only: add a `user-guide/evaluation` sidebar entry to docs-site/astro.config.mjs)
uv run python scripts/update_docs_eval.py

Architecture

This is a FastMCP server that wraps ABS (Australian Bureau of Statistics), RBA (Reserve Bank of Australia), and APRA (Australian Prudential Regulation Authority) 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, APRA), TTLCache wrappers
parsers/           → Pure functions: raw CSV/XML/XLSX responses → normalised dicts
catalogue/         → Curated dicts (abs.py, rba.py, apra.py), search.py ranking,
                     resolver.py semantic-concept shortcuts
periods.py         → Shared period parsing and sort keys for YYYY, YYYY-QN, YYYY-SN,
                     YYYY-MM, and YYYY-MM-DD observation dates
filters.py         → Post-fetch filtering (series_ids, date bounds, last_n); sorts
                     observations chronologically
bounds.py          → Analyst-friendly date bounds → source-native period normalisation
validation.py      → Tool input validation helpers
derived.py         → Transparent derived indicators (real rates, growth rates, yield slope)
convenience.py     → describe_dataset and latest/top observation selection metadata
releases.py        → Release calendar events
governance/        → APRA URL governance and audit checks
models.py          → SeriesDescriptor and Observation dataclasses; shared to_dict() helpers
cache.py           → Dual-layer TTLCache (memory + on-disk JSON cache)