@cyanheads/congressgov-mcp-server 0.7.2 → 0.7.3

package/AGENTS.md

@@ -1,10 +1,10 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.7.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Version:** 0.7.3
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.9`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` + `@modelcontextprotocol/client` ^2.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
 **Zod:** ^4.6.5
 
 > **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.
@@ -53,7 +53,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
 - **Use `ctx.log`** for request-scoped logging. No `console` calls.
-- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
+- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly. Values round-trip as JSON; a `Date` reads back as an ISO string.
 - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
 - **Secrets in env vars only** — never hardcoded.
 - **All tools are read-only.** Every tool gets `annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }`.
@@ -272,7 +272,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land the commit stack, version bump, and changelog on a release branch; open the release PR |
-| `release-pr-review` | Review the release PR and land fixes as ordinary commits; keep its body in sync |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward main, tag, push, and publish to npm, MCP Registry, GitHub Releases, and Docker |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File bugs/features against `@cyanheads/mcp-ts-core` |
@@ -281,9 +281,9 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
-| `api-linter` | MCP definition linter rules reference — look up `format-parity`, `schema-*`, `name-*`, `server-json-*` diagnostics |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper — Tier 3 opt-in |
-| `api-mirror` | MirrorService: persistent local SQLite mirror of bulk upstream datasets — Tier 3 opt-in |
+| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
 | `api-services` | LLM, Speech, Graph services |
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-testing` | createMockContext, test patterns |
@@ -315,8 +315,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `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 release:github` | Create GitHub Release from the current annotated tag |
-| `bun run test` | Run tests |
+| `bun run release:github` | Validate the current annotated tag and create its GitHub Release; `-- --check` validates only |
+| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
 | `bun run dev:stdio` | Dev mode (stdio) |
 | `bun run dev:http` | Dev mode (HTTP) |
 | `bun run start:stdio` | Production mode (stdio) |
@@ -392,6 +392,6 @@ Remind the user to run these after completing a release flow.
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `.codex-plugin/plugin.json` populated — `name` and `interface.displayName` = unscoped repo name; `version`, `description`, `repository`, `license` and `interface.shortDescription` from `package.json`
-- [ ] `.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
+- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable is listed in `env_vars`. Never write `"KEY": ""` into `env` — it overrides the user's exported key
+- [ ] `.claude-plugin/plugin.json` populated — unscoped `name`, `version`, `description`, `author`, `repository`, `license`, `keywords`; inline `mcpServers` entry keyed by the unscoped repo name. User-supplied variables use `userConfig` and `"KEY": "${user_config.<option>}"` env references, matching `manifest.json`
 - [ ] `bun run devcheck` passes

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.7.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
+**Version:** 0.7.3
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.9`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` + `@modelcontextprotocol/client` ^2.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.1.0
 **Zod:** ^4.6.5
 
 > **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.
@@ -53,7 +53,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
 - **Use `ctx.log`** for request-scoped logging. No `console` calls.
-- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
+- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly. Values round-trip as JSON; a `Date` reads back as an ISO string.
 - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
 - **Secrets in env vars only** — never hardcoded.
 - **All tools are read-only.** Every tool gets `annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }`.
