simple-dynamsoft-mcp 7.2.4 → 7.2.6

package/data/metadata/data-manifest.json

@@ -88,8 +88,8 @@
       "branch": "master",
       "owner": "dynamsoft-docs",
       "repo": "web-twain-docs",
-      "commit": "a38d73c583b8379c0d80337e92f291f6c1ab10a8",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/a38d73c583b8379c0d80337e92f291f6c1ab10a8"
+      "commit": "7b8e127b298a2ef9abb7cd870bb742b44a132503",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/7b8e127b298a2ef9abb7cd870bb742b44a132503"
     },
     {
       "name": "data/samples/dynamic-web-twain",
@@ -108,8 +108,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-javascript-samples",
-      "commit": "2f0a723e88e3271170672e61c214a3d1d7a31328",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-javascript-samples/zip/2f0a723e88e3271170672e61c214a3d1d7a31328"
+      "commit": "deb6320704e324073cd0cb5d6edb8064ce130726",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-javascript-samples/zip/deb6320704e324073cd0cb5d6edb8064ce130726"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-c-cpp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.2.4",
+  "version": "7.2.6",
   "description": "MCP server for Dynamsoft SDKs - Capture Vision, Barcode Reader (Mobile/Python/Web), Dynamic Web TWAIN, and Document Viewer. Provides documentation, code snippets, and API guidance.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "npm run test:lite",
-    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/rag-signature-manifest.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js",
+    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",

package/src/index.js

@@ -2,6 +2,7 @@
 import { readFileSync } from "node:fs";
 import { ensureDataReady } from "./data/bootstrap.js";
 import { maybeSyncSubmodulesOnStart } from "./data/submodule-sync.js";
+import { createStartupTimingTracker } from "./observability/startup-timing.js";
 import { createMcpServerInstance } from "./server/create-server.js";
 import { MCP_HTTP_PATH, resolveRuntimeConfig } from "./server/runtime-config.js";
 import { startStdioServer } from "./server/transports/stdio.js";
@@ -10,48 +11,132 @@ import { logEvent } from "./observability/logging.js";
 
 const pkgUrl = new URL("../package.json", import.meta.url);
 const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+const startupTiming = createStartupTimingTracker();
 
-await maybeSyncSubmodulesOnStart();
-const dataStatus = await ensureDataReady();
-logEvent("data", "startup_mode", {
-  mode: dataStatus.mode,
-  path: dataStatus.dataRoot,
-  cache_source: dataStatus.mode.includes("downloaded") ? (dataStatus.downloaded ? "fresh-download" : "cache") : "n/a"
+let runtimeConfig;
+try {
+  runtimeConfig = resolveRuntimeConfig();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  logEvent("transport", "config_error", { message }, { level: "error" });
+  process.exit(1);
+}
+
+startupTiming.mark("runtime_config_resolved", {
+  transport: runtimeConfig.transport
 });
 
-const resourceIndexApi = await import("./server/resource-index.js");
-const ragApi = await import("./rag/index.js");
+let resourceIndexApi = null;
+let ragApi = null;
 
-logEvent("profile", "resolved", {
-  profile: ragApi.ragConfig.profile,
-  provider: ragApi.ragConfig.provider,
-  provider_source: ragApi.ragConfig.providerSource,
-  fallback: ragApi.ragConfig.fallback,
-  fallback_source: ragApi.ragConfig.fallbackSource
-});
+const startupState = {
+  ready: false,
+  stage: "initializing"
+};
 
-const createServer = () => createMcpServerInstance({
-  pkgVersion: pkg.version,
-  resourceIndexApi,
-  ragApi
-});
+function startupCacheSource(dataStatus) {
+  if (!dataStatus.mode.includes("downloaded")) return "n/a";
+  return dataStatus.downloaded ? "fresh-download" : "cache";
+}
+
+function createServer() {
+  if (!resourceIndexApi || !ragApi) {
+    throw new Error("MCP server is still initializing");
+  }
+
+  return createMcpServerInstance({
+    pkgVersion: pkg.version,
+    resourceIndexApi,
+    ragApi
+  });
+}
+
+function logResolvedProfile() {
+  logEvent("profile", "resolved", {
+    profile: ragApi.ragConfig.profile,
+    provider: ragApi.ragConfig.provider,
+    provider_source: ragApi.ragConfig.providerSource,
+    fallback: ragApi.ragConfig.fallback,
+    fallback_source: ragApi.ragConfig.fallbackSource
+  });
+}
 
 async function maybePrewarm() {
-  if (!ragApi.ragConfig.prewarm) return;
+  if (!ragApi?.ragConfig?.prewarm) return;
+
+  startupTiming.mark("prewarm_triggered", {
+    provider: ragApi.ragConfig.provider,
+    block: ragApi.ragConfig.prewarmBlock ? "true" : "false"
+  });
+
   if (ragApi.ragConfig.prewarmBlock) {
     await ragApi.prewarmRagIndex();
-  } else {
-    void ragApi.prewarmRagIndex();
+    startupTiming.mark("prewarm_done", {
+      provider: ragApi.ragConfig.provider
+    });
+    return;
   }
+
+  void ragApi.prewarmRagIndex().then(
+    () => {
+      startupTiming.mark("prewarm_done", {
+        provider: ragApi.ragConfig.provider
+      });
+    },
+    () => {
+      // prewarmRagIndex already logs failure details.
+    }
+  );
 }
 
-let runtimeConfig;
-try {
-  runtimeConfig = resolveRuntimeConfig();
-} catch (error) {
+async function initializeRuntime() {
+  startupState.stage = "submodule_sync";
+  await maybeSyncSubmodulesOnStart();
+  startupTiming.mark("submodule_sync_done");
+
+  startupState.stage = "data_resolve";
+  const dataStatus = await ensureDataReady();
+  logEvent("data", "startup_mode", {
+    mode: dataStatus.mode,
+    path: dataStatus.dataRoot,
+    cache_source: startupCacheSource(dataStatus)
+  });
+  startupTiming.mark("data_ready", {
+    mode: dataStatus.mode,
+    cache_source: startupCacheSource(dataStatus)
+  });
+
+  startupState.stage = "resource_index_import";
+  resourceIndexApi = await import("./server/resource-index.js");
+  startupTiming.mark("resource_index_module_loaded");
+
+  startupState.stage = "resource_index_build";
+  const indexReady = resourceIndexApi.ensureResourceIndexReady();
+  startupTiming.mark("resource_index_ready", {
+    resource_count: indexReady.resourceCount
+  });
+
+  startupState.stage = "rag_import";
+  ragApi = await import("./rag/index.js");
+  startupTiming.mark("rag_module_loaded", {
+    provider: ragApi.ragConfig.provider,
+    fallback: ragApi.ragConfig.fallback
+  });
+
+  logResolvedProfile();
+
+  startupState.ready = true;
+  startupState.stage = "mcp_ready";
+  startupTiming.mark("mcp_ready");
+
+  return dataStatus;
+}
+
+function logStartupFailure(error) {
   const message = error instanceof Error ? error.message : String(error);
-  logEvent("transport", "config_error", { message }, { level: "error" });
-  process.exit(1);
+  startupState.stage = "startup_failed";
+  startupState.ready = false;
+  logEvent("startup", "failed", { message }, { level: "error" });
 }
 
 if (runtimeConfig.transport === "http") {
@@ -59,10 +144,38 @@ if (runtimeConfig.transport === "http") {
     host: runtimeConfig.host,
     port: runtimeConfig.port,
     mcpPath: MCP_HTTP_PATH,
-    createServer
+    createServer,
+    isReady: () => startupState.ready,
+    getReadinessState: () => ({ stage: startupState.stage })
   });
+  startupTiming.mark("http_listener_ready", {
+    host: runtimeConfig.host,
+    port: runtimeConfig.port
+  });
+
+  try {
+    const dataStatus = await initializeRuntime();
+    await maybePrewarm();
+    startupTiming.complete({
+      transport: "http",
+      data_mode: dataStatus.mode
+    });
+  } catch (error) {
+    logStartupFailure(error);
+    process.exit(1);
+  }
 } else {
-  await startStdioServer({ createServer });
+  try {
+    const dataStatus = await initializeRuntime();
+    await startStdioServer({ createServer });
+    startupTiming.mark("stdio_listener_ready");
+    await maybePrewarm();
+    startupTiming.complete({
+      transport: "stdio",
+      data_mode: dataStatus.mode
+    });
+  } catch (error) {
+    logStartupFailure(error);
+    process.exit(1);
+  }
 }
-
-await maybePrewarm();

package/src/observability/startup-timing.js

@@ -0,0 +1,41 @@
+import { logEvent } from "./logging.js";
+
+function createStartupTimingTracker({ now = Date.now, emit } = {}) {
+  const emitEvent =
+    typeof emit === "function"
+      ? emit
+      : (component, event, payload) => {
+          logEvent(component, event, payload);
+        };
+
+  const startedAt = now();
+  let previousAt = startedAt;
+
+  function mark(stage, fields = {}) {
+    const currentAt = now();
+    emitEvent("startup", "stage", {
+      stage,
+      elapsed_ms: currentAt - previousAt,
+      since_boot_ms: currentAt - startedAt,
+      ...fields
+    });
+    previousAt = currentAt;
+  }
+
+  function complete(fields = {}) {
+    const currentAt = now();
+    emitEvent("startup", "complete", {
+      total_ms: currentAt - startedAt,
+      ...fields
+    });
+  }
+
+  return {
+    mark,
+    complete
+  };
+}
+
+export {
+  createStartupTimingTracker
+};

package/src/server/resource-index/builders.js

@@ -2,12 +2,24 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { DDV_PREFERRED_ENTRY_FILES } from "./config.js";
 
-function mapDocTitlesWithOptionalPlatform(articles, includePlatform = false) {
-  return articles.map((article) => ({
-    title: article.title,
-    category: article.breadcrumb || "",
-    ...(includePlatform && article.platform ? { platform: article.platform } : {})
-  }));
+function countSamples(sampleData) {
+  if (Array.isArray(sampleData)) {
+    return sampleData.length;
+  }
+
+  if (sampleData && typeof sampleData === "object") {
+    return Object.values(sampleData).reduce((total, value) => {
+      return total + countSamples(value);
+    }, 0);
+  }
+
+  return 0;
+}
+
+function countDiscoveredSamplesByPlatforms(platforms, discoverSamplesForPlatform) {
+  return platforms.reduce((total, platform) => {
+    return total + countSamples(discoverSamplesForPlatform(platform));
+  }, 0);
 }
 
 function getDcvScenarioTags(sampleName) {
@@ -35,20 +47,20 @@ function buildProductSelectionGuidanceText() {
   return [
     "# Product Selection Guidance",
     "",
-    "## DBR vs DCV",
+    "## Dynamsoft Barcode Reader (DBR) vs Dynamsoft Capture Vision (DCV)",
     "",
-    "Dynamsoft Capture Vision (DCV) is a superset architecture that aggregates DBR, DLR, DDN, DCP, and DCE.",
+    "Dynamsoft Capture Vision (DCV) is a superset architecture that aggregates Dynamsoft Barcode Reader (DBR), Dynamsoft Label Recognizer (DLR), Dynamsoft Document Normalizer (DDN), Dynamsoft Code Parser (DCP), and Dynamsoft Camera Enhancer (DCE).",
     "",
-    "Use DBR when you only need barcode reading and do not need DCV workflows.",
+    "Use Dynamsoft Barcode Reader (DBR) when you only need barcode reading and do not need Dynamsoft Capture Vision (DCV) workflows.",
     "",
-    "Use DCV when your scenario includes:",
+    "Use Dynamsoft Capture Vision (DCV) when your scenario includes:",
     "- VIN scanning",
     "- MRZ/passport/ID scanning",
     "- Driver license parsing",
     "- Document detection/normalization/auto-capture/cropping",
     "- Multi-task image processing and parsing workflows",
     "",
-    "If a query includes MRZ, VIN, driver license, or document-normalization intents, prefer DCV samples/docs."
+    "If a query includes MRZ, VIN, driver license, or document-normalization intents, prefer Dynamsoft Capture Vision (DCV) samples and docs."
   ].join("\n");
 }
 
@@ -146,16 +158,17 @@ function buildIndexData({
   const dcvWebFrameworks = getDcvWebFrameworkPlatforms();
   const dcvMobilePlatforms = getDcvMobilePlatforms();
   const dcvServerPlatforms = getDcvServerPlatforms();
-  const dbrWebSamples = discoverWebSamples();
+  const dbrWebSampleCount = countSamples(discoverWebSamples());
   const dbrWebFrameworks = getDbrWebFrameworkPlatforms();
   const dbrMobilePlatforms = getDbrMobilePlatforms();
   const dbrServerPlatforms = getDbrServerPlatforms();
+  const dwtSampleCount = countSamples(discoverDwtSamples());
   const ddvSamples = discoverDdvSamples();
   const ddvWebFrameworks = getDdvWebFrameworkPlatforms();
 
   return {
     productSelection: {
-      dcvSupersetSummary: "DCV aggregates DBR, DLR, DDN, DCP, and DCE into one pipeline.",
+      dcvSupersetSummary: "Dynamsoft Capture Vision (DCV) aggregates Dynamsoft Barcode Reader (DBR), Dynamsoft Label Recognizer (DLR), Dynamsoft Document Normalizer (DDN), Dynamsoft Code Parser (DCP), and Dynamsoft Camera Enhancer (DCE) into one pipeline.",
       useDbrWhen: [
         "Barcode-only workflows where DCV-specific workflows are not required."
       ],
@@ -175,32 +188,25 @@ function buildIndexData({
             version: dcvCoreVersion,
             platforms: ["core"],
             docCount: dcvCoreDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dcvCoreDocs)
+            sampleCount: 0
           },
           web: {
             version: dcvWebVersion,
             platforms: ["js", ...dcvWebFrameworks],
-            samples: dcvWebSamples,
             docCount: dcvWebDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dcvWebDocs)
+            sampleCount: countSamples(dcvWebSamples)
           },
           mobile: {
             version: dcvMobileVersion,
             platforms: dcvMobilePlatforms,
-            samples: Object.fromEntries(
-              dcvMobilePlatforms.map((platform) => [platform, discoverDcvMobileSamples(platform)])
-            ),
             docCount: dcvMobileDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dcvMobileDocs, true)
+            sampleCount: countDiscoveredSamplesByPlatforms(dcvMobilePlatforms, discoverDcvMobileSamples)
           },
           server: {
             version: dcvServerVersion,
             platforms: dcvServerPlatforms,
-            samples: Object.fromEntries(
-              dcvServerPlatforms.map((platform) => [platform, discoverDcvServerSamples(platform)])
-            ),
             docCount: dcvServerDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dcvServerDocs, true)
+            sampleCount: countDiscoveredSamplesByPlatforms(dcvServerPlatforms, discoverDcvServerSamples)
           }
         }
       },
@@ -210,27 +216,20 @@ function buildIndexData({
           mobile: {
             version: dbrMobileVersion,
             platforms: dbrMobilePlatforms,
-            samples: Object.fromEntries(
-              dbrMobilePlatforms.map((platform) => [platform, discoverMobileSamples(platform)])
-            ),
             docCount: dbrMobileDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dbrMobileDocs, true)
+            sampleCount: countDiscoveredSamplesByPlatforms(dbrMobilePlatforms, discoverMobileSamples)
           },
           web: {
             version: dbrWebVersion,
             platforms: ["js", ...dbrWebFrameworks],
-            samples: dbrWebSamples,
             docCount: dbrWebDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dbrWebDocs)
+            sampleCount: dbrWebSampleCount
           },
           server: {
             version: dbrServerVersion,
             platforms: dbrServerPlatforms,
-            samples: Object.fromEntries(
-              dbrServerPlatforms.map((platform) => [platform, discoverDbrServerSamples(platform)])
-            ),
             docCount: dbrServerDocs.length,
-            docTitles: mapDocTitlesWithOptionalPlatform(dbrServerDocs, true)
+            sampleCount: countDiscoveredSamplesByPlatforms(dbrServerPlatforms, discoverDbrServerSamples)
           }
         }
       },
@@ -240,12 +239,8 @@ function buildIndexData({
           web: {
             version: dwtVersion,
             platforms: ["js"],
-            sampleCategories: discoverDwtSamples(),
             docCount: dwtDocs.articles.length,
-            docTitles: dwtDocs.articles.map((article) => ({
-              title: article.title,
-              category: article.breadcrumb || ""
-            }))
+            sampleCount: dwtSampleCount
           }
         }
       },
@@ -255,12 +250,8 @@ function buildIndexData({
           web: {
             version: ddvVersion,
             platforms: ["js", ...ddvWebFrameworks],
-            samples: ddvSamples,
             docCount: ddvDocs.articles.length,
-            docTitles: ddvDocs.articles.map((article) => ({
-              title: article.title,
-              category: article.breadcrumb || ""
-            }))
+            sampleCount: countSamples(ddvSamples)
           }
         }
       }

package/src/server/resource-index.js

@@ -280,6 +280,7 @@ function buildVersionPolicyText() {
 
 const resourceIndex = [];
 const resourceIndexByUri = new Map();
+let resourceIndexReady = false;
 
 function addResourceToIndex(entry) {
   resourceIndex.push(entry);
@@ -368,10 +369,16 @@ function refreshResourceIndex() {
   for (const entry of resourceIndex) {
     resourceIndexByUri.set(entry.uri, entry);
   }
+  resourceIndexReady = true;
   return { resourceCount: resourceIndex.length };
 }
 
-refreshResourceIndex();
+function ensureResourceIndexReady() {
+  if (!resourceIndexReady) {
+    return refreshResourceIndex();
+  }
+  return { resourceCount: resourceIndex.length };
+}
 
 function editionMatches(normalizedEdition, entryEdition) {
   if (!normalizedEdition) return true;
@@ -397,6 +404,8 @@ function platformMatches(normalizedPlatform, entry) {
 }
 
 function getSampleEntries({ product, edition, platform }) {
+  ensureResourceIndexReady();
+
   const normalizedProduct = normalizeProduct(product);
   const normalizedPlatform = normalizePlatform(platform);
   const normalizedEdition = normalizeEdition(edition, normalizedPlatform, normalizedProduct);
@@ -425,6 +434,7 @@ function formatScopeLabel(entry) {
 }
 
 function getPinnedResources() {
+  ensureResourceIndexReady();
   return resourceIndex.filter((entry) => entry.pinned);
 }
 
@@ -464,6 +474,8 @@ function buildResourceLookupCandidates(uri) {
 }
 
 async function readResourceContent(uri) {
+  ensureResourceIndexReady();
+
   let resource = null;
   for (const candidate of buildResourceLookupCandidates(uri)) {
     resource = resourceIndexByUri.get(candidate);
@@ -481,6 +493,8 @@ async function readResourceContent(uri) {
 }
 
 function getRagSignatureData() {
+  ensureResourceIndexReady();
+
   return {
     resourceCount: resourceIndex.length,
     dcvCoreDocCount: dcvCoreDocs.length,
@@ -585,6 +599,7 @@ export {
   buildIndexData,
   buildResourceIndex,
   refreshResourceIndex,
+  ensureResourceIndexReady,
   editionMatches,
   platformMatches,
   getDisplayEdition,

package/src/server/transports/http.js

@@ -2,7 +2,15 @@ import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { logEvent } from "../../observability/logging.js";
 
-async function startHttpServer({ host, port, mcpPath, createServer }) {
+async function startHttpServer({
+  host,
+  port,
+  mcpPath,
+  createServer,
+  isReady = () => true,
+  getReadinessState = () => ({}),
+  registerSignalHandlers = true
+}) {
   logEvent("transport", "server_start", { mode: "http", host, port, path: mcpPath });
 
   const httpServer = createHttpServer(async (req, res) => {
@@ -13,20 +21,50 @@ async function startHttpServer({ host, port, mcpPath, createServer }) {
       return;
     }
 
-    const server = createServer();
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: undefined
-    });
+    if (!isReady()) {
+      const readiness = getReadinessState();
+      logEvent("transport", "request_rejected_not_ready", {
+        mode: "http",
+        path: requestUrl.pathname,
+        stage: readiness?.stage || "initializing"
+      }, { level: "debug" });
+
+      res.writeHead(503, {
+        "content-type": "application/json; charset=utf-8",
+        "retry-after": "2"
+      });
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Server is warming up. Please retry shortly.",
+            data: {
+              stage: readiness?.stage || "initializing"
+            }
+          },
+          id: null
+        })
+      );
+      return;
+    }
+
+    let server = null;
+    let transport = null;
 
     let closed = false;
     const closeResources = async () => {
       if (closed) return;
       closed = true;
       try {
-        await transport.close();
+        if (transport) {
+          await transport.close();
+        }
       } catch {}
       try {
-        await server.close();
+        if (server) {
+          await server.close();
+        }
       } catch {}
     };
 
@@ -35,6 +73,10 @@ async function startHttpServer({ host, port, mcpPath, createServer }) {
     });
 
     try {
+      server = createServer();
+      transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined
+      });
       await server.connect(transport);
       await transport.handleRequest(req, res);
     } catch (error) {
@@ -71,12 +113,14 @@ async function startHttpServer({ host, port, mcpPath, createServer }) {
     process.exit(0);
   };
 
-  process.on("SIGINT", () => {
-    void shutdown("SIGINT");
-  });
-  process.on("SIGTERM", () => {
-    void shutdown("SIGTERM");
-  });
+  if (registerSignalHandlers) {
+    process.on("SIGINT", () => {
+      void shutdown("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+      void shutdown("SIGTERM");
+    });
+  }
 
   return { httpServer };
 }