@cyanheads/congressgov-mcp-server 0.4.3 → 0.5.0

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.4.3
+**Version:** 0.5.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.5`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
@@ -68,7 +68,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 | Name | Description |
 |:-----|:------------|
-| `congressgov_bill_lookup` | Browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills) |
+| `congressgov_bill_lookup` | Browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills) + bounded document text via `content` |
 | `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 |
@@ -76,8 +76,8 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 | `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline |
 | `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 daily Congressional Record — floor speeches, debates, proceedings |
+| `congressgov_committee_reports` | Browse and retrieve committee reports accompanying legislation + bounded report text via `content` |
+| `congressgov_daily_record` | Browse daily Congressional Record — floor speeches, debates, proceedings + bounded article text via `content` |
 | `congressgov_search_bills` | Keyword-search bill titles/summaries via the opt-in local FTS mirror — off by default |
 
 ### Resources (5)
@@ -110,6 +110,11 @@ src/
     congress-api/
       congress-api-service.ts           # API client — auth, pagination, rate limiting
       types.ts                          # API response types
+    congress-documents/
+      congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, character window
+      document-formats.ts               # Format label → URL resolution over upstream format lists
+      extract-text.ts                   # GPO `<pre>` / XML body → deterministic plain text
+      types.ts                          # Document format + content window types
     congress-mirror/
       congress-mirror-service.ts        # Mirror read path — FTS5 search, ready(), sync accessor
       ingest.ts                         # Bill list + CRS summaries sync generator
@@ -153,7 +158,7 @@ scripts/
 
 ## Services
 
