congressgov mcp server changelog

version

0.10.0 → 0.10.1

https://raw.githubusercontent.com/cyanheads/congressgov-mcp-server/HEAD/AGENTS.md

− **Version:** 0.8.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`− **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1− **Zod:** ^4.6.5− ### Tools (11)− | `congressgov_bill_lookup` | Browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills) + bounded document text via `content`; `summaries` takes `versionCode` and the shared `characterOffset`/`characterLimit` window |− | `congressgov_committee_lookup` | Browse committees and retrieve legislation, reports, nominations |− | `congressgov_roll_votes` | Retrieve House and Senate roll call votes and member voting positions |− | `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline |− | `congressgov_bill_summaries` | Browse recent CRS bill summaries — the "what's happening" feed, bounded by the shared summary page budget and per-row text window |− | `congressgov_crs_reports` | Browse and retrieve nonpartisan CRS policy analysis reports |− | `congressgov_committee_reports` | Browse and retrieve committee reports accompanying legislation + bounded report text via `content` |− | `congressgov_search_bills` | Keyword-search bill titles/summaries via the opt-in local FTS mirror — off by default |− **Summary bounding** (`src/mcp-server/tools/summary-window.ts`, constants in `tool-helpers.ts`). Both summary surfaces enforce two limits. `SUMMARY_PAGE_CHARACTERS` stops a page once its serialized rows reach the budget — the first row always returns, `pagination.nextOffset` counts the rows actually returned, and an enrichment notice discloses the stop. `DEFAULT_SUMMARY_TEXT_CHARACTERS` bounds one row's upstream `text`; a windowed row gains `textTotalCharacters` / `textTruncated` / `textNextOffs− ### Resources (5)−     server-config.ts                    # CONGRESS_API_KEY, base URL (Zod schema)−       congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, character window−       extract-text.ts                   # GPO `<pre>` / XML body → deterministic plain text−       senate-vote-service.ts            # Senate LIS XML client — fetch, retry, not-found−       parse.ts                          # pure XML → domain parsers (fast-xml-parser)− Four services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only; `CongressDocumentsService` backs the `content` operation on `congressgov_bill_lookup`, `congressgov_committee_reports`, and `congressgov_daily_record`.− - The fetch is bounded: a 25 MB ceiling (refused on `Content-Length`, else mid-stream), a 30s deadline, and a content-type allowlist− - The body is extracted as it streams and only the requested window is retained, so a read's live set is flat in the size of the document (transient allocation is not — peak RSS runs above a buffered read); the ceiling bounds how long a response may run, not how much of one fits in a buffer− - `extract-text.ts` unwraps GPO's `<pre>` print output verbatim (whitespace is the document's structure), while no-`<pre>` XML gains one space only at an otherwise-unseparated sibling close→open element boundary; both readings decode character references through `src/utils/character-references.ts` — the one decoder every HTML/XML → text path in the server shares, single-pass so an escaped reference stays escaped — and `extract-text-stream.ts` is their incremental twin, pinned byte-for-byte again− - No live-API fallback — ingests through the existing `CongressApiService`, and a mirror that hasn't finished its initial build returns an empty result with a notice, not an error−   const bills = await api.listBills({ congress: input.congress, limit: input.limit });− `identityErrorContracts` declares `incompatible_identity` (`ValidationError`, -32007) only on bill lookup, roll votes, nominations, CRS reports, committee reports, and daily record. Their `list` handlers reject meaningful entity identifiers before any service call, preserving the explicit operation and harmless pagination/defaulted selectors. Optional blank string identities remain unset. Bill `type`/`number` and CRS `id`/`reportId`/`report_id` aliases normalize before that check; collisions ret− | Deadline or HTTP timeout | `Timeout` (-32004), `upstream_timeout`; HTTP responses retain status |− | API unavailable (5xx) | `serviceUnavailable('Congress.gov API returned HTTP {status}.')` |− | Network error | `serviceUnavailable('Unable to reach the Congress.gov API.')` |− The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end` — the last of which `congressgov_bill_lookup` also raises from its `summaries` branch when `characterOffset` is past the end of every returned row's text. `CongressDocumentsService` raises each with a matching `data.reason`; the framework fills the declared `recovery` hint when the throw carries none, servi− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant f− **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `framework-skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).− | `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` |− `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was − **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.+ **Version:** 0.10.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0+ **Zod:** ^4.6.7+ ### Tools (12)+ | `congressgov_bill_lookup` | Browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills) + bounded document text via `content`; `summaries` takes `versionCode` and the shared `characterOffset`/`characterLimit` window; `fromDateTime`/`toDateTime` apply to `list` only; an `actions` row recording exactly one roll call carries `rollVote` (House from the 115th Congress, Senate from the 101st) |+ | `congressgov_amendment_lookup` | Browse and retrieve amendments (`list`, `get`, `actions`, `cosponsors`, `amendments`, `text`, `content`) keyed by `congress` + `amendmentType` (`hamdt`/`samdt`/`suamdt`, any letter case; `suamdt` only in the 97th–98th) + `amendmentNumber` (number or digit string); `list` takes `fromDateTime`/`toDateTime` on update date and `order`; an `actions` row recording exactly one roll call carries `rollVote`; `content` reads one text version (`textVersionIndex`) as a cha+ | `congressgov_committee_lookup` | Browse committees and retrieve legislation, reports, nominations; a name passed as `committeeCode` resolves among the committees of `chamber` when it is set (all chambers otherwise), and the resolved committee is fetched in the chamber its roster row names |+ | `congressgov_roll_votes` | Retrieve House and Senate roll call votes and member voting positions; `chamber` in any letter case; `members` filters `bioguideId` (House only; Senate fails `unsupported_filter`), `stateCode`, `party` at the tool layer before paging (`pagination.count` counts matches, `memberFilter.rosterCount` is the roster size); House votes from the 115th Congress (`get`/`members` below it fail `not_found` before any request, pointing at the Clerk vote XML in bill actions' `recor+ | `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline; `nominationNumber` accepts `PN730-2` / `pn730-2` / `730-2`; `list` takes `fromDateTime`/`toDateTime` on update date; an action citing its own Senate record vote (`actions` rows, `latestAction` on `list`/`get`) carries `rollVote`, the `congressgov_roll_votes` arguments for it, from the 101st Congress on |+ | `congressgov_bill_summaries` | Browse recent CRS bill summaries — the "what's happening" feed; `limit` rows per page, each row's text bounded by the per-row window |+ | `congressgov_crs_reports` | Browse and retrieve nonpartisan CRS policy analysis reports; IDs are letters then digits (`R40097`) or two digit groups joined by a hyphen (`96-548`), case-insensitive; `list` takes `fromDateTime`/`toDateTime` on update date; `content` reads the report's HTML as text in character windows (PDF-only fails `format_unavailable` naming its URL) |+ | `congressgov_committee_reports` | Browse and retrieve committee reports accompanying legislation + bounded report text via `content`; `list` takes `fromDateTime`/`toDateTime` and `conference`; `part` (default 1) selects one part of a multi-part report on `get`/`text`/`content`, and `parts` lists them when there is more than one |+ | `congressgov_search_bills` | Keyword-search bill titles/summaries via the opt-in local FTS mirror — off by default; every response names the searchable congresses in `mirroredCongresses`, and a `congress` outside them returns an empty result with a notice pointing at `congressgov_bill_lookup` |+ **Summary bounding** (`src/mcp-server/tools/summary-window.ts`, constant in `tool-helpers.ts`). Both summary surfaces enforce one limit: `DEFAULT_SUMMARY_TEXT_CHARACTERS` bounds one row's upstream `text`; a windowed row gains `textTotalCharacters` / `textTruncated` / `textNextOffset`, and its window end is retracted off any HTML tag or character reference it would otherwise split (unless the construct is wider than the whole window, where the requested limit wins). The page and upstream paginati+ ### Resources (6)+ | `skill://congressgov-guide/SKILL.md` | Published legislative research guide |+     server-config.ts                    # CONGRESS_API_KEY, base URL (Zod schema); loads ./.env before the first parse+     call-budget.ts                      # One 50 s upstream budget per tool call / resource read, shared by the three HTTP services+       congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, call budget, character window+       document-body-cache.ts            # Process-local LRU of decompressed bodies — one fetch per document per TTL+       extract-text.ts                   # GPO `<pre>`/XML and HTML readings → deterministic plain text+       senate-vote-service.ts            # Senate LIS XML client — fetch, retry, not-found; falls back to Voteview when the feed can't answer+       parse.ts                          # pure XML → domain parsers (fast-xml-parser); Senate vote coverage, session for a date+       voteview-source.ts                # Voteview fallback source — per-congress file fetch, 1 h cache bounded in bytes, shared load, latest-vote not-found+       voteview-parse.ts                 # pure Voteview CSV → Senate vote shapes (rollcalls, votes, members); drops the President's positions+       csv.ts                            # one-pass RFC 4180 CSV reader+     tools/+       roll-vote-pointer.ts             # congressgov_roll_votes arguments for a recorded vote — House 115th / Senate 101st floors+       amendment-lookup.tool.ts         # congressgov_amendment_lookup+     congress-calendar.ts                # ordinal(), congressFirstYear(), currentCongressNumber() — congress numbering arithmetic+ Four services. `CongressApiService` backs ten tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only; `CongressDocumentsService` backs the `content` operation on `congressgov_bill_lookup`, `congressgov_committee_reports`, `congressgov_daily_record`, `congressgov_crs_reports`, and `congressgov_amendment+ **Call budget** (`call-budget.ts`, `withCallBudget`) — every upstream request a tool call or resource read makes through `CongressApiService`, `SenateVoteService`, or `CongressDocumentsService` spends one 50 s budget (`CALL_BUDGET_MS`) counted from the call's start (`ctx.timestamp`), so chained and parallel requests (a roster paged four times, a `content` lookup and then its document) end together before the 60 s default MCP client timeout:+ - Each request's retry ladder gets what is left as `withRetry` `deadlineMs`; each attempt's timeout (10 s API, 12 s Senate, 30 s document) is clamped to the remainder and its I/O carries the budget's signal+ - A backoff the remainder cannot hold fails at once as the expiry; a `Retry-After` wait it cannot hold fails at once with the upstream's own error and `retryAfter`; a request the spent budget cannot cover is never sent+ - Running out is `Timeout`, reason `upstream_timeout`, with `budgetMs` and `retryAttempts`. A caller abort stays `RequestCancelled`, and a 429 is still never retried+ - Services read the budget from the handler's own `ctx` — pass it to every service call, never a context derived from it (that carries a later timestamp). A request with no `ctx` — the mirror ingester and the `mirror:*` scripts — runs the plain per-request ladder, unbudgeted+ - Every path value is percent-encoded as one segment (the `apiPath` tag), and `buildUrl` refuses empty and dot segments before any request+ - senate.gov's firewall answers automated clients with HTTP 403 (or a firewall page — "Senate.gov - Unauthorized" or "Access Denied" — with a 200; `REFUSAL_PAGE_RE`), and a retry meets the same refusal: a 403 ends the LIS attempt at once, with no retry, and hands the call to the Voteview fallback below, while a 5xx or timeout is retried within the call budget first. A 403 the call falls back from is an expected status for `fetchWithTimeout` (logged at debug, never with the page body) and is note+ - **Voteview fallback** (`voteview-source.ts`, `voteview-parse.ts`, `csv.ts`): when the LIS feed can't answer — that refusal, another 4xx, a 5xx or timeout after its retries, an empty body (every `ServiceUnavailable` the feed raises) — `list`/`get`/`members` are served from Voteview's per-congress files (`rollcalls`, `votes`, `members` CSVs under `voteview.com/static/data/out/`) under the same call budget, and the result carries `source` (`name`, `url`, `congress`, `latestVote`, `citation`; `VOT

