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

LUXEMBOURG_MCP_RATE_LIMIT sets the HTTP per-IP requests/minute limit (0 disables).

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, when allowed_hosts is passed, exact-hostname HTTPS allowlisting including on redirects (_SafeRedirectHandler).
• 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 and GTFS zip: 1 h; air quality: 10 min). HttpClient is constructor-injected, which is what lets tests run offline with a fake.
• src/luxembourg_mcp/server.py — McpServer: the tool registry (name → Tool dataclass with JSON schema), JSON-RPC dispatch in handle(), schema validation, and both transports (stdio loop; stateless ThreadingHTTPServer with body-size cap, RateLimiter, and localhost-Origin check).