@cyanheads/secedgar-mcp-server 0.8.1 → 0.8.3

package/Dockerfile

@@ -75,6 +75,22 @@ RUN if [ "$OTEL_ENABLED" = "true" ]; then \
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
 
+# Copy the mirror lifecycle scripts. `bun run mirror:init` / `mirror:refresh` /
+# `mirror:verify` invoke these directly (Bun runs `.ts` natively) — they must
+# exist inside the container or an operator can't bootstrap, inspect, or refresh
+# the local mirror via `docker exec`.
+COPY --from=build /usr/src/app/scripts/edgar-mirror-init.ts \
+                  /usr/src/app/scripts/edgar-mirror-refresh.ts \
+                  /usr/src/app/scripts/edgar-mirror-verify.ts \
+                  /usr/src/app/scripts/_mirror-context.ts \
+                  ./scripts/
+
+# Emit a minimal `tsconfig.json` so Bun can resolve the `@/...` path alias the
+# mirror scripts import through. The source `tsconfig.json` maps `@/*` to `./src/*`,
+# but production only carries `./dist/*` — without this file, `bun run mirror:init`
+# fails with `Cannot find module '@/config/server-config.js'`.
+RUN echo '{"compilerOptions":{"baseUrl":".","paths":{"@/*":["./dist/*"]}}}' > tsconfig.json
+
 # The 'oven/bun' image already provides a non-root user named 'bun'.
 # We will use this existing user for enhanced security.
 

package/README.md

