simple-dynamsoft-mcp 7.0.1 → 7.1.1

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": "779f3794064a224c3a26740470250389ca9aa0ce",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/779f3794064a224c3a26740470250389ca9aa0ce"
+      "commit": "275eefb2a97512e91cfca139ac58f8a8b6317f8a",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/275eefb2a97512e91cfca139ac58f8a8b6317f8a"
     },
     {
       "name": "data/samples/dynamic-web-twain",

package/data/metadata/dynamsoft_sdks.json

@@ -455,7 +455,7 @@
     "dwt": {
       "name": "Dynamic Web TWAIN",
       "description": "Document scanning SDK for web applications. Supports TWAIN, WIA, ICA, SANE scanners.",
-      "version": "19.3",
+      "version": "19.3.2",
       "default_platform": "web",
       "snippet_path": "dynamic-web-twain",
       "api_docs": "web-twain-api-docs.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.0.1",
+  "version": "7.1.1",
   "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/resources/register-resources.js

@@ -1,9 +1,4 @@
-import {
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-  SubscribeRequestSchema,
-  UnsubscribeRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 export function registerResourceHandlers({
   server,
@@ -12,25 +7,27 @@ export function registerResourceHandlers({
   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 };
-  });
+  for (const entry of getPinnedResources()) {
+    server.registerResource(
+      entry.title,
+      entry.uri,
+      {
+        description: entry.summary,
+        mimeType: entry.mimeType
+      },
+      async (uri) => {
+        const resource = await readResourceContent(uri.toString());
+        if (!resource) {
+          throw new Error(`Resource not found: ${uri}`);
+        }
+        return { contents: [resource] };
+      }
+    );
+  }
 
-  server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    const parsed = parseResourceUri(request.params.uri);
+  async function templateReadHandler(uri) {
+    const uriStr = uri.toString();
+    const parsed = parseResourceUri(uriStr);
     if (parsed && ["dcv", "dbr", "dwt", "ddv"].includes(parsed.product)) {
       const policy = ensureLatestMajor({
         product: parsed.product,
@@ -43,14 +40,25 @@ export function registerResourceHandlers({
       }
     }
 
-    const resource = await readResourceContent(request.params.uri);
+    const resource = await readResourceContent(uriStr);
     if (!resource) {
-      throw new Error(`Resource not found: ${request.params.uri}`);
+      throw new Error(`Resource not found: ${uriStr}`);
     }
 
     return { contents: [resource] };
-  });
+  }
+
+  server.registerResource(
+    "doc-resource",
+    new ResourceTemplate("doc://{product}/{edition}/{platform}/{version}/{+slug}", {}),
+    { description: "Dynamsoft documentation resource" },
+    templateReadHandler
+  );
 
-  server.server.setRequestHandler(SubscribeRequestSchema, async () => ({}));
-  server.server.setRequestHandler(UnsubscribeRequestSchema, async () => ({}));
+  server.registerResource(
+    "sample-resource",
+    new ResourceTemplate("sample://{product}/{edition}/{platform}/{version}/{+rest}", {}),
+    { description: "Dynamsoft sample code resource" },
+    templateReadHandler
+  );
 }

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

@@ -11,14 +11,44 @@ export function registerIndexTools({
   buildIndexData,
   getSampleIdFromUri,
   formatScopeLabel,
-  searchResources
+  searchResources,
+  normalizeSampleName,
+  getSampleEntries,
+  getSampleSuggestions
 }) {
   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: {}
+      description: [
+        "Get a compact index of all Dynamsoft products, editions, platforms, versions, and available docs/samples.",
+        "",
+        "WHEN TO USE:",
+        "- As the first call in any conversation to discover what is available.",
+        "- To determine valid product/edition/platform combinations before calling other tools.",
+        "- To get DBR-vs-DCV selection guidance (DBR for barcode-only; DCV for MRZ, VIN, document normalization, driver license).",
+        "",
+        "WHEN NOT TO USE:",
+        "- Do not call get_index repeatedly; the index is static within a session.",
+        "- If you already know the product/edition/platform, skip directly to search or get_quickstart.",
+        "",
+        "RETURNS: A JSON object with top-level keys: productSelection and products. productSelection contains guidance for choosing between products (for example, DBR vs DCV), and products contains per-product entries (dcv, dbr, dwt, ddv) with editions, platforms, latest versions, and counts of available docs and samples.",
+        "",
+        "PARAMETERS: None.",
+        "",
+        "EXAMPLE WORKFLOW:",
+        "1. Call get_index to discover available products.",
+        "2. Use the returned product/edition/platform values in search, list_samples, or get_quickstart.",
+        "",
+        "RELATED TOOLS: search (find specific resources), list_samples (browse samples), resolve_version (get exact version numbers)."
+      ].join("\n"),
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async () => ({
       content: [{ type: "text", text: JSON.stringify(buildIndexData(), null, 2) }]
@@ -29,21 +59,50 @@ 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 documentation and samples using semantic (RAG) search with fuzzy fallback.",
+        "",
+        "WHEN TO USE:",
+        "- To find docs or samples by keyword, topic, or exact sample ID.",
+        "- To look up specific scenarios: MRZ scanning, VIN reading, barcode decoding, document normalization, etc.",
+        "- When you have a natural-language question about a Dynamsoft SDK.",
+        "- For sample lookup by exact ID (e.g. query='hello-world', type='sample').",
+        "",
+        "WHEN NOT TO USE:",
+        "- To browse all samples in a scope, use list_samples instead.",
+        "- To get starter code quickly, use get_quickstart instead.",
+        "- If you do not know valid products/editions, call get_index first.",
+        "",
+        "PARAMETERS:",
+        "- query (required): Keywords or exact sample ID. Examples: 'barcode scanning from camera', 'MRZ passport reader', 'hello-world'.",
+        "- product: dcv, dbr, dwt, or ddv. Prefer DCV for MRZ/VIN/document-normalization/driver-license; DBR for barcode-only.",
+        "- edition: core, mobile, web, or server.",
+        "- platform: android, ios, js, python, cpp, java, dotnet, nodejs, react, vue, angular, flutter, react-native, maui, etc.",
+        "- version: Version constraint (e.g. '10', '11.x'). Only latest major is served by default.",
+        "- type: 'doc', 'sample', 'index', 'policy', or 'any' (default). Use 'sample' to restrict to sample results.",
+        "- limit: 1-10 (default 5). Max number of results.",
+        "",
+        "RETURNS: An MCP response whose content array includes a leading text summary item followed by zero or more resource_link items with URIs. Use resources/read to fetch full content of doc:// URIs. Use get_sample_files to fetch full project files for sample:// URIs.",
+        "",
+        "RELATED TOOLS: get_index (discover products first), list_samples (browse all samples), get_sample_files (retrieve full sample project files), resources/read (read a doc resource)."
+      ].join("\n"),
       inputSchema: {
-        query: z.string().describe("Keywords to search across docs and samples."),
+        query: z.string().trim().min(1, "Query is required.").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)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     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);
@@ -68,16 +127,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 +283,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,18 +27,50 @@ 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 the full project files for a known sample and return them inline as text.",
+        "",
+        "WHEN TO USE:",
+        "- When you have a sample_id (from list_samples) or a sample:// resource_uri (from search) and need the complete source code.",
+        "- When the user wants to see or scaffold a full sample project (multiple files, build configs, manifests).",
+        "",
+        "WHEN NOT TO USE:",
+        "- If you do not have a sample_id or resource_uri yet, call list_samples or search first to discover one.",
+        "- For doc:// URIs, use resources/read instead (this tool only handles sample:// URIs).",
+        "- If the user just wants a quick code snippet, use get_quickstart instead.",
+        "",
+        "PARAMETERS:",
+        "- product (required): dcv, dbr, dwt, or ddv.",
+        "- edition: mobile, web, or server.",
+        "- platform: android, ios, js, python, cpp, java, dotnet, nodejs, react, vue, angular, flutter, react-native, maui, etc.",
+        "- version: Version constraint. Latest major is used by default.",
+        "- sample_id: Sample identifier as returned by list_samples (e.g. 'hello-world', 'ScanSingleBarcode'). Requires product/edition.",
+        "- resource_uri: A sample:// URI as returned by search (e.g. 'sample://dbr/mobile/android/10/high-level/ScanSingleBarcode'). Preferred over sample_id when available.",
+        "- api_level: 'high-level' or 'low-level' (DBR mobile only).",
+        "",
+        "RETURNS: A text block containing all project files inline, each under a heading with its relative path and wrapped in a fenced code block. Files larger than 50KB are excluded. No zip file is created.",
+        "",
+        "EXAMPLE: get_sample_files with resource_uri='sample://dbr/mobile/android/10/high-level/ScanSingleBarcode' returns all source files for the Android barcode scanning sample.",
+        "",
+        "RELATED TOOLS: list_samples (discover sample IDs), search (find samples by keyword), get_quickstart (quick single-file snippet)."
+      ].join("\n"),
       inputSchema: {
-        product: z.string().describe("Product: dcv, dbr, dwt, or ddv"),
+        product: z.string().trim().min(1, "Product is required.").describe("Product: dcv, dbr, dwt, or ddv"),
         edition: z.string().optional().describe("Edition: 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"),
         version: z.string().optional().describe("Version constraint"),
         sample_id: z.string().optional().describe("Sample identifier (name or path)"),
         resource_uri: z.string().optional().describe("Resource URI returned by search"),
         api_level: z.string().optional().describe("API level: high-level or low-level (mobile only)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async ({ product, edition, platform, version, sample_id, resource_uri, api_level }) => {
@@ -284,10 +316,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-quickstart-tools.js

@@ -29,15 +29,46 @@ export function registerQuickstartTools({
     "get_quickstart",
     {
       title: "Get Quickstart",
-      description: "Opinionated quickstart for a target product/edition/platform. DCV supports MRZ/VIN/document-normalization/driver-license workflows.",
+      description: [
+        "Get an opinionated quickstart with installation instructions and working sample code for a target product/edition/platform.",
+        "",
+        "WHEN TO USE:",
+        "- When the user wants to get started quickly with a Dynamsoft SDK.",
+        "- To generate a ready-to-run code snippet with install commands, license key, and SDK version.",
+        "- For scenario-specific starters: pass scenario='MRZ' for passport reading, 'VIN' for vehicle identification, 'document scan' for document normalization, etc.",
+        "",
+        "WHEN NOT TO USE:",
+        "- If the user wants full project files (multiple source files, build configs), use get_sample_files instead.",
+        "- If the user wants to browse available samples first, use search or list_samples.",
+        "- If the user only needs version info, use resolve_version.",
+        "",
+        "PARAMETERS:",
+        "- product (required): dcv, dbr, dwt, or ddv.",
+        "- edition: core, mobile, web, or server. Inferred from platform if omitted.",
+        "- platform: android, ios, js, python, cpp, java, dotnet, nodejs, react, vue, angular, flutter, react-native, maui, etc.",
+        "- language: kotlin, java, swift, js, ts, python, cpp, csharp, react, vue, angular. Helps select the best sample variant.",
+        "- version: Version constraint. Latest major is used by default.",
+        "- api_level: 'high-level' or 'low-level' (mobile only). Controls API abstraction level in generated code.",
+        "- scenario: MRZ, VIN, document scan, driver license, camera, image, single, multiple, etc. DCV supports MRZ/VIN/document-normalization/driver-license workflows.",
+        "",
+        "RETURNS: A formatted text block with SDK version, trial license key, install commands, and sample code. Ready to copy-paste.",
+        "",
+        "RELATED TOOLS: search (find specific docs or samples), get_sample_files (get full multi-file project), resolve_version (version numbers only)."
+      ].join("\n"),
       inputSchema: {
-        product: z.string().describe("Product: dcv, dbr, dwt, or ddv"),
+        product: z.string().trim().min(1, "Product is required.").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"),
         language: z.string().optional().describe("Language hint: kotlin, java, swift, js, ts, python, cpp, csharp, react, vue, angular"),
         version: z.string().optional().describe("Version constraint"),
         api_level: z.string().optional().describe("API level: high-level or low-level (mobile only)"),
         scenario: z.string().optional().describe("Scenario: camera, image, single, multiple, MRZ, VIN, document scan/normalization, driver license, react, etc.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async ({ product, edition, platform, language, version, api_level, scenario }) => {

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,27 +7,51 @@ export function registerSampleTools({
   normalizeProduct,
   normalizePlatform,
   normalizeEdition,
-  normalizeSampleName,
-  parseSampleUri,
-  resourceIndex,
   getSampleEntries,
   getSampleIdFromUri,
   getDisplayEdition,
-  getDisplayPlatform,
-  formatScopeLabel,
-  searchResources,
-  getSampleSuggestions
+  getDisplayPlatform
 }) {
   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.",
+      description: [
+        "List all available sample IDs and URIs for a given product/edition/platform scope.",
+        "",
+        "WHEN TO USE:",
+        "- To browse the full catalog of samples available for a product/edition/platform.",
+        "- To discover sample IDs before calling get_sample_files.",
+        "- When the user wants to see what samples exist without a specific keyword.",
+        "- Use DCV scope for MRZ, VIN, document normalization, and driver license scenarios.",
+        "",
+        "WHEN NOT TO USE:",
+        "- If you have a specific keyword or topic, use search instead (it ranks results by relevance).",
+        "- If you already have a sample ID or URI, go directly to get_sample_files.",
+        "",
+        "PARAMETERS:",
+        "- product: dcv, dbr, dwt, or ddv. Omit to list across all products.",
+        "- edition: core, mobile, web, or server. Omit to list across all editions.",
+        "- platform: android, ios, js, python, cpp, java, dotnet, nodejs, react, vue, angular, flutter, react-native, maui, etc.",
+        "- limit: 1-200 (default 50). Max number of results.",
+        "",
+        "RETURNS: A single text content item that starts with totals and plain URIs, then appends 'JSON:' followed by a JSON object with total count and sample entries. Each entry includes sample_id, uri (sample:// URI), product, edition, platform, version, title, and summary. Use sample_id or uri with get_sample_files to retrieve full project files.",
+        "",
+        "EXAMPLE: Call list_samples with product='dbr', edition='mobile', platform='android' to see all Android barcode reader samples.",
+        "",
+        "RELATED TOOLS: search (keyword-based discovery), get_sample_files (retrieve full project files for a sample), get_index (discover valid product/edition/platform combinations)."
+      ].join("\n"),
       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)")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async ({ product, edition, platform, limit }) => {
@@ -100,234 +123,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 };
-    }
-  );
 }

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

@@ -13,13 +13,43 @@ export function registerVersionTools({
     "resolve_version",
     {
       title: "Resolve Version",
-      description: "Resolve a concrete latest-major version for a product/edition/platform.",
+      description: [
+        "Resolve a concrete latest-major version number for a Dynamsoft product/edition/platform.",
+        "",
+        "WHEN TO USE:",
+        "- To get the exact current version string (e.g. '10.4.2001') for use in package installation or dependency pinning.",
+        "- When the user asks 'what is the latest version of DBR?'.",
+        "- To verify version compatibility before generating project scaffolding.",
+        "",
+        "WHEN NOT TO USE:",
+        "- If you just need sample code, use get_quickstart (it already includes the correct version).",
+        "- For browsing docs or samples, use search or list_samples (they already scope to latest major).",
+        "",
+        "PARAMETERS:",
+        "- product (required): dcv, dbr, dwt, or ddv.",
+        "- edition: core, mobile, web, or server. Omit to see all editions for the product.",
+        "- platform: android, ios, js, python, cpp, java, dotnet, nodejs, etc. Helps narrow edition when ambiguous.",
+        "- constraint: Version constraint like 'latest', '11.x', '10'. Only latest major version is served; legacy versions (e.g. DBR v9) return an error with migration guidance.",
+        "- feature: Optional feature hint for version policy checks.",
+        "",
+        "RETURNS: A text block showing the resolved version. For DCV/DBR without an edition, returns all edition versions. For DWT/DDV, returns the single web version.",
+        "",
+        "EXAMPLE: resolve_version with product='dbr', edition='web' returns the latest DBR web SDK version string.",
+        "",
+        "RELATED TOOLS: get_quickstart (includes version in starter code), get_index (shows version overview)."
+      ].join("\n"),
       inputSchema: {
-        product: z.string().describe("Product: dcv, dbr, dwt, or ddv"),
+        product: z.string().trim().min(1, "Product is required.").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")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     async ({ product, edition, platform, constraint, feature }) => {