![CongressMCPServer](assets/logo.svg) # Congress.gov API MCP Server This is a Model Context Protocol (MCP) server designed to provide access to the official Congress.gov API (v3) using a hybrid approach: * **MCP Resources:** For direct lookups of core legislative entities (Bills, Members, Congresses, Committees, general Info) using standardized URIs. * **MCP Tools:** For more complex operations like searching across collections (`congress_search`) and retrieving related data lists (`congress_getSubResource`). This server acts as a bridge, allowing MCP clients (like AI assistants or development tools) to easily query and utilize U.S. legislative data. ## Project Structure * `/src`: Contains all source code. * `/config`: Configuration management (`ConfigurationManager.ts`). * `/services`: Core logic for interacting with Congress.gov API (`CongressApiService.ts`, `RateLimitService.ts`). * `/tools`: MCP tool definitions (`search/`, `subresource/`, `index.ts`). * `/types`: TypeScript interfaces and Zod schemas. * `/utils`: Shared utility functions (logging, errors, etc.). * `resourceHandlers.ts`: Logic for handling core entity resource requests. * `createServer.ts`: Server instance creation, resource and tool registration. * `server.ts`: Main application entry point. * `/dist`: Compiled JavaScript output (generated by `npm run build`). * `/docs`: Project documentation (PRD, Feature Spec, RFCs). * `package.json`: Project metadata and dependencies. * `tsconfig.json`: TypeScript compiler options. * `.eslintrc.json`, `.prettierrc.json`: Linting and formatting rules. * `.env`: (Not committed) For storing `CONGRESS_GOV_API_KEY`. ## Getting Started 1. **Install Dependencies:** ```bash npm install ``` 2. **Set API Key:** Create a `.env` file in the project root and add your Congress.gov API key: ``` CONGRESS_GOV_API_KEY=YOUR_API_KEY_HERE ``` (Get a key from [https://api.data.gov/signup/](https://api.data.gov/signup/)) 3. **Build the Server:** ```bash npm run build ``` 4. **Run the Server:** ```bash npm start ``` (This runs `node dist/server.js`) Alternatively, run in development mode using `npm run dev` (uses `ts-node` and `nodemon`). ## Usage with MCP Client Connect your MCP client to the running server (e.g., via stdio if running locally). ### Accessing Resources Use the `access_mcp_resource` command/method with the appropriate URI. **Examples:** * **Get Bill H.R. 3076 (117th Congress):** ``` congress-server congress-gov://bill/117/hr/3076 ``` * **Get Member Pelosi:** ``` congress-server congress-gov://member/P000197 ``` * **Get Info about 118th Congress:** ``` congress-server congress-gov://congress/118 ``` * **Get API Overview:** ``` congress-server congress-gov://info/overview ``` ### Using Tools Use the `use_mcp_tool` command/method. **!!! CRITICAL TOOL WORKFLOW: Finding Entities & Getting Related Data !!!** Many common tasks require a **mandatory two-step process** using both tools: 1. **STEP 1: Find the Entity ID using `congress_search`** * **Purpose:** Locate the specific bill, member, committee, etc., you need and extract its unique identifier(s) (e.g., `memberId`, or the `congress`, `billType`, `billNumber` for a bill URI). * **Tool:** `congress_search` * **Example:** Find member "John Kennedy" (might return multiple results requiring selection): ```xml congress-server congress_search { "collection": "member", "query": "John Kennedy" } ``` * **Output:** Look for the `memberId` (e.g., `K000393`) or other necessary identifiers in the results. * **!!! WARNING !!!** Searching might return multiple results. You **MUST** identify the correct entity and use its specific ID for the next step. * **!!! API LIMITATION !!!** Filtering general searches by `congress` using the `filters` parameter is **NOT SUPPORTED** by the underlying API (e.g., for `/v3/bill` or `/v3/member`) and will be ignored. Congress-specific filtering usually requires using specific API paths (e.g., `/v3/bill/117`), which this tool does not construct. 2. **STEP 2: Get Related Data using `congress_getSubResource`** * **Purpose:** Use the identifier(s) found in Step 1 to construct the `parentUri` and fetch related details (actions, sponsors, text, etc.). * **Tool:** `congress_getSubResource` * **Prerequisite:** You **MUST** have the correct `parentUri` (e.g., `congress-gov://member/K000393`) from Step 1. * **Example:** Get legislation sponsored by member `K000393`: ```xml congress-server congress_getSubResource { "parentUri": "congress-gov://member/K000393", "subResource": "sponsored-legislation", "limit": 5 } ``` * **!!! GUARANTEED ERROR WARNING !!!** You **MUST** use a `subResource` string that is **STRICTLY VALID** for the `parentUri` type (e.g., `'sponsored-legislation'` for members, `'actions'` for bills). Providing an invalid combination **WILL** cause an error. Check the tool description for valid combinations. **Following this two-step process is ESSENTIAL for reliably getting related information.** **Tool Examples:** * **Search for Bills containing "climate" (limit 5):** ```xml congress-server congress_search { "collection": "bill", "query": "climate", "limit": 5 } ``` * **List Members (No Congress Filter Possible Here):** * *Note: As mentioned above, filtering by `congress` directly in `congress_search` is not supported by the API for the 'member' collection.* ```xml congress-server congress_search { "collection": "member", "limit": 10 // Add "query" or other filters like "type" if needed } ``` * **Get Actions for Bill H.R. 3076 (117th) (Requires URI from Search or Known Info):** ```xml congress-server congress_getSubResource { "parentUri": "congress-gov://bill/117/hr/3076", "subResource": "actions", "limit": 10 } ``` * **Get Legislation Sponsored by Member P000197:** ```xml congress-server congress_getSubResource { "parentUri": "congress-gov://member/P000197", "subResource": "sponsored-legislation", "limit": 5 } ``` ## Linting and Formatting * **Lint:** `npm run lint` * **Format:** `npm run format` Code will be automatically linted and formatted on commit via Husky and lint-staged.