@cyanheads/congressgov-mcp-server 0.4.3 → 0.5.0

package/dist/services/congress-documents/congress-documents-service.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Bounded retrieval of legislative document text from www.congress.gov.
+ *
+ * The document bodies behind Congress.gov's format URLs live on `www.congress.gov`
+ * — a different host from the `api.congress.gov` that `CongressApiService` is
+ * scoped to, with no API key, no JSON, and documents that run past a megabyte.
+ * That is a second upstream, not a second method on the API client, so it gets
+ * its own service the way `SenateVoteService` does for the Senate LIS feed.
+ *
+ * Two bounds, deliberately separate:
+ * - **The fetch** is bounded by {@link MAX_DOCUMENT_BYTES}, a request timeout, and
+ *   a content-type allowlist. An oversized document is refused — before the body
+ *   is read when Content-Length says so, mid-stream when it does not — rather
+ *   than silently truncated or pulled whole into memory.
+ * - **The response** is bounded by an exact character offset/limit window. Offsets
+ *   index into the extracted plain text and are never snapped to section or
+ *   paragraph breaks, so feeding `nextOffset` back walks a document with every
+ *   character returned exactly once — no overlap, no gap.
+ *
+ * @module services/congress-documents/congress-documents-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { DocumentContent, FetchDocumentParams } from './types.js';
+/**
+ * Ceiling on a single document. The largest body observed across bills,
+ * committee reports, and the Daily Record is the 119th Congress H.R. 1 USLM XML
+ * at ~2.7 MB (its Formatted Text is ~1.0 MB), so this clears real documents with
+ * room to spare while still refusing a pathological one.
+ */
+export declare const MAX_DOCUMENT_BYTES = 5000000;
+/** Bounds the whole exchange, headers and body — a megabyte-scale body needs the room. */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare class CongressDocumentsService {
+    private readonly maxDocumentBytes;
+    constructor(maxDocumentBytes?: number);
+    /**
+     * Fetch one document and return the requested character window of its text.
+     *
+     * `url` comes from Congress.gov's own format metadata — a caller never supplies
+     * one — and is still checked against {@link ALLOWED_HOSTS} before any request
+     * goes out, so a redirected or malformed upstream link cannot turn this into a
+     * general-purpose fetcher.
+     */
+    fetchDocument(params: FetchDocumentParams, ctx: Context): Promise<DocumentContent>;
+    /** Slice the exact `[offset, offset + limit)` window and describe what remains. */
+    private window;
+    private assertAllowedHost;
+    private doFetch;
+    /**
+     * A 404 means Congress.gov's metadata named a document its own file host does
+     * not hold — a missing document, not a transport failure. Everything else
+     * (5xx, timeout, socket error) is the transport, and stays retryable.
+     */
+    private classifyFetchError;
+    private assertContentType;
+    /** Refuse an oversized document on its advertised length, before reading a byte of it. */
+    private assertAdvertisedSize;
+    /**
+     * Read the body under a hard byte budget, cancelling the stream the moment it
+     * is exceeded. Chunks are decoded once at the end so a multi-byte character
+     * split across a chunk boundary still decodes correctly.
+     */
+    private readBounded;
+    private tooLarge;
+    private isRetryableError;
+    private getRequestContext;
+    private getAbortSignal;
+}
+export declare function initCongressDocuments(): void;
+export declare function getCongressDocuments(): CongressDocumentsService;
+//# sourceMappingURL=congress-documents-service.d.ts.map

package/dist/services/congress-documents/congress-documents-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"congress-documents-service.d.ts","sourceRoot":"","sources":["../../../src/services/congress-documents/congress-documents-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAUtD,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAY,CAAC;AAE5C,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,QAAS,CAAC;AA4CzC,qBAAa,wBAAwB;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAA7C,YAA6B,gBAAgB,GAAE,MAA2B,EAAI;IAE9E;;;;;;;OAOG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAkBvF;IAED,mFAAmF;IACnF,OAAO,CAAC,MAAM;IA8Bd,OAAO,CAAC,iBAAiB;YAoBX,OAAO;IAsBrB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAqB1B,OAAO,CAAC,iBAAiB;IAgBzB,0FAA0F;IAC1F,OAAO,CAAC,oBAAoB;IAQ5B;;;;OAIG;YACW,WAAW;IAoCzB,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,cAAc;CAIvB;AAID,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,wBAAgB,oBAAoB,IAAI,wBAAwB,CAO/D"}

