simple-dynamsoft-mcp 6.3.0 → 7.0.0

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

@@ -0,0 +1,333 @@
+import { z } from "zod";
+import { formatScoreLabel, formatScoreNote } from "../helpers/server-helpers.js";
+
+export function registerSampleTools({
+  server,
+  ensureScopeHydrated,
+  ensureLatestMajor,
+  normalizeProduct,
+  normalizePlatform,
+  normalizeEdition,
+  normalizeSampleName,
+  parseSampleUri,
+  resourceIndex,
+  getSampleEntries,
+  getSampleIdFromUri,
+  getDisplayEdition,
+  getDisplayPlatform,
+  formatScopeLabel,
+  searchResources,
+  getSampleSuggestions
+}) {
+  server.registerTool(
+    "list_samples",
+    {
+      title: "List Samples",
+      description: "List available sample IDs and URIs for a given scope. Use DCV scope for MRZ/VIN/document normalization scenarios.",
+      inputSchema: {
+        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"),
+        limit: z.number().int().min(1).max(200).optional().describe("Max results (default 50)")
+      }
+    },
+    async ({ product, edition, platform, limit }) => {
+      const normalizedProduct = normalizeProduct(product);
+      const normalizedPlatform = normalizePlatform(platform);
+      const normalizedEdition = normalizeEdition(edition, normalizedPlatform, normalizedProduct);
+
+      await ensureScopeHydrated({
+        product: normalizedProduct,
+        edition: normalizedEdition,
+        platform: normalizedPlatform,
+        type: "sample"
+      });
+
+      const policy = ensureLatestMajor({
+        product: normalizedProduct,
+        version: undefined,
+        query: "",
+        edition: normalizedEdition,
+        platform: normalizedPlatform
+      });
+
+      if (!policy.ok) {
+        return { isError: true, content: [{ type: "text", text: policy.message }] };
+      }
+
+      const samples = getSampleEntries({
+        product: normalizedProduct,
+        edition: normalizedEdition,
+        platform: normalizedPlatform
+      });
+
+      const maxResults = Math.min(limit || 50, 200);
+      const selected = samples.slice(0, maxResults);
+
+      const payload = selected.map((entry) => ({
+        sample_id: getSampleIdFromUri(entry.uri),
+        uri: entry.uri,
+        product: entry.product,
+        edition: getDisplayEdition(entry.edition),
+        platform: getDisplayPlatform(entry.platform),
+        version: entry.version,
+        title: entry.title,
+        summary: entry.summary
+      }));
+
+      const lines = [
+        `Total matches: ${samples.length}`,
+        `Returned: ${payload.length}`,
+        "",
+        "Plain URIs (copy/paste):",
+        ...payload.map((item, index) => {
+          const sampleNote = item.sample_id ? ` (sample_id: ${item.sample_id})` : "";
+          return `- ${index + 1}. ${item.uri}${sampleNote}`;
+        })
+      ];
+
+      const output = {
+        total: samples.length,
+        returned: payload.length,
+        samples: payload
+      };
+
+      return {
+        content: [{
+          type: "text",
+          text: `${lines.join("\n")}\n\nJSON:\n${JSON.stringify(output, null, 2)}`
+        }]
+      };
+    }
+  );
+
+  server.registerTool(
+    "resolve_sample",
+    {
+      title: "Resolve Sample",
+      description: "Resolve a sample_id (or sample URI) to matching sample URIs.",
+      inputSchema: {
+        sample_id: z.string().describe("Sample identifier or sample:// URI"),
+        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"),
+        limit: z.number().int().min(1).max(10).optional().describe("Max results (default 5)")
+      }
+    },
+    async ({ sample_id, product, edition, platform, limit }) => {
+      if (!sample_id || !sample_id.trim()) {
+        return { isError: true, content: [{ type: "text", text: "sample_id 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: "sample"
+      });
+
+      const policy = ensureLatestMajor({
+        product: normalizedProduct,
+        version: undefined,
+        query: sample_id,
+        edition: normalizedEdition,
+        platform: normalizedPlatform
+      });
+
+      if (!policy.ok) {
+        return { isError: true, content: [{ type: "text", text: policy.message }] };
+      }
+
+      if (sample_id.includes("://")) {
+        const parsed = parseSampleUri(sample_id);
+        if (!parsed) {
+          return {
+            isError: true,
+            content: [{
+              type: "text",
+              text: "sample_id looks like a URI but is not a valid sample:// URI. For doc:// URIs, use resources/read."
+            }]
+          };
+        }
+        const entry = resourceIndex.find((item) => item.uri === sample_id && item.type === "sample");
+        if (!entry) {
+          return {
+            isError: true,
+            content: [{
+              type: "text",
+              text: `Sample URI not found in index: ${sample_id}. Use list_samples or search.`
+            }]
+          };
+        }
+
+        const payload = [{
+          sample_id: getSampleIdFromUri(entry.uri),
+          uri: entry.uri,
+          product: entry.product,
+          edition: getDisplayEdition(entry.edition),
+          platform: getDisplayPlatform(entry.platform),
+          version: entry.version,
+          title: entry.title,
+          summary: entry.summary
+        }];
+
+        const output = {
+          query: sample_id,
+          returned: payload.length,
+          samples: payload
+        };
+
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `Found ${payload.length} match(es) for "${sample_id}".`,
+              "Plain URIs (copy/paste):",
+              `- 1. ${entry.uri} (sample_id: ${payload[0].sample_id})`,
+              "",
+              "JSON:",
+              JSON.stringify(output, null, 2)
+            ].join("\n")
+          }, {
+            type: "resource_link",
+            uri: entry.uri,
+            name: entry.title,
+            description: `SAMPLE | ${formatScopeLabel(entry)} | v${entry.version}${formatScoreLabel(entry)} | sample_id: ${payload[0].sample_id}`,
+            mimeType: entry.mimeType,
+            annotations: {
+              audience: ["assistant"],
+              priority: 0.8
+            }
+          }]
+        };
+      }
+
+      const sampleQuery = normalizeSampleName(sample_id);
+      const maxResults = Math.min(limit || 5, 10);
+
+      const scopedSamples = getSampleEntries({
+        product: normalizedProduct,
+        edition: normalizedEdition,
+        platform: normalizedPlatform
+      });
+
+      let matches = scopedSamples.filter((entry) => {
+        const entryId = getSampleIdFromUri(entry.uri);
+        return entryId && entryId.toLowerCase() === sampleQuery.toLowerCase();
+      });
+
+      if (matches.length === 0) {
+        matches = await searchResources({
+          query: sample_id,
+          product: normalizedProduct,
+          edition: normalizedEdition,
+          platform: normalizedPlatform,
+          type: "sample",
+          limit: maxResults
+        });
+      }
+
+      const selected = matches.slice(0, maxResults);
+      if (selected.length === 0) {
+        const suggestions = await getSampleSuggestions({
+          query: sample_id,
+          product: normalizedProduct,
+          edition: normalizedEdition,
+          platform: normalizedPlatform,
+          limit: maxResults
+        });
+
+        const content = [{
+          type: "text",
+          text: suggestions.length
+            ? `No exact sample match for "${sample_id}". Related samples:`
+            : `No samples found for "${sample_id}". Try list_samples or search.`
+        }];
+
+        for (const entry of suggestions) {
+          const sampleId = getSampleIdFromUri(entry.uri);
+          content.push({
+            type: "resource_link",
+            uri: entry.uri,
+            name: entry.title,
+            description: `${entry.type.toUpperCase()} | ${formatScopeLabel(entry)} | v${entry.version}${formatScoreLabel(entry)} | sample_id: ${sampleId || "n/a"}`,
+            mimeType: entry.mimeType,
+            annotations: {
+              audience: ["assistant"],
+              priority: 0.6
+            }
+          });
+        }
+
+        if (suggestions.length) {
+          const plainLines = suggestions.map((entry, index) => {
+            const sampleId = getSampleIdFromUri(entry.uri);
+            const sampleNote = sampleId ? ` (sample_id: ${sampleId})` : "";
+            const scoreNote = formatScoreNote(entry);
+            return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote}`;
+          });
+          content.push({
+            type: "text",
+            text: ["Plain URIs (copy/paste):", ...plainLines].join("\n")
+          });
+        }
+
+        return { isError: true, content };
+      }
+
+      const payload = selected.map((entry) => ({
+        sample_id: getSampleIdFromUri(entry.uri),
+        uri: entry.uri,
+        product: entry.product,
+        edition: getDisplayEdition(entry.edition),
+        platform: getDisplayPlatform(entry.platform),
+        version: entry.version,
+        title: entry.title,
+        summary: entry.summary
+      }));
+
+      const lines = [
+        `Found ${selected.length} match(es) for "${sample_id}".`,
+        "Plain URIs (copy/paste):",
+        ...selected.map((entry, index) => {
+          const sampleId = getSampleIdFromUri(entry.uri);
+          const sampleNote = sampleId ? ` (sample_id: ${sampleId})` : "";
+          const scoreNote = formatScoreNote(entry);
+          return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote}`;
+        })
+      ];
+
+      const output = {
+        query: sample_id,
+        returned: payload.length,
+        samples: payload
+      };
+
+      const content = [{
+        type: "text",
+        text: `${lines.join("\n")}\n\nJSON:\n${JSON.stringify(output, null, 2)}`
+      }];
+
+      for (const entry of selected) {
+        const sampleId = getSampleIdFromUri(entry.uri);
+        content.push({
+          type: "resource_link",
+          uri: entry.uri,
+          name: entry.title,
+          description: `${entry.type.toUpperCase()} | ${formatScopeLabel(entry)} | v${entry.version}${formatScoreLabel(entry)} | sample_id: ${sampleId || "n/a"}`,
+          mimeType: entry.mimeType,
+          annotations: {
+            audience: ["assistant"],
+            priority: 0.8
+          }
+        });
+      }
+
+      return { content };
+    }
+  );
+}

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

