ausecon-mcp-server: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.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

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           → Dual-layer TTLCache (memory + on-disk JSON cache)

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 (filters.py) for last_n, date ranges, and 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=csvfilewithlabels (paired code/label columns; the parser also still accepts the code-only csvfile layout).
• RBA serves static CSVs at rba.gov.au/statistics/tables/csv/; most files use {table_id}-data.csv, while catalogue csv_path overrides cover exceptions such as f17-yields.csv. Filtering is done client-side after download.