-Three services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only.
+Four services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only; `CongressDocumentsService` backs the `content` operation on `congressgov_bill_lookup`, `congressgov_committee_reports`, and `congressgov_daily_record`.
 
 **`CongressApiService`** — wraps the Congress.gov REST API v3:
 - API key via `X-Api-Key` header (never logged; kept out of the URL so it can't leak in upstream error messages)
@@ -168,6 +173,13 @@ Three services. `CongressApiService` backs nine tools and the House branch of `c
 - The host returns HTTP 200 with an HTML page for unknown congress/session/vote, so "not found" is detected from the body, not the status code
 - Party totals are derived from the roster (the feed publishes none)
 
+**`CongressDocumentsService`** — reads the document bodies behind Congress.gov's format URLs (`www.congress.gov`):
+- A second host, so a sibling service rather than a method on `CongressApiService` — no API key, no JSON, documents past a megabyte
+- URLs are resolved from upstream format metadata and checked against a `www.congress.gov` allowlist; a caller never supplies one
+- The fetch is bounded: a 5 MB ceiling (refused on `Content-Length`, else mid-stream), a 30s deadline, and a content-type allowlist
+- The response is bounded by an exact character window — offsets index the extracted plain text and are never snapped to section breaks, so feeding `nextOffset` back walks a document with no overlap and no gap
+- `extract-text.ts` unwraps GPO's `<pre>` print output verbatim (whitespace is the document's structure) and decodes entities in one pass
+
 **`CongressMirrorService`** — local SQLite FTS5 mirror of bill title + CRS summary text, backing `congressgov_search_bills` only:
 - Opt-in via `CONGRESS_MIRROR_ENABLED` (off by default); built out-of-band via the `mirror:init`/`mirror:refresh` scripts, never on server startup
 - No live-API fallback — ingests through the existing `CongressApiService`, and a mirror that hasn't finished its initial build returns an empty result with a notice, not an error
@@ -198,6 +210,8 @@ All tools share these patterns. The service layer handles them uniformly:
 | Invalid params | `validationError('...', { field })` |
 | Network error | `serviceUnavailable('Unable to reach the Congress.gov API.')` |
 
+The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end`. `CongressDocumentsService` raises each with a matching `data.reason` and resolves the hint via `ctx.recoveryFor` — note that `ctx.fail` does **not** auto-populate `recovery`, so handler-side `ctx.fail` calls must spread `ctx.recoveryFor(reason)` into their data or the hint never reaches the wire.
+
 ---
 
 ## Naming

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.4.3
+**Version:** 0.5.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.5`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
@@ -68,7 +68,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 | Name | Description |
 |:-----|:------------|
-| `congressgov_bill_lookup` | Browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills) |
+| `congressgov_bill_lookup` | Browse, filter, and retrieve bill data (actions, sponsors, summaries, text, related bills) + bounded document text via `content` |
 | `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 |
@@ -76,8 +76,8 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 | `congressgov_senate_nominations` | Browse presidential nominations, track Senate confirmation pipeline |
 | `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 daily Congressional Record — floor speeches, debates, proceedings |
+| `congressgov_committee_reports` | Browse and retrieve committee reports accompanying legislation + bounded report text via `content` |
+| `congressgov_daily_record` | Browse daily Congressional Record — floor speeches, debates, proceedings + bounded article text via `content` |
 | `congressgov_search_bills` | Keyword-search bill titles/summaries via the opt-in local FTS mirror — off by default |
 
 ### Resources (5)
@@ -110,6 +110,11 @@ src/
     congress-api/
       congress-api-service.ts           # API client — auth, pagination, rate limiting
       types.ts                          # API response types
+    congress-documents/
+      congress-documents-service.ts     # www.congress.gov document fetch — host allowlist, byte ceiling, character window
+      document-formats.ts               # Format label → URL resolution over upstream format lists
+      extract-text.ts                   # GPO `<pre>` / XML body → deterministic plain text
+      types.ts                          # Document format + content window types
     congress-mirror/
       congress-mirror-service.ts        # Mirror read path — FTS5 search, ready(), sync accessor
       ingest.ts                         # Bill list + CRS summaries sync generator
@@ -153,7 +158,7 @@ scripts/
 
 ## Services
 
-Three services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only.
+Four services. `CongressApiService` backs nine tools and the House branch of `congressgov_roll_votes`; `SenateVoteService` backs only the Senate branch of `congressgov_roll_votes` (the Congress.gov API exposes no Senate vote namespace); `CongressMirrorService` backs `congressgov_search_bills` only; `CongressDocumentsService` backs the `content` operation on `congressgov_bill_lookup`, `congressgov_committee_reports`, and `congressgov_daily_record`.
 
 **`CongressApiService`** — wraps the Congress.gov REST API v3:
 - API key via `X-Api-Key` header (never logged; kept out of the URL so it can't leak in upstream error messages)
@@ -168,6 +173,13 @@ Three services. `CongressApiService` backs nine tools and the House branch of `c
 - The host returns HTTP 200 with an HTML page for unknown congress/session/vote, so "not found" is detected from the body, not the status code
 - Party totals are derived from the roster (the feed publishes none)
 
+**`CongressDocumentsService`** — reads the document bodies behind Congress.gov's format URLs (`www.congress.gov`):
+- A second host, so a sibling service rather than a method on `CongressApiService` — no API key, no JSON, documents past a megabyte
+- URLs are resolved from upstream format metadata and checked against a `www.congress.gov` allowlist; a caller never supplies one
+- The fetch is bounded: a 5 MB ceiling (refused on `Content-Length`, else mid-stream), a 30s deadline, and a content-type allowlist
+- The response is bounded by an exact character window — offsets index the extracted plain text and are never snapped to section breaks, so feeding `nextOffset` back walks a document with no overlap and no gap
+- `extract-text.ts` unwraps GPO's `<pre>` print output verbatim (whitespace is the document's structure) and decodes entities in one pass
+
 **`CongressMirrorService`** — local SQLite FTS5 mirror of bill title + CRS summary text, backing `congressgov_search_bills` only:
 - Opt-in via `CONGRESS_MIRROR_ENABLED` (off by default); built out-of-band via the `mirror:init`/`mirror:refresh` scripts, never on server startup
 - No live-API fallback — ingests through the existing `CongressApiService`, and a mirror that hasn't finished its initial build returns an empty result with a notice, not an error
@@ -198,6 +210,8 @@ All tools share these patterns. The service layer handles them uniformly:
 | Invalid params | `validationError('...', { field })` |
 | Network error | `serviceUnavailable('Unable to reach the Congress.gov API.')` |
 