@@ -272,7 +272,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land the commit stack, version bump, and changelog on a release branch; open the release PR |
-| `release-pr-review` | Review the release PR and land fixes as ordinary commits; keep its body in sync |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward main, tag, push, and publish to npm, MCP Registry, GitHub Releases, and Docker |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File bugs/features against `@cyanheads/mcp-ts-core` |
@@ -281,9 +281,9 @@ Available skills:
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
-| `api-linter` | MCP definition linter rules reference — look up `format-parity`, `schema-*`, `name-*`, `server-json-*` diagnostics |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper — Tier 3 opt-in |
-| `api-mirror` | MirrorService: persistent local SQLite mirror of bulk upstream datasets — Tier 3 opt-in |
+| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
 | `api-services` | LLM, Speech, Graph services |
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-testing` | createMockContext, test patterns |
@@ -315,8 +315,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `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 release:github` | Create GitHub Release from the current annotated tag |
-| `bun run test` | Run tests |
+| `bun run release:github` | Validate the current annotated tag and create its GitHub Release; `-- --check` validates only |
+| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
 | `bun run dev:stdio` | Dev mode (stdio) |
 | `bun run dev:http` | Dev mode (HTTP) |
 | `bun run start:stdio` | Production mode (stdio) |
@@ -392,6 +392,6 @@ Remind the user to run these after completing a release flow.
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `.codex-plugin/plugin.json` populated — `name` and `interface.displayName` = unscoped repo name; `version`, `description`, `repository`, `license` and `interface.shortDescription` from `package.json`
-- [ ] `.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
+- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable is listed in `env_vars`. Never write `"KEY": ""` into `env` — it overrides the user's exported key
+- [ ] `.claude-plugin/plugin.json` populated — unscoped `name`, `version`, `description`, `author`, `repository`, `license`, `keywords`; inline `mcpServers` entry keyed by the unscoped repo name. User-supplied variables use `userConfig` and `"KEY": "${user_config.<option>}"` env references, matching `manifest.json`
 - [ ] `bun run devcheck` passes

package/Dockerfile

@@ -9,7 +9,7 @@
 # multi-arch buildx run on an arm64 host. This stage only runs tsc and emits
 # architecture-independent JavaScript, and the production stage installs its own
 # dependencies natively, so building it on the host architecture is safe.
-FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
 
 WORKDIR /usr/src/app
 
@@ -39,7 +39,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.4.0-slim AS production
+FROM oven/bun:1.4.2-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -55,8 +55,11 @@ LABEL org.opencontainers.image.source="https://github.com/cyanheads/congressgov-
 LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
 
-# Copy dependency manifests
-COPY package.json bun.lock ./
+# Copy dependency manifests and preserve the release-age gate and scanner.
+COPY package.json bun.lock bunfig.toml ./
+
+# Seed the scanner because the production install omits this devDependency.
+COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
@@ -69,21 +72,32 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
     bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
-# These are installed by default. Omit them for a smaller image with:
-# docker build --build-arg OTEL_ENABLED=false
+# Installed by default; omit with --build-arg OTEL_ENABLED=false.
+# Resolve each package inside the installed framework's tested peer range.
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
-        @opentelemetry/instrumentation-http \
+      specs=$(bun -e ' \
+        const { peerDependencies: peers } = await Bun.file("node_modules/@cyanheads/mcp-ts-core/package.json").json(); \
+        const names = process.argv.slice(1); \
+        const missing = names.filter((name) => !peers?.[name]); \
+        if (missing.length > 0) throw new Error(`no peerDependencies range for ${missing.join(", ")}`); \
+        console.log(names.map((name) => `${name}@${peers[name]}`).join(" ")); \
+      ' \
+        @hono/otel \
+        @opentelemetry/api-logs \
+        @opentelemetry/exporter-logs-otlp-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \
+        @opentelemetry/instrumentation-http \
         @opentelemetry/instrumentation-pino \
         @opentelemetry/resources \
+        @opentelemetry/sdk-logs \
         @opentelemetry/sdk-metrics \
         @opentelemetry/sdk-node \
         @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions; \
+        @opentelemetry/semantic-conventions) \
+      && bun add --omit=dev --omit=peer --ignore-scripts $specs; \
     fi
 
 # Copy the compiled application code from the build stage
@@ -128,7 +142,6 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/congressgov-mcp-server"
-ENV MCP_FORCE_CONSOLE_LOGGING="true"
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}

package/README.md

@@ -7,13 +7,13 @@
 
 <div align="center">
 
