@cyanheads/congressgov-mcp-server 0.7.0 → 0.7.1

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.7.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.0.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-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.7.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.0.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-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -27,9 +27,11 @@
 
 ---
 
-## Tools
+## Overview
 
-Eleven read-only tools for querying U.S. legislative data:
+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, and presidential nominations. Browse legislative activity, read bill and report text, and track the Senate confirmation pipeline from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+
+### Tools
 
 | Tool | Description |
 |:---|:---|
@@ -45,122 +47,188 @@ Eleven read-only tools for querying U.S. legislative data:
 | `congressgov_daily_record` | Browse the daily Congressional Record — floor speeches, debates, and proceedings |
 | `congressgov_search_bills` | Keyword-search bill titles and CRS summaries via a local full-text mirror (opt-in, off by default) |
 
-### `congressgov_bill_lookup`
+### Resources
 
-Browse and retrieve U.S. legislative bill data from Congress.gov.
+| Resource | Description |
+|:---|:---|
+| `congress://current` | Current congress number, session dates, chamber info |
+| `congress://bill-types` | Reference table of valid bill type codes |
+| `congress://member/{bioguideId}` | Member profile by bioguide ID |
+| `congress://bill/{congress}/{billType}/{billNumber}` | Bill detail by congress, type, and number |
+| `congress://committee/{committeeCode}` | Committee detail by committee code |
+
+Bill, member, and committee data is also reachable through `congressgov_bill_lookup`, `congressgov_member_lookup`, and `congressgov_committee_lookup` (operation `get`) — many MCP clients are tool-only and never surface resources.
 