+The `content` operation adds `documentErrorContracts` (tool-helpers) on top: `document_unavailable`, `format_unavailable`, `document_fetch_failed`, `document_too_large`, and `offset_past_end`. `CongressDocumentsService` raises each with a matching `data.reason` and resolves the hint via `ctx.recoveryFor` — note that `ctx.fail` does **not** auto-populate `recovery`, so handler-side `ctx.fail` calls must spread `ctx.recoveryFor(reason)` into their data or the hint never reaches the wire.
+
 ---
 
 ## Naming

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.4.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-^1.30.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.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.5.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-^1.30.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.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -51,6 +51,7 @@ Browse and retrieve U.S. legislative bill data from Congress.gov.
 
 - 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
 
@@ -112,6 +113,7 @@ Browse the daily Congressional Record — floor speeches, debates, and legislati
 
 - Browse volumes by congress number
 - Retrieve specific issue articles
+- `content` reads one article's actual text, selected by `articleIndex` and bounded by `characterOffset`/`characterLimit`
 
 ---
 

package/dist/index.js

@@ -25,6 +25,7 @@ import { rollVotesTool } from './mcp-server/tools/definitions/roll-votes.tool.js
 import { searchBillsTool } from './mcp-server/tools/definitions/search-bills.tool.js';
 import { senateNominationsTool } from './mcp-server/tools/definitions/senate-nominations.tool.js';
 import { initCongressApi } from './services/congress-api/congress-api-service.js';
+import { initCongressDocuments } from './services/congress-documents/congress-documents-service.js';
 import { getCongressMirror, initCongressMirror, } from './services/congress-mirror/congress-mirror-service.js';
 import { initSenateVoteService } from './services/senate-lis/senate-vote-service.js';
 const REPO_ROOT = 'https://github.com/cyanheads/congressgov-mcp-server';
