simple-dynamsoft-mcp 7.4.42 → 7.5.0

package/README.md

@@ -296,12 +296,15 @@ mcpServers:
 The server exposes this minimal tool surface:
 
 - `get_index` -- compact product/version/sample index with selection guidance
-- `search` -- semantic search across docs and samples (also accepts exact sample IDs)
+- `search` -- semantic search across docs and samples (also accepts exact sample IDs); returns `doc://` and `sample://` links
+- `read_document` -- read the full text (title, public docs URL, body) of a `doc://` URI returned by `search`
 - `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)
 
+Typical doc Q&A flow: `search` -> `read_document` with the exact `doc://` URI -> answer from the returned text and cite its public URL. Clients that support MCP resources can also fetch the same `doc://` / `sample://` URIs with `resources/read`.
+
 ## Advanced Configuration And Operator Docs
 
 Advanced settings, CI/runbook details, and maintenance workflows live in:

package/package.json

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

@@ -2,7 +2,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ensureDataScopesHydrated } from "../data/bootstrap.js";
 import { createScopeHydrator } from "./helpers/server-helpers.js";
 import { registerResourceHandlers } from "./resources/register-resources.js";
+import { createIndexedResourceReader } from "./resources/read-indexed-resource.js";
 import { registerIndexTools } from "./tools/register-index-tools.js";
+import { registerDocumentTools } from "./tools/register-document-tools.js";
 import { registerSampleTools } from "./tools/register-sample-tools.js";
 import { registerVersionTools } from "./tools/register-version-tools.js";
 import { registerQuickstartTools } from "./tools/register-quickstart-tools.js";
@@ -71,6 +73,8 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
       "",
       "How to use it:",
       "- Call get_index first to see valid product/edition/platform combinations before asking the user anything.",
+      "- To answer from documentation: call search, then call read_document with the exact doc:// uri it returned, and base the answer on that text, citing the public documentation URL it contains. Do not answer from search summaries alone or hand doc:// links to the user.",
+      "- For sample:// results, call get_sample_files with resource_uri to get the complete sample project.",
       "- Only ask the user to disambiguate dimensions that actually vary for the chosen product. Do NOT ask about dimensions that don't apply.",
       "",
       "Platform/edition rules (important):",
@@ -84,6 +88,12 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
     ].join("\n")
   });
 
+  const readIndexedResource = createIndexedResourceReader({
+    parseResourceUri,
+    ensureLatestMajor,
+    readResourceContent
+  });
+
   registerIndexTools({
     server,
     ensureScopeHydrated,
@@ -100,6 +110,11 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
     getSampleSuggestions
   });
 
