Metadata-Version: 2.4
Name: govql-mcp-server
Version: 0.4.0
Summary: MCP server for GovQL — query US Congressional data via GraphQL from any MCP client.
Project-URL: Homepage, https://govql.us
Project-URL: Repository, https://github.com/govql/govql
Project-URL: Issues, https://github.com/govql/govql/issues
Author: GovQL
License-Expression: MIT
License-File: LICENSE
Keywords: ai,congress,government,graphql,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: fastmcp>=3.3.0
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

# govql-mcp-server

An MCP (Model Context Protocol) server for [GovQL](https://govql.us) — gives
AI clients like Claude Desktop, Claude Code, and Cursor direct access to the
US Congressional GraphQL API at [api.govql.us/graphql](https://api.govql.us/graphql)
without bespoke HTTP wiring.

For the design rationale (why FastMCP-Python, the passthrough+curated philosophy,
roadmap through v0.4), see
[design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md).

## What you can do with it

Ask an agent questions like:

- *"How did Vermont's two senators vote on the most recent nomination?"*
- *"Which legislators in the 118th Congress switched parties during their service?"*
- *"Who represents Arizona's 3rd congressional district?"*
- *"Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes
   in the most recent Congress."*
- *"Which Democrats most often voted with Republicans in the current Congress?"*

The agent picks the right tool, writes the GraphQL query against the live
schema, and parses the response — no manual API wrangling.

## Install

The server runs as a per-client subprocess over stdio. Pick your client:

### Claude Desktop

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}
```

Restart Claude Desktop. The `govql` tools appear in the tools panel.

### Claude Code

Add to `.mcp.json` in your project (or `~/.mcp.json` for global):

```json
{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}
```

### Cursor

Settings → MCP → Add Server. Use the same `command` / `args` as above.

### Other clients

Any MCP-compatible client that supports stdio servers will work. The command
is `uvx govql-mcp-server` with no required arguments.

## Tools

| Tool | Purpose |
|---|---|
| `execute_graphql` | Run any GraphQL query against the GovQL endpoint. Returns the result plus an `last_ingest` timestamp so the agent can reason about data freshness. |
| `list_types` | Returns the names and kinds of every type in the GovQL schema. Optional `kind` filter (`"OBJECT"`, `"INPUT_OBJECT"`, `"ENUM"`, etc.) to narrow further. Start here when you don't know what's queryable. |
| `describe_type` | Returns one type's full details — fields, arg signatures, input fields, enum values. Call after `list_types` to learn the shape of a specific type before writing a query. |
| `find_legislator` | Find members by name, party, state, chamber, or district when you don't know a bioguide id. Party/state/chamber/district match the member's terms (district is House-only); `current_only` (default) restricts to sitting members. Returns a compact list — each member's `bioguideId` plus current party/state/chamber/district. |
| `find_vote` | Browse roll-call votes by category, chamber, or congress (newest first), or keyword-search the vote `question`. `topic` matches the question text (which includes bill short titles) — not a full subject index, so it misses procedural votes, and bill subjects aren't populated yet. Returns a compact list with each `voteId`. |
| `get_legislator` | Full detail for one member by bioguide id: names, bio, and complete term history (party/state/chamber/district over time) with a `current` block. |
| `get_vote_with_positions` | One vote by id with tallies and per-party breakdown; optionally the individual member positions (filter by party/state/position). |
| `get_voting_record` | A member's voting behavior per congress: participation rate and party-loyalty rate, from the precomputed summaries. |
| `compare_voters` | How often two members voted the same way, per congress+chamber, with an agreement rate. |
| `find_party_defectors` | Members who least often voted with their own party's majority in a congress; optional party/chamber filters. |

## Configuration

All env vars are optional — the package is zero-config for end users.

| Env var | Default | Purpose |
|---|---|---|
| `GOVQL_ENDPOINT` | `https://api.govql.us/graphql` | Endpoint to query. Override to point at a local dev stack. |
| `GOVQL_TIMEOUT_MS` | `30000` | Per-request HTTP timeout. |
| `LOG_LEVEL` | `INFO` | Logging level. Logs go to stderr only (stdout is reserved for the MCP transport). |

## Limits (enforced by the upstream API)

- Max query depth: 10
- Max query complexity: ~10 billion points (`first: N` multiplies child cost
  by N — keep page sizes reasonable on deeply nested queries)
- Rate limit: 100 requests / 60 s per source IP

A depth or complexity violation surfaces as a GraphQL `errors` entry in the
tool response so the agent can adjust and retry.

## Data freshness

Every `execute_graphql` response includes a `last_ingest` ISO timestamp.
Vote data refreshes hourly; legislator data refreshes daily.

## Status

As of 0.4.0, the server provides the three foundational tools (`execute_graphql`,
`list_types`, `describe_type`) plus the curated **discovery** tools
(`find_legislator`, `find_vote`), **per-entity detail** tools (`get_legislator`,
`get_vote_with_positions`), and **analysis** tools (`get_voting_record`,
`compare_voters`, `find_party_defectors`) — the curated discovery/detail/analysis
set is now complete. The remaining `most_agreeing_pairs` and bill/committee
tools are post-v0.4: the bill/committee tools await GovQL data population, and
`most_agreeing_pairs` awaits a server-side cross-party ranking aggregate — see
[design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md).

## Links

- [GovQL project site](https://govql.us)
- [GraphQL API](https://api.govql.us/graphql)
- [Source / issues](https://github.com/govql/govql)
