@cyanheads/congressgov-mcp-server 0.8.0 → 0.8.1

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.8.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
+**Version:** 0.8.1
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.16`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
-**Zod:** ^4.6.5
+**Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -330,11 +330,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ---
 
+**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow. Verification — `devcheck`, tests, and release gates — runs locally; don't add a workflow that re-runs it.
+
 ## Bundling
 
 `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 packed on. MCPB is stdio-only — HTTP deployments are unaffected. The bundle file ships as `dist/congressgov-mcp-server.mcpb`.
 
-**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.
+**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, every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"`, and an optional string option carries `"default": ""`. The host substitutes only the `user_config` reference; `"${X}"` reaches the server literally.
 
 ---
 
@@ -375,6 +377,7 @@ After a version bump and final commit, publish to both npm and GHCR:
 bun publish --access public
 
 docker buildx build --platform linux/amd64,linux/arm64 \
+  --build-arg APP_VERSION=<version> \
   -t ghcr.io/cyanheads/congressgov-mcp-server:<version> \
   -t ghcr.io/cyanheads/congressgov-mcp-server:latest \
   --push .

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.8.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
+**Version:** 0.8.1
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.16`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
-**Zod:** ^4.6.5
+**Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -330,11 +330,13 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ---
 
+**CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow. Verification — `devcheck`, tests, and release gates — runs locally; don't add a workflow that re-runs it.
+
 ## Bundling
 
 `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 packed on. MCPB is stdio-only — HTTP deployments are unaffected. The bundle file ships as `dist/congressgov-mcp-server.mcpb`.
 
-**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.
+**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, every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"`, and an optional string option carries `"default": ""`. The host substitutes only the `user_config` reference; `"${X}"` reaches the server literally.
 
 ---
 
@@ -375,6 +377,7 @@ After a version bump and final commit, publish to both npm and GHCR:
 bun publish --access public
 
 docker buildx build --platform linux/amd64,linux/arm64 \
+  --build-arg APP_VERSION=<version> \
   -t ghcr.io/cyanheads/congressgov-mcp-server:<version> \
   -t ghcr.io/cyanheads/congressgov-mcp-server:latest \
   --push .

package/Dockerfile

@@ -9,7 +9,7 @@
 # multi-arch buildx run on an arm64 host. This stage only runs tsc and emits
 # architecture-independent JavaScript; the native deps stage cross-installs the
 # production tree, so both build-time Bun stages run on the host architecture.
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
 
 WORKDIR /usr/src/app
 
@@ -45,7 +45,7 @@ RUN bun run build
 # A clean image rather than `FROM build`: the build stage's node_modules holds
 # devDependencies.
 # ==============================================================================
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
 
 WORKDIR /usr/src/app
 
@@ -112,7 +112,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.4.3-slim AS production
+FROM oven/bun:1.4.4-slim AS production
 
 WORKDIR /usr/src/app
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.8.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/congressgov-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/congressgov-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/congressgov-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.8.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/congressgov-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/congressgov-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/congressgov-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -29,7 +29,7 @@
 
 ## Overview
 
-U.S. congressional data from the Congress.gov API v3 and the Senate's official vote feed: bills, enacted laws, members, committees, roll call votes, nominations, CRS and committee reports, and the Congressional Record. Browse legislative activity, read bill and report text, and follow the Senate confirmation pipeline from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+US congressional data from Congress.gov and the Senate's official vote feed: bills, enacted laws, members, committees, roll call votes, nominations, CRS and committee reports, and the Congressional Record. Browse legislative activity, read bill and report text, and follow nominations through Senate confirmation.
 
 ### Tools
 
@@ -71,9 +71,9 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 ### `congressgov_bill_lookup` <sub>tool</sub>
 
 - `list` browses one `congress`, narrowed by `billType` and a `fromDateTime`/`toDateTime` range on the record's update date, newest first unless `order: 'oldest'`; `get`, `actions`, `amendments`, `cosponsors`, `committees`, `subjects`, `summaries`, `text`, `titles`, `related`, and `content` need `congress` + `billType` + `billNumber`