@@ -316,6 +316,14 @@ docker build -t secedgar-mcp-server .
 docker run -e EDGAR_USER_AGENT="MyApp my@email.com" -p 3010:3010 secedgar-mcp-server
 ```
 
+The image ships the mirror CLI, so the local mirror (`EDGAR_MIRROR_ENABLED`) can be bootstrapped, inspected, and refreshed inside a running container:
+
+```sh
+docker exec <container> bun run mirror:verify    # sync status + sample reads
+docker exec <container> bun run mirror:init      # one-time bootstrap (downloads the SEC bulk archive)
+docker exec <container> bun run mirror:refresh   # re-ingest when the archive has been rebuilt
+```
+
 ## Project structure
 
 | Directory | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/secedgar-mcp-server",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.",
   "mcpName": "io.github.cyanheads/secedgar-mcp-server",
   "type": "module",
@@ -12,7 +12,17 @@
   "exports": {
     ".": "./dist/index.js"
   },
-  "files": ["dist/", "README.md", "LICENSE", "Dockerfile", "server.json"],
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "Dockerfile",
+    "server.json",
+    "scripts/edgar-mirror-init.ts",
+    "scripts/edgar-mirror-refresh.ts",
+    "scripts/edgar-mirror-verify.ts",
+    "scripts/_mirror-context.ts"
+  ],
   "scripts": {
     "build": "bun scripts/build.ts",
     "rebuild": "bun scripts/clean.ts && bun scripts/build.ts",
@@ -82,12 +92,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.9.19",
+    "@cyanheads/mcp-ts-core": "^0.9.21",
     "@duckdb/node-api": "^1.5.3-r.3",
     "better-sqlite3": "^12.10.0",
     "domhandler": "^6.0.1",
     "domutils": "^4.0.2",
-    "fflate": "^0.8.2",
+    "fflate": "^0.8.3",
     "html-to-text": "^10.0.0",
     "htmlparser2": "^12.0.0",
     "node-cron": "^4.2.1",

package/scripts/_mirror-context.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Minimal logger + abort signal for the out-of-band mirror scripts.
+ * Scripts run outside the MCP request pipeline, so they have no `Context`; this
+ * wires console output and a SIGINT/SIGTERM-driven AbortController to the
+ * `MirrorLogger` shape the ingesters consume — an interrupt lets the framework
+ * persist sync state before exit, so a re-run resumes cleanly.
+ * @module scripts/_mirror-context
+ */
+
+type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error';
+
+function makeLogger(prefix: string) {
+  const emit = (level: LogLevel, message: string, meta?: object): void => {
+    const tag = `[${new Date().toISOString()}] ${level.toUpperCase()} ${prefix}`;
+    const metaStr = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+    const line = `${tag} ${message}${metaStr}`;
+    if (level === 'error') console.error(line);
+    else if (level === 'warning') console.warn(line);
+    else console.log(line);
+  };
+  return {
+    debug: (m: string, meta?: object) => emit('debug', m, meta),
+    info: (m: string, meta?: object) => emit('info', m, meta),
+    notice: (m: string, meta?: object) => emit('notice', m, meta),
+    warning: (m: string, meta?: object) => emit('warning', m, meta),
+    error: (m: string, meta?: object) => emit('error', m, meta),
+  };
+}
+
+/** Build a script context: a `MirrorLogger` plus a SIGINT/SIGTERM-aborted signal. */
+export function makeScriptContext(prefix: string): {
+  log: ReturnType<typeof makeLogger>;
+  signal: AbortSignal;
+} {
+  const controller = new AbortController();
+  const onSignal = (sig: string) => () => {
+    console.error(`\nReceived ${sig}; aborting mirror sync (state is persisted per page)...`);
+    controller.abort(new Error(`Aborted by ${sig}`));
+  };
+  process.once('SIGINT', onSignal('SIGINT'));
+  process.once('SIGTERM', onSignal('SIGTERM'));
+  return { log: makeLogger(prefix), signal: controller.signal };
+}

package/scripts/edgar-mirror-init.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview One-shot bootstrap of the EDGAR local mirror. Downloads
+ * `company_tickers.json` and the `companyfacts.zip` bulk archive into the local
+ * SQLite stores. Idempotent and resumable — the framework persists state per
+ * page, so re-running after an interrupt continues without re-applying lost work.
+ *
+ * Usage:
+ *   bun run mirror:init
+ *
+ * Env vars (see CLAUDE.md Config table):
+ *   EDGAR_USER_AGENT   required — "AppName contact@email.com"
+ *   EDGAR_MIRROR_PATH  mirror directory (default ./data/edgar-mirror)
+ *
+ * @module scripts/edgar-mirror-init
+ */
+
+import { getServerConfig } from '@/config/server-config.js';
+import { EdgarMirror } from '@/services/edgar/mirror/index.js';
+import { makeScriptContext } from './_mirror-context.js';
+
+async function main(): Promise<void> {
+  const cfg = getServerConfig();
+  const ctx = makeScriptContext('mirror:init');
+  const mirror = new EdgarMirror({ dir: cfg.mirrorPath, userAgent: cfg.userAgent, log: ctx.log });
+
+  const start = Date.now();
+  let lastReport = start;
+  ctx.log.notice('Starting EDGAR mirror init (tickers + company-facts)', { dir: cfg.mirrorPath });
+
+  try {
+    const result = await mirror.runInit({
+      signal: ctx.signal,
+      onProgress: (layer, info) => {
+        const now = Date.now();
+        if (now - lastReport < 10_000) return;
+        lastReport = now;
+        const elapsedMin = ((now - start) / 60_000).toFixed(1);
+        console.log(
+          `  [${layer}] pages=${info.pages} records=${info.records} elapsed=${elapsedMin}m`,
+        );
+      },
+    });
+    const elapsedMin = ((Date.now() - start) / 60_000).toFixed(1);
+    console.log(
+      `\nInit complete in ${elapsedMin}m — tickers: ${result.tickers.total} rows, company-facts: ${result.companyFacts.total} rows`,
+    );
+    await mirror.close();
+  } catch (err) {
+    console.error('\nInit failed:', err instanceof Error ? err.message : err);
+    await mirror.close().catch(() => {});
+    process.exit(1);
+  }
+}
+
+void main();

package/scripts/edgar-mirror-refresh.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Incremental refresh of the EDGAR local mirror. Re-downloads
+ * `company_tickers.json` and re-ingests `companyfacts.zip` when the bulk archive
+ * has been rebuilt since the last sync (a HEAD check short-circuits otherwise).
+ * Intended for an external cron under stdio deployments; HTTP deployments can
+ * schedule this in-process via `EDGAR_MIRROR_REFRESH_CRON`.
+ *
+ * Usage:
+ *   bun run mirror:refresh
+ *
+ * @module scripts/edgar-mirror-refresh
+ */
+
+import { getServerConfig } from '@/config/server-config.js';
+import { EdgarMirror } from '@/services/edgar/mirror/index.js';
+import { makeScriptContext } from './_mirror-context.js';
+
+async function main(): Promise<void> {
+  const cfg = getServerConfig();
+  const ctx = makeScriptContext('mirror:refresh');
+  const mirror = new EdgarMirror({ dir: cfg.mirrorPath, userAgent: cfg.userAgent, log: ctx.log });
+
+  const start = Date.now();
+  ctx.log.notice('Starting EDGAR mirror refresh', { dir: cfg.mirrorPath });
+
+  try {
+    const result = await mirror.runRefresh({ signal: ctx.signal });
+    const elapsedMin = ((Date.now() - start) / 60_000).toFixed(1);
+    console.log(
+      `\nRefresh complete in ${elapsedMin}m — tickers: +${result.tickers.recordsApplied}, company-facts: +${result.companyFacts.recordsApplied}`,
+    );
+    await mirror.close();
+  } catch (err) {
+    console.error('\nRefresh failed:', err instanceof Error ? err.message : err);
+    await mirror.close().catch(() => {});
+    process.exit(1);
+  }
+}
+
+void main();

package/scripts/edgar-mirror-verify.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Operability check for the EDGAR local mirror. Prints the sync
+ * status of both layers and runs a couple of sample reads so an operator can
+ * confirm the mirror is populated and queryable after an init or refresh.
+ *
+ * Usage:
+ *   bun run mirror:verify
+ *
+ * @module scripts/edgar-mirror-verify
+ */
+
+import { getServerConfig } from '@/config/server-config.js';
+import { EdgarMirror } from '@/services/edgar/mirror/index.js';
+
+async function main(): Promise<void> {
+  const cfg = getServerConfig();
+  const mirror = new EdgarMirror({ dir: cfg.mirrorPath, userAgent: cfg.userAgent });
+
+  try {
+    const status = await mirror.status();
+    console.log(`Mirror directory: ${cfg.mirrorPath}`);
+    console.log(JSON.stringify(status, null, 2));
+
+    if (await mirror.tickersReady()) {
+      const rows = await mirror.getTickerRows();
+      console.log(`tickers: ${rows.length} rows`);
+    } else {
+      console.log('tickers: not ready (run `bun run mirror:init`)');
+    }
+
+    if (await mirror.companyFactsReady()) {
+      // Apple Inc. (CIK 0000320193) — a stable probe for the company-facts layer.
+      const concept = await mirror.getCompanyConcept('320193', 'us-gaap', 'Revenues');
+      console.log(
+        `company-facts probe (AAPL us-gaap/Revenues): ${
+          concept ? `${Object.keys(concept.units).length} unit(s)` : 'absent'
+        }`,
+      );
+    } else {
+      console.log('company-facts: not ready (run `bun run mirror:init`)');
+    }
+
+    await mirror.close();
+  } catch (err) {
+    console.error('Verify failed:', err instanceof Error ? err.message : err);
+    await mirror.close().catch(() => {});
+    process.exit(1);
+  }
+}
+
+void main();

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/secedgar-mcp-server",
     "source": "github"
   },
-  "version": "0.8.1",
+  "version": "0.8.3",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/secedgar-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.8.1",
+      "version": "0.8.3",
       "environmentVariables": [
         {
           "name": "EDGAR_USER_AGENT",
@@ -44,7 +44,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/secedgar-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.8.1",
+      "version": "0.8.3",
       "environmentVariables": [
         {
           "name": "EDGAR_USER_AGENT",