-- Filter by congress number, bill type, and update-date range
-- Retrieve detailed sub-resources: actions, amendments, committees, cosponsors, related bills, subjects, summaries, text versions, and titles
-- `content` reads a text version's actual document text, a bounded character window at a time — pick the version with `textVersionIndex`, the window with `characterOffset`/`characterLimit`, and follow `nextOffset` to walk a full bill
-- `list` defaults to `order='recent'` (newest update-date first); pass `order='oldest'` for ascending
-- Pagination support for browsing large result sets
+### Prompts
+
+| Prompt | Description |
+|:---|:---|
+| `congressgov_bill_analysis` | Structured framework for analyzing a bill |
+| `congressgov_legislative_research` | Research framework for a policy area across Congress |
+
+## Capability reference
+
+### `congressgov_bill_lookup` <sub>tool</sub>
+
+- Operations: `list` (browse by congress/billType/date range — no keyword search), `get` (full detail), or drill into `actions`, `amendments`, `cosponsors`, `committees`, `subjects`, `summaries`, `text`, `titles`, `related`
+- `list` defaults to `order='recent'` (newest update-date first); `limit` 1–250, `offset` pagination
+- `content` reads a text version's actual document text: select the version with `textVersionIndex` (0-based, against `text`'s order), the window with `characterOffset`/`characterLimit` (1–100,000 chars, default 25,000), and follow `nextOffset` to walk a full bill
+- Typed failures on `content`: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`, alongside the shared `not_found` / `rate_limited` / `invalid_request` / `upstream_error` set
 
 ---
 
-### `congressgov_member_lookup`
+### `congressgov_enacted_laws` <sub>tool</sub>
 
-Discover congressional members and their legislative activity.
+- `list` filters by congress and `lawType` (`pub` public laws, `priv` private) — the enactment-status filter `congressgov_bill_lookup` doesn't offer
+- `get` returns the origin bill record; the law citation lives on the bill's `laws[]` array (e.g. `{"number":"118-2","type":"Public Law"}`)
+- `lawNumber` accepts either the bare number (`90`) or the full `{congress}-{number}` citation a `list` row carries; a citation naming a different congress than the `congress` param is rejected rather than silently resolved
+- `limit` 1–250, `offset` pagination for `list`
 
-- Browse by state, district, congress number, and chamber
-- Retrieve a member's sponsored and cosponsored legislation
-- Look up specific members by bioguide ID
+---
+
+### `congressgov_member_lookup` <sub>tool</sub>
+
+- No name search — `list` filters by `stateCode` (+ optional `district`, which requires `stateCode`), `congress`, and `currentMember`
+- `get` returns the full profile by `bioguideId` (e.g. `P000197`); `sponsored`/`cosponsored` return that member's legislative portfolio
+- `limit` 1–250, `offset` pagination
 
 ---
 
-### `congressgov_committee_lookup`
+### `congressgov_committee_lookup` <sub>tool</sub>
+
+- Committee codes are chamber-prefix (`h`/`s`/`j`) + abbreviation + 2-digit number (e.g. `hsju00`); `get` and sub-resources infer chamber from the prefix, or accept an explicit override
+- `committeeCode` also accepts a committee name, resolved automatically (all-token match, then a bigram-similarity fallback labeled `approximate: true`) against the full cross-chamber roster
+- `list` with `filter` name-matches the same way, paging past the 250-row upstream cap to search the complete roster before filtering
+- `bills` sub-resource defaults to `order='recent'` (newest update-date first, computed client-side since upstream ignores sort); rows carry no titles — chain `congressgov_bill_lookup get` per row
+- `nominations` sub-resource is Senate-only
+
+---
 
-Browse congressional committees and their legislation, reports, and nominations.
+### `congressgov_roll_votes` <sub>tool</sub>
 
-- Filter by chamber (House, Senate, Joint)
-- Retrieve committee bills, reports, and nominations
-- Detail and sub-resource lookups need only `committeeCode` — `chamber` is auto-detected from the code
-- Committee bills default to `order='recent'` (newest-first); pass `order='oldest'` for ascending update-date order
+- `chamber` is `house` (default, Congress.gov API) or `senate` (the Senate's official LIS XML feed — the API exposes no Senate votes)
+- `list` browses by congress + session (1 or 2), newest-first by default (computed client-side for strict ordering); `get` returns tallies and party breakdown, `members` returns each member's recorded position
+- Roll call numbers reset each session and are specific to one chamber
+- `limit` 1–250, `offset` pagination for `list` and `members`
 
 ---
 
-### `congressgov_roll_votes`
+### `congressgov_senate_nominations` <sub>tool</sub>
+
+- Nominations use `PN` numbering; `list` browses by congress, `get` returns detail, `actions`/`committees`/`hearings` cover the confirmation pipeline, `nominees` returns individuals in a batch (requires `ordinal`)
+- Multi-part parents (e.g. `PN851`) carry no activity of their own — sub-resources live on partitioned children (`851-1`, `851-2`, …); a bare-parent sub-resource call on such a nomination returns an enrichment notice pointing at the partitioned form
+- `ordinal` is discovered from the nomination's `nominees` array via `get` first
+
+---
 
-Retrieve House and Senate roll call votes and individual member voting positions.
+### `congressgov_bill_summaries` <sub>tool</sub>
 
-- Set `chamber` to `house` (default, from the Congress.gov API) or `senate` (from the Senate's official LIS feed — the API exposes no Senate votes)
-- `list` browses votes by congress and session, newest first; pass `order='oldest'` for ascending
-- `get` returns the question, result, tallies, party breakdown, and associated bill/nomination/amendment
-- `members` returns each member's recorded position
+- Filters by `congress` and `billType` (requires `congress`); date filters apply to the CRS summary's update time, not the bill's action date
+- Defaults to summaries updated in the last 7 days when neither date bound is supplied
+- For summaries of one specific bill, use `congressgov_bill_lookup` with `operation='summaries'` instead
 
 ---
 
-### `congressgov_bill_summaries`
+### `congressgov_crs_reports` <sub>tool</sub>
+
+- Report IDs use letter-number codes (e.g. `R40097`, `RL33612`, `IF12345`)
+- `list` browses the catalog; `get` returns full detail (authors, topics, summary, download formats) by `reportNumber`
+- `limit` 1–250, `offset` pagination for `list`
 
-Browse recent CRS bill summaries.
+---
 
-- Filter by congress and bill type
-- Browse chronologically to see what's moving through Congress
+### `congressgov_committee_reports` <sub>tool</sub>
+
+- Report types: `hrpt` (House), `srpt` (Senate), `erpt` (Executive); `list` browses by congress + optional `reportType`, `get` returns citation/title/committees/associated bill
+- `text` lists each format's `{type, url}` link (report formats arrive one per entry, unlike bill text versions); `content` then reads the actual text, a bounded character window at a time via `characterOffset`/`characterLimit` (1–100,000 chars, default 25,000)
+- Typed failures on `content`: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`
 
 ---
 