@@ -0,0 +1,136 @@
+import { z } from "zod";
+
+export function registerVersionTools({
+  server,
+  ensureLatestMajor,
+  normalizeProduct,
+  normalizePlatform,
+  normalizeEdition,
+  LATEST_MAJOR,
+  LATEST_VERSIONS
+}) {
+  server.registerTool(
+    "resolve_version",
+    {
+      title: "Resolve Version",
+      description: "Resolve a concrete latest-major version for a product/edition/platform.",
+      inputSchema: {
+        product: z.string().describe("Product: dcv, dbr, dwt, or 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"),
+        constraint: z.string().optional().describe("Version constraint, e.g., latest, 11.x, 10"),
+        feature: z.string().optional().describe("Optional feature hint")
+      }
+    },
+    async ({ product, edition, platform, constraint, feature }) => {
+      const normalizedProduct = normalizeProduct(product);
+      const normalizedPlatform = normalizePlatform(platform);
+      const normalizedEdition = normalizeEdition(edition, normalizedPlatform, normalizedProduct);
+
+      if (!["dcv", "dbr", "dwt", "ddv"].includes(normalizedProduct)) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Unknown product "${product}". Use dcv, dbr, dwt, or ddv.` }]
+        };
+      }
+
+      const policy = ensureLatestMajor({
+        product: normalizedProduct,
+        version: constraint,
+        query: feature,
+        edition: normalizedEdition,
+        platform: normalizedPlatform
+      });
+
+      if (!policy.ok) {
+        return { isError: true, content: [{ type: "text", text: policy.message }] };
+      }
+
+      if (normalizedProduct === "dcv") {
+        if (!normalizedEdition) {
+          const lines = [
+            "# DCV Version Resolution",
+            `- Latest major: v${LATEST_MAJOR.dcv}`,
+            `- Core: ${LATEST_VERSIONS.dcv.core}`,
+            `- Web: ${LATEST_VERSIONS.dcv.web}`,
+            `- Mobile: ${LATEST_VERSIONS.dcv.mobile}`,
+            `- Server/Desktop: ${LATEST_VERSIONS.dcv.server}`,
+            "",
+            "Specify edition/platform to resolve a single version."
+          ];
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+
+        const resolved = LATEST_VERSIONS.dcv[normalizedEdition];
+        if (!resolved) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Edition "${normalizedEdition}" is not hosted by this MCP server.` }]
+          };
+        }
+
+        const displayPlatform = normalizedPlatform === "web" ? "js" : normalizedPlatform;
+        const lines = [
+          "# DCV Version Resolution",
+          `- Edition: ${normalizedEdition}`,
+          displayPlatform ? `- Platform: ${displayPlatform}` : "",
+          `- Latest major: v${LATEST_MAJOR.dcv}`,
+          `- Resolved version: ${resolved}`
+        ].filter(Boolean);
+
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
+      if (normalizedProduct === "dbr") {
+        if (!normalizedEdition) {
+          const lines = [
+            "# DBR Version Resolution",
+            `- Latest major: v${LATEST_MAJOR.dbr}`,
+            `- Mobile: ${LATEST_VERSIONS.dbr.mobile}`,
+            `- Web: ${LATEST_VERSIONS.dbr.web}`,
+            `- Server/Desktop: ${LATEST_VERSIONS.dbr.server}`,
+            "",
+            "Specify edition/platform to resolve a single version."
+          ];
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+
+        const resolved = LATEST_VERSIONS.dbr[normalizedEdition];
+        if (!resolved) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Edition "${normalizedEdition}" is not hosted by this MCP server.` }]
+          };
+        }
+
+        const displayPlatform = normalizedPlatform === "web" ? "js" : normalizedPlatform;
+        const lines = [
+          "# DBR Version Resolution",
+          `- Edition: ${normalizedEdition}`,
+          displayPlatform ? `- Platform: ${displayPlatform}` : "",
+          `- Latest major: v${LATEST_MAJOR.dbr}`,
+          `- Resolved version: ${resolved}`
+        ].filter(Boolean);
+
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
+      if (normalizedProduct === "dwt") {
+        const lines = [
+          "# DWT Version Resolution",
+          `- Latest major: v${LATEST_MAJOR.dwt}`,
+          `- Resolved version: ${LATEST_VERSIONS.dwt.web}`
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
+
+      const lines = [
+        "# DDV Version Resolution",
+        `- Latest major: v${LATEST_MAJOR.ddv}`,
+        `- Resolved version: ${LATEST_VERSIONS.ddv.web}`
+      ];
+
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}

package/src/server/transports/http.js

@@ -0,0 +1,84 @@
+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 }) {
+  logEvent("transport", "server_start", { mode: "http", host, port, path: mcpPath });
+
+  const httpServer = createHttpServer(async (req, res) => {
+    const requestUrl = new URL(req.url || "/", `http://${host}:${port}`);
+    if (requestUrl.pathname !== mcpPath) {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Not Found");
+      return;
+    }
+
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined
+    });
+
+    let closed = false;
+    const closeResources = async () => {
+      if (closed) return;
+      closed = true;
+      try {
+        await transport.close();
+      } catch {}
+      try {
+        await server.close();
+      } catch {}
+    };
+
+    res.on("close", () => {
+      void closeResources();
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logEvent("transport", "request_error", { mode: "http", message }, { level: "error" });
+      if (!res.headersSent) {
+        res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: "Internal server error"
+          },
+          id: null
+        }));
+      }
+      await closeResources();
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(port, host, () => {
+      httpServer.off("error", reject);
+      resolve();
+    });
+  });
+
+  const shutdown = async (signal) => {
+    logEvent("transport", "server_shutdown", { mode: "http", signal });
+    await new Promise((resolve) => {
+      httpServer.close(() => resolve());
+    });
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => {
+    void shutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    void shutdown("SIGTERM");
+  });
+
+  return { httpServer };
+}
+
+export { startHttpServer };

package/src/server/transports/stdio.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { logEvent } from "../../observability/logging.js";
+
+async function startStdioServer({ createServer }) {
+  logEvent("transport", "server_start", { mode: "stdio" });
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return { server, transport };
+}
+
+export { startStdioServer };