package/dist/services/congress-documents/congress-documents-service.js

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Bounded retrieval of legislative document text from www.congress.gov.
+ *
+ * The document bodies behind Congress.gov's format URLs live on `www.congress.gov`
+ * — a different host from the `api.congress.gov` that `CongressApiService` is
+ * scoped to, with no API key, no JSON, and documents that run past a megabyte.
+ * That is a second upstream, not a second method on the API client, so it gets
+ * its own service the way `SenateVoteService` does for the Senate LIS feed.
+ *
+ * Two bounds, deliberately separate:
+ * - **The fetch** is bounded by {@link MAX_DOCUMENT_BYTES}, a request timeout, and
+ *   a content-type allowlist. An oversized document is refused — before the body
+ *   is read when Content-Length says so, mid-stream when it does not — rather
+ *   than silently truncated or pulled whole into memory.
+ * - **The response** is bounded by an exact character offset/limit window. Offsets
+ *   index into the extracted plain text and are never snapped to section or
+ *   paragraph breaks, so feeding `nextOffset` back walks a document with every
+ *   character returned exactly once — no overlap, no gap.
+ *
+ * @module services/congress-documents/congress-documents-service
+ */
+import { invalidParams, JsonRpcErrorCode, McpError, notFound, serviceUnavailable, } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { extractDocumentText } from './extract-text.js';
+/**
+ * Ceiling on a single document. The largest body observed across bills,
+ * committee reports, and the Daily Record is the 119th Congress H.R. 1 USLM XML
+ * at ~2.7 MB (its Formatted Text is ~1.0 MB), so this clears real documents with
+ * room to spare while still refusing a pathological one.
+ */
+export const MAX_DOCUMENT_BYTES = 5_000_000;
+/** Bounds the whole exchange, headers and body — a megabyte-scale body needs the room. */
+export const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_ATTEMPTS = 3;
+const BASE_BACKOFF_MS = 500;
+/** Every format URL these tools resolve points here; nothing else is fetched. */
+const ALLOWED_HOSTS = new Set(['www.congress.gov']);
+/** Content types the text extractor can read. PDF and everything else are refused. */
+const ALLOWED_CONTENT_TYPES = new Set(['application/xml', 'text/html', 'text/plain', 'text/xml']);
+/**
+ * Contract reasons this service raises. The matching `recovery` hints live once
+ * in `documentErrorContracts` (tool-helpers) and reach the wire via
+ * `ctx.recoveryFor` — services have no `ctx.fail`, but carrying `reason` in
+ * `data` plus the resolved hint gives clients the same shape.
+ */
+const DOCUMENT_UNAVAILABLE = 'document_unavailable';
+const DOCUMENT_FETCH_FAILED = 'document_fetch_failed';
+const DOCUMENT_TOO_LARGE = 'document_too_large';
+const OFFSET_PAST_END = 'offset_past_end';
+function isNativeAbortSignal(value) {
+    if (typeof AbortSignal !== 'function' ||
+        typeof AbortSignal.prototype.throwIfAborted !== 'function' ||
+        !value) {
+        return false;
+    }
+    try {
+        AbortSignal.prototype.throwIfAborted.call(value);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof TypeError);
+    }
+}
+export class CongressDocumentsService {
+    maxDocumentBytes;
+    constructor(maxDocumentBytes = MAX_DOCUMENT_BYTES) {
+        this.maxDocumentBytes = maxDocumentBytes;
+    }
+    /**
+     * Fetch one document and return the requested character window of its text.
+     *
+     * `url` comes from Congress.gov's own format metadata — a caller never supplies
+     * one — and is still checked against {@link ALLOWED_HOSTS} before any request
+     * goes out, so a redirected or malformed upstream link cannot turn this into a
+     * general-purpose fetcher.
+     */
+    async fetchDocument(params, ctx) {
+        this.assertAllowedHost(params.url, ctx);
+        const operation = 'CongressDocumentsService GET document';
+        const requestContext = this.getRequestContext(ctx, operation);
+        const signal = this.getAbortSignal(ctx);
+        const body = await withRetry(() => this.doFetch(params.url, requestContext, ctx, signal), {
+            operation,
+            context: requestContext,
+            baseDelayMs: BASE_BACKOFF_MS,
+            maxRetries: MAX_ATTEMPTS - 1,
+            isTransient: (error) => this.isRetryableError(error),
+            ...(signal ? { signal } : {}),
+        });
+        const text = extractDocumentText(body);
+        return this.window(text, params, ctx);
+    }
+    /** Slice the exact `[offset, offset + limit)` window and describe what remains. */
+    window(text, params, ctx) {
+        const totalCharacters = text.length;
+        const offset = params.characterOffset;
+        /** An empty document is a real (if unusual) answer at offset 0 — not a bad offset. */
+        if (totalCharacters > 0 && offset >= totalCharacters) {
+            throw invalidParams(`characterOffset ${offset} is past the end of this document, which has ${totalCharacters} characters.`, {
+                reason: OFFSET_PAST_END,
+                ...ctx.recoveryFor(OFFSET_PAST_END),
+                totalCharacters,
+                offset,
+                retryable: false,
+            });
+        }
+        const slice = text.slice(offset, offset + params.characterLimit);
+        const end = offset + slice.length;
+        const truncated = end < totalCharacters;
+        return {
+            text: slice,
+            totalCharacters,
+            offset,
+            truncated,
+            nextOffset: truncated ? end : null,
+        };
+    }
+    assertAllowedHost(url, ctx) {
+        let host;
+        try {
+            const parsed = new URL(url);
+            if (parsed.protocol === 'https:' || parsed.protocol === 'http:')
+                host = parsed.hostname;
+        }
+        catch {
+            host = undefined;
+        }
+        if (host === undefined || !ALLOWED_HOSTS.has(host.toLowerCase())) {
+            throw notFound('The upstream metadata points at a document this server does not retrieve — only documents hosted on www.congress.gov are read.', {
+                reason: DOCUMENT_UNAVAILABLE,
+                ...ctx.recoveryFor(DOCUMENT_UNAVAILABLE),
+                retryable: false,
+            });
+        }
+    }
+    async doFetch(url, requestContext, ctx, signal) {
+        let response;
+        try {
+            response = await fetchWithTimeout(url, REQUEST_TIMEOUT_MS, requestContext, {
+                headers: { Accept: 'text/html, application/xml, text/plain, */*' },
+                expectedStatuses: [404],
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch (error) {
+            throw this.classifyFetchError(error, ctx);
+        }
+        this.assertContentType(response, ctx);
+        this.assertAdvertisedSize(response, ctx);
+        return this.readBounded(response, ctx);
+    }
+    /**
+     * A 404 means Congress.gov's metadata named a document its own file host does
+     * not hold — a missing document, not a transport failure. Everything else
+     * (5xx, timeout, socket error) is the transport, and stays retryable.
+     */
+    classifyFetchError(error, ctx) {
+        if (!(error instanceof McpError))
+            return error;
+        if (error.code === JsonRpcErrorCode.NotFound) {
+            return notFound('Congress.gov does not hold the document its metadata pointed to.', {
+                reason: DOCUMENT_UNAVAILABLE,
+                ...ctx.recoveryFor(DOCUMENT_UNAVAILABLE),
+                retryable: false,
+            }, { cause: error });
+        }
+        /** The framework message embeds the request URL; re-message without echoing it. */
+        return serviceUnavailable('Unable to retrieve the document from Congress.gov.', { reason: DOCUMENT_FETCH_FAILED, ...ctx.recoveryFor(DOCUMENT_FETCH_FAILED) }, { cause: error });
+    }
+    assertContentType(response, ctx) {
+        const raw = response.headers.get('content-type') ?? '';
+        const mediaType = raw.split(';')[0]?.trim().toLowerCase() ?? '';
+        if (ALLOWED_CONTENT_TYPES.has(mediaType))
+            return;
+        throw serviceUnavailable(`Congress.gov returned content type '${mediaType || 'unknown'}', which this server cannot read as text.`, {
+            reason: DOCUMENT_FETCH_FAILED,
+            ...ctx.recoveryFor(DOCUMENT_FETCH_FAILED),
+            contentType: mediaType,
+            /** A wrong media type is deterministic — retrying re-downloads the same bytes. */
+            retryable: false,
+        });
+    }
+    /** Refuse an oversized document on its advertised length, before reading a byte of it. */
+    assertAdvertisedSize(response, ctx) {
+        const header = response.headers.get('content-length');
+        if (header === null)
+            return;
+        const contentLength = Number(header);
+        if (!Number.isFinite(contentLength) || contentLength <= this.maxDocumentBytes)
+            return;
+        throw this.tooLarge(ctx, { contentLength });
+    }
+    /**
+     * Read the body under a hard byte budget, cancelling the stream the moment it
+     * is exceeded. Chunks are decoded once at the end so a multi-byte character
+     * split across a chunk boundary still decodes correctly.
+     */
+    async readBounded(response, ctx) {
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let bytes = 0;
+        if (reader) {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (!value)
+                    continue;
+                bytes += value.byteLength;
+                if (bytes > this.maxDocumentBytes) {
+                    await reader.cancel().catch(() => undefined);
+                    throw this.tooLarge(ctx, { bytesRead: bytes });
+                }
+                chunks.push(value);
+            }
+        }
+        if (bytes === 0) {
+            throw serviceUnavailable('Congress.gov returned an empty document body.', {
+                reason: DOCUMENT_FETCH_FAILED,
+                ...ctx.recoveryFor(DOCUMENT_FETCH_FAILED),
+                retryable: false,
+            });
+        }
+        const merged = new Uint8Array(bytes);
+        let at = 0;
+        for (const chunk of chunks) {
+            merged.set(chunk, at);
+            at += chunk.byteLength;
+        }
+        return new TextDecoder('utf-8').decode(merged);
+    }
+    tooLarge(ctx, data) {
+        return invalidParams(`This document exceeds the ${this.maxDocumentBytes.toLocaleString('en-US')}-byte ceiling this server retrieves.`, {
+            reason: DOCUMENT_TOO_LARGE,
+            ...ctx.recoveryFor(DOCUMENT_TOO_LARGE),
+            ...data,
+            maxBytes: this.maxDocumentBytes,
+            retryable: false,
+        });
+    }
+    isRetryableError(error) {
+        if (error instanceof McpError) {
+            if (error.data?.retryable === false)
+                return false;
+            return (error.code === JsonRpcErrorCode.ServiceUnavailable ||
+                error.code === JsonRpcErrorCode.Timeout);
+        }
+        return true;
+    }
+    getRequestContext(ctx, operation) {
+        const ctxRecord = ctx;
+        const requestId = typeof ctxRecord.requestId === 'string' ? ctxRecord.requestId : 'congress-documents-service';
+        const timestamp = typeof ctxRecord.timestamp === 'string' ? ctxRecord.timestamp : new Date().toISOString();
+        return { operation, requestId, timestamp };
+    }
+    getAbortSignal(ctx) {
+        const signal = ctx.signal;
+        return isNativeAbortSignal(signal) ? signal : undefined;
+    }
+}
+let _service;
+export function initCongressDocuments() {
+    _service = new CongressDocumentsService();
+}
+export function getCongressDocuments() {
+    if (!_service) {
+        throw new Error('CongressDocumentsService not initialized — call initCongressDocuments() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=congress-documents-service.js.map

package/dist/services/congress-documents/congress-documents-service.js.map

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

package/dist/services/congress-documents/document-formats.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Resolve a requested document format to its upstream URL.
+ * @module services/congress-documents/document-formats
+ */
+import type { DocumentFormat } from './types.js';
+export declare const DOCUMENT_FORMATS: readonly ['text', 'xml'];
+/**
+ * Upstream `type` labels for each supported format, in preference order.
+ *
+ * `Formatted Text` is GPO's `<pre>`-wrapped print output and is the only format
+ * present on every document checked — bills back to 1999, committee reports, and
+ * Daily Record articles. XML is inconsistent: `United States Legislative Markup`
+ * ships on some newer bill versions, the legacy `Formatted XML` on many more, and
+ * neither on committee reports or the Daily Record. PDF is not offered.
+ */
+export declare const DOCUMENT_FORMAT_LABELS: Record<DocumentFormat, readonly string[]>;
+/**
+ * Pick the URL for `format` from an upstream format list.
+ *
+ * Labels are tried in preference order, and within one label a non-errata entry
+ * wins over an errata reprint — committee reports publish both under the same
+ * `Formatted Text` label and the errata is the correction, not the report.
+ * Returns `undefined` when the document publishes nothing in this format, which
+ * callers surface as the `format_unavailable` contract failure.
+ */
+export declare function selectDocumentUrl(entries: unknown, format: DocumentFormat): string | undefined;
+/** The upstream labels a format resolves to, for error messages that name what was searched. */
+export declare function describeFormat(format: DocumentFormat): string;
+//# sourceMappingURL=document-formats.d.ts.map

package/dist/services/congress-documents/document-formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-formats.d.ts","sourceRoot":"","sources":["../../../src/services/congress-documents/document-formats.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,YAAY,CAAC;AAEpE,eAAO,MAAM,gBAAgB,YAAI,MAAM,EAAE,KAAK,CAAU,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAG5E,CAAC;AAUF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAa9F;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAE7D"}

package/dist/services/congress-documents/document-formats.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Resolve a requested document format to its upstream URL.
+ * @module services/congress-documents/document-formats
+ */
+export const DOCUMENT_FORMATS = ['text', 'xml'];
+/**
+ * Upstream `type` labels for each supported format, in preference order.
+ *
+ * `Formatted Text` is GPO's `<pre>`-wrapped print output and is the only format
+ * present on every document checked — bills back to 1999, committee reports, and
+ * Daily Record articles. XML is inconsistent: `United States Legislative Markup`
+ * ships on some newer bill versions, the legacy `Formatted XML` on many more, and
+ * neither on committee reports or the Daily Record. PDF is not offered.
+ */
+export const DOCUMENT_FORMAT_LABELS = {
+    text: ['Formatted Text'],
+    xml: ['United States Legislative Markup', 'Formatted XML'],
+};
+function refUrl(ref) {
+    return typeof ref.url === 'string' && ref.url.trim() !== '' ? ref.url.trim() : undefined;
+}
+function matchesLabel(ref, label) {
+    return typeof ref.type === 'string' && ref.type.trim().toLowerCase() === label.toLowerCase();
+}
+/**
+ * Pick the URL for `format` from an upstream format list.
+ *
+ * Labels are tried in preference order, and within one label a non-errata entry
+ * wins over an errata reprint — committee reports publish both under the same
+ * `Formatted Text` label and the errata is the correction, not the report.
+ * Returns `undefined` when the document publishes nothing in this format, which
+ * callers surface as the `format_unavailable` contract failure.
+ */
+export function selectDocumentUrl(entries, format) {
+    if (!Array.isArray(entries))
+        return;
+    const refs = entries.filter((entry) => typeof entry === 'object' && entry !== null);
+    for (const label of DOCUMENT_FORMAT_LABELS[format]) {
+        const matched = refs.filter((ref) => matchesLabel(ref, label) && refUrl(ref) !== undefined);
+        const preferred = matched.find((ref) => ref.isErrata !== 'Y') ?? matched[0];
+        const url = preferred ? refUrl(preferred) : undefined;
+        if (url)
+            return url;
+    }
+    return;
+}
+/** The upstream labels a format resolves to, for error messages that name what was searched. */
+export function describeFormat(format) {
+    return DOCUMENT_FORMAT_LABELS[format].join(' / ');
+}
+//# sourceMappingURL=document-formats.js.map

package/dist/services/congress-documents/document-formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-formats.js","sourceRoot":"","sources":["../../../src/services/congress-documents/document-formats.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAU,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA8C;IAC/E,IAAI,EAAE,CAAC,gBAAgB,CAAC;IACxB,GAAG,EAAE,CAAC,kCAAkC,EAAE,eAAe,CAAC;CAC3D,CAAC;AAEF,SAAS,MAAM,CAAC,GAAsB;IACpC,OAAO,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3F,CAAC;AAED,SAAS,YAAY,CAAC,GAAsB,EAAE,KAAa;IACzD,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC;AAC/F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,MAAsB;IACxE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CACzB,CAAC,KAAK,EAA8B,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CACnF,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,sBAAsB,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;QAC5F,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5E,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACtD,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;IACtB,CAAC;IACD,OAAO;AACT,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACpD,CAAC"}

package/dist/services/congress-documents/extract-text.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Turn a Congress.gov document body into the plain text offsets index into.
+ * @module services/congress-documents/extract-text
+ */
+/**
+ * Extract the readable plain text of a Congress.gov document body.
+ *
+ * "Formatted Text" is not semantic HTML — it is GPO's monospace print output
+ * wrapped in `<pre>`, sometimes inside `<html><body>` and sometimes bare, with
+ * the occasional inline anchor and HTML-escaped entities. The pre-formatted
+ * layout (column alignment, indentation, blank-line structure) is the document's
+ * real structure, so whitespace is preserved verbatim rather than collapsed the
+ * way `htmlToMarkdown` collapses narrative prose. XML bodies run through the same
+ * pipeline minus the `<pre>` unwrap.
+ *
+ * The result is the string every character offset indexes into, so it has to be
+ * deterministic: line endings are normalized to `\n` before anything else, and
+ * the transform is applied once per fetch.
+ */
+export declare function extractDocumentText(body: string): string;
+//# sourceMappingURL=extract-text.d.ts.map

package/dist/services/congress-documents/extract-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-text.d.ts","sourceRoot":"","sources":["../../../src/services/congress-documents/extract-text.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4DH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD"}

package/dist/services/congress-documents/extract-text.js

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Turn a Congress.gov document body into the plain text offsets index into.
+ * @module services/congress-documents/extract-text
+ */
+/** Entities GPO emits by name. Numeric references are decoded generically. */
+const NAMED_ENTITIES = {
+    amp: '&',
+    apos: "'",
+    gt: '>',
+    lt: '<',
+    nbsp: ' ',
+    quot: '"',
+};
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+const TAG_RE = /<[^>]*>/g;
+const ENTITY_RE = /&(#[xX][0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g;
+/**
+ * Decode HTML/XML character references in one pass.
+ *
+ * A single pass is the point: decoding `&amp;` in its own sweep would turn the
+ * literal `&amp;lt;` into `<` instead of the `&lt;` the document actually says.
+ * An unrecognized reference is left verbatim rather than guessed at.
+ */
+function decodeEntities(text) {
+    return text.replace(ENTITY_RE, (match, ref) => {
+        if (ref.startsWith('#')) {
+            const hex = ref[1] === 'x' || ref[1] === 'X';
+            const codePoint = Number.parseInt(hex ? ref.slice(2) : ref.slice(1), hex ? 16 : 10);
+            if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff)
+                return match;
+            return String.fromCodePoint(codePoint);
+        }
+        return NAMED_ENTITIES[ref.toLowerCase()] ?? match;
+    });
+}
+/**
+ * The tag name has to end at the `>` or at whitespace. A loose `<\s*pre[^>]*>`
+ * also matches USLM's `<preamble>` — which truncated a 2.6 MB bill to its
+ * 223-character preamble, and reported that as the document's full length.
+ */
+const PRE_OPEN_RE = /<\s*pre(?:\s[^>]*)?\/?>/i;
+const PRE_CLOSE_RE = /<\s*\/\s*pre\s*>/gi;
+/**
+ * The content between the first `<pre>` and the last `</pre>`, or `undefined`
+ * when the body carries no `<pre>` block at all (every XML body, and any future
+ * shape that is not GPO print output).
+ */
+function unwrapPre(body) {
+    const open = PRE_OPEN_RE.exec(body);
+    if (!open)
+        return;
+    const start = open.index + open[0].length;
+    let closeAt = -1;
+    for (const close of body.matchAll(PRE_CLOSE_RE)) {
+        if (close.index > start)
+            closeAt = close.index;
+    }
+    return closeAt > start ? body.slice(start, closeAt) : body.slice(start);
+}
+/**
+ * Extract the readable plain text of a Congress.gov document body.
+ *
+ * "Formatted Text" is not semantic HTML — it is GPO's monospace print output
+ * wrapped in `<pre>`, sometimes inside `<html><body>` and sometimes bare, with
+ * the occasional inline anchor and HTML-escaped entities. The pre-formatted
+ * layout (column alignment, indentation, blank-line structure) is the document's
+ * real structure, so whitespace is preserved verbatim rather than collapsed the
+ * way `htmlToMarkdown` collapses narrative prose. XML bodies run through the same
+ * pipeline minus the `<pre>` unwrap.
+ *
+ * The result is the string every character offset indexes into, so it has to be
+ * deterministic: line endings are normalized to `\n` before anything else, and
+ * the transform is applied once per fetch.
+ */
+export function extractDocumentText(body) {
+    const normalized = body.replace(/\r\n?/g, '\n');
+    const stripped = normalized.replace(COMMENT_RE, '');
+    const inner = unwrapPre(stripped) ?? stripped;
+    return decodeEntities(inner.replace(TAG_RE, '')).trim();
+}
+//# sourceMappingURL=extract-text.js.map

package/dist/services/congress-documents/extract-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-text.js","sourceRoot":"","sources":["../../../src/services/congress-documents/extract-text.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8EAA8E;AAC9E,MAAM,cAAc,GAA2B;IAC7C,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,GAAG;IACT,EAAE,EAAE,GAAG;IACP,EAAE,EAAE,GAAG;IACP,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;CACV,CAAC;AAEF,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,MAAM,GAAG,UAAU,CAAC;AAC1B,MAAM,SAAS,GAAG,uCAAuC,CAAC;AAE1D;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;QACpD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;YAC7C,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACpF,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,GAAG,QAAQ;gBAAE,OAAO,KAAK,CAAC;YACxF,OAAO,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,cAAc,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,KAAK,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAC/C,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAE1C,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK;YAAE,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC;IACjD,CAAC;IACD,OAAO,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC;IAC9C,OAAO,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/services/congress-documents/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Domain types for bounded retrieval of Congress.gov document text.
+ * @module services/congress-documents/types
+ */
+/** The document formats this server retrieves. PDF is deliberately absent — extraction cost. */
+export type DocumentFormat = 'text' | 'xml';
+/**
+ * One entry of an upstream format list. Bill text versions and committee reports
+ * carry these under `formats[]`; Daily Congressional Record articles carry the
+ * same `{type, url}` pairs under `text[]`. Every field is optional — upstream
+ * rows are sparse and untyped at this boundary.
+ */
+export interface DocumentFormatRef {
+    isErrata?: unknown;
+    type?: unknown;
+    url?: unknown;
+}
+/** Parameters for a single bounded document read. */
+export interface FetchDocumentParams {
+    /** Maximum characters to return. */
+    characterLimit: number;
+    /** First character of the document to return, 0-based. */
+    characterOffset: number;
+    /** Absolute URL resolved from upstream metadata — never caller-supplied. */
+    url: string;
+}
+/**
+ * A bounded window onto one document's plain text.
+ *
+ * `offset` + `text.length` is exactly `nextOffset` when more remains, so feeding
+ * `nextOffset` back walks the document with no overlap and no gap.
+ */
+export interface DocumentContent {
+    /** Offset to pass next, or null at the end of the document. */
+    nextOffset: number | null;
+    /** Echo of the requested start offset. */
+    offset: number;
+    /** The requested character window, verbatim. */
+    text: string;
+    /** Characters in the whole document, not this window. */
+    totalCharacters: number;
+    /** True when characters remain past this window. */
+    truncated: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/congress-documents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/congress-documents/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gGAAgG;AAChG,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB"}

package/dist/services/congress-documents/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Domain types for bounded retrieval of Congress.gov document text.
+ * @module services/congress-documents/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/congress-documents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/congress-documents/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Access U.S. congressional data - bills, votes, members, committees - through MCP. STDIO & Streamable HTTP.",
   "mcpName": "io.github.cyanheads/congressgov-mcp-server",
   "type": "module",