fec-mcp-server: 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

MCP (Model Context Protocol) server providing tools to query FEC campaign finance data via the OpenFEC API. Designed for non-partisan campaign finance transparency research.

Commands

npm run build               # Compile TypeScript to build/
npm run test                # Run tests once
npm run test:e2e            # Run e2e tests against live FEC API
npm run typecheck           # Type check without emitting
npm run dev                 # Run with tsx watch (development)
npm run acceptance:fec-day  # Live acceptance checks (federal targets)
npm run acceptance:notable  # Live smoke test (notable classification)

Run a single test file:

npx vitest run tests/tools/get-receipts.test.ts

Architecture

MCP Server Flow

src/index.ts          → Entry point, STDIO transport
src/server.ts         → McpServer creation
src/tools/index.ts    → Tool registration hub (registerTools function)
src/config.ts         → Loads FEC_API_KEY from environment

Tool Pattern

Each tool follows this structure:

• src/tools/{tool-name}.ts - Tool definition constant + execute function
• src/schemas/{tool-name}.schema.ts - Zod schema object for MCP SDK

Tools export:

• {TOOL_NAME}_TOOL - Contains name, description, inputSchema
• execute{ToolName} - Async function taking FECClient + params

API Layer

• src/api/client.ts - FECClient class wrapping fetch calls to OpenFEC
• src/api/endpoints.ts - API URL constants and endpoint builders
• src/api/types.ts - FEC response interfaces (FECCandidate, FECScheduleA, etc.)

Notable Engine

src/notable/reference-data.ts  → Loads bundled reference lists (lobbyists, PACs, etc.)
src/notable/matchers.ts        → Fuzzy + exact matching against reference lists
src/notable/classifier.ts      → Classifies receipts/disbursements as notable with flag reasons
src/notable/formatters.ts      → Renders notable blocks for tool output
resources/reference-lists/     → Bundled CSV snapshots (lobbyists, leadership PACs, etc.)