-### `congressgov_crs_reports`
+### `congressgov_daily_record` <sub>tool</sub>
+
+- Hierarchical navigation: `list` (volumes) → `issues` (within a volume) → `articles` (within an issue)
+- `content` reads one article's text, selected by `articleIndex` (0-based) and bounded by `characterOffset`/`characterLimit`; the Congressional Record publishes Formatted Text and PDF only (no XML)
+- Typed failures on `content`: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`
 
-Browse and retrieve CRS reports — nonpartisan policy analyses written by subject-matter experts at the Library of Congress.
+---
 
-- Browse the full report catalog
-- Retrieve individual reports by product number
+### `congressgov_search_bills` <sub>tool</sub>
+
+- **Opt-in:** off by default and absent from `tools/list` entirely until `CONGRESS_MIRROR_ENABLED=true`
+- Keyword-searches a local SQLite FTS5 mirror of bill titles + CRS summaries — the discovery path the Congress.gov API itself lacks; policy area and full bill text are not indexed
+- Narrows with `congress`, `billType`, and `originChamber`; returns BM25-ranked matches with each bill's derived id, ready for a follow-up `congressgov_bill_lookup` call
+- With the flag set but the index not yet built (`bun run mirror:init`), the tool answers with an empty result and a build-the-index notice instead of an error
+- `limit` 1–100 (a narrower cap than the other tools' 1–250), `offset` pagination
 
 ---
 
-### `congressgov_daily_record`
+### `congress://current` <sub>resource</sub>
 
-Browse the daily Congressional Record — floor speeches, debates, and legislative text published each day Congress is in session.
+- Current congress number, session dates, and chamber info — baseline context for other queries
+- Cached publicly for 1 hour
 
-- Browse volumes by congress number
-- Retrieve specific issue articles
-- `content` reads one article's actual text, selected by `articleIndex` and bounded by `characterOffset`/`characterLimit`
+---
+
+### `congress://bill-types` <sub>resource</sub>
+
+- Static reference table of the 8 valid bill type codes (`hr`, `s`, `hjres`, `sjres`, `hconres`, `sconres`, `hres`, `sres`) with chamber and an example citation
+- Cached publicly for 24 hours — fixed by chamber rules, not fetched upstream
 
 ---
 
-### `congressgov_search_bills`
+### `congress://member/{bioguideId}` <sub>resource</sub>
 
-Keyword-search bill titles and CRS summaries against a local full-text mirror — the discovery path the Congress.gov API itself lacks.
+- `bioguideId` must match one uppercase letter followed by 6 digits (e.g. `P000197`)
+- Returns the member profile — name, state, party, terms, leadership, office, legislation counts
 
-- **Opt-in:** off by default, and not offered to clients until `CONGRESS_MIRROR_ENABLED=true`. With the flag set but the index not yet built (`bun run mirror:init`), the tool is callable and answers with an empty result and a build-the-index notice
-- Narrow with `congress`, `billType`, and `originChamber` filters
-- Returns BM25-ranked matches with each bill's derived id, ready for a follow-up `congressgov_bill_lookup` call
+---
 
