simple-dynamsoft-mcp 6.3.0 → 7.0.0

package/src/{resource-index → server/resource-index}/samples.js

@@ -19,6 +19,13 @@ let cachedDbrWebFrameworkPlatforms = null;
 let cachedDdvWebFrameworkPlatforms = null;
 let cachedDcvWebFrameworkPlatforms = null;
 
+function resetSampleDiscoveryCaches() {
+  cachedWebFrameworkPlatforms = null;
+  cachedDbrWebFrameworkPlatforms = null;
+  cachedDdvWebFrameworkPlatforms = null;
+  cachedDcvWebFrameworkPlatforms = null;
+}
+
 function getCodeFileExtensions() {
   return CODE_FILE_EXTENSIONS;
 }
@@ -719,5 +726,6 @@ export {
   getMainCodeFile,
   getMimeTypeForExtension,
   getDbrServerSampleContent,
-  getDcvServerSampleContent
+  getDcvServerSampleContent,
+  resetSampleDiscoveryCaches
 };

package/src/{resource-index.js → server/resource-index.js}

@@ -53,7 +53,8 @@ import {
   getMainCodeFile,
   getMimeTypeForExtension,
   getDbrServerSampleContent,
-  getDcvServerSampleContent
+  getDcvServerSampleContent,
+  resetSampleDiscoveryCaches
 } from "./resource-index/samples.js";
 import { parseResourceUri, parseSampleUri, getSampleIdFromUri } from "./resource-index/uri.js";
 import {
@@ -126,95 +127,107 @@ function inferDcvServerPlatform(articlePath) {
   return "server";
 }
 
-const dbrWebDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dbrWeb,
-    urlBase: DOCS_CONFIG.dbrWeb.urlBase,
-    excludeDirs: DOCS_CONFIG.dbrWeb.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dbrWeb.excludeFiles
-  }).articles,
-  "web",
-  () => "web"
-);
-
-const dbrMobileDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dbrMobile,
-    urlBase: DOCS_CONFIG.dbrMobile.urlBase,
-    excludeDirs: DOCS_CONFIG.dbrMobile.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dbrMobile.excludeFiles
-  }).articles,
-  "mobile",
-  inferDbrMobilePlatform
-);
-
-const dbrServerDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dbrServer,
-    urlBase: DOCS_CONFIG.dbrServer.urlBase,
-    excludeDirs: DOCS_CONFIG.dbrServer.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dbrServer.excludeFiles
-  }).articles,
-  "server",
-  inferDbrServerPlatform
-);
-
-const dcvCoreDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dcvCore,
-    urlBase: DOCS_CONFIG.dcvCore.urlBase,
-    excludeDirs: DOCS_CONFIG.dcvCore.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dcvCore.excludeFiles
-  }).articles,
-  "core",
-  () => "core"
-);
-
-const dcvWebDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dcvWeb,
-    urlBase: DOCS_CONFIG.dcvWeb.urlBase,
-    excludeDirs: DOCS_CONFIG.dcvWeb.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dcvWeb.excludeFiles
-  }).articles,
-  "web",
-  () => "web"
-);
-
-const dcvMobileDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dcvMobile,
-    urlBase: DOCS_CONFIG.dcvMobile.urlBase,
-    excludeDirs: DOCS_CONFIG.dcvMobile.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dcvMobile.excludeFiles
-  }).articles,
-  "mobile",
-  inferDcvMobilePlatform
-);
-
-const dcvServerDocs = withEditionScope(
-  loadMarkdownDocs({
-    rootDir: DOC_ROOTS.dcvServer,
-    urlBase: DOCS_CONFIG.dcvServer.urlBase,
-    excludeDirs: DOCS_CONFIG.dcvServer.excludeDirs,
-    excludeFiles: DOCS_CONFIG.dcvServer.excludeFiles
-  }).articles,
-  "server",
-  inferDcvServerPlatform
-);
-
-const dwtDocs = loadMarkdownDocs({
-  rootDir: DOC_ROOTS.dwtArticles,
-  urlBase: DOCS_CONFIG.dwt.urlBase,
-  includeDirNames: DOCS_CONFIG.dwt.includeDirNames
-});
-
-const ddvDocs = loadMarkdownDocs({
-  rootDir: DOC_ROOTS.ddv,
-  urlBase: DOCS_CONFIG.ddv.urlBase,
-  excludeDirs: DOCS_CONFIG.ddv.excludeDirs,
-  excludeFiles: DOCS_CONFIG.ddv.excludeFiles
-});
+let dbrWebDocs = [];
+let dbrMobileDocs = [];
+let dbrServerDocs = [];
+let dcvCoreDocs = [];
+let dcvWebDocs = [];
+let dcvMobileDocs = [];
+let dcvServerDocs = [];
+let dwtDocs = { articles: [] };
+let ddvDocs = { articles: [] };
+
+function loadDocumentationSets() {
+  dbrWebDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dbrWeb,
+      urlBase: DOCS_CONFIG.dbrWeb.urlBase,
+      excludeDirs: DOCS_CONFIG.dbrWeb.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dbrWeb.excludeFiles
+    }).articles,
+    "web",
+    () => "web"
+  );
+
+  dbrMobileDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dbrMobile,
+      urlBase: DOCS_CONFIG.dbrMobile.urlBase,
+      excludeDirs: DOCS_CONFIG.dbrMobile.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dbrMobile.excludeFiles
+    }).articles,
+    "mobile",
+    inferDbrMobilePlatform
+  );
+
+  dbrServerDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dbrServer,
+      urlBase: DOCS_CONFIG.dbrServer.urlBase,
+      excludeDirs: DOCS_CONFIG.dbrServer.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dbrServer.excludeFiles
+    }).articles,
+    "server",
+    inferDbrServerPlatform
+  );
+
+  dcvCoreDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dcvCore,
+      urlBase: DOCS_CONFIG.dcvCore.urlBase,
+      excludeDirs: DOCS_CONFIG.dcvCore.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dcvCore.excludeFiles
+    }).articles,
+    "core",
+    () => "core"
+  );
+
+  dcvWebDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dcvWeb,
+      urlBase: DOCS_CONFIG.dcvWeb.urlBase,
+      excludeDirs: DOCS_CONFIG.dcvWeb.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dcvWeb.excludeFiles
+    }).articles,
+    "web",
+    () => "web"
+  );
+
+  dcvMobileDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dcvMobile,
+      urlBase: DOCS_CONFIG.dcvMobile.urlBase,
+      excludeDirs: DOCS_CONFIG.dcvMobile.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dcvMobile.excludeFiles
+    }).articles,
+    "mobile",
+    inferDcvMobilePlatform
+  );
+
+  dcvServerDocs = withEditionScope(
+    loadMarkdownDocs({
+      rootDir: DOC_ROOTS.dcvServer,
+      urlBase: DOCS_CONFIG.dcvServer.urlBase,
+      excludeDirs: DOCS_CONFIG.dcvServer.excludeDirs,
+      excludeFiles: DOCS_CONFIG.dcvServer.excludeFiles
+    }).articles,
+    "server",
+    inferDcvServerPlatform
+  );
+
+  dwtDocs = loadMarkdownDocs({
+    rootDir: DOC_ROOTS.dwtArticles,
+    urlBase: DOCS_CONFIG.dwt.urlBase,
+    includeDirNames: DOCS_CONFIG.dwt.includeDirNames
+  });
+
+  ddvDocs = loadMarkdownDocs({
+    rootDir: DOC_ROOTS.ddv,
+    urlBase: DOCS_CONFIG.ddv.urlBase,
+    excludeDirs: DOCS_CONFIG.ddv.excludeDirs,
+    excludeFiles: DOCS_CONFIG.ddv.excludeFiles
+  });
+}
 
 const dbrServerSdk = registry.sdks["dbr-server"];
 const dcvMobileSdk = registry.sdks["dcv-mobile"];
