@cyanheads/federal-regulations-mcp-server 0.1.0

package/scripts/_mirror-context.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Shared bootstrap for the eCFR mirror lifecycle scripts
+ * (mirror:init / mirror:refresh / mirror:verify). These run out-of-band (CLI /
+ * cron), not inside the MCP request pipeline, so they wire up the minimum the
+ * mirror's `sync` ingester needs: the eCFR service (which the ingester calls)
+ * and an abort signal. The framework logger is already a global singleton.
+ *
+ * Imported by the three named lifecycle scripts; travels with them into the npm
+ * tarball and the Docker runtime stage (see Dockerfile + package.json files[]).
+ *
+ * @module scripts/_mirror-context
+ */
+
+import { config } from '@cyanheads/mcp-ts-core/config';
+import { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { IStorageProvider, ListResult } from '@cyanheads/mcp-ts-core/storage/types';
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { initEcfrService } from '@/services/ecfr/ecfr-service.js';
+
+/**
+ * A minimal Map-backed in-memory storage provider. The mirror owns its own
+ * SQLite store and the eCFR service does not use `ctx.state`, so this exists only
+ * to satisfy the `initEcfrService(config, storage)` convention; it is never read.
+ */
+class InMemoryProvider implements IStorageProvider {
+  private readonly store = new Map<string, unknown>();
+
+  private k(tenantId: string, key: string): string {
+    return `${tenantId}:${key}`;
+  }
+
+  async clear(tenantId: string): Promise<number> {
+    let n = 0;
+    for (const key of this.store.keys()) {
+      if (key.startsWith(`${tenantId}:`)) {
+        this.store.delete(key);
+        n++;
+      }
+    }
+    return n;
+  }
+
+  async delete(tenantId: string, key: string): Promise<boolean> {
+    return this.store.delete(this.k(tenantId, key));
+  }
+
+  async deleteMany(tenantId: string, keys: string[]): Promise<number> {
+    let n = 0;
+    for (const key of keys) if (this.store.delete(this.k(tenantId, key))) n++;
+    return n;
+  }
+
+  async get<T>(tenantId: string, key: string): Promise<T | null> {
+    return (this.store.get(this.k(tenantId, key)) as T) ?? null;
+  }
+
+  async getMany<T>(tenantId: string, keys: string[]): Promise<Map<string, T>> {
+    const out = new Map<string, T>();
+    for (const key of keys) {
+      const v = this.store.get(this.k(tenantId, key));
+      if (v !== undefined) out.set(key, v as T);
+    }
+    return out;
+  }
+
+  async list(tenantId: string, prefix: string): Promise<ListResult> {
+    const full = `${tenantId}:${prefix}`;
+    const keys = [...this.store.keys()]
+      .filter((k) => k.startsWith(full))
+      .map((k) => k.slice(tenantId.length + 1));
+    return { keys };
+  }
+
+  async set(tenantId: string, key: string, value: unknown): Promise<void> {
+    this.store.set(this.k(tenantId, key), value);
+  }
+
+  async setMany(tenantId: string, entries: Map<string, unknown>): Promise<void> {
+    for (const [key, value] of entries) this.store.set(this.k(tenantId, key), value);
+  }
+}
+
+/**
+ * Initialize the services the mirror sync depends on. The mirror reads
+ * `getEcfrService()` from inside its `sync` generator, so it must be constructed
+ * before any `runSync` call.
+ */
+export async function bootstrapMirrorServices(): Promise<void> {
+  await logger.initialize('info');
+  const storage = new StorageService(new InMemoryProvider());
+  initEcfrService(config, storage);
+}
+
+/** An abort signal that fires on SIGINT/SIGTERM so a long init stops cleanly. */
+export function signalFromProcess(): AbortSignal {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  return controller.signal;
+}

package/scripts/ecfr-mirror-init.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview `mirror:init` — full out-of-band ingest of the codified CFR into
+ * the local SQLite + FTS5 mirror. Idempotent and resumable: re-running after an
+ * interrupt continues from the persisted cursor/checkpoint. A full sweep of all
+ * ~50 titles can take a long time and must never run on server startup.
+ *
+ * @module scripts/ecfr-mirror-init
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { ecfrMirror } from '@/services/ecfr-mirror/ecfr-mirror.js';
+import { bootstrapMirrorServices, signalFromProcess } from './_mirror-context.js';
+
+await bootstrapMirrorServices();
+
+logger.info('eCFR mirror init: starting full sync');
+const result = await ecfrMirror.runSync({
+  mode: 'init',
+  signal: signalFromProcess(),
+  onProgress: (info) => {
+    logger.info('eCFR mirror init progress', {
+      pages: info.pages,
+      records: info.records,
+      checkpoint: info.checkpoint,
+    });
+  },
+});
+
+logger.info('eCFR mirror init: complete', {
+  pagesFetched: result.pagesFetched,
+  recordsApplied: result.recordsApplied,
+  total: result.total,
+});
+
+await ecfrMirror.close();

package/scripts/ecfr-mirror-refresh.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview `mirror:refresh` — incremental refresh of the codified CFR mirror
+ * from the persisted high-water checkpoint. Re-walks the titles and upserts
+ * current text; the dataset stays queryable throughout. Wired on a weekly cron in
+ * the server's `setup()`, and runnable on demand here.
+ *
+ * @module scripts/ecfr-mirror-refresh
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { ecfrMirror } from '@/services/ecfr-mirror/ecfr-mirror.js';
+import { bootstrapMirrorServices, signalFromProcess } from './_mirror-context.js';
+
+await bootstrapMirrorServices();
+
+logger.info('eCFR mirror refresh: starting');
+const result = await ecfrMirror.runSync({
+  mode: 'refresh',
+  signal: signalFromProcess(),
+});
+
+logger.info('eCFR mirror refresh: complete', {
+  pagesFetched: result.pagesFetched,
+  recordsApplied: result.recordsApplied,
+  total: result.total,
+});
+
+await ecfrMirror.close();

package/scripts/ecfr-mirror-verify.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+/**
+ * @fileoverview `mirror:verify` — read-only health check of the codified CFR
+ * mirror: prints sync status (ready marker, checkpoint, record count) and runs a
+ * sample FTS query so an operator can confirm the index is queryable.
+ *
+ * @module scripts/ecfr-mirror-verify
+ */
+
+import { logger } from '@cyanheads/mcp-ts-core/utils';
+import { ecfrMirror, mirrorSearch } from '@/services/ecfr-mirror/ecfr-mirror.js';
+import { bootstrapMirrorServices } from './_mirror-context.js';
+
+await bootstrapMirrorServices();
+
+const status = await ecfrMirror.status();
+logger.info('eCFR mirror status', {
+  ready: status.ready,
+  status: status.status,
+  total: status.total,
+  checkpoint: status.checkpoint,
+  completedAt: status.completedAt,
+});
+
+if (status.ready) {
+  const sample = await mirrorSearch('definitions', undefined, 3);
+  logger.info('eCFR mirror sample query "definitions"', {
+    totalCount: sample.totalCount,
+    firstHit: sample.results[0]?.cfrCite ?? '(none)',
+  });
+}
+
+await ecfrMirror.close();

package/server.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.cyanheads/federal-regulations-mcp-server",
+  "description": "Search and trace US federal rules across the Federal Register, eCFR, and Regulations.gov.",
+  "repository": {
+    "url": "https://github.com/cyanheads/federal-regulations-mcp-server",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/federal-regulations-mcp-server",
+      "runtimeHint": "node",
+      "version": "0.1.0",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "run"
+        },
+        {
+          "type": "positional",
+          "value": "start:stdio"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "REGULATIONS_GOV_API_KEY",
+          "description": "api.data.gov key for the Regulations.gov tools (get_docket, find_comments). Free at https://api.data.gov/signup/. The Federal Register and eCFR tools work without it.",
+          "format": "string",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/federal-regulations-mcp-server",
+      "runtimeHint": "node",
+      "version": "0.1.0",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "run"
+        },
+        {
+          "type": "positional",
+          "value": "start:http"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "MCP_HTTP_HOST",
+          "description": "The hostname for the HTTP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "127.0.0.1"
+        },
+        {
+          "name": "MCP_HTTP_PORT",
+          "description": "The port to run the HTTP server on.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3010"
+        },
+        {
+          "name": "MCP_HTTP_ENDPOINT_PATH",
+          "description": "The endpoint path for the MCP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "/mcp"
+        },
+        {
+          "name": "MCP_AUTH_MODE",
+          "description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",
+          "format": "string",
+          "isRequired": false,
+          "default": "none"
+        },
+        {
+          "name": "REGULATIONS_GOV_API_KEY",
+          "description": "api.data.gov key for the Regulations.gov tools (get_docket, find_comments). Free at https://api.data.gov/signup/. The Federal Register and eCFR tools work without it.",
+          "format": "string",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "streamable-http",
+        "url": "http://localhost:3010/mcp"
+      }
+    }
+  ]
+}