-## Resources
+### `congress://bill/{congress}/{billType}/{billNumber}` <sub>resource</sub>
 
-| URI Pattern | Description |
-|:---|:---|
-| `congress://current` | Current congress number, session dates, chamber info |
-| `congress://bill-types` | Reference table of valid bill type codes |
-| `congress://member/{bioguideId}` | Member profile by bioguide ID |
-| `congress://bill/{congress}/{billType}/{billNumber}` | Bill detail by congress, type, and number |
-| `congress://committee/{committeeCode}` | Committee detail by committee code |
+- `congress` and `billNumber` must be positive integers; `billType` must be a valid bill type code
+- Returns bill detail — sponsor, status, policy area, committees, latest action
 
-## Prompts
+---
 
-| Prompt | Description |
-|:---|:---|
-| `congressgov_bill_analysis` | Structured framework for analyzing a bill |
-| `congressgov_legislative_research` | Research framework for a policy area across Congress |
+### `congress://committee/{committeeCode}` <sub>resource</sub>
 
-## Features
+- `committeeCode` must match `h`/`s`/`j` followed by 3–8 lowercase alphanumeric characters (e.g. `hsju00`); chamber is inferred from the first letter
+- Returns committee detail — name, chamber, subcommittees, history, legislation counts
+
+---
+
+### `congressgov_bill_analysis` <sub>prompt</sub>
+
+- Arguments: `congress`, `billType`, `billNumber` — all required strings
+- Returns one user message framing a structured analysis (summary, sponsors, committee referrals, action timeline, related legislation, policy implications, outlook) and naming which tools to call for each section
+
+---
 
-Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+### `congressgov_legislative_research` <sub>prompt</sub>
 
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling across all tools
-- Pluggable auth (`none`, `jwt`, `oauth`)
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`
-- Structured logging with optional OpenTelemetry tracing
-- Runs locally (stdio/HTTP) or in Docker from the same codebase
+- Arguments: `topic` required; `congress` optional (defaults to the current congress)
+- The discovery plan is configuration-aware: with `CONGRESS_MIRROR_ENABLED` it opens with `congressgov_search_bills`; without it, it asks for a seed (a bill, member, committee, or CRS report id) since no registered tool accepts a topic string
+- Synthesizes findings into landscape, key players, substance, recent activity, and outlook
+
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 Congress.gov-specific:
 
-- Type-safe client for the Congress.gov REST API v3
+- Type-safe client for the Congress.gov REST API v3, plus a second client for the Senate's official LIS XML feed (`fast-xml-parser`) backing Senate roll votes
 - Optional API key from [api.data.gov](https://api.data.gov/signup/) — defaults to `DEMO_KEY` (30 req/hr); own key gets 5,000 req/hr
-- Automatic pagination and response normalization
-- Rate limiting awareness
+- Bounded document-text retrieval for bill text, committee reports, and Congressional Record articles — a 25 MB fetch ceiling, 30s deadline, and a `www.congress.gov` host allowlist
+- Opt-in local SQLite FTS5 mirror (`CONGRESS_MIRROR_ENABLED`) adds keyword search over bill titles and CRS summaries, the one discovery path the API itself lacks
 - All tools are read-only and idempotent
 
+Agent-friendly output:
+
+- Effective-query echo and total-count enrichment on every browse/list operation, plus a notice when a query resolves to zero matches or an offset runs past the end
+- Character-exact document windows — `content` operations return `offset`/`nextOffset` so walking a multi-megabyte bill or report never skips or repeats a character
+- Typed failure reasons on document reads (`document_unavailable`, `format_unavailable`, `document_too_large`, `offset_past_end`, …) alongside the shared upstream-error set, each resolved to a recovery hint
+
 ## Getting started
 
 ### Public Hosted Instance
@@ -190,6 +258,8 @@ Add the following to your MCP client configuration file.
       "command": "bunx",
       "args": ["@cyanheads/congressgov-mcp-server@latest"],
       "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info",
         "CONGRESS_API_KEY": "your-api-key"
       }
     }
@@ -207,6 +277,8 @@ Or with npx (no Bun required):
       "command": "npx",
       "args": ["-y", "@cyanheads/congressgov-mcp-server@latest"],
       "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info",
         "CONGRESS_API_KEY": "your-api-key"
       }
     }
@@ -214,11 +286,37 @@ Or with npx (no Bun required):
 }
 ```
 
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "congressgov-mcp-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "-e", "CONGRESS_API_KEY=your-api-key",
+        "ghcr.io/cyanheads/congressgov-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
 Get a free API key at [api.data.gov/signup](https://api.data.gov/signup/) for 5,000 req/hr. Without a key the server falls back to `DEMO_KEY` (30 req/hr).
 
+For Streamable HTTP, set the transport and start the server:
+
+```sh
+MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CONGRESS_API_KEY=your-api-key bun run start:http
+# Server listens at http://localhost:3010/mcp
+```
+
 ### Prerequisites
 
-- [Bun v1.3.2](https://bun.sh/) or higher.
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
 
 ### Installation
 
@@ -240,22 +338,33 @@ cd congressgov-mcp-server
 bun install
 ```
 
-## Configuration
+4. **Configure environment:**
 
-All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:
+```sh
+cp .env.example .env
+# edit .env and set required vars
+```
+
+## Configuration
 
 | Variable | Description | Default |
 |:---|:---|:---|
-| `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: 5,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` |
-| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
-| `MCP_SESSION_MODE` | HTTP session mode: `auto`, `stateful`, or `stateless`. This server holds no per-session state; the Docker image runs `stateless`. | `auto` (resolves to `stateful`) |
-| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
+| `CONGRESS_API_KEY` | API key from [api.data.gov](https://api.data.gov/signup/). Omit to use `DEMO_KEY` (30 req/hr); own key: 5,000 req/hr. | `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` |
+| `CONGRESS_MIRROR_REFRESH_CRON` | Cron schedule for the in-process mirror refresh (HTTP transport only). Unset runs `mirror:refresh` manually. | — |
+| `CONGRESS_MIRROR_CONGRESSES` | Comma-separated congress numbers to mirror (e.g. `118,119`). | current congress + 1 prior |
+| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
+| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
+| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
+| `MCP_SESSION_MODE` | HTTP session mode: `auto`, `stateful`, or `stateless`; `auto` resolves to `stateful`. | `stateless` |
+| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `notice`, `warning`, `error`, etc.). | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
-| `STORAGE_PROVIDER_TYPE` | Storage backend | `in-memory` |
-| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs) | `false` |
+| `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
+| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |
+
+See [`.env.example`](./.env.example) for the full list of optional overrides.
 
 ## Running the server
 
@@ -269,27 +378,36 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
   ```
 
 - **Run checks and tests:**
+
   ```sh
-  bun run devcheck     # Lints, formats, type-checks
-  bun run test         # Runs test suite
+  bun run devcheck   # Lint, format, typecheck, security
+  bun run test       # Vitest test suite
+  bun run lint:mcp   # Validate MCP definitions against spec
   ```
 
 ### Docker
 
 ```sh
 docker build -t congressgov-mcp-server .
-docker run -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server
+docker run --rm -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server
 ```
 
+The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/congressgov-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
+
 ## Project structure
 
 | Directory | Purpose |
 |:---|:---|
-| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). Eleven Congress.gov tools. |
-| `src/mcp-server/resources/definitions/` | Resource definitions. Congress, bill, member, and committee resources. |
-| `src/mcp-server/prompts/definitions/` | Prompt definitions. Bill analysis and legislative research prompts. |
-| `src/services/congress-api/` | Congress.gov API client — auth, pagination, rate limiting. |
+| `src/index.ts` | `createApp()` entry point — registers tools/resources/prompts and inits services. |
 | `src/config/` | Server-specific environment variable parsing and validation with Zod. |
+| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`) — eleven Congress.gov tools. |
+| `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`) — congress, bill, member, and committee resources. |
+| `src/mcp-server/prompts/definitions/` | Prompt definitions (`*.prompt.ts`) — bill analysis and legislative research. |
+| `src/services/congress-api/` | Congress.gov API client — auth, pagination, rate limiting. |
+| `src/services/congress-documents/` | Bounded document-text fetch — host allowlist, byte ceiling, character window. |
+| `src/services/congress-mirror/` | Local SQLite FTS5 bill-search mirror — ingest, normalize, schema. |
+| `src/services/senate-lis/` | Senate LIS XML client for Senate roll call votes. |
+| `scripts/` | Mirror lifecycle CLI scripts (`mirror:init` / `mirror:refresh` / `mirror:verify`). |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 
 ## Development guide
