statfin-mcp: Instructions file for Claude Code

StatFin MCP Server

MCP server for Statistics Finland's StatFin database. See README.md for project overview and ARCHITECTURE.md for technical details.

Quick Reference

Development Commands

npm install          # Install dependencies
npm run dev          # Development (stdio, watch mode)
npm run build        # Build TypeScript
npm run typecheck    # Type checking
npm run test:run     # Run unit tests
npm run test:coverage # Run tests with coverage
npm start            # Production (HTTP transport)

Project Structure

src/
├── server.ts              # MCP server (stdio + HTTP transports)
├── config.ts              # Environment configuration
├── tools/                 # 7 MCP tools (search, list, query, etc.)
├── services/              # PxWeb client, cache, rate limiter
├── types/                 # TypeScript definitions
└── utils/                 # Logger, HTTP helpers

tests/
├── unit/                  # Unit tests (vitest)
├── integration/           # Real API tests
└── fixtures/              # API response fixtures

MCP Tools

1. search_statistics - Full-text search (primary discovery)
2. list_subject_areas - Browse 149 topic areas
3. list_tables - Tables in a subject area
4. get_table_metadata - Table structure/variables
5. get_variable_values - Variable codes (regions, years)
6. query_table - Execute data queries
7. get_api_status - Health and rate limits

Key Patterns

Rate Limiting: Token bucket, 8 req/min per instance (3 instances = 24 req/min, under 30 limit)

Caching: Timestamp-validated. Query results cached until table's updated timestamp changes.

Query Selection (variable codes are table-specific and version-stamped — always fetch them via get_table_metadata; the codes below are from table 11re.px):

{ variable: "alue_23_20260101", filter: "item", values: ["KU091"] }   // Specific values
{ variable: "timeperiod_y", filter: "top", top: 5 }                   // Latest N values
{ variable: "sukupuoli_9_20180101", filter: "all" }                   // All values (caution!)