simple-dynamsoft-mcp 7.0.0 → 7.1.0

package/README.md

@@ -223,13 +223,23 @@ Location:
 
 The server exposes this minimal tool surface:
 
-- `get_index`
-- `search`
-- `list_samples`
-- `resolve_sample`
-- `resolve_version`
-- `get_quickstart`
-- `generate_project`
+- `get_index` -- compact product/version/sample index with selection guidance
+- `search` -- semantic search across docs and samples (also accepts exact sample IDs)
+- `list_samples` -- browse available samples for a product/edition/platform
+- `resolve_version` -- resolve current version for a product/edition/platform
+- `get_quickstart` -- opinionated quickstart: picks a sample by scenario, returns code + install instructions
+- `get_sample_files` -- get full project files for a known sample (discovered via list_samples or search)
+
+## Companion: Dynamsoft SDK Skills
+
+For AI agents that support skills (Claude Code, OpenCode, Codex), install [dynamsoft-sdk-skills](https://github.com/user/dynamsoft-sdk-skills) for guided integration workflows:
+
+    npx dynamsoft-sdk-skills install --all
+
+- **Skills** provide integration patterns, gotchas, and decision trees (loaded into agent context)
+- **MCP Server** provides runtime tools: version resolution, doc search, sample browsing, and retrieval of full sample project files
+
+Both work independently, but together the skills guide agents to use MCP tools at the right moments.
 
 ## Quick Troubleshooting
 

package/data/metadata/data-manifest.json

@@ -8,8 +8,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "barcode-reader-docs-js",
-      "commit": "10c2fc25201f89eb5a6a412bce5fe2fb7e4b3f5f",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-js/zip/10c2fc25201f89eb5a6a412bce5fe2fb7e4b3f5f"
+      "commit": "acab784e29ff035b355dcd6d6ebe284fcb34eef3",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-js/zip/acab784e29ff035b355dcd6d6ebe284fcb34eef3"
     },
     {
       "name": "data/documentation/barcode-reader-docs-mobile",
@@ -88,8 +88,8 @@
       "branch": "master",
       "owner": "dynamsoft-docs",
       "repo": "web-twain-docs",
-      "commit": "5da9b65024e8eeecab1dced934638c57cafe0b79",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/5da9b65024e8eeecab1dced934638c57cafe0b79"
+      "commit": "779f3794064a224c3a26740470250389ca9aa0ce",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/779f3794064a224c3a26740470250389ca9aa0ce"
     },
     {
       "name": "data/samples/dynamic-web-twain",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "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": {

package/src/server/create-server.js

@@ -75,7 +75,10 @@ registerIndexTools({
   buildIndexData,
   getSampleIdFromUri,
   formatScopeLabel,
-  searchResources
+  searchResources,
+  normalizeSampleName,
+  getSampleEntries,
+  getSampleSuggestions
 });
 
 registerSampleTools({
@@ -85,16 +88,10 @@ registerSampleTools({
   normalizeProduct,
   normalizePlatform,
   normalizeEdition,
-  normalizeSampleName,
-  parseSampleUri,
-  resourceIndex,
   getSampleEntries,
   getSampleIdFromUri,
   getDisplayEdition,
-  getDisplayPlatform,
-  formatScopeLabel,
-  searchResources,
-  getSampleSuggestions
+  getDisplayPlatform
 });
 
 registerVersionTools({

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

@@ -11,7 +11,10 @@ export function registerIndexTools({
   buildIndexData,
   getSampleIdFromUri,
   formatScopeLabel,
-  searchResources
+  searchResources,
+  normalizeSampleName,
+  getSampleEntries,
+  getSampleSuggestions
 }) {
   server.registerTool(
     "get_index",
@@ -29,7 +32,7 @@ export function registerIndexTools({
     "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.",
+      description: "Search across docs and samples with semantic (RAG) search and fuzzy fallback. Accepts keywords or exact sample IDs. 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"),
@@ -68,16 +71,126 @@ export function registerIndexTools({
       }
 
       const maxResults = Math.min(limit || 5, 10);
+
+      // Exact sample-ID fast path (when searching for samples)
+      const effectiveType = type || "any";
+      if (effectiveType === "sample" || effectiveType === "any") {
+        const normalizedQuery = normalizeSampleName(query);
+        const scopedSamples = getSampleEntries({
+          product: normalizedProduct,
+          edition: normalizedEdition,
+          platform: normalizedPlatform
+        });
+        const exactMatches = scopedSamples.filter((entry) => {
+          const entryId = getSampleIdFromUri(entry.uri);
+          return entryId && entryId.toLowerCase() === normalizedQuery.toLowerCase();
+        });
+        if (exactMatches.length > 0) {
+          const selected = exactMatches.slice(0, maxResults);
+          const content = [
+            {
+              type: "text",
+              text: `Found ${selected.length} exact match(es) for "${query}". Read the links you need with resources/read.`
+            }
+          ];
+
+          for (const entry of selected) {
+            const versionLabel = entry.version ? `v${entry.version}` : "n/a";
+            const scopeLabel = formatScopeLabel(entry);
+            const sampleId = 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 = selected.map((entry, index) => {
+            const sampleId = getSampleIdFromUri(entry.uri);
+            const action = "get_sample_files resource_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 };
+        }
+      }
+
       const topResults = await searchResources({
         query,
         product: normalizedProduct,
         edition: normalizedEdition,
         platform: normalizedPlatform,
-        type: type || "any",
+        type: effectiveType,
         limit: maxResults
       });
 
       if (topResults.length === 0) {
+        // Only try sample suggestions when searching samples or any type
+        if (effectiveType === "sample" || effectiveType === "any") {
+          const suggestions = await getSampleSuggestions({
+            query,
+            product: normalizedProduct,
+            edition: normalizedEdition,
+            platform: normalizedPlatform,
+            limit: maxResults
+          });
+
+          if (suggestions.length > 0) {
+            const content = [
+              {
+                type: "text",
+                text: `No exact results for "${query}". Related samples:`
+              }
+            ];
+
+            for (const entry of suggestions) {
+              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.6
+                }
+              });
+            }
+
+            const plainLines = suggestions.map((entry, index) => {
+              const sampleId = entry.type === "sample" ? 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 { content };
+          }
+        }
+
         return {
           content: [{
             type: "text",
@@ -114,7 +227,7 @@ export function registerIndexTools({
 
       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 action = entry.type === "sample" ? "get_sample_files resource_uri" : "resources/read uri";
         const sampleNote = sampleId ? ` sample_id=${sampleId}` : "";
         const scoreNote = formatScoreNote(entry);
         return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote} (${action})`;

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

@@ -27,10 +27,10 @@ export function registerProjectTools({
   getSampleSuggestions
 }) {
   server.registerTool(
-    "generate_project",
+    "get_sample_files",
     {
-      title: "Generate Project",
-      description: "Generate a project structure from a sample and return files inline (no zip/download).",
+      title: "Get Sample Files",
+      description: "Get project files for a known sample (by sample_id or resource_uri) and return them inline. Use list_samples or search to discover sample IDs first.",
       inputSchema: {
         product: z.string().describe("Product: dcv, dbr, dwt, or ddv"),
         edition: z.string().optional().describe("Edition: mobile, web, server/desktop"),
@@ -284,10 +284,10 @@ export function registerProjectTools({
       const validFiles = files.filter((f) => f.content.length < 50000);
 
       const output = [
-        `# Project Generation: ${sampleLabel}`,
+        `# Sample Files: ${sampleLabel}`,
         "",
-        "This output contains the file structure for the project.",
-        "Note: This tool returns files inline and does not create a downloadable zip.",
+        "Below are the retrieved sample project files.",
+        "Note: Files are returned inline and no downloadable zip is created.",
         ""
       ];
 

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

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { formatScoreLabel, formatScoreNote } from "../helpers/server-helpers.js";
 
 export function registerSampleTools({
   server,
@@ -8,16 +7,10 @@ export function registerSampleTools({
   normalizeProduct,
   normalizePlatform,
   normalizeEdition,
-  normalizeSampleName,
-  parseSampleUri,
-  resourceIndex,
   getSampleEntries,
   getSampleIdFromUri,
   getDisplayEdition,
-  getDisplayPlatform,
-  formatScopeLabel,
-  searchResources,
-  getSampleSuggestions
+  getDisplayPlatform
 }) {
   server.registerTool(
     "list_samples",
@@ -100,234 +93,4 @@ export function registerSampleTools({
       };
     }
   );
-
-  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 };
-    }
-  );
 }