@@ -297,12 +415,13 @@ docker run -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server
 See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
-- Use `ctx.log` for logging, `ctx.state` for storage
-- All tools are read-only with `readOnlyHint: true` and `idempotentHint: true`
+- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
+- All tools are read-only, with `readOnlyHint: true` and `idempotentHint: true` annotations
+- Wrap external API calls: validate raw → normalize to a domain type → return the output schema; never fabricate missing fields
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck
@@ -311,4 +430,4 @@ bun run test
 
 ## License
 
-This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
+Apache-2.0 — see [LICENSE](./LICENSE) for details.

package/changelog/0.1.x/0.1.0.md

@@ -0,0 +1,36 @@
+---
+summary: Initial release — MCP server wrapping Congress.gov API v3 with 10 tools, 5 resources, and 2 prompts for U.S. legislative data
+breaking: false
+---
+
+# 0.1.0 — 2026-03-24
+
+Initial release. MCP server wrapping the Congress.gov API v3 — the official machine-readable interface to U.S. legislative data maintained by the Library of Congress.
+
+### Added
+
+- **10 read-only tools** for querying legislative data:
+  - `congressgov_bill_lookup` — browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills)
+  - `congressgov_enacted_laws` — browse enacted public and private laws by congress
+  - `congressgov_member_lookup` — discover members by state/district/congress, retrieve legislative portfolios
+  - `congressgov_committee_lookup` — browse committees and retrieve legislation, reports, nominations
+  - `congressgov_roll_votes` — retrieve House 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
+  - `congressgov_crs_reports` — browse and retrieve nonpartisan CRS policy analysis reports
+  - `congressgov_committee_reports` — browse and retrieve committee reports accompanying legislation
+  - `congressgov_daily_record` — browse daily Congressional Record (floor speeches, debates, proceedings)
+- **5 resources** for direct data access:
+  - `congress://current` — current congress number, session dates, chamber info
+  - `congress://bill-types` — reference table of valid bill type codes
+  - `congress://member/{bioguideId}` — member profile
+  - `congress://bill/{congress}/{billType}/{billNumber}` — bill detail
+  - `congress://committee/{committeeCode}` — committee detail
+- **2 prompt templates** for structured analysis:
+  - `congressgov_bill_analysis` — framework for analyzing a bill
+  - `congressgov_legislative_research` — research framework for a policy area across Congress
+- **Congress API service** with authentication, pagination, rate limiting, and response normalization
+- **Server configuration** via `CONGRESS_API_KEY` env var (free key from api.data.gov)
+- Dual transport support: stdio and streamable HTTP
+- Docker support
+- Built on `@cyanheads/mcp-ts-core` framework

package/changelog/0.2.x/0.2.0.md