Showing the first 40 of each.

• + congressgov-guide

• + congressgov_amendment_lookup
• + congressgov_search_bills

version

0.9.0 → 0.10.0

version

0.8.1 → 0.9.0

version

0.8.0 → 0.8.1

https://raw.githubusercontent.com/cyanheads/congressgov-mcp-server/HEAD/AGENTS.md

− **Version:** 0.7.3− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.9`− **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0− | `CONGRESS_API_KEY` | No | Optional. Defaults to `DEMO_KEY` (30 req/hr). Own key from [api.data.gov](https://api.data.gov/signup/): 5,000 req/hr. |− - Rate limiting: 5,000 requests/hour per key− | Rate limit hit | `rateLimited('Congress.gov API rate limit reached (5,000 requests/hour).')` |− The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end` — the last of which `congressgov_bill_lookup` also raises from its `summaries` branch when `characterOffset` is past the end of every returned row's text. `CongressDocumentsService` raises each with a matching `data.reason` and resolves the hint via `ctx.recoveryFor` — note that `ctx.fail` does **not** auto− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. Plugin hosts auto-load a root `skills/`, so development guidance belongs in `framework-skills/`.− | `git-wrapup` | Land the commit stack, version bump, and changelog on a release branch; open the release PR |− | `release-and-publish` | Fast-forward main, tag, push, and publish to npm, MCP Registry, GitHub Releases, and Docker |− | `report-issue-framework` | File bugs/features against `@cyanheads/mcp-ts-core` |− | `report-issue-local` | File bugs/features against this server's repo |− | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper — Tier 3 opt-in |− Remind the user to run these after completing a release flow.+ **Version:** 0.8.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1+ | `CONGRESS_API_KEY` | No | Optional. Fallbacks: `DEMO_KEY` 30/hour and 50/day per IP; registered key from [api.data.gov](https://api.data.gov/signup/) 5,000/hour. Valid upstream hourly quota headers take precedence. |+ - **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.+ - Rate limiting: rolling process-local attempt budgets, reserved before every dispatch (failures, retries, concurrent calls included). Credential fallbacks are demo 30/hour + 50/day and registered 5,000/hour; valid upstream hourly headers override the fallback. Observed remaining is a conservative shared-quota bound, expires one local hour after observation, and never claims an upstream reset time. Other clients are outside local accounting+ `identityErrorContracts` declares `incompatible_identity` (`ValidationError`, -32007) only on bill lookup, roll votes, nominations, CRS reports, committee reports, and daily record. Their `list` handlers reject meaningful entity identifiers before any service call, preserving the explicit operation and harmless pagination/defaulted selectors. Optional blank string identities remain unset. Bill `type`/`number` and CRS `id`/`reportId`/`report_id` aliases normalize before that check; collisions ret+ | Rate limit hit | `rateLimited(...)` with `rate_limited`, credential/shared-quota guidance and upstream `Retry-After` when supplied |+ | Deadline or HTTP timeout | `Timeout` (-32004), `upstream_timeout`; HTTP responses retain status |+ The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end` — the last of which `congressgov_bill_lookup` also raises from its `summaries` branch when `characterOffset` is past the end of every returned row's text. `CongressDocumentsService` raises each with a matching `data.reason`; the framework fills the declared `recovery` hint when the throw carries none, servi+ Framework-handled tool, resource, and prompt errors carry `data.requestId`, matching that call's server log records; a tool's `content[]` closes with `request <id>`. Protocol-level rejections and resource-parameter errors containing only `{ uri }` are excluded. `runToolContract` fills declared recovery hints but adds no request ID.+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant f+ | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |+ | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |+ | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |+ | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |+ | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |+ The `release-and-publish` run handles npm, MCP Registry, bundle, GitHub Release, and GHCR publishing.

version

0.7.4 → 0.8.0

description

Access U.S. congressional data - bills, votes, members, committees - via MCP. → Access U.S. congressional data (bills, votes, members, committees) via MCP.

version

0.7.3 → 0.7.4