@cyanheads/congressgov-mcp-server 0.3.32 → 0.4.0

package/dist/services/congress-mirror/ingest.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview The Congress bill ingester — the one irreducibly per-source part
+ * of the mirror. Merges two upstream Congress.gov sources into one row per bill:
+ * the bill list (`/bill/{congress}`, sorted by updateDate) supplies the skeleton
+ * (title, chamber, latest action, update date); the CRS summaries list
+ * (`/summaries/{congress}`) supplies the summary text. Both reuse the existing
+ * `CongressApiService` — no new HTTP-calling code, only merge/orchestration.
+ *
+ * Merge order matters: the framework upsert writes every declared column for each
+ * record, so a partial (summary-only) upsert would null the title. The summaries
+ * are therefore loaded into a per-congress map first, then attached as each full
+ * bill row is emitted. Summaries are fully re-walked every sync (not date-filtered)
+ * so a re-emitted bill never loses a previously-stored summary. The durable
+ * checkpoint is the bills' `updateDate` high-water mark; refresh re-scans bills
+ * from it inclusively (`sort=updateDate asc`), and the upsert makes the overlap
+ * harmless.
+ * @module services/congress-mirror/ingest
+ */
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { htmlToPlainText } from './normalize.js';
+/** Congress.gov list endpoints cap the page size at 250 (confirmed live). */
+const PAGE_SIZE = 250;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Read a non-empty string (or a stringified number) from a raw field. */
+function str(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed === '' ? undefined : trimmed;
+    }
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return;
+}
+/** Read an integer from a raw field (number or numeric string). */
+function int(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return Math.trunc(value);
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number.parseInt(value.trim(), 10);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return;
+}
+/**
+ * Derive the composite primary key. Matches the existing
+ * `congress://bill/{congress}/{billType}/{billNumber}` resource addressing; the
+ * bill type is lowercased so both upstream sources key identically.
+ */
+function deriveBillId(congress, billType, billNumber) {
+    return `${congress}/${billType.toLowerCase()}/${billNumber}`;
+}
+/**
+ * The bill list emits date-only `updateDate` ("2026-06-30"); the API's
+ * `fromDateTime` filter wants full ISO 8601. Widen a date-only checkpoint to the
+ * start of that day so the inclusive re-scan catches same-day updates.
+ */
+function toFromDateTime(checkpoint) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(checkpoint) ? `${checkpoint}T00:00:00Z` : checkpoint;
+}
+/**
+ * Page the CRS summaries list for one congress into a `billId → plain-text
+ * summary` map, keeping the latest version per bill (by summary update/action
+ * stamp). Summaries ship as HTML and are stripped to plain text before storage.
+ */
+async function buildSummaryMap(api, congress, signal) {
+    const latest = new Map();
+    let offset = 0;
+    while (!signal.aborted) {
+        const result = await api.listSummaries({ congress, limit: PAGE_SIZE, offset });
+        const rows = result.data;
+        if (rows.length === 0)
+            break;
+        for (const raw of rows) {
+            if (!isRecord(raw) || !isRecord(raw.bill))
+                continue;
+            const bill = raw.bill;
+            const c = int(bill.congress);
+            const billType = str(bill.type)?.toLowerCase();
+            const billNumber = int(bill.number);
+            if (c === undefined || billType === undefined || billNumber === undefined)
+                continue;
+            const text = typeof raw.text === 'string' ? htmlToPlainText(raw.text) : '';
+            if (!text)
+                continue;
+            const id = deriveBillId(c, billType, billNumber);
+            const stamp = str(raw.updateDate) ?? str(raw.actionDate) ?? '';
+            const existing = latest.get(id);
+            if (!existing || stamp >= existing.stamp)
+                latest.set(id, { text, stamp });
+        }
+        if (rows.length < PAGE_SIZE || result.pagination.nextOffset == null)
+            break;
+        offset += PAGE_SIZE;
+    }
+    const map = new Map();
+    for (const [id, value] of latest)
+        map.set(id, value.text);
+    return map;
+}
+/** Map one raw bill-list record to a full mirror row, joining the summary map. */
+function toBillRow(raw, fallbackCongress, summaries) {
+    const billType = str(raw.type)?.toLowerCase();
+    const billNumber = int(raw.number);
+    if (billType === undefined || billNumber === undefined)
+        return null;
+    const congress = int(raw.congress) ?? fallbackCongress;
+    const id = deriveBillId(congress, billType, billNumber);
+    const latestAction = isRecord(raw.latestAction) ? raw.latestAction : undefined;
+    return {
+        billId: id,
+        congress,
+        billType,
+        billNumber,
+        title: str(raw.title) ?? null,
+        summary: summaries.get(id) ?? null,
+        originChamber: str(raw.originChamber) ?? null,
+        latestActionDate: latestAction ? (str(latestAction.actionDate) ?? null) : null,
+        latestActionText: latestAction ? (str(latestAction.text) ?? null) : null,
+        updateDate: str(raw.updateDate) ?? null,
+    };
+}
+/**
+ * Build the Congress bill ingester. The returned generator walks the configured
+ * congresses; for each, it loads the summary map, then streams bill pages
+ * (`sort=updateDate asc`) as full merged rows, advancing the durable checkpoint
+ * to the max `updateDate` seen.
+ *
+ * @param getApi - Accessor for the Congress API service (injectable for tests).
+ * @param congresses - Congress numbers to mirror.
+ */
+export function createCongressBillIngester(getApi, congresses) {
+    return async function* sync({ mode, checkpoint, signal }) {
+        const api = getApi();
+        const fromDateTime = mode === 'refresh' && checkpoint ? toFromDateTime(checkpoint) : undefined;
+        let maxUpdate = checkpoint;
+        logger.info(`Congress bill mirror sync starting (mode=${mode}, congresses=${congresses.join(',')}${fromDateTime ? `, since=${fromDateTime}` : ''})`);
+        for (const congress of congresses) {
+            if (signal.aborted)
+                return;
+            const summaries = await buildSummaryMap(api, congress, signal);
+            logger.info(`Congress ${congress}: ${summaries.size} summaries loaded`);
+            let offset = 0;
+            let billsMirrored = 0;
+            while (!signal.aborted) {
+                const result = await api.listBills({
+                    congress,
+                    sort: 'updateDate asc',
+                    limit: PAGE_SIZE,
+                    offset,
+                    ...(fromDateTime ? { fromDateTime } : {}),
+                });
+                const rows = result.data;
+                if (rows.length === 0)
+                    break;
+                const records = [];
+                for (const raw of rows) {
+                    if (!isRecord(raw))
+                        continue;
+                    const record = toBillRow(raw, congress, summaries);
+                    if (!record)
+                        continue;
+                    records.push(record);
+                    const updated = typeof record.updateDate === 'string' ? record.updateDate : undefined;
+                    if (updated && (maxUpdate === undefined || updated > maxUpdate))
+                        maxUpdate = updated;
+                }
+                billsMirrored += records.length;
+                yield { records, ...(maxUpdate ? { checkpoint: maxUpdate } : {}) };
+                if (rows.length < PAGE_SIZE || result.pagination.nextOffset == null)
+                    break;
+                offset += PAGE_SIZE;
+            }
+            logger.info(`Congress ${congress}: ${billsMirrored} bills mirrored`);
+        }
+    };
+}
+//# sourceMappingURL=ingest.js.map