@@ -0,0 +1,26 @@
+---
+summary: API response key corrections across four endpoints, getVoteMembers + getNominee service methods, dedicated members/nominees tool operations
+breaking: false
+---
+
+# 0.2.0 — 2026-03-24
+
+### Fixed
+
+- Corrected API response keys for laws (`laws` → `bills`), House votes (`houseVotes` → `houseRollCallVotes`), committee reports (`committeeReports` → `reports`), and CRS reports endpoint path (`/crs-report` → `/crsreport`)
+- Handled array-wrapped responses from committee report detail endpoint
+- Added nested array unwrapping in `fetchList` for endpoints that nest arrays inside objects (e.g. committee-bills)
+- Fixed committee bills sub-resource list key (`bills` → `committee-bills`)
+- Stripped milliseconds from default ISO date in bill summaries for API compatibility
+
+### Added
+
+- `getVoteMembers()` service method — dedicated endpoint for individual member voting positions
+- `getNominee()` service method — individual nominee lookup by ordinal within a nomination
+- Separate 'members' operation path in `congressgov_roll_votes` using the new vote members endpoint
+- Separate 'nominees' operation in `congressgov_senate_nominations` with ordinal requirement and actionable error message
+
+### Changed
+
+- Added missing `idempotentHint: true` annotation to all tool definitions
+- Updated dev dependencies: `@biomejs/biome` 2.4.7→2.4.8, `tsx` 4.19.0→4.21.0, `vitest` 4.1.0→4.1.1

package/changelog/0.2.x/0.2.1.md

@@ -0,0 +1,16 @@
+---
+summary: Full test suite (10 tool + 5 resource + 2 prompt tests + service), tree.md refresh
+breaking: false
+---
+
+# 0.2.1 — 2026-03-24
+
+### Added
+
+- Full test suite: 10 tool tests, 5 resource tests, 2 prompt tests, and congress-api-service tests using `createMockContext` and Vitest
+- Updated `docs/tree.md` to reflect new `tests/` directory structure
+
+### Fixed
+
+- Operator precedence parentheses in `congress-api-service.ts` for nullish coalescing expressions
+- Formatting in `senate-nominations.tool.ts`

package/changelog/0.3.x/0.3.0.md

@@ -0,0 +1,26 @@
+---
+summary: Scoped package rename to @cyanheads/congressgov-mcp-server, TS 5.9 → 6.0, pagination improvements, format-helpers.ts, README overhaul
+breaking: false
+---
+
+# 0.3.0 — 2026-03-24
+
+### Changed
+
+- Renamed package to `@cyanheads/congressgov-mcp-server` (scoped under `@cyanheads`)
+- Bumped TypeScript from `^5.9.3` to `^6.0.2`
+- `getDailyIssues` now uses `fetchList` with full pagination support
+- `getMemberLegislation` simplified to return `fetchList` result directly
+- Removed redundant duplicate key from `fetchList` return shape
+- README overhaul: scoped package name, npm badge, npx/Docker/HTTP config examples, cleaner table formatting
+
+### Added
+
+- `format-helpers.ts` — shared `formatResult` formatter for all tool output (readable text with HTML stripping, list summarization, pagination headers)
+- All 10 tools now use `format: formatResult` for structured text output
+- `notFound` error for missing committee reports instead of returning empty objects
+- Detection of Congress.gov API 500-as-404 responses (structured JSON error bodies vs. real outages)
+
+### Fixed
+
+- Daily record `issues` operation now passes `limit` and `offset` params through to the API

package/changelog/0.3.x/0.3.1.md

@@ -0,0 +1,14 @@
+---
+summary: 5xx retry with exponential backoff (3 attempts, 1s/2s/4s), npm badge URL fix
+breaking: false
+---
+
+# 0.3.1 — 2026-03-24
+
+### Changed
+
+- Added retry with exponential backoff for 5xx API errors (3 attempts with 1s/2s/4s delays)
+
+### Fixed
+
+- npm badge URL now points to scoped package `@cyanheads/congressgov-mcp-server`