@@ -72,6 +73,7 @@ await createApp({
     setup(core) {
         initCongressApi();
         initSenateVoteService();
+        initCongressDocuments();
         /**
          * The bill FTS mirror is opt-in (off by default). When enabled, wire the
          * service; a full init runs out-of-band via `mirror:init` (never on startup).

package/dist/index.js.map

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

package/dist/mcp-server/prompts/definitions/legislative-research.prompt.d.ts

@@ -1,5 +1,14 @@
 /**
  * @fileoverview Prompt providing a research framework for investigating a policy area across Congress.
+ *
+ * The discovery plan branches on the mirror configuration, because the two
+ * deployments expose different capabilities: with `CONGRESS_MIRROR_ENABLED` the
+ * server registers `congressgov_search_bills` and topical discovery is real;
+ * without it no registered tool accepts a topic string, and the honest plan is
+ * to say so and ask for a seed identifier. Every step names a tool that is
+ * registered in that configuration and an operation that accepts the input the
+ * step supplies.
+ *
  * @module mcp-server/prompts/definitions/legislative-research
  */
 import { z } from '@cyanheads/mcp-ts-core';

package/dist/mcp-server/prompts/definitions/legislative-research.prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legislative-research.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/legislative-research.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,eAAO,MAAM,yBAAyB;;;kBA2CpC,CAAC"}
+{"version":3,"file":"legislative-research.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/legislative-research.prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAsCnD,eAAO,MAAM,yBAAyB;;;kBAiCpC,CAAC"}

package/dist/mcp-server/prompts/definitions/legislative-research.prompt.js

@@ -1,10 +1,52 @@
 /**
  * @fileoverview Prompt providing a research framework for investigating a policy area across Congress.
+ *
+ * The discovery plan branches on the mirror configuration, because the two
+ * deployments expose different capabilities: with `CONGRESS_MIRROR_ENABLED` the
+ * server registers `congressgov_search_bills` and topical discovery is real;
+ * without it no registered tool accepts a topic string, and the honest plan is
+ * to say so and ask for a seed identifier. Every step names a tool that is
+ * registered in that configuration and an operation that accepts the input the
+ * step supplies.
+ *
  * @module mcp-server/prompts/definitions/legislative-research
  */
 import { prompt, z } from '@cyanheads/mcp-ts-core';
+import { getServerConfig } from '../../../config/server-config.js';
+/** Shared closing framework — the synthesis half is configuration-independent. */
+const SYNTHESIS = `Synthesize findings into:
+- **Landscape** — What legislation is active on this topic? What stage are key bills at?
+- **Key Players** — Which members and committees are driving activity?
+- **Substance** — What do the bill summaries and subject terms actually say?
+- **Recent Activity** — What has each bill's latest action been in the last 30 days?
+- **Outlook** — What is the likely trajectory for this policy area?`;
+/** Discovery plan when the local bill-search mirror is on and search_bills is registered. */
+function mirrorPlan(topic) {
+    return `Keyword search over the local bill mirror is the one topical entry point — the Congress.gov API has no keyword search, so every other tool browses by congress, date, chamber, or identifier.
+
+1. **Find candidate bills** — Call congressgov_search_bills with "${topic}" as the query. It matches bill titles and CRS summary text over a bounded congress window; it does not match policy area, full bill text, CRS reports, or the Congressional Record. Narrow with congress, billType, or originChamber when the result set is broad; use fewer or broader keywords when it is empty.
+2. **Read each candidate** — Each hit carries congress, billType, and billNumber. Pass them to congressgov_bill_lookup with operation='get', then 'summaries', 'subjects', 'actions', 'cosponsors', and 'related' for substance, status, and companion bills.
+3. **Follow the sponsors** — Take a bioguideId from the bill's sponsors or its 'cosponsors' rows and call congressgov_member_lookup with operation='get' for the profile or 'sponsored' for the rest of that member's portfolio.
+4. **Follow the committees** — Call congressgov_bill_lookup with operation='committees' for the committees a bill was referred to, or congressgov_committee_lookup with operation='list' and a filter matching a committee *name* ("armed services", "energy") — not the topic string — then its 'bills' and 'reports' operations on the resulting system code.
+
+Report the boundary along with the findings: the search covers bill titles and summaries only, so silence from it is not evidence that no CRS analysis or floor debate exists.`;
+}
+/** Discovery plan when the mirror is off — no registered tool accepts a topic. */
+const NO_MIRROR_PLAN = `This deployment cannot search by topic. The Congress.gov API has no keyword search, and this server's optional local bill-search index is turned off (an operator enables it with CONGRESS_MIRROR_ENABLED=true), so no registered tool accepts a topic string. congressgov_crs_reports, congressgov_bill_summaries, and congressgov_daily_record browse by congress, date, or identifier only — scanning them for a topic means reading thousands of unrelated rows.
+
+Ask for one of these seeds before going further, and say why it is needed:
+- a bill — congress + bill type + number (e.g. 119, hr, 4765)
+- a member — bioguideId (e.g. P000197)
+- a committee — name or system code (e.g. "armed services", hsas00)
+- a CRS report — report id (e.g. R46991)
+
+From a seed, these steps are executable:
+1. **Bill** — congressgov_bill_lookup with operation='get', then 'summaries', 'subjects', 'actions', 'cosponsors', 'committees', and 'related'. Sponsors and related bills are how the search widens without a keyword index.
+2. **Member** — congressgov_member_lookup with operation='get', 'sponsored', or 'cosponsored'. There is no member name search; a bioguideId comes from a bill's sponsors or from operation='list' filtered by state and district.
+3. **Committee** — congressgov_committee_lookup with operation='list' and a filter matching a committee *name* to resolve a system code, then 'bills' and 'reports' on that code.
+4. **CRS report** — congressgov_crs_reports with operation='get' and a known report id.`;
 export const legislativeResearchPrompt = prompt('congressgov_legislative_research', {
-    description: 'Research framework for investigating a policy area across Congress: relevant bills, key members, committee activity, CRS reports, and floor activity.',
+    description: 'Research framework for investigating a policy area across Congress: relevant bills, key members, committee activity, and legislative status. The discovery plan reflects whether this deployment can search by keyword.',
     args: z.object({
         topic: z
             .string()
@@ -18,6 +60,7 @@ export const legislativeResearchPrompt = prompt('congressgov_legislative_researc
         const congressNote = args.congress
             ? `Focus on the ${args.congress}th Congress.`
             : 'Start with the current congress (use the congress://current resource to find the number).';
+        const plan = getServerConfig().mirrorEnabled ? mirrorPlan(args.topic) : NO_MIRROR_PLAN;
         return [
             {
                 role: 'user',
@@ -25,21 +68,9 @@ export const legislativeResearchPrompt = prompt('congressgov_legislative_researc
                     type: 'text',
                     text: `Research the topic "${args.topic}" across congressional activity. ${congressNote}
 
-Since the Congress.gov API has no keyword search, use these discovery strategies:
-
-1. **CRS Reports** — Use congressgov_crs_reports to find nonpartisan policy analyses on this topic.
-2. **Recent Summaries** — Use congressgov_bill_summaries with a broad date range to find recently summarized bills that may relate to this topic.
-3. **Bill Detail** — Once candidate bills surface, use congressgov_bill_lookup with operation='get' (and sub-resources like 'actions', 'cosponsors', 'related') for full sponsor, status, and policy area data.
-4. **Committee Activity** — Identify relevant committees using congressgov_committee_lookup, then check their recent bills and reports.
-5. **Key Members** — Identify members known for this policy area, then check their sponsored legislation via congressgov_member_lookup.
-6. **Floor Activity** — Check congressgov_daily_record for recent floor debate on the topic.
+${plan}
 
-Synthesize findings into:
-- **Landscape** — What legislation is active on this topic? What stage are key bills at?
-- **Key Players** — Which members and committees are driving activity?
-- **Policy Analysis** — What do CRS reports say about the issues?
-- **Recent Activity** — What happened in the last 30 days?
-- **Outlook** — What is the likely trajectory for this policy area?`,
+${SYNTHESIS}`,
                 },
             },
         ];

package/dist/mcp-server/prompts/definitions/legislative-research.prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"legislative-research.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/legislative-research.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,kCAAkC,EAAE;IAClF,WAAW,EACT,uJAAuJ;IACzJ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CAAC,iFAAiF,CAAC;QAC9F,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,4DAA4D,CAAC;KAC1E,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ;YAChC,CAAC,CAAC,gBAAgB,IAAI,CAAC,QAAQ,cAAc;YAC7C,CAAC,CAAC,2FAA2F,CAAC;QAEhG,OAAO;YACL;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,uBAAuB,IAAI,CAAC,KAAK,oCAAoC,YAAY;;;;;;;;;;;;;;;;oEAgB7B;iBAC3D;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"legislative-research.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/legislative-research.prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,kFAAkF;AAClF,MAAM,SAAS,GAAG;;;;;oEAKkD,CAAC;AAErE,6FAA6F;AAC7F,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO;;oEAE2D,KAAK;;;;;+KAKsG,CAAC;AAChL,CAAC;AAED,kFAAkF;AAClF,MAAM,cAAc,GAAG;;;;;;;;;;;;wFAYiE,CAAC;AAEzF,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,kCAAkC,EAAE;IAClF,WAAW,EACT,yNAAyN;IAC3N,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,CAAC,iFAAiF,CAAC;QAC9F,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,4DAA4D,CAAC;KAC1E,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ;YAChC,CAAC,CAAC,gBAAgB,IAAI,CAAC,QAAQ,cAAc;YAC7C,CAAC,CAAC,2FAA2F,CAAC;QAEhG,MAAM,IAAI,GAAG,eAAe,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;QAEvF,OAAO;YACL;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,uBAAuB,IAAI,CAAC,KAAK,oCAAoC,YAAY;;EAE/F,IAAI;;EAEJ,SAAS,EAAE;iBACJ;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/bill-lookup.tool.d.ts

@@ -4,10 +4,17 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 export declare const billLookupTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    format: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        xml: "xml";
+    }>>;
+    characterOffset: z.ZodDefault<z.ZodNumber>;
+    characterLimit: z.ZodDefault<z.ZodNumber>;
     operation: z.ZodEnum<{
         actions: "actions";
         amendments: "amendments";
         committees: "committees";
+        content: "content";
         cosponsors: "cosponsors";
         get: "get";
         list: "list";
@@ -37,6 +44,7 @@ export declare const billLookupTool: import("@cyanheads/mcp-ts-core").ToolDefini
     }>>;
     limit: z.ZodDefault<z.ZodNumber>;
     offset: z.ZodDefault<z.ZodNumber>;
+    textVersionIndex: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     data: z.ZodOptional<z.ZodArray<z.ZodObject<{}, z.core.$loose>>>;
     pagination: z.ZodOptional<z.ZodObject<{
@@ -67,6 +75,36 @@ export declare const billLookupTool: import("@cyanheads/mcp-ts-core").ToolDefini
     readonly retryable: true;
     readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly reason: 'document_unavailable';
+    readonly retryable: false;
+    readonly when: "The 'content' selection resolves to no retrievable document — the text version or article index is past the end of the list, the record publishes no formats at all, or Congress.gov does not hold the file its own metadata names.";
+    readonly recovery: "Run the tool's 'text' or 'articles' operation first to see which documents Congress.gov publishes for this record, then retry with a selection it lists.";
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly reason: 'format_unavailable';
+    readonly retryable: false;
+    readonly when: "The document exists but publishes nothing in the requested 'format' — some text versions and committee reports ship PDF only, and no Congressional Record article publishes XML.";
+    readonly recovery: "Retry with format 'text', which every document checked publishes; if that fails too the document is PDF-only, so read it at the format URL the text operation returns.";
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly reason: 'document_fetch_failed';
+    readonly retryable: true;
+    readonly when: 'www.congress.gov did not return a readable document — a non-2xx status, a network failure, an empty body, or a content type that is not text or XML.';
+    readonly recovery: 'Retry after a short delay; if the failure persists, request a different format or read the document at the sourceUrl the text operation returns.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly reason: 'document_too_large';
+    readonly retryable: false;
+    readonly when: 'The document is larger than the byte ceiling this server retrieves, so no character window can be served from it.';
+    readonly recovery: "Request the other 'format' for this document, which is usually far smaller, or read it directly at the sourceUrl the text operation returns.";
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly reason: 'offset_past_end';
+    readonly retryable: false;
+    readonly when: 'characterOffset is at or beyond the last character of the document, so the window would be empty.';
+    readonly recovery: 'Restart the walk at characterOffset 0 and follow nextOffset, which goes null once the document has been read to the end.';
 }], {
     effectiveQuery: z.ZodString;
     totalCount: z.ZodNumber;

package/dist/mcp-server/tools/definitions/bill-lookup.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bill-lookup.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-lookup.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAuCjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2IzB,CAAC"}
+{"version":3,"file":"bill-lookup.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-lookup.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA+CjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkOzB,CAAC"}

package/dist/mcp-server/tools/definitions/bill-lookup.tool.js

@@ -5,9 +5,11 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { validationError } from '@cyanheads/mcp-ts-core/errors';
 import { formatBills } from '../../../mcp-server/tools/format-helpers.js';
-import { buildEffectiveQuery, congressErrorContracts, listEnrichment, listOrDetail, normalizeOptionalString, notifyIfNoMatches, numericIdentifier, toIdentifierNumber, validateDateTimeRange, validateIsoDateTime, } from '../../../mcp-server/tools/tool-helpers.js';
+import { buildEffectiveQuery, congressErrorContracts, documentErrorContracts, documentWindowInput, listEnrichment, listOrDetail, normalizeOptionalString, notifyIfNoMatches, numericIdentifier, toIdentifierNumber, validateDateTimeRange, validateIsoDateTime, } from '../../../mcp-server/tools/tool-helpers.js';
 import { getCongressApi } from '../../../services/congress-api/congress-api-service.js';
 import { BILL_TYPE_CODES } from '../../../services/congress-api/types.js';
+import { getCongressDocuments } from '../../../services/congress-documents/congress-documents-service.js';
+import { describeFormat, selectDocumentUrl, } from '../../../services/congress-documents/document-formats.js';
 const BillTypeEnum = z.enum(BILL_TYPE_CODES);
 const OperationEnum = z.enum([
     'list',
@@ -21,14 +23,15 @@ const OperationEnum = z.enum([
     'text',
     'titles',
     'related',
+    'content',
 ]);
 const SUB_RESOURCE_MAP = {
     related: 'relatedbills',
 };
 export const billLookupTool = tool('congressgov_bill_lookup', {
-    description: `Browse and retrieve U.S. legislative bill data from Congress.gov. Discover bills by filtering on congress, bill type, and date range — there is no keyword search. Use 'list' to browse (requires congress, defaults to most-recently-updated first), 'get' for full bill detail (sponsor, policy area, CBO estimates, law info), or drill into a specific bill with 'actions', 'amendments', 'cosponsors', 'committees', 'subjects', 'summaries', 'text', 'titles', or 'related' (each requires congress + billType + billNumber).`,
+    description: `Browse and retrieve U.S. legislative bill data from Congress.gov. Discover bills by filtering on congress, bill type, and date range — there is no keyword search. Use 'list' to browse (requires congress, defaults to most-recently-updated first), 'get' for full bill detail (sponsor, policy area, CBO estimates, law info), or drill into a specific bill with 'actions', 'amendments', 'cosponsors', 'committees', 'subjects', 'summaries', 'text', 'titles', or 'related' (each requires congress + billType + billNumber). 'text' lists the published versions and their format URLs; 'content' then reads one version's actual text, a bounded character window at a time.`,
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
-    errors: congressErrorContracts,
+    errors: [...congressErrorContracts, ...documentErrorContracts],
     input: z.object({
         operation: OperationEnum.describe('Which data to retrieve.'),
         congress: z.number().int().positive().describe('Congress number (e.g., 118, 119).'),
@@ -48,8 +51,15 @@ export const billLookupTool = tool('congressgov_bill_lookup', {
             .describe("Sort order for 'list' (sorts by update date). 'recent' (default) is newest first; 'oldest' is ascending. Ignored by other operations."),
         limit: z.number().int().min(1).max(250).default(20).describe('Results per page (1-250).'),
         offset: z.number().int().min(0).default(0).describe('Pagination offset.'),
+        textVersionIndex: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Which text version 'content' reads, 0-based against the same order 'text' returns — 0 is the most recent version. Ignored by other operations."),
+        ...documentWindowInput,
     }),
-    output: listOrDetail('bill', 'Bill record (sponsor, policy area, latest action, CBO estimates, law citation) for `get`; absent for `list` and sub-resources.'),
+    output: listOrDetail('bill', "Bill record (sponsor, policy area, latest action, CBO estimates, law citation) for `get`; absent for `list` and sub-resources. For `content`, an alternative key 'content' carries {text, format, sourceUrl, documentTitle, totalCharacters, offset, truncated, nextOffset} — one exact character window of the document."),
     enrichment: listEnrichment,
     format: formatBills,
     async handler(input, ctx) {
@@ -98,6 +108,64 @@ export const billLookupTool = tool('congressgov_bill_lookup', {
             ctx.enrich.total(1);
             return result;
         }
+        if (input.operation === 'content') {
+            /** One upstream page of exactly the selected version — not the whole list. */
+            const versions = await api.getBillSubResource({
+                congress: input.congress,
+                billType: input.billType,
+                billNumber,
+                subResource: 'text',
+                limit: 1,
+                offset: input.textVersionIndex,
+            }, ctx);
+            /**
+             * `pagination.count` decides the range, not the presence of a row: for an
+             * enacted bill the endpoint appends the "Public Law" version to every page,
+             * so an out-of-range offset comes back holding that row instead of empty.
+             * Selecting `data[0]` alone would serve the Public Law text for any index
+             * past the end — a different document than the caller asked for.
+             */
+            const version = input.textVersionIndex < versions.pagination.count ? versions.data[0] : undefined;
+            if (!version) {
+                throw ctx.fail('document_unavailable', `No text version at index ${input.textVersionIndex} for ${input.billType.toUpperCase()} ${billNumber} — Congress.gov publishes ${versions.pagination.count} version(s) for this bill.`, {
+                    ...ctx.recoveryFor('document_unavailable'),
+                    textVersionIndex: input.textVersionIndex,
+                    available: versions.pagination.count,
+                });
+            }
+            const url = selectDocumentUrl(version.formats, input.format);
+            if (!url) {
+                throw ctx.fail('format_unavailable', `This text version publishes no '${input.format}' document (looked for ${describeFormat(input.format)}).`, {
+                    ...ctx.recoveryFor('format_unavailable'),
+                    format: input.format,
+                    textVersionIndex: input.textVersionIndex,
+                });
+            }
+            const document = await getCongressDocuments().fetchDocument({
+                url,
+                characterOffset: input.characterOffset,
+                characterLimit: input.characterLimit,
+            }, ctx);
+            const versionType = typeof version.type === 'string' ? version.type : 'Bill Text';
+            ctx.log.info('Bill text content retrieved', {
+                congress: input.congress,
+                billType: input.billType,
+                billNumber,
+                textVersionIndex: input.textVersionIndex,
+                format: input.format,
+                totalCharacters: document.totalCharacters,
+            });
+            ctx.enrich.echo(`${versionType} of ${input.billType.toUpperCase()} ${billNumber} (${input.congress}th Congress), ${input.format} characters ${document.offset}–${document.offset + document.text.length}`);
+            ctx.enrich.total(document.totalCharacters);
+            return {
+                content: {
+                    ...document,
+                    format: input.format,
+                    sourceUrl: url,
+                    documentTitle: `${input.billType.toUpperCase()} ${billNumber} — ${versionType}`,
+                },
+            };
+        }
         const subResource = SUB_RESOURCE_MAP[input.operation] ?? input.operation;
         const result = await api.getBillSubResource({
             congress: input.congress,

package/dist/mcp-server/tools/definitions/bill-lookup.tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"bill-lookup.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-lookup.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bill-lookup.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/bill-lookup.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/committee-reports.tool.d.ts

@@ -4,7 +4,14 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 export declare const committeeReportsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    format: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        xml: "xml";
+    }>>;
+    characterOffset: z.ZodDefault<z.ZodNumber>;
+    characterLimit: z.ZodDefault<z.ZodNumber>;
     operation: z.ZodEnum<{
+        content: "content";
         get: "get";
         list: "list";
         text: "text";
@@ -48,6 +55,36 @@ export declare const committeeReportsTool: import("@cyanheads/mcp-ts-core").Tool
     readonly retryable: true;
     readonly when: 'Congress.gov returned an unexpected error (5xx or another non-2xx status).';
     readonly recovery: 'Retry after a short delay; if the failure persists the Congress.gov service may be temporarily degraded.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly reason: 'document_unavailable';
+    readonly retryable: false;
+    readonly when: "The 'content' selection resolves to no retrievable document — the text version or article index is past the end of the list, the record publishes no formats at all, or Congress.gov does not hold the file its own metadata names.";
+    readonly recovery: "Run the tool's 'text' or 'articles' operation first to see which documents Congress.gov publishes for this record, then retry with a selection it lists.";
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly reason: 'format_unavailable';
+    readonly retryable: false;
+    readonly when: "The document exists but publishes nothing in the requested 'format' — some text versions and committee reports ship PDF only, and no Congressional Record article publishes XML.";
+    readonly recovery: "Retry with format 'text', which every document checked publishes; if that fails too the document is PDF-only, so read it at the format URL the text operation returns.";
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+    readonly reason: 'document_fetch_failed';
+    readonly retryable: true;
+    readonly when: 'www.congress.gov did not return a readable document — a non-2xx status, a network failure, an empty body, or a content type that is not text or XML.';
+    readonly recovery: 'Retry after a short delay; if the failure persists, request a different format or read the document at the sourceUrl the text operation returns.';
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly reason: 'document_too_large';
+    readonly retryable: false;
+    readonly when: 'The document is larger than the byte ceiling this server retrieves, so no character window can be served from it.';
+    readonly recovery: "Request the other 'format' for this document, which is usually far smaller, or read it directly at the sourceUrl the text operation returns.";
+}, {
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly reason: 'offset_past_end';
+    readonly retryable: false;
+    readonly when: 'characterOffset is at or beyond the last character of the document, so the window would be empty.';
+    readonly recovery: 'Restart the walk at characterOffset 0 and follow nextOffset, which goes null once the document has been read to the end.';
 }], {
     effectiveQuery: z.ZodString;
     totalCount: z.ZodNumber;

package/dist/mcp-server/tools/definitions/committee-reports.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"committee-reports.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/committee-reports.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAajD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8G/B,CAAC"}
+{"version":3,"file":"committee-reports.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/committee-reports.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAiCjD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8K/B,CAAC"}