-- Copied bill-row keys `type` and `number` are accepted as `billType` and `billNumber`; bill type codes are case-insensitive, and `relatedbills` (any case) selects `related`. Send one name per field: canonical and alias keys together are rejected.
-- `content` reads the text version at `textVersionIndex` (0-based in `text` order, 0 is the most recent) and returns one character window in `content.text` with `totalCharacters`, `truncated`, and `nextOffset`
-- `summaries` takes an optional `versionCode` (`00` introduced, `49` public law) and applies the same page budget and row window as `congressgov_bill_summaries`, steered by `characterOffset`/`characterLimit`; a cut row carries `textTotalCharacters`, `textTruncated`, and `textNextOffset`
+- `type` and `number` from a bill row are accepted as `billType` and `billNumber`; bill type codes are case-insensitive. Send one name per field, since canonical and alias keys together are rejected
+- `content` reads the text version at `textVersionIndex` (0 is the most recent) and returns one character window in `content.text` with `totalCharacters`, `truncated`, and `nextOffset`
+- `summaries` takes an optional `versionCode` (`00` introduced, `49` public law) and pages like `congressgov_bill_summaries`, using `characterOffset`/`characterLimit`
 
 ---
 
@@ -94,8 +94,7 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 ### `congressgov_committee_lookup` <sub>tool</sub>
 
 - `committeeCode` is a chamber prefix (`h`/`s`/`j`), letters, and a 2-digit suffix (e.g. `hsju00`); `get`, `bills`, `reports`, and the Senate-only `nominations` infer `chamber` from the prefix
-- A committee name in `committeeCode` resolves when exactly one committee matches, and otherwise returns the candidate rows with a notice; `list` with `filter` name-matches every committee in scope, past the 250-row page cap, and fuzzy hits carry `approximate: true`
-- Exact matches require every query token; typo matches require each token to match a name token at the similarity floor. Blank filters browse normally; unrelated tokens return no matches.
+- A committee name in `committeeCode` resolves when exactly one committee matches, and otherwise returns candidate rows with a notice; `list` with `filter` name-matches every committee in scope, and fuzzy hits carry `approximate: true`
 - `bills` is newest first by default (`order`), and its rows carry no titles, so chain `congressgov_bill_lookup` `get` per row
 
 ---
@@ -126,7 +125,7 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 ### `congressgov_crs_reports` <sub>tool</sub>
 
 - `list` browses the catalog; `get` takes a `reportNumber` such as `R40097`, `RL33612`, or `IF12345`
-- `id`, `reportId`, and `report_id` are accepted as `reportNumber`. Send only one identifier key; canonical and alias keys together, or multiple aliases, are rejected.
+- `id`, `reportId`, and `report_id` are accepted as `reportNumber`; send only one identifier key
 - `get` returns authors, topics, summary, and download formats
 
 ---
@@ -207,35 +206,57 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 Congress.gov-specific:
 
 - Type-safe client for the Congress.gov REST API v3, plus a client for the Senate's LIS XML feed that backs Senate roll votes
