# 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.

```bash
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:

```bash
# 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

```bash
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:

```json
{
  "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](https://api.data.gov/signup/),
[Senate LDA](https://lda.senate.gov/api/register/); USASpending needs none), copy
`.env.example` to `.env`, fill them in, and:

```bash
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](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](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

```bash
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](SPEC.md), [BUILD_PLAN.md](BUILD_PLAN.md), and [CLAUDE.md](CLAUDE.md)
for the design.

## License

MIT.