@cyanheads/congressgov-mcp-server 0.7.0 → 0.7.2

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.2-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,192 @@ 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
+- `summaries` selects one version with `versionCode` (the code a summary row carries — `00` introduced, `49` public law) and reads each row's text through the same `characterOffset`/`characterLimit` window; a row past the window carries `textTotalCharacters`, `textTruncated`, and `textNextOffset`, and a window end never splits an HTML tag or character reference, so following `textNextOffset` reassembles the upstream text exactly
+- 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 — `offset_past_end` also covers a `summaries` call whose `characterOffset` is past the end of every returned row
 
 ---
 
-### `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
+- Senate `list` rows carry the feed's year-less `voteDate` ("19-Dec") alongside a derived `voteDateIso` (`2023-12-19`), resolved across the whole session — including the January votes of a session that sat past December 31
+- 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
+- A page stops adding rows once they reach a fixed response-character budget: at least one row always returns, `pagination.nextOffset` resumes at the first row not returned, and a notice discloses the stop
+- A summary past the per-row window arrives as an exact character window carrying `textTotalCharacters`, `textTruncated`, and `textNextOffset`; the notice names the `congressgov_bill_lookup` call that reads on from there
+- For summaries of one specific bill — and to read a windowed summary to the end — 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 +262,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 +281,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 +290,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 +342,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 +382,37 @@ 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. |
+| `src/utils/` | Shared pure helpers — single-pass HTML/XML character-reference decoding. |
+| `scripts/` | Mirror lifecycle CLI scripts (`mirror:init` / `mirror:refresh` / `mirror:verify`). |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 
 ## Development guide
@@ -297,12 +420,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 +435,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