package/dist/services/congress-mirror/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../../src/services/congress-mirror/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,OAAO,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,6EAA6E;AAC7E,MAAM,SAAS,GAAG,GAAG,CAAC;AAOtB,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,0EAA0E;AAC1E,SAAS,GAAG,CAAC,KAAc;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9E,OAAO;AACT,CAAC;AAED,mEAAmE;AACnE,SAAS,GAAG,CAAC,KAAc;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IACnD,CAAC;IACD,OAAO;AACT,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,QAAgB,EAAE,QAAgB,EAAE,UAAkB;IAC1E,OAAO,GAAG,QAAQ,IAAI,QAAQ,CAAC,WAAW,EAAE,IAAI,UAAU,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,UAAkB;IACxC,OAAO,qBAAqB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,eAAe,CAC5B,GAAc,EACd,QAAgB,EAChB,MAAmB;IAEnB,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2C,CAAC;IAClE,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACpD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YACtB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7B,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;YAC/C,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS;gBAAE,SAAS;YACpF,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;YACjD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChC,IAAI,CAAC,QAAQ,IAAI,KAAK,IAAI,QAAQ,CAAC,KAAK;gBAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,IAAI,IAAI;YAAE,MAAM;QAC3E,MAAM,IAAI,SAAS,CAAC;IACtB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM;QAAE,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1D,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kFAAkF;AAClF,SAAS,SAAS,CAChB,GAAc,EACd,gBAAwB,EACxB,SAA8B;IAE9B,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC;IACvD,MAAM,EAAE,GAAG,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACxD,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,OAAO;QACL,MAAM,EAAE,EAAE;QACV,QAAQ;QACR,QAAQ;QACR,UAAU;QACV,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI;QAC7B,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI;QAClC,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,IAAI;QAC7C,gBAAgB,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;QAC9E,gBAAgB,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;QACxE,UAAU,EAAE,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAuB,EACvB,UAAoB;IAEpB,OAAO,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAe;QACnE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;QACrB,MAAM,YAAY,GAAG,IAAI,KAAK,SAAS,IAAI,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/F,IAAI,SAAS,GAAuB,UAAU,CAAC;QAC/C,MAAM,CAAC,IAAI,CACT,4CAA4C,IAAI,gBAAgB,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,GAClF,YAAY,CAAC,CAAC,CAAC,WAAW,YAAY,EAAE,CAAC,CAAC,CAAC,EAC7C,GAAG,CACJ,CAAC;QAEF,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC3B,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/D,MAAM,CAAC,IAAI,CAAC,YAAY,QAAQ,KAAK,SAAS,CAAC,IAAI,mBAAmB,CAAC,CAAC;YAExE,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,IAAI,aAAa,GAAG,CAAC,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACvB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC;oBACjC,QAAQ;oBACR,IAAI,EAAE,gBAAgB;oBACtB,KAAK,EAAE,SAAS;oBAChB,MAAM;oBACN,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC1C,CAAC,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;gBACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;oBAAE,MAAM;gBAE7B,MAAM,OAAO,GAAgB,EAAE,CAAC;gBAChC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;wBAAE,SAAS;oBAC7B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;oBACnD,IAAI,CAAC,MAAM;wBAAE,SAAS;oBACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACrB,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;oBACtF,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,GAAG,SAAS,CAAC;wBAAE,SAAS,GAAG,OAAO,CAAC;gBACvF,CAAC;gBACD,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;gBAChC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;gBAEnE,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,IAAI,IAAI;oBAAE,MAAM;gBAC3E,MAAM,IAAI,SAAS,CAAC;YACtB,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,YAAY,QAAQ,KAAK,aAAa,iBAAiB,CAAC,CAAC;QACvE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/services/congress-mirror/normalize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Pure normalization helpers for the bill mirror — HTML→plain-text
+ * stripping (summaries ship as HTML; the FTS index and snippet surface want plain
+ * text) and FTS5 `MATCH` escaping (tokenize + individually quote so a stray `-`,
+ * an unbalanced quote, or an FTS5 reserved word can't break the query). No I/O.
+ * @module services/congress-mirror/normalize
+ */
+/**
+ * Strip HTML tags to plain text and decode the handful of entities Congress.gov
+ * emits in summary bodies. Block-ish tags collapse to spaces so adjacent words
+ * don't fuse (`</p><p>` → space), and whitespace is collapsed to single spaces —
+ * a discovery/snippet surface doesn't need paragraph structure, and flat text
+ * tokenizes more cleanly for FTS5.
+ */
+export declare function htmlToPlainText(html: string): string;
+/**
+ * Build an FTS5 `MATCH` expression from free-text input. Each token is stripped
+ * of embedded quotes and wrapped in double quotes, which neutralizes every FTS5
+ * operator (`-`, `*`, `:`, `NEAR`, `AND`, `OR`, `NOT`) so punctuation or a
+ * reserved word can't raise a SQLite syntax error. Tokens are AND-combined
+ * (implicit-AND across terms). Returns an empty string when the input has no
+ * searchable tokens — callers treat that as "no match", not a thrown query.
+ */
+export declare function toFtsMatch(input: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/services/congress-mirror/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/services/congress-mirror/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcpD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD"}

package/dist/services/congress-mirror/normalize.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Pure normalization helpers for the bill mirror — HTML→plain-text
+ * stripping (summaries ship as HTML; the FTS index and snippet surface want plain
+ * text) and FTS5 `MATCH` escaping (tokenize + individually quote so a stray `-`,
+ * an unbalanced quote, or an FTS5 reserved word can't break the query). No I/O.
+ * @module services/congress-mirror/normalize
+ */
+/**
+ * Strip HTML tags to plain text and decode the handful of entities Congress.gov
+ * emits in summary bodies. Block-ish tags collapse to spaces so adjacent words
+ * don't fuse (`</p><p>` → space), and whitespace is collapsed to single spaces —
+ * a discovery/snippet surface doesn't need paragraph structure, and flat text
+ * tokenizes more cleanly for FTS5.
+ */
+export function htmlToPlainText(html) {
+    return html
+        .replace(/<\s*br\s*\/?\s*>/gi, ' ')
+        .replace(/<\s*\/?(p|div|li|ul|ol|h[1-6]|tr|table)\b[^>]*>/gi, ' ')
+        .replace(/<[^>]*>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&#039;/g, "'")
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Build an FTS5 `MATCH` expression from free-text input. Each token is stripped
+ * of embedded quotes and wrapped in double quotes, which neutralizes every FTS5
+ * operator (`-`, `*`, `:`, `NEAR`, `AND`, `OR`, `NOT`) so punctuation or a
+ * reserved word can't raise a SQLite syntax error. Tokens are AND-combined
+ * (implicit-AND across terms). Returns an empty string when the input has no
+ * searchable tokens — callers treat that as "no match", not a thrown query.
+ */
+export function toFtsMatch(input) {
+    return input
+        .trim()
+        .split(/\s+/)
+        .map((t) => t.replace(/"/g, '').trim())
+        .filter((t) => t.length > 0)
+        .map((t) => `"${t}"`)
+        .join(' AND ');
+}
+//# sourceMappingURL=normalize.js.map

package/dist/services/congress-mirror/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/services/congress-mirror/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI;SACR,OAAO,CAAC,oBAAoB,EAAE,GAAG,CAAC;SAClC,OAAO,CAAC,mDAAmD,EAAE,GAAG,CAAC;SACjE,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,IAAI,EAAE;SACN,KAAK,CAAC,KAAK,CAAC;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SACtC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;SACpB,IAAI,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC"}

package/dist/services/congress-mirror/schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Mirror store schema for the Congress bill FTS index. A single
+ * MirrorService-owned table (`bills`) with an FTS5 index over `title` + `summary`
+ * and secondary indexes on the filterable columns. The primary key is the derived
+ * `billId` (`{congress}/{billType}/{billNumber}`) — a single column, matching the
+ * `congress://bill/{congress}/{billType}/{billNumber}` resource addressing.
+ * @module services/congress-mirror/schema
+ */
+import type { SqliteMirrorStoreSpec } from '@cyanheads/mcp-ts-core/mirror';
+/** Primary table name (the MirrorService-owned table). */
+export declare const BILLS_TABLE = "bills";
+/**
+ * The MirrorService primary-table spec. One row per bill, merged from the bill
+ * list (title, chamber, latest action, update date) and the CRS summaries list
+ * (summary text). `title` + `summary` are FTS-indexed; `congress`, `billType`,
+ * and `originChamber` back the exact-match search filters.
+ */
+export declare function billStoreSpec(path: string): SqliteMirrorStoreSpec;
+//# sourceMappingURL=schema.d.ts.map

package/dist/services/congress-mirror/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/services/congress-mirror/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3E,0DAA0D;AAC1D,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CA0BjE"}

package/dist/services/congress-mirror/schema.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Mirror store schema for the Congress bill FTS index. A single
+ * MirrorService-owned table (`bills`) with an FTS5 index over `title` + `summary`
+ * and secondary indexes on the filterable columns. The primary key is the derived
+ * `billId` (`{congress}/{billType}/{billNumber}`) — a single column, matching the
+ * `congress://bill/{congress}/{billType}/{billNumber}` resource addressing.
+ * @module services/congress-mirror/schema
+ */
+/** Primary table name (the MirrorService-owned table). */
+export const BILLS_TABLE = 'bills';
+/**
+ * The MirrorService primary-table spec. One row per bill, merged from the bill
+ * list (title, chamber, latest action, update date) and the CRS summaries list
+ * (summary text). `title` + `summary` are FTS-indexed; `congress`, `billType`,
+ * and `originChamber` back the exact-match search filters.
+ */
+export function billStoreSpec(path) {
+    return {
+        path,
+        table: BILLS_TABLE,
+        primaryKey: 'billId',
+        version: 1,
+        columns: {
+            billId: 'TEXT',
+            congress: 'INTEGER',
+            billType: 'TEXT',
+            billNumber: 'INTEGER',
+            title: 'TEXT',
+            summary: 'TEXT',
+            originChamber: 'TEXT',
+            latestActionDate: 'TEXT',
+            latestActionText: 'TEXT',
+            updateDate: 'TEXT',
+        },
+        fts: ['title', 'summary'],
+        indexes: [
+            { columns: ['congress'] },
+            { columns: ['billType'] },
+            { columns: ['originChamber'] },
+            { columns: ['updateDate'] },
+        ],
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/services/congress-mirror/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/services/congress-mirror/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,WAAW;QAClB,UAAU,EAAE,QAAQ;QACpB,OAAO,EAAE,CAAC;QACV,OAAO,EAAE;YACP,MAAM,EAAE,MAAM;YACd,QAAQ,EAAE,SAAS;YACnB,QAAQ,EAAE,MAAM;YAChB,UAAU,EAAE,SAAS;YACrB,KAAK,EAAE,MAAM;YACb,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,MAAM;YACrB,gBAAgB,EAAE,MAAM;YACxB,gBAAgB,EAAE,MAAM;YACxB,UAAU,EAAE,MAAM;SACnB;QACD,GAAG,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;QACzB,OAAO,EAAE;YACP,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE;YACzB,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE;YACzB,EAAE,OAAO,EAAE,CAAC,eAAe,CAAC,EAAE;YAC9B,EAAE,OAAO,EAAE,CAAC,YAAY,CAAC,EAAE;SAC5B;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Domain types for the Congress bill FTS mirror — the merged row
+ * shape, the search filters, and the search page envelope. The mirror row is the
+ * single-table projection of two upstream Congress.gov sources (the bill list and
+ * the CRS summaries list) keyed by a derived `billId`.
+ * @module services/congress-mirror/types
+ */
+import type { BillType } from '../../services/congress-api/types.js';
+/**
+ * One mirrored bill — a flat row keyed by the derived `billId`
+ * (`{congress}/{billType}/{billNumber}`). `title` comes from the bill list;
+ * `summary` from the CRS summaries list (HTML-stripped, latest version), nullable
+ * because CRS summarizes only a fraction of bills.
+ */
+export interface BillMirrorRow {
+    billId: string;
+    billNumber: number;
+    billType: string;
+    congress: number;
+    latestActionDate: string | null;
+    latestActionText: string | null;
+    originChamber: string | null;
+    summary: string | null;
+    title: string | null;
+    updateDate: string | null;
+}
+/** Filters accepted by the keyword search. */
+export interface SearchBillsFilters {
+    billType?: BillType | undefined;
+    congress?: number | undefined;
+    limit: number;
+    offset: number;
+    originChamber?: string | undefined;
+    query: string;
+}
+/** A single search result — a merged mirror row projected for display. */
+export interface SearchBillResult {
+    billId: string;
+    billNumber: number;
+    billType: string;
+    congress: number;
+    latestActionDate?: string;
+    latestActionText?: string;
+    originChamber?: string;
+    summaryPreview?: string;
+    title: string;
+}
+/** Search page returned by the mirror service. */
+export interface SearchBillsPage {
+    items: SearchBillResult[];
+    limit: number;
+    offset: number;
+    total: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/congress-mirror/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf"}

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Domain types for the Congress bill FTS mirror — the merged row
+ * shape, the search filters, and the search page envelope. The mirror row is the
+ * single-table projection of two upstream Congress.gov sources (the bill list and
+ * the CRS summaries list) keyed by a derived `billId`.
+ * @module services/congress-mirror/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.3.32",
+  "version": "0.4.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",
@@ -9,7 +9,19 @@
   "bin": {
     "congressgov-mcp-server": "dist/index.js"
   },
-  "files": ["dist/", "README.md", "LICENSE", "CLAUDE.md", "AGENTS.md", "Dockerfile", "server.json"],
+  "files": [
+    "dist/",
+    "scripts/_mirror-context.ts",
+    "scripts/congress-mirror-init.ts",
+    "scripts/congress-mirror-refresh.ts",
+    "scripts/congress-mirror-verify.ts",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "Dockerfile",
+    "server.json"
+  ],
   "scripts": {
     "build": "bun scripts/build.ts",
     "rebuild": "bun scripts/clean.ts && bun scripts/build.ts",
@@ -31,7 +43,10 @@
     "dev:stdio": "MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts",
     "dev:http": "MCP_TRANSPORT_TYPE=http bun --watch src/index.ts",
     "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
-    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js",
+    "mirror:init": "bun run scripts/congress-mirror-init.ts",
+    "mirror:refresh": "bun run scripts/congress-mirror-refresh.ts",
+    "mirror:verify": "bun run scripts/congress-mirror-verify.ts"
   },
   "keywords": [
     "mcp",
@@ -79,16 +94,27 @@
   "dependencies": {
     "@cyanheads/mcp-ts-core": "^0.10.10",
     "fast-xml-parser": "^5.9.3",
+    "node-cron": "^4.4.1",
     "pino-pretty": "^13.1.3",
     "zod": "^4.4.3"
   },
+  "peerDependencies": {
+    "better-sqlite3": "^12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.5.1",
     "@types/node": "^26.0.1",
+    "better-sqlite3": "^12.11.1",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",
     "tsc-alias": "^1.8.17",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
-  }
+  },
+  "trustedDependencies": ["better-sqlite3"]
 }

package/scripts/_mirror-context.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Shared bootstrap for the mirror lifecycle CLI scripts
+ * (congress-mirror-init / congress-mirror-refresh / congress-mirror-verify).
+ * Builds the Congress API client and the mirror service from the environment and
+ * hands back the underlying mirror — no MCP transport, no tool registration.
+ * Imported by the three named scripts, so it must travel with them in the npm
+ * tarball and the Docker image.
+ * @module scripts/_mirror-context
+ */
+
+import type { Mirror } from '@cyanheads/mcp-ts-core/mirror';
+import { getServerConfig } from '@/config/server-config.js';
+import { initCongressApi } from '@/services/congress-api/congress-api-service.js';
+import { initCongressMirror } from '@/services/congress-mirror/congress-mirror-service.js';
+
+/**
+ * Build the mirror from env config and return its instance. The CLI builds the
+ * mirror regardless of `CONGRESS_MIRROR_ENABLED` (that flag gates the tool and the
+ * in-process scheduler, not out-of-band index construction); the ingester pages
+ * the live Congress.gov API via `CongressApiService`, so init it here.
+ */
+export function getMirror(): Mirror {
+  const config = getServerConfig();
+  initCongressApi();
+  const service = initCongressMirror({
+    mirrorPath: config.mirrorPath,
+    congresses: config.congresses,
+  });
+  return service.mirrorInstance;
+}

package/scripts/congress-mirror-init.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview mirror:init — full out-of-band build of the Congress bill FTS
+ * mirror. Pages the bill list and CRS summaries for the configured congress
+ * window, merges them into one row per bill, and writes the SQLite index.
+ * Idempotent (the framework upserts by primary key) — safe to re-run after an
+ * interrupt. Run as a one-shot job or at Docker build, never on server startup.
+ * @module scripts/congress-mirror-init
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { getMirror } from './_mirror-context.js';
+
+const mirror = getMirror();
+logger.info('Starting Congress bill mirror init (full build)');
+
+const result = await mirror.runSync({ mode: 'init', signal: AbortSignal.timeout(3_600_000) });
+
+logger.info(
+  `Congress bill mirror init complete: ${result.recordsApplied} records applied across ${result.pagesFetched} pages (total ${result.total}).`,
+);
+await mirror.close();
+process.exit(0);

package/scripts/congress-mirror-refresh.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview mirror:refresh — incremental refresh of the Congress bill FTS
+ * mirror. Re-scans bills updated since the durable checkpoint and re-walks the
+ * CRS summaries, merging them into the existing index; the index stays
+ * transactionally queryable throughout. Run out-of-band for stdio deployments
+ * (the HTTP server schedules this on a cron when CONGRESS_MIRROR_REFRESH_CRON is
+ * set).
+ * @module scripts/congress-mirror-refresh
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { getMirror } from './_mirror-context.js';
+
+const mirror = getMirror();
+logger.info('Starting Congress bill mirror refresh');
+
+const result = await mirror.runSync({ mode: 'refresh', signal: AbortSignal.timeout(3_600_000) });
+
+logger.info(
+  `Congress bill mirror refresh complete: ${result.recordsApplied} records applied (total ${result.total}).`,
+);
+await mirror.close();
+process.exit(0);

package/scripts/congress-mirror-verify.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview mirror:verify — report the Congress bill mirror health: readiness,
+ * sync status, last completion, record count, and a SQLite integrity check. Exits
+ * non-zero when the mirror is not ready or integrity fails, so it can gate a
+ * deployment or a post-build smoke check.
+ * @module scripts/congress-mirror-verify
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { getMirror } from './_mirror-context.js';
+
+const mirror = getMirror();
+const status = await mirror.status();
+
+logger.info(
+  `Congress bill mirror status: ready=${status.ready}, status=${status.status}, total=${status.total ?? 0}, completedAt=${status.completedAt ?? 'never'}`,
+);
+if (status.error) logger.warning(`Last sync error: ${status.error}`);
+
+if (!status.ready) {
+  logger.error('Mirror is NOT ready — run mirror:init to build the index.');
+  await mirror.close();
+  process.exit(1);
+}
+
+const integrity = await mirror.store.integrityCheck();
+if (!integrity.ok) {
+  logger.error(`SQLite integrity check FAILED: ${integrity.results.join('; ')}`);
+  await mirror.close();
+  process.exit(1);
+}
+
+logger.info('Congress bill mirror integrity check passed.');
+await mirror.close();
+process.exit(0);

package/server.json

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