@@ -261,6 +274,7 @@ function buildVersionPolicyText() {
 }
 
 const resourceIndex = [];
+const resourceIndexByUri = new Map();
 
 function addResourceToIndex(entry) {
   resourceIndex.push(entry);
@@ -340,9 +354,19 @@ function buildResourceIndex() {
   });
 }
 
-buildResourceIndex();
+function refreshResourceIndex() {
+  resetSampleDiscoveryCaches();
+  loadDocumentationSets();
+  resourceIndex.length = 0;
+  buildResourceIndex();
+  resourceIndexByUri.clear();
+  for (const entry of resourceIndex) {
+    resourceIndexByUri.set(entry.uri, entry);
+  }
+  return { resourceCount: resourceIndex.length };
+}
 
-const resourceIndexByUri = new Map(resourceIndex.map((entry) => [entry.uri, entry]));
+refreshResourceIndex();
 
 function editionMatches(normalizedEdition, entryEdition) {
   if (!normalizedEdition) return true;
@@ -399,9 +423,49 @@ function getPinnedResources() {
   return resourceIndex.filter((entry) => entry.pinned);
 }
 
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function buildResourceLookupCandidates(uri) {
+  const candidates = [];
+  if (typeof uri !== "string" || uri.length === 0) return candidates;
+  candidates.push(uri);
+
+  if (!uri.includes("://")) return candidates;
+  const [scheme, rest] = uri.split("://");
+  if (scheme !== "doc") return candidates;
+
+  const parts = String(rest || "").split("/").filter(Boolean);
+  if (parts.length < 5) return candidates;
+
+  const head = parts.slice(0, 4);
+  const slugRaw = parts.slice(4).join("/");
+  const decodedOnce = safeDecodeURIComponent(slugRaw);
+  const decodedTwice = safeDecodeURIComponent(decodedOnce);
+
+  for (const slug of [decodedOnce, decodedTwice]) {
+    const canonical = `${scheme}://${head.join("/")}/${encodeURIComponent(slug)}`;
+    if (!candidates.includes(canonical)) {
+      candidates.push(canonical);
+    }
+  }
+
+  return candidates;
+}
+
 async function readResourceContent(uri) {
-  const resource = resourceIndexByUri.get(uri);
+  let resource = null;
+  for (const candidate of buildResourceLookupCandidates(uri)) {
+    resource = resourceIndexByUri.get(candidate);
+    if (resource) break;
+  }
   if (!resource) return null;
+
   const content = await resource.loadContent();
   return {
     uri,
@@ -515,6 +579,7 @@ export {
   buildVersionPolicyText,
   buildIndexData,
   buildResourceIndex,
+  refreshResourceIndex,
   editionMatches,
   platformMatches,
   getDisplayEdition,

package/src/server/resources/register-resources.js

@@ -0,0 +1,56 @@
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  SubscribeRequestSchema,
+  UnsubscribeRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+export function registerResourceHandlers({
+  server,
+  getPinnedResources,
+  parseResourceUri,
+  ensureLatestMajor,
+  readResourceContent
+}) {
+  server.server.registerCapabilities({
+    resources: {
+      listChanged: false,
+      subscribe: true
+    }
+  });
+
+  server.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const resources = getPinnedResources().map((entry) => ({
+      uri: entry.uri,
+      name: entry.title,
+      description: entry.summary,
+      mimeType: entry.mimeType
+    }));
+    return { resources };
+  });
+
+  server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const parsed = parseResourceUri(request.params.uri);
+    if (parsed && ["dcv", "dbr", "dwt", "ddv"].includes(parsed.product)) {
+      const policy = ensureLatestMajor({
+        product: parsed.product,
+        version: parsed.version,
+        edition: parsed.edition,
+        platform: parsed.platform
+      });
+      if (!policy.ok) {
+        throw new Error(policy.message);
+      }
+    }
+
+    const resource = await readResourceContent(request.params.uri);
+    if (!resource) {
+      throw new Error(`Resource not found: ${request.params.uri}`);
+    }
+
+    return { contents: [resource] };
+  });
+
+  server.server.setRequestHandler(SubscribeRequestSchema, async () => ({}));
+  server.server.setRequestHandler(UnsubscribeRequestSchema, async () => ({}));
+}

