# cdgmcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
exposes a Congress.gov-style legislative **GraphQL API** to MCP clients (such as
VS Code, Claude Desktop, or other agents). It provides high-level tools for
querying bills, actions, committee activities and cosponsors, plus a raw
GraphQL escape hatch for advanced queries.

## Features

### Tools

| Tool | Description |
| --- | --- |
| `search_bills` | Search/list bills with filters (congress, chamber, type, title, latest action, dates, sponsor). |
| `get_bill` | Fetch a single bill's full details, with optional actions, cosponsors, committee activities, titles and text versions. |
| `search_committee_activities` | Find committee referrals/activities and their related bills. |
| `search_actions` | Search the legislative action history (e.g. "Passed House", "Became Public Law"). |
| `search_cosponsors` | Search cosponsorship records across bills. |
| `get_node` | Fetch any object directly by its Relay global `id`. |
| `graphql_query` | Run an arbitrary read-only GraphQL query (mutations rejected). |

The API is built with Hot Chocolate 16.2.0 and follows Relay conventions. The
search tools are connection-based: each returns `pageInfo.endCursor`, which you
can pass back as the `after` argument to fetch the next page.

### Resources

| URI | Description |
| --- | --- |
| `cdg://schema` | The live GraphQL schema (SDL). |
| `cdg://guide` | Data model and usage guide. |
| `cdg://endpoint` | The configured GraphQL endpoint. |

## Example questions it can answer

- What bills have been recently introduced in the House or Senate?
- What bills have passed the House or Senate and became law recently?
- What bills have been referred to the Commerce Committee recently?
- Of the bills referred to the Agriculture Committee, which cosponsors recur
  across them?

## Configuration

The GraphQL endpoint defaults to `http://dotnet10-dev:5208/graphql/`. Override
it with the `CDG_GRAPHQL_ENDPOINT` environment variable.

## Build & run

```bash
npm install
npm run build
npm start          # or: node dist/index.js
```

For development (no build step) use:

```bash
npm run dev        # runs src/index.ts via tsx
```

## Use with VS Code

Add to your `.vscode/mcp.json` (or user `mcp.json`):

```json
{
  "servers": {
    "cdgmcp": {
      "command": "node",
      "args": ["${workspaceFolder}/cdgmcp/dist/index.js"],
      "env": {
        "CDG_GRAPHQL_ENDPOINT": "http://dotnet10-dev:5208/graphql/"
      }
    }
  }
}
```

The server communicates over stdio.

This is supposed to be a standalone testing something, but I haven't seen it work.

```
HOST=0.0.0.0 npx @modelcontextprotocol/inspector node dist/index.js
```