fbi-crime-data-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

FBI Crime Data MCP Server — a Python MCP server providing 17 tools (15 for querying the FBI Crime Data Explorer API at https://api.usa.gov/crime/fbi/cde, plus 2 admin tools for cache and spillover management). Built with fastmcp (v3.2+) and httpx, deployable via uvx fbi-crime-data-mcp.

Build & Run

uv sync                                           # install deps
FBI_API_KEY=xxx uv run fbi-crime-data-mcp          # run server (stdio)
uv run pytest                                      # run tests
FBI_API_KEY=xxx uv run pytest -m integration        # integration tests (hits real API)

Architecture

• src/fbi_crime_data_mcp/server.py — FastMCP server entry point with lifespan context. Imports all tool modules. Configures three ErrorAwareCachingMiddleware instances (from caching.py) with FileTreeStore for tiered disk-backed caching (90-day TTL for summaries/trends/reference/NIBRS estimation; 30-day TTL for agency lookups and granular crime/officer data; 1-day TTL for homepage summary), plus a ResponseSpilloverMiddleware for oversized responses. Cache persists to ~/.cache/fbi-crime-data-mcp/.
• src/fbi_crime_data_mcp/api_client.py — Shared httpx.AsyncClient wrapper with sliding-window rate limiter (1000 req/hr). AppContext dataclass is the lifespan context available to all tools via ctx.lifespan_context.
• src/fbi_crime_data_mcp/response_utils.py — Post-processing for API responses: process_crime_response() trims verbose sections (tooltips, participated_population) and aggregates monthly mm-yyyy data into yearly totals, adding a top-level _partial_years marker when any year has fewer than 12 months of data; filter_agencies_by_name() does case-insensitive substring filtering on agency lists.
• src/fbi_crime_data_mcp/constants.py — All validation enums: SRS offenses, NIBRS codes, arrest offenses, bias codes, LESDC chart types, states.
• src/fbi_crime_data_mcp/caching.py — ErrorAwareCachingMiddleware, a ResponseCachingMiddleware subclass whose on_call_tool skips writing results that start with an UNCACHEABLE_PREFIXES entry (Error:, Rate limit reached). Tools never raise, so without this a timeout or HTTP 5xx would be cached for the full TTL. Mirrors fastmcp 3.2 private internals; tests/test_caching.py guards the layout.
• src/fbi_crime_data_mcp/spillover.py — ResponseSpilloverMiddleware saves oversized tool responses (>128K chars) to disk under ~/.cache/fbi-crime-data-mcp/spillover/, returning a preview with the file path. Content-addressed filenames avoid duplicates.
• src/fbi_crime_data_mcp/validators.py — Shared validation helpers used by tools: level, data_type, aggregate, state, ORI, date format (mm-yyyy / yyyy), year range, and offense code validators. Also provides build_geo_path() for constructing national/state/agency API paths and effective_aggregate() for aggregate passthrough logic.
• src/fbi_crime_data_mcp/tools/ — One module per tool, each registers via @mcp.tool() decorator on the shared mcp instance imported from server.py.