@cyanheads/congressgov-mcp-server 0.3.20 → 0.3.22

package/AGENTS.md

@@ -1,8 +1,11 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.3.20
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Version:** 0.3.22
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.13`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
+**Zod:** ^4.4.3
 
 > **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.
 
@@ -37,7 +40,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 | Env Var | Required | Description |
 |:--------|:---------|:------------|
-| `CONGRESS_API_KEY` | Yes | API key from [api.data.gov](https://api.data.gov/signup/) (free, 5,000 req/hr) |
+| `CONGRESS_API_KEY` | No | Optional. Defaults to `DEMO_KEY` (30 req/hr). Own key from [api.data.gov](https://api.data.gov/signup/): 1,000 req/hr. |
 | `CONGRESS_API_BASE_URL` | No | Defaults to `https://api.congress.gov/v3` |
 
 ---
@@ -51,6 +54,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Secrets in env vars only** — never hardcoded.
 - **All tools are read-only.** Every tool gets `annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }`.
 - **API key stays out of logs.** The service appends `api_key` as a query param — never log full URLs.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
 ---
 
@@ -181,7 +185,7 @@ All tools share these patterns. The service layer handles them uniformly:
 ```ts
 // Framework — z is re-exported, no separate zod import needed
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { notFound, serviceUnavailable, rateLimited } from '@cyanheads/mcp-ts-core/errors';
+import { McpError, JsonRpcErrorCode, notFound, serviceUnavailable, rateLimited, validationError } from '@cyanheads/mcp-ts-core/errors';
 
 // Server's own code — via path alias
 import { getCongressApi } from '@/services/congress-api/congress-api-service.js';
@@ -209,11 +213,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
-| `release-and-publish` | Post-wrapup ship workflow: verification gate, push, publish to npm/MCP Registry/GHCR |
 | `report-issue-framework` | File bugs/features against `@cyanheads/mcp-ts-core` |
 | `report-issue-local` | File bugs/features against this server's repo |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -227,7 +234,6 @@ Available skills:
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
 | `api-workers` | Cloudflare Workers runtime |
-| `tool-defs-analysis` | Audit MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -240,10 +246,14 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run build` | Compile TypeScript |
 | `bun run rebuild` | Clean + build |
 | `bun run clean` | Remove build artifacts |
-| `bun run devcheck` | Lint + format + typecheck + security |
+| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
 | `bun run tree` | Generate directory structure doc |
+| `bun run list-skills` | List available skills from `.claude/skills/` or `skills/` |
 | `bun run format` | Auto-fix formatting |
 | `bun run lint:mcp` | Validate MCP tool/resource/prompt definitions |
+| `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` |
+| `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run test` | Run tests |
@@ -254,6 +264,14 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ---
 
+## Bundling
+
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. 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.
+
+---
+
 ## Changelog
 
 Directory-based, grouped by minor series using the `.x` semver-wildcard convention. Source of truth is `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.3.x/0.3.13.md`) — one file per released version. At release time, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited, never renamed, never moved. `CHANGELOG.md` is a **navigation index** (header + link + one-line summary per version), regenerated by `bun run changelog:build`. Devcheck hard-fails on drift. Never hand-edit `CHANGELOG.md`.
@@ -273,6 +291,8 @@ security: false                          # optional — true flags security fixe
 
 `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
 ---
 
 ## Publishing
@@ -295,14 +315,17 @@ Remind the user to run these after completing a release flow.
 ## Checklist
 
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
-- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
+- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage
 - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
 - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
-- [ ] Raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
-- [ ] Normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream Congress.gov data
-- [ ] Tests include at least one sparse payload case with omitted upstream fields
+- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
+- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream Congress.gov data
+- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
 - [ ] `bun run devcheck` passes

package/CLAUDE.md

@@ -1,8 +1,11 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.3.20
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Version:** 0.3.22
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.13`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
+**Zod:** ^4.4.3
 
 > **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.
 
@@ -37,7 +40,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 | Env Var | Required | Description |
 |:--------|:---------|:------------|
