@cyanheads/congressgov-mcp-server 0.4.2 → 0.5.0

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.2",
+  "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",

package/server.json

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