-[![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/)
+[![Version](https://img.shields.io/badge/Version-0.7.3-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.1.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.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)
+[![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%2Fcongressgov-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)
 
@@ -29,23 +29,23 @@
 
 ## Overview
 
-U.S. congressional data from the Congress.gov API v3 and the Senate's official vote feed — bills, enacted laws, members, committees, roll call votes, 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.
+U.S. congressional data from the Congress.gov API v3 and the Senate's official vote feed: bills, enacted laws, members, committees, roll call votes, nominations, CRS and committee reports, and the Congressional Record. Browse legislative activity, read bill and report text, and follow the Senate confirmation pipeline from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
 ### Tools
 
 | Tool | Description |
 |:---|:---|
-| `congressgov_bill_lookup` | Browse and retrieve U.S. legislative bill data — actions, sponsors, summaries, text, related bills |
+| `congressgov_bill_lookup` | Browse and retrieve bills: actions, sponsors, summaries, text, related bills |
 | `congressgov_enacted_laws` | Browse enacted public and private laws by congress |
-| `congressgov_member_lookup` | Discover congressional members by state/district/congress, retrieve legislative portfolios |
-| `congressgov_committee_lookup` | Browse congressional committees and their legislation, reports, and nominations |
-| `congressgov_roll_votes` | Retrieve House and Senate roll call votes and individual member voting positions |
-| `congressgov_senate_nominations` | Browse presidential nominations to federal positions and track the Senate confirmation process |
-| `congressgov_bill_summaries` | Browse recent CRS bill summaries — the "what's happening" feed |
-| `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 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_member_lookup` | Find members by state, district, or congress, and retrieve their legislative portfolios |
+| `congressgov_committee_lookup` | Browse committees and their legislation, reports, and nominations |
+| `congressgov_roll_votes` | Retrieve House and Senate roll call votes and each member's position |
+| `congressgov_senate_nominations` | Browse presidential nominations and track Senate confirmation |
+| `congressgov_bill_summaries` | Browse recently updated CRS bill summaries |
+| `congressgov_crs_reports` | Browse and retrieve nonpartisan CRS policy reports |
+| `congressgov_committee_reports` | Browse and read committee reports accompanying legislation |
+| `congressgov_daily_record` | Browse and read the daily Congressional Record |
+| `congressgov_search_bills` | Keyword-search bill titles and CRS summaries via a local full-text mirror (opt-in) |
 
 ### Resources
 
@@ -57,7 +57,7 @@ U.S. congressional data from the Congress.gov API v3 and the Senate's official v
 | `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.
+Bill, member, and committee data is also reachable through `congressgov_bill_lookup`, `congressgov_member_lookup`, and `congressgov_committee_lookup` (operation `get`), since many MCP clients are tool-only and never surface resources.
 
 ### Prompts
 
@@ -70,150 +70,132 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 
 ### `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
+- `list` browses one `congress`, narrowed by `billType` and a `fromDateTime`/`toDateTime` range on the record's update date, newest first unless `order: 'oldest'`; `get`, `actions`, `amendments`, `cosponsors`, `committees`, `subjects`, `summaries`, `text`, `titles`, `related`, and `content` need `congress` + `billType` + `billNumber`
+- `content` reads the text version at `textVersionIndex` (0-based in `text` order, 0 is the most recent) and returns one character window in `content.text` with `totalCharacters`, `truncated`, and `nextOffset`
+- `summaries` takes an optional `versionCode` (`00` introduced, `49` public law) and applies the same page budget and row window as `congressgov_bill_summaries`, steered by `characterOffset`/`characterLimit`; a cut row carries `textTotalCharacters`, `textTruncated`, and `textNextOffset`
 
 ---
 
 ### `congressgov_enacted_laws` <sub>tool</sub>
 
-- `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`
+- `list` browses one `congress`, optionally by `lawType` (`pub` or `priv`), the enactment filter `congressgov_bill_lookup` lacks; `get` needs `lawType` + `lawNumber`, taken from a list row's `laws[].number` (`118-90`) or its bare number (`90`)
+- `get` returns the origin bill record, with the law citation on its `laws[]` array
 
 ---
 
 ### `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
+- No name search: `list` filters by `stateCode` (plus `district`, `0` for at-large, which requires `stateCode`), `congress`, and `currentMember`
+- `get` returns the profile for a `bioguideId` (e.g. `P000197`); `sponsored` and `cosponsored` return that member's legislation
 
 ---
 
 ### `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
+- `committeeCode` is a chamber prefix (`h`/`s`/`j`), letters, and a 2-digit suffix (e.g. `hsju00`); `get`, `bills`, `reports`, and the Senate-only `nominations` infer `chamber` from the prefix
+- A committee name in `committeeCode` resolves when exactly one committee matches, and otherwise returns the candidate rows with a notice; `list` with `filter` name-matches every committee in scope, past the 250-row page cap, and fuzzy hits carry `approximate: true`
+- `bills` is newest first by default (`order`), and its rows carry no titles, so chain `congressgov_bill_lookup` `get` per row
 
 ---
 
 ### `congressgov_roll_votes` <sub>tool</sub>
 
-- `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`
+- `chamber` is `house` (default, Congress.gov API) or `senate` (the Senate's LIS feed); every call needs `congress` + `session` (1 or 2), and `get`/`members` add `voteNumber`, which resets each session and is specific to one chamber
+- `list` is newest first unless `order: 'oldest'`; `get` returns the question, result, tallies, and party breakdown, and `members` returns each member's position
+- Senate votes start at the 101st Congress (1989), and Senate rows pair the feed's year-less `voteDate` with a derived `voteDateIso`
 
 ---
 
 ### `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
+- `list` browses one `congress`; `get`, `actions`, `committees`, `hearings`, and `nominees` need a `nominationNumber` (`1000` for PN1000), and `nominees` also needs an `ordinal` from the `nominees` array `get` returns
+- Multi-part nominations (e.g. PN851) keep their activity on partitioned children (`851-1`, `851-2`, …); an empty sub-resource call on the bare number returns a notice pointing there
 
 ---
 
 ### `congressgov_bill_summaries` <sub>tool</sub>
 
-- 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
+- Optional `congress` and `billType` (which requires `congress`); `fromDateTime`/`toDateTime` filter on the summary's update time, not the bill's action date, and cover the last 7 days when both are omitted
+- A page stops adding rows at 50,000 serialized characters (at least one row always returns, and `pagination.nextOffset` resumes); a summary over 25,000 characters arrives windowed with `textTotalCharacters`, `textTruncated`, and `textNextOffset`
+- For one bill's summaries, or to read a windowed summary to the end, use `congressgov_bill_lookup` `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`
+- `list` browses the catalog; `get` takes a `reportNumber` such as `R40097`, `RL33612`, or `IF12345`
+- `get` returns authors, topics, summary, and download formats
 
 ---
 
 ### `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`
+- `list` browses one `congress`, optionally by `reportType` (`hrpt` House, `srpt` Senate, `erpt` Executive); `get`, `text`, and `content` need `reportType` + `reportNumber`
+- `get` returns the citation, title, committees, and associated bill; `text` lists `{type, url}` format links, and `content` reads the report as one character window
 
 ---
 
 ### `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`
+- Navigation runs `list` (volumes) → `issues` (by `volumeNumber`) → `articles` (by `volumeNumber` + `issueNumber`)
+- `content` reads the article at `articleIndex` (0-based across the issue) as one character window; Record articles publish Formatted Text and PDF only, so `format: 'xml'` fails as `format_unavailable`
 
 ---
 
 ### `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
+- `query` keywords (AND-combined) over bill titles and CRS summaries, narrowed by `congress`, `billType`, and `originChamber`; `limit` 1–100, `offset` pagination
+- BM25-ranked rows carry `billId` plus `congress`/`billType`/`billNumber` for `congressgov_bill_lookup`, and a `summaryPreview`; policy area and full bill text are not indexed
+- Listed only when `CONGRESS_MIRROR_ENABLED=true`; until `bun run mirror:init` builds the index, it returns an empty result with a notice
 
 ---
 
 ### `congress://current` <sub>resource</sub>
 
-- Current congress number, session dates, and chamber info — baseline context for other queries
+- Current congress number, session dates, and chamber info, the baseline for other queries
 - Cached publicly for 1 hour
 
 ---
 
 ### `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
+- The 8 bill type codes (`hr`, `s`, `hjres`, `sjres`, `hconres`, `sconres`, `hres`, `sres`) with description, chamber, and an example citation
+- Static, with no upstream call; cached publicly for 24 hours
 
 ---
 
 ### `congress://member/{bioguideId}` <sub>resource</sub>
 
-- `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
+- `bioguideId` is one uppercase letter and 6 digits (e.g. `P000197`)
+- Returns the member profile: name, state, party, terms, leadership, office, legislation counts
 
 ---
 
 ### `congress://bill/{congress}/{billType}/{billNumber}` <sub>resource</sub>
 
-- `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
+- `congress` and `billNumber` are positive integers; `billType` is one of the 8 bill type codes
+- Returns bill detail: sponsor, status, policy area, committees, latest action
 
 ---
 
 ### `congress://committee/{committeeCode}` <sub>resource</sub>
 
-- `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
+- `committeeCode` is `h`/`s`/`j` followed by 3–8 lowercase alphanumeric characters (e.g. `hsju00`); chamber comes 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
+- Arguments: `congress`, `billType`, and `billNumber`, all required
+- Returns one user message framing a seven-part analysis, from summary to outlook, with the tools to call for each part
 
 ---
 
 ### `congressgov_legislative_research` <sub>prompt</sub>
 
-- 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
+- Arguments: `topic` required; `congress` optional, defaulting to the current congress
+- With `CONGRESS_MIRROR_ENABLED`, the plan opens with `congressgov_search_bills`; without it, the prompt asks for a seed bill, member, committee, or CRS report ID, since no other tool takes a topic
 
 ## Features
 
@@ -221,17 +203,17 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 
 Congress.gov-specific:
 
-- Type-safe client for the Congress.gov REST API v3, plus a 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
-- 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
+- Type-safe client for the Congress.gov REST API v3, plus a client for the Senate's LIS XML feed that backs Senate roll votes
+- The Congress.gov API has no keyword search, so tools browse by congress, type, date range, chamber, state, and district, and address bills by `congress` + `billType` + `billNumber`, members by `bioguideId`, and committees by system code; list operations page with `limit` 1–250 (default 20) and `offset`
+- `content` on bill text, committee reports, and Record articles reads `format` `text` (default) or `xml` through a `characterOffset`/`characterLimit` window (1–100,000 characters, default 25,000), fetched only from `www.congress.gov` under a 25 MB ceiling and a 30s deadline
+- Optional API key from [api.data.gov](https://api.data.gov/signup/): `DEMO_KEY` allows 30 req/hr, your own key 5,000 req/hr
+- Opt-in local SQLite FTS5 mirror (`CONGRESS_MIRROR_ENABLED`) adds keyword search over bill titles and CRS summaries
 
 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
+- Every list response carries `effectiveQuery` and `totalCount`; a `notice` fires when nothing matched, and a page past the end says so in the rendered output
+- Exact character windows: `content` returns `offset`, `truncated`, and `nextOffset`, so walking a multi-megabyte bill never skips or repeats a character
+- Typed `content` failures (`document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, `offset_past_end`) alongside the shared `not_found`, `rate_limited`, `invalid_request`, and `upstream_error` reasons, each with a recovery hint
 
 ## Getting started
 
@@ -309,8 +291,6 @@ Or with Docker:
 }
 ```
 
-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
@@ -321,6 +301,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CONGRESS_API_KEY=your-api-key bun run
 ### Prerequisites
 
 - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
+- Optional: a free [api.data.gov key](https://api.data.gov/signup/) raises the limit from 30 to 5,000 requests per hour.
 
 ### Installation
 
@@ -346,27 +327,30 @@ bun install
 
 ```sh
 cp .env.example .env
-# edit .env and set required vars
+# edit .env and set CONGRESS_API_KEY (and the mirror vars, if you want keyword search)
 ```
 
 ## Configuration
 
 | Variable | Description | Default |
 |:---|:---|:---|
-| `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_KEY` | API key from [api.data.gov](https://api.data.gov/signup/). `DEMO_KEY` allows 30 req/hr; your 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_REFRESH_CRON` | Cron schedule for the in-process mirror refresh (HTTP transport only). Unset means running `mirror:refresh` yourself. | — |
 | `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_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`; `auto` resolves to `stateful`. | `stateless` |
 | `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` |
+| `OTEL_ENABLED` | Enable [OpenTelemetry](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP endpoint for traces and metrics. | — |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Explicit OTLP logs endpoint; the base endpoint does not enable log export. | — |
+| `LOG_TOOL_FAILURE_PAYLOADS` | Log failed-call input and output with key-based redaction; secrets inside free-form values are not redacted. | `false` |
+| `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` | Maximum bytes per failed-call input or output record. | `16384` |
 
 See [`.env.example`](./.env.example) for the full list of optional overrides.
 
@@ -381,6 +365,14 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
   bun run start:http   # or start:stdio
   ```
 
+- **Build the bill search mirror** (with `CONGRESS_MIRROR_ENABLED=true`):
+
+  ```sh
+  bun run mirror:init      # full build
+  bun run mirror:refresh   # incremental refresh
+  bun run mirror:verify    # readiness and integrity check
+  ```
+
 - **Run checks and tests:**
 
   ```sh
@@ -396,23 +388,23 @@ docker build -t 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.
+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. The image carries the mirror scripts, so `docker exec <container> bun run mirror:init` builds the index in place.
 
 ## Project structure
 
 | Directory | Purpose |
 |:---|:---|
-| `src/index.ts` | `createApp()` entry point — registers tools/resources/prompts and inits services. |
+| `src/index.ts` | `createApp()` entry point: registers tools, resources, and prompts, inits services, and schedules the mirror refresh. |
 | `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/mcp-server/tools/` | Tool definitions (`definitions/*.tool.ts`) plus shared input, formatting, and summary-window helpers. |
+| `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`). |
+| `src/mcp-server/prompts/definitions/` | Prompt definitions (`*.prompt.ts`). |
+| `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`). |
+| `src/utils/` | HTML/XML character-reference decoding. |
+| `scripts/` | Build, devcheck, and release tooling, plus the `mirror:init` / `mirror:refresh` / `mirror:verify` CLIs. |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 
 ## Development guide

package/changelog/0.7.x/0.7.3.md

@@ -0,0 +1,36 @@
+---
+summary: "Framework upkeep brings stricter HTTP validation, integer-to-string input repair, and optional telemetry logging."
+breaking: true
+security: false
+---
+
+# 0.7.3 — 2026-09-26
+
+## Changed
+
+- **HTTP clients** inherit MCP SDK 2.1.0 through framework 0.13.9: 2026-07-28 POSTs require `MCP-Protocol-Version` (otherwise `400` / `-32020`), and batches over 100 messages receive `400` / `-32600`. Clients relying on either previously accepted form must adapt.
+- **Cancellation** inherits SDK 2.1.0 handling for `requestId: 0`; stdin EOF aborts in-flight stdio requests without answering them.
+- **Error envelopes** inherit framework 0.13.7 stack removal and 0.13.8 request-context removal; output-contract violations now return `InternalError` (`-32603`) instead of `ValidationError` (`-32007`).
+- **Telemetry** inherits framework 0.13.7 base OTLP endpoint resolution and 0.13.8 opt-in log export (`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`) and failed-call payload logging (`LOG_TOOL_FAILURE_PAYLOADS`, capped by `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`). Payload redaction matches keys, not secrets embedded in free-form values.
+- **Docker** preserves the release-age gate and Socket scanner during production installs, resolves optional telemetry packages within framework peer ranges, includes OTLP log peers, and removes the unused `MCP_FORCE_CONSOLE_LOGGING` setting.
+- **Packaging** excludes built `.mcpb` bundles from npm and excludes `docs/idea.md` and `logs/` from MCPB bundles.
+- **Development checks** reject unloadable definitions and malformed `server.json`, enforce manifest version and Docker build-platform parity, and validate release annotations before GitHub publication.
+- **Documentation** clarifies existing tool inputs, summary windows, pagination, and mirror commands; updates the VS Code install link, framework guidance, and synchronized development skills.
+
+## Fixed
+
+- **String identifiers** inherit framework 0.13.9 safe-integer repair: an integer `nominationNumber`, for example `677`, reaches the handler as `"677"` when that string passes the schema. Argument rejection hints retain field paths and identify key rewrites.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.9 (locked to 0.13.9).
+- `@socketsecurity/bun-security-scanner` ^1.1.2 → ^1.1.3 (development).
+- `ignore` ^7.0.9 → ^7.0.10 (development).
+- Bun 1.4.0 → 1.4.2 (`packageManager` and Docker base images).
+- Transitive `@modelcontextprotocol/server` and `@modelcontextprotocol/core` 2.0.0 → 2.1.0; unused framework client, ext-apps, and dotenv dependencies leave the lockfile.
+- Transitive `@babel/parser` 7.29.8 → 7.29.9.
+- Transitive `@oxc-project/types` 0.150.0 → 0.151.0.
+- Transitive `rolldown` and its platform bindings 1.2.9 → 1.2.10.
+- Transitive `@vue/compiler-core`, `@vue/compiler-dom`, `@vue/compiler-sfc`, `@vue/compiler-ssr`, and `@vue/shared` 3.5.42 → 3.5.43.
+- Transitive `is-core-module` 2.16.2 → 2.17.0.
+- Transitive `magic-string` 1.4.1 → 1.4.2.

package/dist/mcp-server/tools/tool-helpers.d.ts

@@ -226,8 +226,8 @@ export declare const documentErrorContracts: readonly [{
     readonly recovery: "Restart the walk at characterOffset 0 and follow the response's nextOffset (or a summary row's textNextOffset), which goes null once the text has been read to the end.";
 }];
 /**
- * Shared `errors[]` contract for every Congress.gov tool. All ten tools reach
- * the same `CongressApiService` fetch path, so they surface the same four
+ * Shared `errors[]` contract for every Congress.gov API tool. Every tool except
+ * the mirror-backed `congressgov_search_bills` reaches the same `CongressApiService` fetch path, so they surface the same four
  * upstream failure modes. The service raises each with a matching `data.reason`
  * and `data.recovery.hint` (see `classifyUpstreamError`), making the failures
  * machine-readable; declaring them here advertises the contract in `tools/list`.

package/dist/mcp-server/tools/tool-helpers.js

@@ -374,8 +374,8 @@ export const documentErrorContracts = [
     },
 ];
 /**
- * Shared `errors[]` contract for every Congress.gov tool. All ten tools reach
- * the same `CongressApiService` fetch path, so they surface the same four
+ * Shared `errors[]` contract for every Congress.gov API tool. Every tool except
+ * the mirror-backed `congressgov_search_bills` reaches the same `CongressApiService` fetch path, so they surface the same four
  * upstream failure modes. The service raises each with a matching `data.reason`
  * and `data.recovery.hint` (see `classifyUpstreamError`), making the failures
  * machine-readable; declaring them here advertises the contract in `tools/list`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Access U.S. congressional data - bills, votes, members, committees - through MCP. STDIO & Streamable HTTP.",
   "mcpName": "io.github.cyanheads/congressgov-mcp-server",
   "type": "module",
@@ -12,6 +12,7 @@
   "files": [
     "changelog/",
     "dist/",
+    "!dist/*.mcpb",
     "scripts/_mirror-context.ts",
     "scripts/congress-mirror-init.ts",
     "scripts/congress-mirror-refresh.ts",
@@ -85,7 +86,7 @@
     "url": "git+https://github.com/cyanheads/congressgov-mcp-server.git"
   },
   "license": "Apache-2.0",
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.2",
   "engines": {
     "node": ">=24.0.0",
     "bun": ">=1.4.0"
@@ -94,7 +95,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.13.6",
+    "@cyanheads/mcp-ts-core": "^0.13.9",
     "better-sqlite3": "^13.0.3",
     "fast-xml-parser": "^5.11.1",
     "node-cron": "^4.6.0",
@@ -103,10 +104,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",
-    "@socketsecurity/bun-security-scanner": "^1.1.2",
+    "@socketsecurity/bun-security-scanner": "^1.1.3",
     "@types/node": "^26.6.2",
     "depcheck": "^1.4.7",
-    "ignore": "^7.0.9",
+    "ignore": "^7.0.10",
     "tsc-alias": "^1.9.5",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1"

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/congressgov-mcp-server",
     "source": "github"
   },
-  "version": "0.7.2",
+  "version": "0.7.3",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.7.2",
+      "version": "0.7.3",
       "packageArguments": [
         {
           "type": "positional",
@@ -54,7 +54,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.7.2",
+      "version": "0.7.3",
       "packageArguments": [
         {
           "type": "positional",