package/src/server/runtime-config.js

@@ -0,0 +1,66 @@
+const DEFAULT_TRANSPORT = "stdio";
+const DEFAULT_HTTP_HOST = "127.0.0.1";
+const DEFAULT_HTTP_PORT = 3333;
+const SUPPORTED_TRANSPORTS = new Set(["stdio", "http"]);
+
+const MCP_HTTP_PATH = "/mcp";
+
+function parseCliArgs(argv) {
+  const parsed = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) continue;
+    const option = token.slice(2);
+    if (!option) continue;
+
+    const equalsIndex = option.indexOf("=");
+    if (equalsIndex >= 0) {
+      const key = option.slice(0, equalsIndex);
+      const value = option.slice(equalsIndex + 1);
+      if (key) parsed[key] = value;
+      continue;
+    }
+
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      parsed[option] = next;
+      i += 1;
+      continue;
+    }
+
+    parsed[option] = "true";
+  }
+
+  return parsed;
+}
+
+function resolveRuntimeConfig(argv = process.argv.slice(2)) {
+  const parsed = parseCliArgs(argv);
+  const transport = String(parsed.transport || DEFAULT_TRANSPORT).toLowerCase();
+
+  if (!SUPPORTED_TRANSPORTS.has(transport)) {
+    throw new Error(`Invalid --transport "${transport}". Expected "stdio" or "http".`);
+  }
+
+  if (transport === "http") {
+    const host = String(parsed.host || DEFAULT_HTTP_HOST);
+    const portRaw = String(parsed.port || String(DEFAULT_HTTP_PORT));
+    const port = Number.parseInt(portRaw, 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error(`Invalid --port "${portRaw}". Expected an integer between 1 and 65535.`);
+    }
+    return { transport, host, port };
+  }
+
+  return {
+    transport,
+    host: DEFAULT_HTTP_HOST,
+    port: DEFAULT_HTTP_PORT
+  };
+}
+
+export {
+  MCP_HTTP_PATH,
+  parseCliArgs,
+  resolveRuntimeConfig
+};

