simple-dynamsoft-mcp 7.1.0 → 7.1.1

package/data/metadata/data-manifest.json

@@ -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.1.0",
+  "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/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

@@ -20,8 +20,35 @@ export function registerIndexTools({
     "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) }]
@@ -32,21 +59,50 @@ export function registerIndexTools({
     "search",
     {
       title: "Search",
-      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.",
+      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);

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

@@ -30,15 +30,47 @@ export function registerProjectTools({
     "get_sample_files",
     {
       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.",
+      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 }) => {

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

@@ -16,12 +16,42 @@ export function registerSampleTools({
     "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 }) => {

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 }) => {