statsbudget-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project

MCP (Model Context Protocol) server exposing Swedish national budget data (statsbudgeten) — expenditure outturn, tax revenue, and tax quota/Laffer analysis — as tools for Claude Desktop and other MCP clients. Built on FastMCP. Python 3.12+.

Commands

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run the server
statsbudget-mcp                      # or: python -m statsbudget_mcp.server

# Tests (unit only — no network calls)
pytest tests/ -m "not integration"

# Single test
pytest tests/test_statskontoret.py::test_name -v

# All tests, including live SCB/Statskontoret API calls
pytest tests/

# Lint
ruff check src/ tests/

Tests marked @pytest.mark.integration (in test_scb_client.py, test_laffer.py) hit live external APIs — excluded by default via -m "not integration". asyncio_mode = "auto" is set in pyproject.toml, so async test functions don't need @pytest.mark.asyncio.

Architecture

Three independent data sources feed one FastMCP server (server.py), which holds module-level singleton clients (_scb, _sk, _cache) initialized in the lifespan context manager and accessed via _require_*() guards from each tool.

• statskontoret.py — StatskontoretClient scrapes the Statskontoret open-data page for download links, classifies them (expenditure vs. income, ZIP vs. Excel), downloads ZIPs, and parses semicolon-delimited Swedish-locale CSVs (comma decimals) into ExpenditureRow/IncomeRow dataclasses. Column mapping is header-name-based (Swedish column names, e.g. Utgiftsområde, Utfall) with a fallback default, since Statskontoret's schema isn't guaranteed stable.
• scb_client.py — SCBClient queries SCB's PxWeb v1 REST API (JSON POST) for tax revenue (SkatteIntakt) and tax quota (SkattekvotBNP) tables, with retry/backoff on transient errors (_RETRYABLE_EXCEPTIONS).
• laffer.py — builds tax-quota-vs-GDP timeseries from SCBClient data, annotated with a static list of Swedish tax reforms (TAX_REFORMS, 1971–2020). Explicitly descriptive, not a causal Laffer curve (see module docstring).
• cache.py — BudgetCache is a schema-versioned SQLite cache (~/.statsbudget-cache/statsbudget.db). A cache is only considered "populated" when both expenditure and income tables have rows AND snapshot_complete is true — partial snapshots are never trusted.
• formatters.py — ASCII visualizations (bars, flow diagrams, decision chains, Laffer timeline) for terminal/text MCP clients.
• server.py — defines all MCP tools/resources and owns startup semantics (see below).