+  registerDocumentTools({
+    server,
+    readIndexedResource
+  });
+
   registerSampleTools({
     server,
     registry,
@@ -183,9 +198,8 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
   registerResourceHandlers({
     server,
     getPinnedResources,
-    parseResourceUri,
-    ensureLatestMajor,
-    readResourceContent
+    readResourceContent,
+    readIndexedResource
   });
 
   return server;

package/src/server/resources/read-indexed-resource.js

@@ -0,0 +1,33 @@
+// Products whose versioned doc/sample URIs are subject to the latest-major policy.
+const VERSION_POLICY_PRODUCTS = ["dbr", "dwt", "ddv", "mrz", "mds"];
+
+// Shared read path for doc:// and sample:// URIs. Used by the MCP resource
+// templates (resources/read) and the read_document tool so both enforce the
+// same version policy and stale-URI guidance.
+export function createIndexedResourceReader({ parseResourceUri, ensureLatestMajor, readResourceContent }) {
+  return async function readIndexedResource(uri) {
+    const uriStr = String(uri);
+    const parsed = parseResourceUri(uriStr);
+    if (parsed && VERSION_POLICY_PRODUCTS.includes(parsed.product)) {
+      const policy = ensureLatestMajor({
+        product: parsed.product,
+        version: parsed.version,
+        edition: parsed.edition,
+        platform: parsed.platform
+      });
+      if (!policy.ok) {
+        throw new Error(policy.message);
+      }
+    }
+
+    const resource = await readResourceContent(uriStr);
+    if (!resource) {
+      // Doc URIs embed a positional index + exact version, so they can go stale
+      // across data refreshes. Point the agent back to search to re-discover the
+      // current URI instead of dead-ending (issue #153).
+      throw new Error(`Resource not found: ${uriStr}. The URI may be stale (doc URIs change across data refreshes). Call search with keywords from the title to get the current URI.`);
+    }
+
+    return resource;
+  };
+}

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

@@ -3,9 +3,8 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 export function registerResourceHandlers({
   server,
   getPinnedResources,
-  parseResourceUri,
-  ensureLatestMajor,
-  readResourceContent
+  readResourceContent,
+  readIndexedResource
 }) {
   for (const entry of getPinnedResources()) {
     server.registerResource(
@@ -26,29 +25,7 @@ export function registerResourceHandlers({
   }
 
   async function templateReadHandler(uri) {
-    const uriStr = uri.toString();
-    const parsed = parseResourceUri(uriStr);
-    if (parsed && ["dbr", "dwt", "ddv", "mrz", "mds"].includes(parsed.product)) {
-      const policy = ensureLatestMajor({
-        product: parsed.product,
-        version: parsed.version,
-        edition: parsed.edition,
-        platform: parsed.platform
-      });
-      if (!policy.ok) {
-        throw new Error(policy.message);
-      }
-    }
-
-    const resource = await readResourceContent(uriStr);
-    if (!resource) {
-      // Doc URIs embed a positional index + exact version, so they can go stale
-      // across data refreshes. Point the agent back to search to re-discover the
-      // current URI instead of dead-ending (issue #153).
-      throw new Error(`Resource not found: ${uriStr}. The URI may be stale (doc URIs change across data refreshes). Call search with keywords from the title to get the current URI.`);
-    }
-
-    return { contents: [resource] };
+    return { contents: [await readIndexedResource(uri.toString())] };
   }
 
   server.registerResource(

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

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { logEvent } from "../../observability/logging.js";
+
+function errorResult(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+
+export function registerDocumentTools({ server, readIndexedResource }) {
+  server.registerTool(
+    "read_document",
+    {
+      title: "Read Document",
+      description: [
+        "Read the full text of a Dynamsoft documentation page by its doc:// URI.",
+        "",
+        "WHEN TO USE:",
+        "- After search returns doc:// results: call read_document with the exact uri from a resource_link or the plain URI list before answering.",
+        "- When you need the actual article body (API details, parameters, code snippets) instead of the search summary.",
+        "",
+        "WHEN NOT TO USE:",
+        "- For sample:// URIs, use get_sample_files with resource_uri instead (complete sample projects).",
+        "- Do not construct or edit doc:// URIs yourself; they are generated by search and may change across data refreshes.",
+        "",
+        "PARAMETERS:",
+        "- uri (required): The exact doc:// URI returned by search (e.g. a resource_link uri).",
+        "",
+        "RETURNS: The document as markdown text: title, public documentation URL (cite it in answers), and the full article body.",
+        "On failure (stale or missing URI, unsupported version, unsupported scheme) returns isError with guidance; call search again to get a current URI.",
+        "",
+        "RELATED TOOLS: search (find doc:// URIs), get_sample_files (read sample:// projects), get_quickstart (starter code)."
+      ].join("\n"),
+      inputSchema: {
+        uri: z.string().trim().min(1, "uri is required.").describe("Exact doc:// URI returned by search.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ uri }) => {
+      const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(uri)?.[1]?.toLowerCase();
+      if (scheme === "sample") {
+        return errorResult(`read_document only reads doc:// URIs. For sample:// URIs, call get_sample_files with resource_uri="${uri}".`);
+      }
+      if (scheme !== "doc") {
+        return errorResult(`Unsupported URI: "${uri}". read_document accepts only doc:// URIs returned by search.`);
+      }
+
+      let resource;
+      try {
+        resource = await readIndexedResource(uri);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logEvent("read_document", "read_failed", { uri, error: message });
+        return errorResult(`Failed to read document: ${message}`);
+      }
+
+      const text = typeof resource.text === "string" ? resource.text : "";
+      if (!text.trim()) {
+        logEvent("read_document", "empty_document", { uri });
+        return errorResult(`Document ${uri} has no readable text content. Call search again to find an alternative document.`);
+      }
+
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}

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

@@ -118,9 +118,9 @@ export function registerIndexTools({
         "- 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.",
+        "RETURNS: An MCP response whose content array includes a leading text summary item followed by zero or more resource_link items with URIs. For doc:// URIs, call read_document with the exact returned uri to get the full document text before answering. For sample:// URIs, call get_sample_files with resource_uri to get the full project files.",
         "",
-        "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)."
+        "RELATED TOOLS: get_index (discover products first), list_samples (browse all samples), read_document (read a doc:// result), get_sample_files (retrieve full sample project files)."
       ].join("\n"),
       inputSchema: {
         query: z.string().trim().min(1, "Query is required.").describe("Keywords to search across docs and samples."),
@@ -199,7 +199,7 @@ export function registerIndexTools({
           const content = [
             {
               type: "text",
-              text: `Found ${selected.length} exact match(es) for "${query}". Read the links you need with resources/read.`
+              text: `Found ${selected.length} exact match(es) for "${query}". Call get_sample_files with the exact resource_uri to get the full sample project.`
             }
           ];
 
@@ -325,9 +325,10 @@ export function registerIndexTools({
       // Capture Vision / DCV is the umbrella framework, not a selectable public
       // product — steer the agent to the right offering (issue #150).
       const dcvUmbrella = /\b(capture[\s-]?vision|dcv)\b/i.test(query) && !normalizedProduct;
+      const readGuidance = "For doc:// results, call read_document with the exact uri to get the document text; for sample:// results, call get_sample_files with resource_uri.";
       const leadText = dcvUmbrella
-        ? `"Capture Vision" (DCV) is Dynamsoft's umbrella framework — pick the public product for your task: DBR (barcodes), MRZ (passports/IDs), MDS (document capture), DWT (scanner hardware), DDV (document viewer). Results below span the closest matches.\nFound ${topResults.length} result(s) for "${query}".`
-        : `Found ${topResults.length} result(s) for "${query}". Read the links you need with resources/read.`;
+        ? `"Capture Vision" (DCV) is Dynamsoft's umbrella framework — pick the public product for your task: DBR (barcodes), MRZ (passports/IDs), MDS (document capture), DWT (scanner hardware), DDV (document viewer). Results below span the closest matches.\nFound ${topResults.length} result(s) for "${query}". ${readGuidance}`
+        : `Found ${topResults.length} result(s) for "${query}". ${readGuidance}`;
       const content = [
         {
           type: "text",
@@ -356,7 +357,7 @@ export function registerIndexTools({
 
       const plainLines = topResults.map((entry, index) => {
         const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
-        const action = entry.type === "sample" ? "get_sample_files resource_uri" : "resources/read uri";
+        const action = entry.type === "sample" ? "get_sample_files resource_uri" : "read_document 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

@@ -83,7 +83,7 @@ export function registerProjectTools({
         "",
         "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).",
+        "- For doc:// URIs, use read_document instead (this tool only handles sample:// URIs).",
         "- If the user just wants a quick code snippet, use get_quickstart instead.",
         "",
         "PARAMETERS:",
@@ -137,7 +137,7 @@ export function registerProjectTools({
             isError: true,
             content: [{
               type: "text",
-              text: "resource_uri must use the sample:// scheme. For doc:// URIs, use resources/read instead."
+              text: "resource_uri must use the sample:// scheme. For doc:// URIs, call read_document with the exact uri instead."
             }]
           };
         }