package/changelog/0.3.x/0.3.10.md

@@ -0,0 +1,15 @@
+---
+summary: New `order` input on committee_lookup bills sub-resource, core 0.3.5 → 0.3.7 bump, tool description cleanup
+breaking: false
+---
+
+# 0.3.10 — 2026-04-19
+
+### Added
+
+- Added an `order` input to `congressgov_committee_lookup` for the `bills` sub-resource (`'recent'` default, `'oldest'` alternative). `'recent'` surfaces newest-activity bills directly — the tool handles the count probe + tail fetch internally so callers no longer need the `offset = count - limit` workaround
+
+### Changed
+
+- Bumped `@cyanheads/mcp-ts-core` from `^0.3.5` to `^0.3.7`
+- Cleaned tool descriptions — removed cross-references to sibling tools and resource URIs, and dropped internal API/implementation notes from `congressgov_bill_lookup`, `congressgov_bill_summaries`, `congressgov_committee_lookup`, `congressgov_enacted_laws`, and `congressgov_member_lookup`

package/changelog/0.3.x/0.3.11.md

@@ -0,0 +1,18 @@
+---
+summary: Security — API key moved from query string to X-Api-Key header (rotate keys); roll-votes members operation now paginates client-side; ordinal description clarified
+breaking: false
+---
+
+# 0.3.11 — 2026-04-19
+
+### Security
+
+- Switched Congress.gov API auth from the `?api_key=` query parameter to the `X-Api-Key` header, so the key is no longer embedded in request URLs. Previously, upstream fetch failures (e.g., HTTP 500 on an unknown CRS report ID) surfaced the full URL — including the key — in the error message returned to clients. Rotate any key that was in use before this release
+
+### Fixed
+
+- Fixed `congressgov_roll_votes` `members` operation silently ignoring `limit` and `offset` — the `/house-vote/.../members` endpoint returns the full ~435-member list and does not honor upstream pagination, so the service now paginates the `results` array client-side and returns a `pagination: { count, nextOffset }` alongside the vote record
+
+### Changed
+
+- Clarified the `ordinal` parameter description on `congressgov_senate_nominations` — the value addresses a batch of nominees, not a single individual; the `nominees` operation returns every person in that batch

package/changelog/0.3.x/0.3.12.md

@@ -0,0 +1,15 @@
+---
+summary: Core 0.3.7 → 0.5.2 bump, four tools relaxed to passthrough output schemas for format-parity compliance, test fixup
+breaking: false
+---
+
+# 0.3.12 — 2026-04-20
+
+### Changed
+
+- Bumped `@cyanheads/mcp-ts-core` from `^0.3.7` to `^0.5.2`
+- Simplified the output schemas on `congressgov_bill_lookup`, `congressgov_bill_summaries`, `congressgov_crs_reports`, and `congressgov_member_lookup` to `z.object({}).passthrough()`, aligning them with the other six tools in this server. The upstream Congress.gov API returns highly variable shapes across endpoint families, so the previously typed fields were aspirational documentation rather than a real contract — handler return values, rendered `content[]` markdown, and `structuredContent` payloads are unchanged. Only the advertised JSON Schema on `tools/list` is now looser for these four tools. This was also required to satisfy the new `format-parity` lint rule introduced in `@cyanheads/mcp-ts-core` 0.5.x; see [cyanheads/mcp-ts-core#37](https://github.com/cyanheads/mcp-ts-core/issues/37) for context on the tradeoff
+
+### Fixed
+
+- Corrected a stale assertion in `tests/services/congress-api/congress-api-service.test.ts` that still expected the API key to appear in the URL `?api_key=` query parameter; the service has sent it via the `X-Api-Key` header since 0.3.11 (see that release's Security note). The production auth path was already correct — only the test was out of date