simple-dynamsoft-mcp 2.0.5 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "2.0.5",
+  "version": "2.2.0",
   "description": "MCP server for Dynamsoft SDKs - Barcode Reader (Mobile/Python/Web) and Dynamic Web TWAIN. Provides documentation, code snippets, and API guidance.",
   "repository": {
     "type": "git",

package/src/index.js

@@ -12,6 +12,9 @@ const projectRoot = join(__dirname, "..");
 const registryUrl = new URL("../data/dynamsoft_sdks.json", import.meta.url);
 const registry = JSON.parse(readFileSync(registryUrl, "utf8"));
 
+const dwtDocsUrl = new URL("../data/web-twain-api-docs.json", import.meta.url);
+const dwtDocs = JSON.parse(readFileSync(dwtDocsUrl, "utf8"));
+
 const codeSnippetRoot = join(projectRoot, "code-snippet");
 
 // ============================================================================
@@ -213,6 +216,78 @@ function discoverPythonSamples() {
   return samples;
 }
 
+function discoverWebSamples() {
+  const categories = {
+    "root": [],
+    "frameworks": [],
+    "scenarios": []
+  };
+  const webPath = join(codeSnippetRoot, "dynamsoft-barcode-reader", "web");
+
+  if (!existsSync(webPath)) return categories;
+
+  // Find HTML files in root
+  for (const entry of readdirSync(webPath, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".html")) {
+      categories["root"].push(entry.name.replace(".html", ""));
+    }
+  }
+
+  // Find samples in subdirectories
+  for (const subdir of ["frameworks", "scenarios"]) {
+    const subdirPath = join(webPath, subdir);
+    if (existsSync(subdirPath)) {
+      for (const entry of readdirSync(subdirPath, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          categories[subdir].push(entry.name);
+        } else if (entry.isFile() && entry.name.endsWith(".html")) {
+          categories[subdir].push(entry.name.replace(".html", ""));
+        }
+      }
+    }
+  }
+
+  // Remove empty categories
+  for (const [key, value] of Object.entries(categories)) {
+    if (value.length === 0) delete categories[key];
+  }
+
+  return categories;
+}
+
+function getWebSamplePath(category, sampleName) {
+  const webPath = join(codeSnippetRoot, "dynamsoft-barcode-reader", "web");
+
+  if (category === "root" || !category) {
+    // Try root level
+    const htmlPath = join(webPath, `${sampleName}.html`);
+    if (existsSync(htmlPath)) return htmlPath;
+  } else {
+    // Try in subdirectory
+    const dirPath = join(webPath, category, sampleName);
+    if (existsSync(dirPath) && statSync(dirPath).isDirectory()) {
+      // Look for index.html or main html file
+      const indexPath = join(dirPath, "index.html");
+      if (existsSync(indexPath)) return indexPath;
+      // Look for any html file
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.endsWith(".html")) {
+          return join(dirPath, entry.name);
+        }
+      }
+    }
+    // Try as html file directly
+    const htmlPath = join(webPath, category, `${sampleName}.html`);
+    if (existsSync(htmlPath)) return htmlPath;
+  }
+
+  // Fallback: search all
+  const rootPath = join(webPath, `${sampleName}.html`);
+  if (existsSync(rootPath)) return rootPath;
+
+  return null;
+}
+
 function discoverDwtSamples() {
   const categories = {};
   const dwtPath = join(codeSnippetRoot, "dynamic-web-twain");
@@ -382,7 +457,9 @@ server.registerTool(
     lines.push("- `list_sdks` - List all SDKs");
     lines.push("- `get_sdk_info` - Get detailed SDK info for a platform");
     lines.push("- `list_samples` - List code samples (mobile)");
+    lines.push("- `list_web_samples` - List web barcode reader samples");
     lines.push("- `get_code_snippet` - Get actual source code");
+    lines.push("- `get_web_sample` - Get web barcode reader sample code");
     lines.push("- `get_quick_start` - Get complete working example");
     lines.push("- `get_gradle_config` - Get Android build config");
     lines.push("- `get_license_info` - Get license setup code");
@@ -391,6 +468,8 @@ server.registerTool(
     lines.push("- `get_python_sample` - Get Python SDK sample code");
     lines.push("- `get_dwt_sample` - Get Dynamic Web TWAIN sample");
     lines.push("- `list_dwt_categories` - List DWT sample categories");
+    lines.push("- `search_dwt_docs` - Search DWT API documentation");
+    lines.push("- `get_dwt_api_doc` - Get specific DWT documentation article");
 
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
@@ -576,6 +655,99 @@ server.registerTool(
   }
 );
 
+// ============================================================================
+// TOOL: list_web_samples
+// ============================================================================
+
+server.registerTool(
+  "list_web_samples",
+  {
+    title: "List Web Barcode Samples",
+    description: "List available JavaScript/Web barcode reader code samples",
+    inputSchema: {}
+  },
+  async () => {
+    const categories = discoverWebSamples();
+    const sdkEntry = registry.sdks["dbr-web"];
+
+    const lines = [
+      "# Web Barcode Reader Samples",
+      "",
+      `**SDK Version:** ${sdkEntry.version}`,
+      `**Install:** \`npm install dynamsoft-barcode-reader-bundle\``,
+      `**CDN:** \`${sdkEntry.platforms.web.installation.cdn}\``,
+      "",
+      "## Available Samples",
+      ""
+    ];
+
+    for (const [category, samples] of Object.entries(categories)) {
+      const categoryTitle = category === "root" ? "Basic Samples" : category.charAt(0).toUpperCase() + category.slice(1);
+      lines.push(`### ${categoryTitle}`);
+      lines.push(samples.map(s => `- ${s}`).join("\n"));
+      lines.push("");
+    }
+
+    lines.push("Use `get_web_sample` with sample_name to get code.");
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+// ============================================================================
+// TOOL: get_web_sample
+// ============================================================================
+
+server.registerTool(
+  "get_web_sample",
+  {
+    title: "Get Web Barcode Sample",
+    description: "Get JavaScript/Web barcode reader sample code",
+    inputSchema: {
+      sample_name: z.string().describe("Sample name, e.g. hello-world, read-an-image"),
+      category: z.string().optional().describe("Category: root, frameworks, scenarios (optional)")
+    }
+  },
+  async ({ sample_name, category }) => {
+    const samplePath = getWebSamplePath(category, sample_name);
+
+    if (!samplePath) {
+      const categories = discoverWebSamples();
+      const allSamples = Object.entries(categories)
+        .map(([cat, samples]) => samples.map(s => `${cat}/${s}`))
+        .flat();
+      return {
+        content: [{
+          type: "text",
+          text: `Sample "${sample_name}" not found.\n\nAvailable samples:\n${allSamples.map(s => `- ${s}`).join("\n")}\n\nUse \`list_web_samples\` to see all available samples.`
+        }]
+      };
+    }
+
+    const content = readCodeFile(samplePath);
+    if (!content) {
+      return { content: [{ type: "text", text: `Could not read "${sample_name}".` }] };
+    }
+
+    const sdkEntry = registry.sdks["dbr-web"];
+
+    const output = [
+      `# Web Barcode Reader: ${sample_name}`,
+      "",
+      `**SDK Version:** ${sdkEntry.version}`,
+      `**Install:** \`npm install dynamsoft-barcode-reader-bundle\``,
+      `**CDN:** \`${sdkEntry.platforms.web.installation.cdn}\``,
+      `**Trial License:** \`${registry.trial_license}\``,
+      "",
+      "```html",
+      content,
+      "```"
+    ];
+
+    return { content: [{ type: "text", text: output.join("\n") }] };
+  }
+);
+
 // ============================================================================
 // TOOL: list_dwt_categories
 // ============================================================================
@@ -609,6 +781,161 @@ server.registerTool(
     }
 
     lines.push("Use `get_dwt_sample` with category and sample_name to get code.");
+    lines.push("");
+    lines.push("**API Documentation Tools:**");
+    lines.push("- `search_dwt_docs` - Search DWT API documentation by keyword");
+    lines.push("- `get_dwt_api_doc` - Get specific DWT documentation article");
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+// ============================================================================
+// TOOL: search_dwt_docs
+// ============================================================================
+
+server.registerTool(
+  "search_dwt_docs",
+  {
+    title: "Search DWT Documentation",
+    description: "Search Dynamic Web TWAIN API documentation by keyword. Returns matching articles with titles, URLs, and content excerpts.",
+    inputSchema: {
+      query: z.string().describe("Search keyword or phrase (e.g., 'LoadImage', 'PDF', 'scanner', 'OCR')"),
+      max_results: z.number().optional().describe("Maximum number of results to return (default: 5)")
+    }
+  },
+  async ({ query, max_results = 5 }) => {
+    const searchTerms = query.toLowerCase().split(/\s+/);
+    const results = [];
+
+    for (const article of dwtDocs.articles) {
+      const titleLower = article.title.toLowerCase();
+      const contentLower = article.content.toLowerCase();
+      const breadcrumbLower = (article.breadcrumb || "").toLowerCase();
+
+      // Score based on matches in title (higher weight), breadcrumb, and content
+      let score = 0;
+      for (const term of searchTerms) {
+        if (titleLower.includes(term)) score += 10;
+        if (breadcrumbLower.includes(term)) score += 5;
+        if (contentLower.includes(term)) score += 1;
+      }
+
+      if (score > 0) {
+        // Extract a relevant excerpt (first 300 chars that contain a search term)
+        let excerpt = article.content.substring(0, 300);
+        for (const term of searchTerms) {
+          const idx = contentLower.indexOf(term);
+          if (idx > 50) {
+            const start = Math.max(0, idx - 50);
+            excerpt = "..." + article.content.substring(start, start + 300) + "...";
+            break;
+          }
+        }
+
+        results.push({
+          title: article.title,
+          url: article.url,
+          breadcrumb: article.breadcrumb,
+          score,
+          excerpt: excerpt.replace(/\n+/g, " ").trim()
+        });
+      }
+    }
+
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    const topResults = results.slice(0, max_results);
+
+    if (topResults.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: `No documentation found for "${query}".\n\nTry different keywords like:\n- API names: LoadImage, SaveAsPDF, AcquireImage\n- Features: scanner, PDF, OCR, barcode\n- Topics: initialization, upload, viewer`
+        }]
+      };
+    }
+
+    const lines = [
+      `# DWT Documentation Search: "${query}"`,
+      "",
+      `Found ${results.length} matches. Showing top ${topResults.length}:`,
+      ""
+    ];
+
+    for (let i = 0; i < topResults.length; i++) {
+      const r = topResults[i];
+      lines.push(`## ${i + 1}. ${r.title}`);
+      lines.push(`**Category:** ${r.breadcrumb}`);
+      lines.push(`**URL:** ${r.url}`);
+      lines.push("");
+      lines.push(`> ${r.excerpt}`);
+      lines.push("");
+    }
+
+    lines.push("Use `get_dwt_api_doc` with the article title to get full documentation.");
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+// ============================================================================
+// TOOL: get_dwt_api_doc
+// ============================================================================
+
+server.registerTool(
+  "get_dwt_api_doc",
+  {
+    title: "Get DWT API Documentation",
+    description: "Get full Dynamic Web TWAIN documentation article by title or URL. Use search_dwt_docs first to find relevant articles.",
+    inputSchema: {
+      title: z.string().describe("Article title or partial title to match (e.g., 'Loading Documents', 'OCR', 'PDF')")
+    }
+  },
+  async ({ title }) => {
+    const titleLower = title.toLowerCase();
+
+    // Try exact match first, then partial match
+    let article = dwtDocs.articles.find(a => a.title.toLowerCase() === titleLower);
+
+    if (!article) {
+      // Try partial match on title
+      article = dwtDocs.articles.find(a => a.title.toLowerCase().includes(titleLower));
+    }
+
+    if (!article) {
+      // Try matching URL
+      article = dwtDocs.articles.find(a => a.url.toLowerCase().includes(titleLower));
+    }
+
+    if (!article) {
+      // Suggest similar articles
+      const suggestions = dwtDocs.articles
+        .filter(a => {
+          const words = titleLower.split(/\s+/);
+          return words.some(w => a.title.toLowerCase().includes(w) || a.breadcrumb.toLowerCase().includes(w));
+        })
+        .slice(0, 5)
+        .map(a => `- ${a.title}`);
+
+      return {
+        content: [{
+          type: "text",
+          text: `Article "${title}" not found.\n\n${suggestions.length > 0 ? `Similar articles:\n${suggestions.join("\n")}` : "Use search_dwt_docs to find relevant articles."}`
+        }]
+      };
+    }
+
+    const lines = [
+      `# ${article.title}`,
+      "",
+      `**Category:** ${article.breadcrumb}`,
+      `**URL:** ${article.url}`,
+      "",
+      "---",
+      "",
+      article.content
+    ];
 
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
@@ -906,6 +1233,49 @@ server.registerTool(
       };
     }
 
+    // Handle Web Barcode Reader SDK
+    if (sdkId === "dbr-web") {
+      const sdkEntry = registry.sdks["dbr-web"];
+      const sampleName = use_case?.includes("image") ? "read-an-image" : "hello-world";
+      const samplePath = getWebSamplePath("root", sampleName);
+
+      if (!samplePath || !existsSync(samplePath)) {
+        return { content: [{ type: "text", text: `Sample not found. Use list_web_samples to see available.` }] };
+      }
+
+      const content = readCodeFile(samplePath);
+
+      return {
+        content: [{
+          type: "text", text: [
+            "# Quick Start: Web Barcode Reader",
+            "",
+            `**SDK Version:** ${sdkEntry.version}`,
+            `**Trial License:** \`${registry.trial_license}\``,
+            "",
+            "## Option 1: CDN",
+            "```html",
+            `<script src="${sdkEntry.platforms.web.installation.cdn}"></script>`,
+            "```",
+            "",
+            "## Option 2: NPM",
+            "```bash",
+            "npm install dynamsoft-barcode-reader-bundle",
+            "```",
+            "",
+            `## Sample: ${sampleName}.html`,
+            "```html",
+            content,
+            "```",
+            "",
+            "## Notes",
+            "- Trial license requires network connection",
+            `- User Guide: ${sdkEntry.platforms.web.docs["user-guide"]}`
+          ].join("\n")
+        }]
+      };
+    }
+
     // Handle Mobile SDK (original logic)
     const level = normalizeApiLevel(api_level);
     const platformKey = platform || "android";
@@ -1406,6 +1776,29 @@ for (const sampleName of pythonSamples) {
   );
 }
 
+// Register Web barcode reader sample resources
+const webCategories = discoverWebSamples();
+for (const [category, samples] of Object.entries(webCategories)) {
+  for (const sampleName of samples) {
+    const resourceUri = `dynamsoft://samples/web/${category}/${sampleName}`;
+    const resourceName = `web-${category}-${sampleName}`.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    server.registerResource(
+      resourceName,
+      resourceUri,
+      {
+        title: `Web: ${sampleName}`,
+        description: `Web barcode reader ${category}: ${sampleName}`,
+        mimeType: "text/html"
+      },
+      async (uri) => {
+        const samplePath = getWebSamplePath(category, sampleName);
+        const content = samplePath && existsSync(samplePath) ? readCodeFile(samplePath) : "Sample not found";
+        return { contents: [{ uri: uri.href, text: content, mimeType: "text/html" }] };
+      }
+    );
+  }
+}
+
 // Register DWT sample resources
 const dwtCategories = discoverDwtSamples();
 for (const [category, samples] of Object.entries(dwtCategories)) {
@@ -1429,6 +1822,35 @@ for (const [category, samples] of Object.entries(dwtCategories)) {
   }
 }
 
+// Register DWT API documentation resources
+for (let i = 0; i < dwtDocs.articles.length; i++) {
+  const article = dwtDocs.articles[i];
+  const resourceName = `dwt-doc-${i}`.toLowerCase();
+  const resourceUri = `dynamsoft://docs/dwt/${encodeURIComponent(article.title)}`;
+  server.registerResource(
+    resourceName,
+    resourceUri,
+    {
+      title: `DWT Doc: ${article.title}`,
+      description: `${article.breadcrumb}: ${article.title}`,
+      mimeType: "text/markdown"
+    },
+    async (uri) => {
+      const content = [
+        `# ${article.title}`,
+        "",
+        `**Category:** ${article.breadcrumb}`,
+        `**URL:** ${article.url}`,
+        "",
+        "---",
+        "",
+        article.content
+      ].join("\n");
+      return { contents: [{ uri: uri.href, text: content, mimeType: "text/markdown" }] };
+    }
+  );
+}
+
 // ============================================================================
 // Start Server
 // ============================================================================

package/test/server.test.js

@@ -121,7 +121,7 @@ await test('Server responds to initialize request', async () => {
 });
 
 // Test 2: List tools
-await test('tools/list returns all 14 tools', async () => {
+await test('tools/list returns all 18 tools', async () => {
     const response = await sendRequest({
         jsonrpc: '2.0',
         id: 1,
@@ -130,14 +130,15 @@ await test('tools/list returns all 14 tools', async () => {
 
     assert(response.result, 'Should have result');
     assert(response.result.tools, 'Should have tools array');
-    assert(response.result.tools.length === 14, `Expected 14 tools, got ${response.result.tools.length}`);
+    assert(response.result.tools.length === 18, `Expected 18 tools, got ${response.result.tools.length}`);
 
     const toolNames = response.result.tools.map(t => t.name);
     const expectedTools = [
         'list_sdks', 'get_sdk_info', 'list_samples', 'list_python_samples',
-        'list_dwt_categories', 'get_code_snippet', 'get_python_sample',
-        'get_dwt_sample', 'get_quick_start', 'get_gradle_config',
-        'get_license_info', 'get_api_usage', 'search_samples', 'generate_project'
+        'list_web_samples', 'list_dwt_categories', 'get_code_snippet',
+        'get_web_sample', 'get_python_sample', 'get_dwt_sample', 'get_quick_start',
+        'get_gradle_config', 'get_license_info', 'get_api_usage', 'search_samples',
+        'generate_project', 'search_dwt_docs', 'get_dwt_api_doc'
     ];
 
     for (const expected of expectedTools) {
@@ -347,7 +348,81 @@ await test('generate_project returns project structure', async () => {
     assert(text.includes('AndroidManifest.xml') || text.includes('build.gradle'), 'Should include project files');
 });
 
-// Test 14: resources/list returns registered resources
+// Test 14: list_web_samples tool
+await test('list_web_samples returns web barcode samples', async () => {
+    const response = await sendRequest({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: 'list_web_samples',
+            arguments: {}
+        }
+    });
+
+    assert(response.result, 'Should have result');
+    assert(response.result.content, 'Should have content');
+    const text = response.result.content[0].text;
+    assert(text.includes('Web Barcode Reader Samples'), 'Should include web samples header');
+});
+
+// Test 15: get_web_sample tool
+await test('get_web_sample returns web barcode sample code', async () => {
+    const response = await sendRequest({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: 'get_web_sample',
+            arguments: { sample_name: 'hello-world' }
+        }
+    });
+
+    assert(response.result, 'Should have result');
+    assert(response.result.content, 'Should have content');
+    const text = response.result.content[0].text;
+    assert(text.includes('Web Barcode Reader') || text.includes('html') || text.includes('not found'), 'Should return sample or indicate not found');
+});
+
+// Test 16: search_dwt_docs tool
+await test('search_dwt_docs finds documentation articles', async () => {
+    const response = await sendRequest({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: 'search_dwt_docs',
+            arguments: { query: 'PDF' }
+        }
+    });
+
+    assert(response.result, 'Should have result');
+    assert(response.result.content, 'Should have content');
+    const text = response.result.content[0].text;
+    assert(text.includes('DWT Documentation Search'), 'Should include search header');
+    assert(text.includes('PDF') || text.includes('pdf'), 'Should find PDF-related articles');
+});
+
+// Test 17: get_dwt_api_doc tool
+await test('get_dwt_api_doc returns documentation article', async () => {
+    const response = await sendRequest({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: 'get_dwt_api_doc',
+            arguments: { title: 'OCR' }
+        }
+    });
+
+    assert(response.result, 'Should have result');
+    assert(response.result.content, 'Should have content');
+    const text = response.result.content[0].text;
+    // Should return either the article or suggestions
+    assert(text.includes('OCR') || text.includes('not found'), 'Should handle OCR query');
+});
+
+// Test 18: resources/list returns registered resources
 await test('resources/list returns registered resources', async () => {
     const response = await sendRequest({
         jsonrpc: '2.0',
@@ -362,9 +437,10 @@ await test('resources/list returns registered resources', async () => {
     // Check for expected resource types
     const uris = response.result.resources.map(r => r.uri);
     assert(uris.some(u => u.includes('sdk-info')), 'Should have sdk-info resources');
+    assert(uris.some(u => u.includes('docs/dwt')), 'Should have DWT doc resources');
 });
 
-// Test 15: Invalid tool call returns error
+// Test 19: Invalid tool call returns error
 await test('Invalid tool call returns proper error', async () => {
     const response = await sendRequest({
         jsonrpc: '2.0',
@@ -380,7 +456,7 @@ await test('Invalid tool call returns proper error', async () => {
         'Should return error for invalid tool');
 });
 
-// Test 16: Tool with invalid arguments returns error
+// Test 20: Tool with invalid arguments returns error
 await test('Tool with missing required arguments returns error', async () => {
     const response = await sendRequest({
         jsonrpc: '2.0',