law-scrapper-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 overview

Law Scrapper MCP v4.3.1 is a modular Python MCP server that exposes 13 tools for searching and analyzing Polish legal acts from the Sejm API (api.sejm.gov.pl/eli/). Built with the official Python MCP SDK (mcp[cli]==2.0.0, MCPServer[AppContext]), it supports STDIO (default) and stateless Streamable HTTP at /mcp on port 7683.

Development commands

Standard uv invocations (uv sync, uv run pytest, uv run ruff check, uv run mypy) apply as usual; see pyproject.toml. The non-obvious ones:

# HTTP transport is opt-in via env var, not a flag
LAW_MCP_TRANSPORT=streamable-http uv run python -m law_scrapper_mcp

# Integration tests need the marker, or they are silently skipped
uv run pytest tests/integration/ -v -m integration

# Release management
uv run python scripts/check_release.py --version 2.4.0
# Prepare new release (via skill): /prepare-release X.Y.Z

Testing strategy

Three test layers: unit, in-memory integration (official mcp.Client + respx), and transport integration (real STDIO subprocess, loopback Streamable HTTP). CI additionally runs MCP conformance against /mcp. See tests/TEST_SUITE_SUMMARY.md for exact commands and file layout.

Architecture

Layered, src/ layout: models/ → client/ → services/ → tools/ → server.py.

Key patterns:

• Document Store: Acts loaded into memory for section-level reading and search (asyncio.Lock)
• Result Store: Search results persisted for chained filtering (LRU eviction, TTL, asyncio.Lock)
• Circuit Breaker: CLOSED → OPEN → HALF_OPEN states protecting Sejm API from cascading failures
• Egress restraint: token-bucket pacing (LAW_MCP_API_RATE_PER_SECOND/_BURST), a bounded server-pause (LAW_MCP_API_MAX_SERVER_PAUSE), and document downloads aborted mid-stream past LAW_MCP_DOC_STORE_MAX_SIZE_BYTES
• Enriched responses: Every tool returns EnrichedResponse with hints; native outputSchema and object structuredContent
• Pagination: PageInfo model exposed as the page_info field with limit/offset on list and content tools (defaults: 20 items, 10,000 chars; maxima: 100 items, 50,000 chars)
• TTL cache: Async API response cache with configurable TTL (metadata=24h, search=10min)
• Error handling: @handle_tool_errors re-raises ToolExecutionError so failures surface as is_error=True
• Async throughout: httpx.AsyncClient with an explicit retry loop (budget-bounded, client/failure_policy.py), semaphore rate limiting, asyncio.Lock
• Official MCP SDK: Tools access lifespan resources via ctx.request_context.lifespan_context; HTTP via streamable_http_app(stateless_http=True, streamable_http_path="/mcp")