civicgraph-mcp

A money-in-politics knowledge graph, as an MCP server. It links entities across federal campaign donations, lobbying disclosures, and government contracts — so an agent can trace a name from a donor record, to a lobbying client, to a federal contract, and surface the "follow the money" / revolving-door connections nobody else exposes as a tool.

Why this exists

The raw sources each already have MCP servers — FEC (donations), Senate LDA (lobbying), USASpending (contracts). But they're islands. The valuable, hard, unbuilt part isn't the rows; it's the joins: resolving that the "John A. Smith" in an FEC filing, the lobbyist in an LDA report, and the contractor contact in USASpending are (or aren't) the same entity, and letting you walk those connections. That linkage — explainable entity resolution — is the product.

Quick start (offline, no API keys)

The whole pipeline runs on committed sample data, so a fresh checkout works with no network and no keys.

uv sync                          # create the env, install deps

uv run civicgraph ingest         # load the oklahoma-2024 slice from samples
uv run civicgraph build          # build the single-source graph (24 nodes, 22 edges)
uv run civicgraph resolve        # cross-source entity resolution (8 merges -> 17 entities)

uv run civicgraph eval           # measure resolution quality (P/R/F1 on a labeled set)

Then query it:

# Find an entity
uv run civicgraph search "Heartland"
#   -> HEARTLAND DEFENSE SYSTEMS, INC.  sources: [fec, usaspending]

# Resolve a name to a canonical entity, with confidence + the features behind it
uv run civicgraph resolve-name "James Carter" --state OK --employer "Carter & Lowe LLP" --kind person

# Follow the money: a PAC -> a defense agency, through a donor who is also a contractor
PAC=$(uv run civicgraph search "Oklahoma Prosperity PAC" | jq -r '.results[0].entity_id')
ARMY=$(uv run civicgraph search "Department of the Army" | jq -r '.results[0].entity_id')
uv run civicgraph path "$PAC" "$ARMY"
#   OKLAHOMA PROSPERITY PAC  <-donated_to (FEC, $7,500)-  HEARTLAND DEFENSE SYSTEMS
#                            -contracted_with (USASpending, $4.2M)->  Department of the Army

Every edge carries its source record URL + date; every resolution carries a confidence score and the features that drove it.

Use it as an MCP server

uv run civicgraph serve          # speaks MCP over stdio

Register it with an MCP host (e.g. Claude Desktop). Populate the store once (ingest / build / resolve), then point the host at the repo:

{
  "mcpServers": {
    "civicgraph": {
      "command": "uv",
      "args": ["run", "civicgraph", "serve"],
      "cwd": "/path/to/civicgraph-mcp"
    }
  }
}

Tools

Tool	What it does
resolve_entity(name, state?, employer?, kind?)	Fuzzy-match a name/org to a canonical entity, with confidence, the matching features, and runner-up alternatives.
entity_profile(entity_id)	Everything we know: donations, lobbying roles, contracts, aliases, sources — edges summarized by type, each with provenance.
connections(entity_id, hops=1, types?)	Neighbors in the graph, optionally filtered to specific edge types.
path_between(entity_a, entity_b, max_hops=4)	Shortest sourced path between two entities — how they're connected.
search(query, limit=10)	Full-text search across entity names and aliases.

(ping, graph_stats are also exposed.)

Live data

The offline demo uses synthetic samples. To ingest real federal data for the slice, get free keys (FEC, Senate LDA; USASpending needs none), copy .env.example to .env, fill them in, and:

uv run civicgraph ingest --live
uv run civicgraph build && uv run civicgraph resolve

FEC's 1,000 req/hr limit is respected via on-disk caching + backoff; raw snapshots are written under data/raw/ before normalization so runs are auditable.

How it works

FEC ─┐
LDA ─┼─▶ adapters (snapshot → normalize) ─▶ staging ─▶ graph (raw nodes + edges)
USAspending ─┘                                              │
                                       entity resolution (block → score → merge)
                                                            │
                              DuckDB store ◀── canonical entities + node_map
                                                            │
                                        FastMCP server / civicgraph CLI

• Bounded slice. v1 is Oklahoma, 2024 cycle — see docs/slice.md. Scope discipline is a feature: a correct, explainable small graph first.
• Explainable resolution. A strong name match alone never merges; identity needs corroboration (shared employer/firm, state, zip), and conflicting evidence is penalized. Auto-merge above a high threshold, surface a candidate in the middle band, never link below. See docs/resolution-eval.md for the measured precision/recall.
• Non-destructive. Edges reference raw nodes; resolution only repoints a node_map, so it's re-runnable and merges are never destructive.

Development

uv run pytest        # full offline suite
uv run ruff check .  # lint

If uv run civicgraph ... ever reports No module named 'civicgraph' (a known editable-install quirk on some setups, e.g. project paths containing spaces), run with PYTHONPATH=src uv run civicgraph ... — the test suite is unaffected.

See SPEC.md, BUILD_PLAN.md, and CLAUDE.md for the design.

License

MIT.