@cyanheads/congressgov-mcp-server 0.3.31 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.3.31",
+  "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",
@@ -77,18 +92,29 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.10.9",
+    "@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.0",
-    "@types/node": "^26.0.0",
+    "@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.31",
+  "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.31",
+      "version": "0.4.0",
       "packageArguments": [
         {
           "type": "positional",
@@ -33,7 +33,7 @@
       "environmentVariables": [
         {
           "name": "CONGRESS_API_KEY",
-          "description": "API key from api.data.gov \u2014 optional (falls back to DEMO_KEY: 30 req/hr). Own key: 1000 req/hr. Free signup at api.data.gov.",
+          "description": "API key from api.data.gov \u2014 optional (falls back to DEMO_KEY: 30 req/hr). Own key: 5000 req/hr. Free signup at api.data.gov.",
           "format": "string",
           "isRequired": false
         },
@@ -54,7 +54,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.3.31",
+      "version": "0.4.0",
       "packageArguments": [
         {
           "type": "positional",
@@ -68,7 +68,7 @@
       "environmentVariables": [
         {
           "name": "CONGRESS_API_KEY",
-          "description": "API key from api.data.gov \u2014 optional (falls back to DEMO_KEY: 30 req/hr). Own key: 1000 req/hr. Free signup at api.data.gov.",
+          "description": "API key from api.data.gov \u2014 optional (falls back to DEMO_KEY: 30 req/hr). Own key: 5000 req/hr. Free signup at api.data.gov.",
           "format": "string",
           "isRequired": false
         },