-- The Congress.gov API has no keyword search, so tools browse by congress, type, date range, chamber, state, and district, and address bills by `congress` + `billType` + `billNumber`, members by `bioguideId`, and committees by system code; list operations page with `limit` 1–250 (default 20) and `offset`
-- `content` on bill text, committee reports, and Record articles reads `format` `text` (default) or `xml` through a `characterOffset`/`characterLimit` window (1–100,000 characters, default 25,000), fetched only from `www.congress.gov` under a 25 MB ceiling and a 30s deadline
-- Optional API key from [api.data.gov](https://api.data.gov/signup/): documented fallbacks are `DEMO_KEY` 30 requests/hour and 50/day per IP, registered keys 5,000/hour. Valid upstream hourly quota headers override the fallback; actual quotas vary
+- The Congress.gov API has no keyword search, so tools browse by congress, type, date range, chamber, state, and district; list operations page with `limit` 1–250 (default 20) and `offset`
+- `content` on bill text, committee reports, and Record articles reads `format` `text` (default) or `xml` in a `characterOffset`/`characterLimit` window (1–100,000 characters, default 25,000), fetched only from `www.congress.gov` under a 25 MB ceiling and a 30s deadline
+- Optional API key from [api.data.gov](https://api.data.gov/signup/): `DEMO_KEY` allows 30 requests/hour and 50/day per IP, registered keys 5,000/hour
 - Opt-in local SQLite FTS5 mirror (`CONGRESS_MIRROR_ENABLED`) adds keyword search over bill titles and CRS summaries
 
 Agent-friendly output:
 
-- Every list response carries `effectiveQuery` and `totalCount`; a `notice` fires when nothing matched, and a page past the end says so in the rendered output
-- `list` rejects entity identities it would discard: bill `billNumber`, vote `voteNumber`, nomination `nominationNumber`, CRS/committee `reportNumber`, and Record `volumeNumber`. The `incompatible_identity` domain error names the detail operation to select or the field to remove; pagination and defaulted selectors remain accepted.
-- Exact character windows: `content` returns `offset`, `truncated`, and `nextOffset`, so walking a multi-megabyte bill never skips or repeats a character
-- Typed `content` failures (`document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`) alongside the shared `not_found`, `rate_limited`, `invalid_request`, `upstream_error`, and `upstream_timeout` reasons, each with a recovery hint. Document byte ceilings and exhausted document/summary offsets use domain validation (-32007); malformed arguments remain protocol invalid parameters (-32602)
+- Every list response carries `effectiveQuery` and `totalCount`, with a `notice` when nothing matched
+- `list` rejects detail-only identifiers (`billNumber`, `voteNumber`, `nominationNumber`, `reportNumber`, `volumeNumber`) with an `incompatible_identity` error that names the operation to use instead
+- `content` returns `offset`, `truncated`, and `nextOffset`, so walking a multi-megabyte bill never skips or repeats a character
+- Typed failures (`document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`, `not_found`, `rate_limited`, `invalid_request`, `upstream_error`, `upstream_timeout`), each with a recovery hint
 
 ## Getting started
 
 ### Public Hosted Instance
 
-A public instance is available at `https://congressgov.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
+A public instance is available at `https://congressgov.caseyjhand.com/mcp` — no installation required. It serves Streamable HTTP; each client takes its own config shape.
+
+For Claude Code:
+
+```sh
+claude mcp add --transport http congressgov-mcp-server https://congressgov.caseyjhand.com/mcp
+```
+
+For Cline (`cline_mcp_settings.json`):
 
 ```json
 {
   "mcpServers": {
     "congressgov-mcp-server": {
-      "type": "streamable-http",
+      "type": "streamableHttp",
       "url": "https://congressgov.caseyjhand.com/mcp"
     }
   }
 }
 ```
 
+For Cursor (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "congressgov-mcp-server": {
+      "url": "https://congressgov.caseyjhand.com/mcp"
+    }
+  }
+}
+```
+
+Claude Desktop adds remote servers under Settings → Connectors.
+
 ### Self-Hosted / Local
 
 Add the following to your MCP client configuration file.
@@ -305,7 +326,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CONGRESS_API_KEY=your-api-key bun run
 ### Prerequisites
 
 - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
-- Optional: a free [api.data.gov key](https://api.data.gov/signup/) uses a documented fallback of 5,000 requests/hour instead of the demo fallback of 30/hour and 50/day per IP. Upstream hourly headers may advertise a different quota.
+- Optional: a free [api.data.gov key](https://api.data.gov/signup/) raises the limit to 5,000 requests/hour from the demo key's 30/hour and 50/day per IP.
 
 ### Installation
 
@@ -338,7 +359,7 @@ cp .env.example .env
 
 | Variable | Description | Default |
 |:---|:---|:---|
-| `CONGRESS_API_KEY` | API key from [api.data.gov](https://api.data.gov/signup/). Fallbacks: `DEMO_KEY` 30/hour and 50/day per IP; registered key 5,000/hour. Upstream hourly quota headers take precedence. | `DEMO_KEY` |
+| `CONGRESS_API_KEY` | API key from [api.data.gov](https://api.data.gov/signup/). | `DEMO_KEY` |
 | `CONGRESS_API_BASE_URL` | Congress.gov API base URL. | `https://api.congress.gov/v3` |
 | `CONGRESS_MIRROR_ENABLED` | Enable the local bill search mirror and the `congressgov_search_bills` tool. | `false` |
 | `CONGRESS_MIRROR_PATH` | Filesystem path to the SQLite mirror index. | `.mirror/bills.sqlite3` |

package/changelog/0.8.x/0.8.1.md

@@ -0,0 +1,28 @@
+---
+summary: "Framework errors preserve Markdown-bearing text, startup failures identify invalid configuration, and dependencies and maintenance tooling are refreshed."
+breaking: false
+security: false
+---
+
+# 0.8.1 — 2026-10-25
+
+## Changed
+
+- **Framework error rendering** escapes Markdown-bearing messages and recovery hints in `content[]`, preserving the original structured values.
+- **Framework configuration failures** identify the environment variable and schema path at startup.
+- **Maintenance tooling and references** sync with the framework, including audit attribution by the installed root version, configuration examples, and framework API guidance.
+- **Hosted client examples** give separate Claude Code, Cline, Cursor, and Claude Desktop connection instructions.
+
+## Fixed
+
+- **Large-document tests** verify each complete-document window independently, preserving exact text and continuation assertions without extending deadlines.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.15 → ^0.13.16.
+- `zod` ^4.6.5 → ^4.6.7.
+- `@biomejs/biome` ^2.5.15 → ^2.6.2.
+- `ignore` ^7.0.12 → ^7.0.13.
+- `tsc-alias` ^1.9.7 → ^1.9.8.
+- `vitest` ^5.0.3 → ^5.0.5.
+- Bun 1.4.3 → 1.4.4 (`packageManager`, Docker stages, and README badge).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Access U.S. congressional data (bills, votes, members, committees) via MCP. STDIO or Streamable HTTP.",
   "mcpName": "io.github.cyanheads/congressgov-mcp-server",
   "type": "module",
@@ -86,7 +86,7 @@
     "url": "git+https://github.com/cyanheads/congressgov-mcp-server.git"
   },
   "license": "Apache-2.0",
-  "packageManager": "bun@1.4.3",
+  "packageManager": "bun@1.4.4",
   "engines": {
     "node": ">=24.0.0",
     "bun": ">=1.4.0"
@@ -95,21 +95,21 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.13.15",
+    "@cyanheads/mcp-ts-core": "^0.13.16",
     "better-sqlite3": "^13.0.3",
     "fast-xml-parser": "^5.11.2",
     "node-cron": "^4.6.0",
     "pino-pretty": "^13.2.0",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.15",
+    "@biomejs/biome": "^2.6.2",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
     "@types/node": "^26.6.5",
     "depcheck": "^1.4.7",
-    "ignore": "^7.0.12",
-    "tsc-alias": "^1.9.7",
+    "ignore": "^7.0.13",
+    "tsc-alias": "^1.9.8",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   }
 }

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/congressgov-mcp-server",
     "source": "github"
   },
-  "version": "0.8.0",
+  "version": "0.8.1",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "npx",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "environmentVariables": [
         {
           "name": "CONGRESS_API_KEY",
@@ -44,7 +44,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "npx",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "environmentVariables": [
         {
           "name": "MCP_TRANSPORT_TYPE",