package/src/server/tools/register-index-tools.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { formatScoreLabel, formatScoreNote } from "../helpers/server-helpers.js";
+
+export function registerIndexTools({
+  server,
+  ensureScopeHydrated,
+  ensureLatestMajor,
+  normalizeProduct,
+  normalizePlatform,
+  normalizeEdition,
+  buildIndexData,
+  getSampleIdFromUri,
+  formatScopeLabel,
+  searchResources
+}) {
+  server.registerTool(
+    "get_index",
+    {
+      title: "Get Index",
+      description: "Get a compact index of products, editions, versions, samples/docs, plus DBR-vs-DCV selection guidance.",
+      inputSchema: {}
+    },
+    async () => ({
+      content: [{ type: "text", text: JSON.stringify(buildIndexData(), null, 2) }]
+    })
+  );
+
+  server.registerTool(
+    "search",
+    {
+      title: "Search",
+      description: "Semantic (RAG) search across docs and samples with fuzzy fallback; returns resource links for lazy loading. Prefer DCV for MRZ/VIN/document-normalization/driver-license scenarios; DBR for barcode-only.",
+      inputSchema: {
+        query: z.string().describe("Keywords to search across docs and samples."),
+        product: z.string().optional().describe("Product: dcv, dbr, dwt, ddv"),
+        edition: z.string().optional().describe("Edition: core, mobile, web, server/desktop"),
+        platform: z.string().optional().describe("Platform: android, ios, maui, react-native, flutter, js, python, cpp, java, dotnet, nodejs, angular, blazor, capacitor, electron, es6, native-ts, next, nuxt, pwa, react, requirejs, svelte, vue, webview, spm, core"),
+        version: z.string().optional().describe("Version constraint (major or full version)"),
+        type: z.enum(["doc", "sample", "index", "policy", "any"]).optional(),
+        limit: z.number().int().min(1).max(10).optional().describe("Max results (default 5)")
+      }
+    },
+    async ({ query, product, edition, platform, version, type, limit }) => {
+      if (!query || !query.trim()) {
+        return { isError: true, content: [{ type: "text", text: "Query is required." }] };
+      }
+      const normalizedProduct = normalizeProduct(product);
+      const normalizedPlatform = normalizePlatform(platform);
+      const normalizedEdition = normalizeEdition(edition, normalizedPlatform, normalizedProduct);
+
+      await ensureScopeHydrated({
+        product: normalizedProduct,
+        edition: normalizedEdition,
+        platform: normalizedPlatform,
+        type: type || "any"
+      });
+
+      const policy = ensureLatestMajor({
+        product: normalizedProduct,
+        version,
+        query,
+        edition: normalizedEdition,
+        platform: normalizedPlatform
+      });
+
+      if (!policy.ok) {
+        return { isError: true, content: [{ type: "text", text: policy.message }] };
+      }
+
+      const maxResults = Math.min(limit || 5, 10);
+      const topResults = await searchResources({
+        query,
+        product: normalizedProduct,
+        edition: normalizedEdition,
+        platform: normalizedPlatform,
+        type: type || "any",
+        limit: maxResults
+      });
+
+      if (topResults.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: `No results for "${query}". Try get_index for available products or adjust filters.`
+          }]
+        };
+      }
+
+      const content = [
+        {
+          type: "text",
+          text: `Found ${topResults.length} result(s) for "${query}". Read the links you need with resources/read.`
+        }
+      ];
+
+      for (const entry of topResults) {
+        const versionLabel = entry.version ? `v${entry.version}` : "n/a";
+        const scopeLabel = formatScopeLabel(entry);
+        const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
+        const sampleHint = sampleId ? ` | sample_id: ${sampleId}` : "";
+        const scoreLabel = formatScoreLabel(entry);
+        content.push({
+          type: "resource_link",
+          uri: entry.uri,
+          name: entry.title,
+          description: `${entry.type.toUpperCase()} | ${scopeLabel} | ${versionLabel}${scoreLabel} - ${entry.summary}${sampleHint}`,
+          mimeType: entry.mimeType,
+          annotations: {
+            audience: ["assistant"],
+            priority: 0.8
+          }
+        });
+      }
+
+      const plainLines = topResults.map((entry, index) => {
+        const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
+        const action = entry.type === "sample" ? "generate_project resource_uri" : "resources/read uri";
+        const sampleNote = sampleId ? ` sample_id=${sampleId}` : "";
+        const scoreNote = formatScoreNote(entry);
+        return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote} (${action})`;
+      });
+      content.push({
+        type: "text",
+        text: ["Plain URIs (copy/paste):", ...plainLines].join("\n")
+      });
+
+      return { content };
+    }
+  );
+}