simple-dynamsoft-mcp 7.2.3 → 7.2.5

package/data/metadata/data-manifest.json

@@ -28,8 +28,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "barcode-reader-docs-server",
-      "commit": "80a3d89c3b8ee53e4640a87fe36cf6d96714929e",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-server/zip/80a3d89c3b8ee53e4640a87fe36cf6d96714929e"
+      "commit": "5479d530342edc40d1602addebbb8cd60ed781ce",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-server/zip/5479d530342edc40d1602addebbb8cd60ed781ce"
     },
     {
       "name": "data/documentation/capture-vision-docs",
@@ -78,8 +78,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "document-viewer-docs",
-      "commit": "26ea218ada436b1bbae04a224ebe2d42a08fef5b",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/document-viewer-docs/zip/26ea218ada436b1bbae04a224ebe2d42a08fef5b"
+      "commit": "4a49e918d174f4efac927981b81c81024d9ba3dc",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/document-viewer-docs/zip/4a49e918d174f4efac927981b81c81024d9ba3dc"
     },
     {
       "name": "data/documentation/web-twain-docs",
@@ -88,8 +88,8 @@
       "branch": "master",
       "owner": "dynamsoft-docs",
       "repo": "web-twain-docs",
-      "commit": "275eefb2a97512e91cfca139ac58f8a8b6317f8a",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/275eefb2a97512e91cfca139ac58f8a8b6317f8a"
+      "commit": "a38d73c583b8379c0d80337e92f291f6c1ab10a8",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/a38d73c583b8379c0d80337e92f291f6c1ab10a8"
     },
     {
       "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/data/metadata/dynamsoft_sdks.json

@@ -492,7 +492,7 @@
     "ddv": {
       "name": "Dynamsoft Document Viewer",
       "description": "Browser-based JavaScript SDK for viewing, editing, and annotating documents (PDFs and images).",
-      "version": "3.2",
+      "version": "3.2.1",
       "default_platform": "web",
       "snippet_path": "dynamsoft-document-viewer",
       "api_docs": "ddv-api-docs.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.2.3",
+  "version": "7.2.5",
   "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/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/paths.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DOC_DIRS, SAMPLE_DIRS } from "./config.js";
 import { getResolvedDataRoot } from "../../data/root.js";
@@ -13,6 +13,9 @@ const samplesRoot = join(dataRoot, "samples");
 const docsRoot = join(dataRoot, "documentation");
 
 const registryPath = join(metadataRoot, "dynamsoft_sdks.json");
+const dataManifestPath = join(metadataRoot, "data-manifest.json");
+
+const manifestCommitLookupCache = new Map();
 
 const SAMPLE_ROOTS = {
   dbrWeb: join(samplesRoot, SAMPLE_DIRS.dbrWeb),
@@ -60,28 +63,92 @@ function getExistingPath(...candidates) {
   return null;
 }
 
-function readSubmoduleHead(repoPath) {
+function normalizeManifestRepoPath(pathValue) {
+  return String(pathValue || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+}
+
+function getManifestRepoPath(repoPath, dataRootPath = dataRoot) {
+  const resolvedDataRoot = resolve(dataRootPath);
+  const resolvedRepoPath = resolve(repoPath);
+  const manifestRepoPath = normalizeManifestRepoPath(
+    relative(resolvedDataRoot, resolvedRepoPath)
+  );
+
+  if (!manifestRepoPath || manifestRepoPath === ".") {
+    throw new Error(`Unable to resolve manifest repo path for ${repoPath}`);
+  }
+
+  if (manifestRepoPath.startsWith("..")) {
+    throw new Error(
+      `Repo path ${repoPath} is outside data root ${resolvedDataRoot}`
+    );
+  }
+
+  return manifestRepoPath;
+}
+
+function buildManifestCommitLookup(manifestPath = dataManifestPath) {
+  const resolvedManifestPath = resolve(manifestPath);
+  const cachedLookup = manifestCommitLookupCache.get(resolvedManifestPath);
+  if (cachedLookup) {
+    return cachedLookup;
+  }
+
+  if (!existsSync(resolvedManifestPath)) {
+    throw new Error(`Missing data manifest at ${resolvedManifestPath}`);
+  }
+
+  let manifest = null;
   try {
-    const gitMarker = join(repoPath, ".git");
-    if (!existsSync(gitMarker)) return "";
-    let gitDir = gitMarker;
-    const markerStats = statSync(gitMarker);
-    if (!markerStats.isDirectory()) {
-      const markerText = readFileSync(gitMarker, "utf8").trim();
-      if (!markerText.toLowerCase().startsWith("gitdir:")) return "";
-      const relGitDir = markerText.slice("gitdir:".length).trim();
-      gitDir = resolve(repoPath, relGitDir);
+    manifest = JSON.parse(readFileSync(resolvedManifestPath, "utf8"));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to parse data manifest at ${resolvedManifestPath}: ${reason}`
+    );
+  }
+
+  if (!manifest || !Array.isArray(manifest.repos)) {
+    throw new Error(
+      `Invalid data manifest at ${resolvedManifestPath}: missing repos array`
+    );
+  }
+
+  const lookup = new Map();
+  for (const repo of manifest.repos) {
+    const repoPath = normalizeManifestRepoPath(repo?.path);
+    const commit = String(repo?.commit || "").trim();
+    if (!repoPath || !commit) {
+      throw new Error(
+        `Invalid data manifest entry at ${resolvedManifestPath}: path and commit are required`
+      );
     }
-    const headPath = join(gitDir, "HEAD");
-    if (!existsSync(headPath)) return "";
-    const headText = readFileSync(headPath, "utf8").trim();
-    if (!headText.startsWith("ref:")) return headText;
-    const refPath = join(gitDir, headText.slice("ref:".length).trim());
-    if (!existsSync(refPath)) return "";
-    return readFileSync(refPath, "utf8").trim();
-  } catch {
-    return "";
+    lookup.set(repoPath, commit);
   }
+
+  manifestCommitLookupCache.set(resolvedManifestPath, lookup);
+  return lookup;
+}
+
+function readManifestRepoCommit(repoPath, options = {}) {
+  const dataRootPath = options.dataRootPath || dataRoot;
+  const manifestPath = options.manifestPath || dataManifestPath;
+  const commitLookup =
+    options.commitLookup || buildManifestCommitLookup(manifestPath);
+  const manifestRepoPath = getManifestRepoPath(repoPath, dataRootPath);
+  const commit = commitLookup.get(manifestRepoPath);
+
+  if (!commit) {
+    throw new Error(
+      `Missing commit for ${manifestRepoPath} in data manifest ${resolve(manifestPath)}`
+    );
+  }
+
+  return commit;
 }
 
 export {
@@ -91,8 +158,10 @@ export {
   samplesRoot,
   docsRoot,
   registryPath,
+  dataManifestPath,
   SAMPLE_ROOTS,
   DOC_ROOTS,
   getExistingPath,
-  readSubmoduleHead
+  buildManifestCommitLookup,
+  readManifestRepoCommit
 };

package/src/server/resource-index.js

@@ -17,7 +17,12 @@ import {
 } from "./normalizers.js";
 import { DOCS_CONFIG } from "./resource-index/config.js";
 import { loadMarkdownDocs } from "./resource-index/docs-loader.js";
-import { registryPath, DOC_ROOTS, SAMPLE_ROOTS, readSubmoduleHead } from "./resource-index/paths.js";
+import {
+  registryPath,
+  DOC_ROOTS,
+  SAMPLE_ROOTS,
+  readManifestRepoCommit
+} from "./resource-index/paths.js";
 import {
   getCodeFileExtensions,
   isCodeFile,
@@ -275,6 +280,7 @@ function buildVersionPolicyText() {
 
 const resourceIndex = [];
 const resourceIndexByUri = new Map();
+let resourceIndexReady = false;
 
 function addResourceToIndex(entry) {
   resourceIndex.push(entry);
@@ -363,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;
@@ -392,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);
@@ -420,6 +434,7 @@ function formatScopeLabel(entry) {
 }
 
 function getPinnedResources() {
+  ensureResourceIndexReady();
   return resourceIndex.filter((entry) => entry.pinned);
 }
 
@@ -459,6 +474,8 @@ function buildResourceLookupCandidates(uri) {
 }
 
 async function readResourceContent(uri) {
+  ensureResourceIndexReady();
+
   let resource = null;
   for (const candidate of buildResourceLookupCandidates(uri)) {
     resource = resourceIndexByUri.get(candidate);
@@ -476,6 +493,8 @@ async function readResourceContent(uri) {
 }
 
 function getRagSignatureData() {
+  ensureResourceIndexReady();
+
   return {
     resourceCount: resourceIndex.length,
     dcvCoreDocCount: dcvCoreDocs.length,
@@ -489,38 +508,38 @@ function getRagSignatureData() {
     ddvDocCount: ddvDocs.articles.length,
     versions: LATEST_VERSIONS,
     dataSources: {
-      dbrWebSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrWeb),
-      dbrMobileSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrMobile),
-      dbrPythonSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrPython),
-      dbrDotnetSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrDotnet),
-      dbrJavaSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrJava),
-      dbrCppSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrCpp),
-      dbrMauiSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrMaui),
-      dbrReactNativeSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrReactNative),
-      dbrFlutterSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrFlutter),
-      dbrNodejsSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dbrNodejs),
-      dcvWebSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvWeb),
-      dcvMobileSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvMobile),
-      dcvPythonSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvPython),
-      dcvDotnetSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvDotnet),
-      dcvJavaSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvJava),
-      dcvCppSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvCpp),
-      dcvMauiSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvMaui),
-      dcvReactNativeSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvReactNative),
-      dcvFlutterSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvFlutter),
-      dcvNodejsSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvNodejs),
-      dcvSpmSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dcvSpm),
-      dwtSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.dwt),
-      ddvSamplesHead: readSubmoduleHead(SAMPLE_ROOTS.ddv),
-      dbrWebDocsHead: readSubmoduleHead(DOC_ROOTS.dbrWeb),
-      dbrMobileDocsHead: readSubmoduleHead(DOC_ROOTS.dbrMobile),
-      dbrServerDocsHead: readSubmoduleHead(DOC_ROOTS.dbrServer),
-      dcvCoreDocsHead: readSubmoduleHead(DOC_ROOTS.dcvCore),
-      dcvWebDocsHead: readSubmoduleHead(DOC_ROOTS.dcvWeb),
-      dcvMobileDocsHead: readSubmoduleHead(DOC_ROOTS.dcvMobile),
-      dcvServerDocsHead: readSubmoduleHead(DOC_ROOTS.dcvServer),
-      dwtDocsHead: readSubmoduleHead(DOC_ROOTS.dwt),
-      ddvDocsHead: readSubmoduleHead(DOC_ROOTS.ddv),
+      dbrWebSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrWeb),
+      dbrMobileSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrMobile),
+      dbrPythonSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrPython),
+      dbrDotnetSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrDotnet),
+      dbrJavaSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrJava),
+      dbrCppSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrCpp),
+      dbrMauiSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrMaui),
+      dbrReactNativeSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrReactNative),
+      dbrFlutterSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrFlutter),
+      dbrNodejsSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dbrNodejs),
+      dcvWebSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvWeb),
+      dcvMobileSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvMobile),
+      dcvPythonSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvPython),
+      dcvDotnetSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvDotnet),
+      dcvJavaSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvJava),
+      dcvCppSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvCpp),
+      dcvMauiSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvMaui),
+      dcvReactNativeSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvReactNative),
+      dcvFlutterSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvFlutter),
+      dcvNodejsSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvNodejs),
+      dcvSpmSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dcvSpm),
+      dwtSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.dwt),
+      ddvSamplesHead: readManifestRepoCommit(SAMPLE_ROOTS.ddv),
+      dbrWebDocsHead: readManifestRepoCommit(DOC_ROOTS.dbrWeb),
+      dbrMobileDocsHead: readManifestRepoCommit(DOC_ROOTS.dbrMobile),
+      dbrServerDocsHead: readManifestRepoCommit(DOC_ROOTS.dbrServer),
+      dcvCoreDocsHead: readManifestRepoCommit(DOC_ROOTS.dcvCore),
+      dcvWebDocsHead: readManifestRepoCommit(DOC_ROOTS.dcvWeb),
+      dcvMobileDocsHead: readManifestRepoCommit(DOC_ROOTS.dcvMobile),
+      dcvServerDocsHead: readManifestRepoCommit(DOC_ROOTS.dcvServer),
+      dwtDocsHead: readManifestRepoCommit(DOC_ROOTS.dwt),
+      ddvDocsHead: readManifestRepoCommit(DOC_ROOTS.ddv),
       registrySha256
     }
   };
@@ -580,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 };
 }