-| `CONGRESS_API_KEY` | Yes | API key from [api.data.gov](https://api.data.gov/signup/) (free, 5,000 req/hr) |
+| `CONGRESS_API_KEY` | No | Optional. Defaults to `DEMO_KEY` (30 req/hr). Own key from [api.data.gov](https://api.data.gov/signup/): 1,000 req/hr. |
 | `CONGRESS_API_BASE_URL` | No | Defaults to `https://api.congress.gov/v3` |
 
 ---
@@ -51,6 +54,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Secrets in env vars only** — never hardcoded.
 - **All tools are read-only.** Every tool gets `annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }`.
 - **API key stays out of logs.** The service appends `api_key` as a query param — never log full URLs.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
 ---
 
@@ -181,7 +185,7 @@ All tools share these patterns. The service layer handles them uniformly:
 ```ts
 // Framework — z is re-exported, no separate zod import needed
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { notFound, serviceUnavailable, rateLimited } from '@cyanheads/mcp-ts-core/errors';
+import { McpError, JsonRpcErrorCode, notFound, serviceUnavailable, rateLimited, validationError } from '@cyanheads/mcp-ts-core/errors';
 
 // Server's own code — via path alias
 import { getCongressApi } from '@/services/congress-api/congress-api-service.js';
@@ -209,11 +213,14 @@ Available skills:
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
-| `release-and-publish` | Post-wrapup ship workflow: verification gate, push, publish to npm/MCP Registry/GHCR |
 | `report-issue-framework` | File bugs/features against `@cyanheads/mcp-ts-core` |
 | `report-issue-local` | File bugs/features against this server's repo |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -227,7 +234,6 @@ Available skills:
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
 | `api-workers` | Cloudflare Workers runtime |
-| `tool-defs-analysis` | Audit MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -240,10 +246,14 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run build` | Compile TypeScript |
 | `bun run rebuild` | Clean + build |
 | `bun run clean` | Remove build artifacts |
-| `bun run devcheck` | Lint + format + typecheck + security |
+| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
 | `bun run tree` | Generate directory structure doc |
+| `bun run list-skills` | List available skills from `.claude/skills/` or `skills/` |
 | `bun run format` | Auto-fix formatting |
 | `bun run lint:mcp` | Validate MCP tool/resource/prompt definitions |
+| `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` |
+| `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run test` | Run tests |
@@ -254,6 +264,14 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ---
 
+## Bundling
+
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. 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.
+
+---
+
 ## Changelog
 
 Directory-based, grouped by minor series using the `.x` semver-wildcard convention. Source of truth is `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.3.x/0.3.13.md`) — one file per released version. At release time, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited, never renamed, never moved. `CHANGELOG.md` is a **navigation index** (header + link + one-line summary per version), regenerated by `bun run changelog:build`. Devcheck hard-fails on drift. Never hand-edit `CHANGELOG.md`.
@@ -273,6 +291,8 @@ security: false                          # optional — true flags security fixe
 
 `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
 ---
 
 ## Publishing
@@ -295,14 +315,17 @@ Remind the user to run these after completing a release flow.
 ## Checklist
 
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
-- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
+- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage
 - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
 - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
-- [ ] Raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
-- [ ] Normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream Congress.gov data
-- [ ] Tests include at least one sparse payload case with omitted upstream fields
+- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
+- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream Congress.gov data
+- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
 - [ ] `bun run devcheck` passes

package/README.md

@@ -7,9 +7,15 @@
 
 <div align="center">
 
-[![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) [![Version](https://img.shields.io/badge/Version-0.3.20-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-0.3.22-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-^1.29.0-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-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+</div>
+
+<div align="center">
+
+[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/congressgov-mcp-server/releases/latest/download/congressgov-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=congressgov-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY29uZ3Jlc3Nnb3YtbWNwLXNlcnZlciJdLCJlbnYiOnsiQ09OR1JFU1NfQVBJX0tFWSI6InlvdXItYXBpLWtleSJ9fQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22congressgov-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/congressgov-mcp-server%22%5D%2C%22env%22%3A%7B%22CONGRESS_API_KEY%22%3A%22your-api-key%22%7D%7D)
+
+[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 </div>
 
@@ -136,9 +142,9 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
 Congress.gov-specific:
 
 - Type-safe client for the Congress.gov REST API v3
-- Authentication via free API key from [api.data.gov](https://api.data.gov/signup/)
+- Optional API key from [api.data.gov](https://api.data.gov/signup/) — defaults to `DEMO_KEY` (30 req/hr); own key gets 1,000 req/hr
 - Automatic pagination and response normalization
-- Rate limiting awareness (5,000 requests/hour per key)
+- Rate limiting awareness
 - All tools are read-only and idempotent
 
 ## Getting started
@@ -194,7 +200,7 @@ Or with npx (no Bun required):
 }
 ```
 
-Get a free API key at [api.data.gov/signup](https://api.data.gov/signup/) (5,000 requests/hour).
+Get a free API key at [api.data.gov/signup](https://api.data.gov/signup/) for 1,000 req/hr. Without a key the server falls back to `DEMO_KEY` (30 req/hr).
 
 ### Prerequisites
 
@@ -226,7 +232,7 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
 
 | Variable | Description | Default |
 |:---|:---|:---|
-| `CONGRESS_API_KEY` | **Required.** API key from [api.data.gov](https://api.data.gov/signup/) | — |
+| `CONGRESS_API_KEY` | Optional. API key from [api.data.gov](https://api.data.gov/signup/). Omit to use `DEMO_KEY` (30 req/hr); own key: 1,000 req/hr. | `DEMO_KEY` |
 | `CONGRESS_API_BASE_URL` | Congress.gov API base URL | `https://api.congress.gov/v3` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port | `3010` |

package/dist/config/server-config.d.ts

@@ -4,7 +4,7 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 declare const ServerConfigSchema: z.ZodObject<{
-    apiKey: z.ZodString;
+    apiKey: z.ZodDefault<z.ZodString>;
     baseUrl: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 export type ServerConfig = z.infer<typeof ServerConfigSchema>;

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;iBAOtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAM9C"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;iBAYtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAM9C"}

package/dist/config/server-config.js

@@ -5,7 +5,10 @@
 import { z } from '@cyanheads/mcp-ts-core';
 import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
-    apiKey: z.string().min(1).describe('Congress.gov API key from api.data.gov'),
+    apiKey: z
+        .string()
+        .default('DEMO_KEY')
+        .describe('Congress.gov API key from api.data.gov — optional (DEMO_KEY: 30 req/hr, own key: 1000 req/hr)'),
     baseUrl: z
         .string()
         .url()

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAC5E,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,6BAA6B,CAAC;SACtC,QAAQ,CAAC,2BAA2B,CAAC;CACzC,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,uBAAuB;KACjC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,+FAA+F,CAChG;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,6BAA6B,CAAC;SACtC,QAAQ,CAAC,2BAA2B,CAAC;CACzC,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,MAAM,EAAE,kBAAkB;QAC1B,OAAO,EAAE,uBAAuB;KACjC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.js

@@ -59,6 +59,7 @@ await createApp({
     landing: {
         repoRoot: REPO_ROOT,
         tagline: 'U.S. legislative data — bills, votes, members, committees — via MCP.',
+        requireAuth: false,
     },
     setup() {
         initCongressApi();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "description": "Access U.S. congressional data - bills, votes, members, committees - through MCP. STDIO & Streamable HTTP.",
   "mcpName": "io.github.cyanheads/congressgov-mcp-server",
   "type": "module",
@@ -15,9 +15,13 @@
     "rebuild": "bun scripts/clean.ts && bun scripts/build.ts",
     "clean": "bun scripts/clean.ts",
     "devcheck": "bun scripts/devcheck.ts",
+    "audit:refresh": "rm -f bun.lock && bun install && bun audit",
     "tree": "bun scripts/tree.ts",
+    "list-skills": "bun scripts/list-skills.ts",
     "format": "biome check --write --unsafe .",
     "lint:mcp": "bun scripts/lint-mcp.ts",
+    "lint:packaging": "bun scripts/lint-packaging.ts",
+    "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/congressgov-mcp-server.mcpb",
     "changelog:build": "bun scripts/build-changelog.ts",
     "changelog:check": "bun scripts/build-changelog.ts --check",
     "test": "vitest run",
@@ -37,7 +41,10 @@
     "bills",
     "legislative-data",
     "typescript",
-    "us-government"
+    "us-government",
+    "bun",
+    "stdio",
+    "streamable-http"
   ],
   "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/congressgov-mcp-server#readme)",
   "funding": [
@@ -68,11 +75,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.9.1",
-    "pino-pretty": "^13.1.3"
+    "@cyanheads/mcp-ts-core": "^0.9.13",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
+    "@biomejs/biome": "^2.4.16",
     "@types/node": "^25.9.1",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/congressgov-mcp-server",
     "source": "github"
   },
-  "version": "0.3.20",
+  "version": "0.3.22",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.3.20",
+      "version": "0.3.22",
       "packageArguments": [
         {
           "type": "positional",
@@ -33,9 +33,9 @@
       "environmentVariables": [
         {
           "name": "CONGRESS_API_KEY",
-          "description": "API key from api.data.gov for the Congress.gov API.",
+          "description": "API key from api.data.gov \u2014 optional (falls back to DEMO_KEY: 30 req/hr). Own key: 1000 req/hr. Free signup at api.data.gov.",
           "format": "string",
-          "isRequired": true
+          "isRequired": false
         },
         {
           "name": "MCP_LOG_LEVEL",
@@ -54,7 +54,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.3.20",
+      "version": "0.3.22",
       "packageArguments": [
         {
           "type": "positional",
@@ -68,9 +68,9 @@
       "environmentVariables": [
         {
           "name": "CONGRESS_API_KEY",
-          "description": "API key from api.data.gov for the Congress.gov API.",
+          "description": "API key from api.data.gov \u2014 optional (falls back to DEMO_KEY: 30 req/hr). Own key: 1000 req/hr. Free signup at api.data.gov.",
           "format": "string",
-          "isRequired": true
+          "isRequired": false
         },
         {
           "name": "MCP_HTTP_HOST",