luxembourg-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.

Commands

pip install -e .                                            # install (editable)

PYTHONPATH=src python -m unittest discover -s tests -v     # offline test suite (deterministic, no network)
PYTHONPATH=src python -m unittest tests.test_server.ProtocolTests.test_initialize   # single test
LUXEMBOURG_MCP_LIVE=1 PYTHONPATH=src python -m unittest tests.test_live_tools -v    # opt-in E2E against real upstreams

luxembourg-mcp                                              # stdio transport (default)
luxembourg-mcp --transport http --port 8000                 # HTTP: /mcp endpoint, / catalog, /health, /status

LUXEMBOURG_MCP_RATE_LIMIT sets the HTTP per-IP requests/minute limit (0 disables; IPv6 bucketed by /64). LUXEMBOURG_MCP_MAX_CONNECTIONS caps concurrent HTTP connections (default 32).

Hard constraint: zero dependencies

dependencies = [] in pyproject.toml is deliberate. The MCP protocol (JSON-RPC), HTTP client, XML/CSV/zip parsing, and JSON Schema validation are all hand-implemented on the stdlib. Do not add runtime dependencies; extend the existing minimal implementations instead (e.g. validate_schema in server.py supports only the schema keywords the tools actually declare).

Architecture

Three layers, strictly ordered:

• src/luxembourg_mcp/http.py — HttpClient wraps urllib; every network failure becomes UpstreamError. Enforces a 25 MB response cap and exact-hostname HTTPS allowlisting including on redirects (_SafeRedirectHandler): allowed_hosts when passed, otherwise the request URL's own host only (so a hardcoded upstream that starts redirecting cross-host fails loudly in the weekly live tests — update the constant rather than widening the policy).
• src/luxembourg_mcp/providers.py — LuxembourgData, one method per tool ("fetch → parse → shape"). Upstream base URLs are hardcoded constants. TTL cache via _cached() for expensive fetches (STATEC catalog, GTFS zip, ENTSO-E electricity documents, plenary votes, deputies, ADEM figures and commune registers: 1 h; air quality and LU-Alert metadata: 10 min; FLEX and Vël'OK: 2 min). _latest_resource() picks the newest file in datasets that publish one per day/quarter. HttpClient is constructor-injected, which is what lets tests run offline with a fake.
• src/luxembourg_mcp/status.py — StatusMonitor behind GET /status (the catalogue's per-card status lights): one cheap HttpClient.probe() per upstream in UPSTREAMS (reads only 4 KB; dataset-backed tools probe the small data.public.lu API v2 record, not v1), refreshed at most every 10 min, stale-while-revalidate; the first visitor waits at most 5 s and each round has a 30 s deadline, because request threads share the HTTP connection cap with /mcp. One failure = degraded, two in a row = down; a tool shows the worst state of its TOOL_UPSTREAMS.
• src/luxembourg_mcp/server.py — McpServer: the tool registry (name → Tool dataclass with JSON schema), JSON-RPC dispatch (dispatch() → HTTP status + body; handle() wraps it for stdio/tests), schema validation, and both transports (stdio loop; stateless ThreadingHTTPServer with body-size cap, RateLimiter, and localhost-Origin check).