simple-dynamsoft-mcp 7.3.54 → 7.4.0

package/src/server/create-server.js

@@ -61,110 +61,132 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
     refreshRagIndexes
   });
 
-const server = new McpServer({
-  name: "simple-dynamsoft-mcp",
-  version: pkgVersion,
-  description: "MCP server for the public Dynamsoft offerings: Barcode Reader, Dynamic Web TWAIN, Document Viewer, MRZ, and MDS. Includes guidance for choosing the right public product by workflow."
-});
+  const server = new McpServer({
+    name: "simple-dynamsoft-mcp",
+    version: pkgVersion,
+    description: "MCP server for the public Dynamsoft offerings: Barcode Reader, Dynamic Web TWAIN, Document Viewer, MRZ, and MDS. Includes guidance for choosing the right public product by workflow."
+  }, {
+    instructions: [
+      "This server answers questions about five public Dynamsoft offerings: DBR, DWT, DDV, MRZ, MDS.",
+      "",
+      "How to use it:",
+      "- Call get_index first to see valid product/edition/platform combinations before asking the user anything.",
+      "- 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):",
+      "- DBR (Dynamsoft Barcode Reader) is the ONLY product with multiple editions: mobile, web, and server/desktop. Ask which one when it is unclear.",
+      "- DWT (Dynamic Web TWAIN), DDV (Document Viewer), MRZ (MRZ Scanner), and MDS (Mobile Document Scanner) are web/JavaScript-only in this MCP. NEVER ask the user which platform or language for these — there is no .NET/Java/C++/mobile option here. Go straight to the web quickstart or samples.",
+      "",
+      "api_level rule:",
+      "- api_level (high-level / low-level) applies ONLY to DBR mobile. Never ask about it, or pass it, for web, server, or any product other than DBR mobile.",
+      "",
+      "For scopes this MCP does not index (e.g. MRZ/MDS on mobile or server), tools return official documentation and sample links — pass those on rather than inventing code."
+    ].join("\n")
+  });
 
-registerIndexTools({
-  server,
-  ensureScopeHydrated,
-  ensureLatestMajor,
-  normalizeProduct,
-  normalizePlatform,
-  normalizeEdition,
-  buildIndexData,
-  getSampleIdFromUri,
-  formatScopeLabel,
-  searchResources,
-  normalizeSampleName,
-  getSampleEntries,
-  getSampleSuggestions
-});
+  registerIndexTools({
+    server,
+    ensureScopeHydrated,
+    ensureLatestMajor,
+    normalizeProduct,
+    normalizePlatform,
+    normalizeEdition,
+    buildIndexData,
+    getSampleIdFromUri,
+    formatScopeLabel,
+    searchResources,
+    normalizeSampleName,
+    getSampleEntries,
+    getSampleSuggestions
+  });
 
-registerSampleTools({
-  server,
-  registry,
-  ensureScopeHydrated,
-  ensureLatestMajor,
-  normalizeProduct,
-  normalizePlatform,
-  normalizeEdition,
-  getSampleEntries,
-  getSampleIdFromUri,
-  getDisplayEdition,
-  getDisplayPlatform
-});
+  registerSampleTools({
+    server,
+    registry,
+    ensureScopeHydrated,
+    ensureLatestMajor,
+    normalizeProduct,
+    normalizePlatform,
+    normalizeEdition,
+    getSampleEntries,
+    getSampleIdFromUri,
+    getDisplayEdition,
+    getDisplayPlatform
+  });
 
-registerVersionTools({
-  server,
-  ensureLatestMajor,
-  normalizeProduct,
-  normalizePlatform,
-  normalizeEdition,
-  LATEST_MAJOR,
-  LATEST_VERSIONS
-});
+  registerVersionTools({
+    server,
+    ensureLatestMajor,
+    normalizeProduct,
+    normalizePlatform,
+    normalizeEdition,
+    LATEST_MAJOR,
+    LATEST_VERSIONS
+  });
 
-registerQuickstartTools({
-  server,
-  registry,
-  ensureScopeHydrated,
-  ensureLatestMajor,
-  normalizeProduct,
-  normalizePlatform,
-  normalizeEdition,
-  normalizeApiLevel,
-  discoverDcvMobileSamples,
-  discoverDcvWebSamples,
-  findCodeFilesInSample,
-  getMobileSamplePath,
-  getDbrServerSamplePath,
-  getDcvMobileSamplePath,
-  getDcvServerSamplePath,
-  getDcvWebSamplePath,
-  getDwtSamplePath,
-  getDdvSamplePath,
-  readCodeFile,
-  getMainCodeFile,
-  getWebSamplePath
-});
+  registerQuickstartTools({
+    server,
+    registry,
+    ensureScopeHydrated,
+    ensureLatestMajor,
+    normalizeProduct,
+    normalizePlatform,
+    normalizeEdition,
+    normalizeApiLevel,
+    discoverDcvMobileSamples,
+    discoverDcvWebSamples,
+    findCodeFilesInSample,
+    getMobileSamplePath,
+    getDbrServerSamplePath,
+    getDcvMobileSamplePath,
+    getDcvServerSamplePath,
+    getDcvWebSamplePath,
+    getDwtSamplePath,
+    getDdvSamplePath,
+    readCodeFile,
+    getMainCodeFile,
+    getWebSamplePath,
+    getMrzWebSamplePath,
+    getMdsWebSamplePath,
+    getSampleSuggestions,
+    getSampleIdFromUri,
+    formatScopeLabel
+  });
 
-registerProjectTools({
-  server,
-  ensureScopeHydrated,
-  ensureLatestMajor,
-  normalizeProduct,
-  normalizePlatform,
-  normalizeEdition,
-  normalizeApiLevel,
-  normalizeSampleName,
-  parseResourceUri,
-  parseSampleUri,
-  formatScopeLabel,
-  getSampleIdFromUri,
-  discoverDwtSamples,
-  getMobileSamplePath,
-  getWebSamplePath,
-  getDbrServerSamplePath,
-  getDcvMobileSamplePath,
-  getDcvServerSamplePath,
-  getDcvWebSamplePath,
-  getMrzWebSamplePath,
-  getMdsWebSamplePath,
-  getDwtSamplePath,
-  getDdvSamplePath,
-  getSampleSuggestions
-});
+  registerProjectTools({
+    server,
+    ensureScopeHydrated,
+    ensureLatestMajor,
+    normalizeProduct,
+    normalizePlatform,
+    normalizeEdition,
+    normalizeApiLevel,
+    normalizeSampleName,
+    parseResourceUri,
+    parseSampleUri,
+    formatScopeLabel,
+    getSampleIdFromUri,
+    discoverDwtSamples,
+    getMobileSamplePath,
+    getWebSamplePath,
+    getDbrServerSamplePath,
+    getDcvMobileSamplePath,
+    getDcvServerSamplePath,
+    getDcvWebSamplePath,
+    getMrzWebSamplePath,
+    getMdsWebSamplePath,
+    getDwtSamplePath,
+    getDdvSamplePath,
+    getSampleSuggestions
+  });
 
-registerResourceHandlers({
-  server,
-  getPinnedResources,
-  parseResourceUri,
-  ensureLatestMajor,
-  readResourceContent
-});
+  registerResourceHandlers({
+    server,
+    getPinnedResources,
+    parseResourceUri,
+    ensureLatestMajor,
+    readResourceContent
+  });
 
-return server;
+  return server;
 }

package/src/server/normalizers.js

@@ -306,6 +306,79 @@ function isWebPlatform(platform) {
   return platform === "web" || isWebFrameworkPlatform(platform);
 }
 
+// Canonical platform values a caller may pass. Derived from the alias table so
+// this stays in sync automatically as platforms are added (issue #152).
+// "core" is a valid (DCV-internal) platform advertised in tool descriptions but
+// isn't an alias value, so add it explicitly to keep the validator consistent
+// with what the schema tells agents to pass.
+const KNOWN_PLATFORMS = new Set([...Object.values(platformAliases), "core"]);
+const KNOWN_EDITIONS = new Set(["core", "mobile", "web", "server"]);
+
+function nearestKnownKey(value, candidates) {
+  const v = String(value || "").toLowerCase();
+  if (!v) return "";
+  // Prefix / substring match first (cheap, catches "reactnative" -> "react-native").
+  let best = "";
+  let bestScore = Infinity;
+  for (const candidate of candidates) {
+    const c = candidate.toLowerCase();
+    if (c === v) return candidate;
+    const stripped = v.replace(/[-_.\s]/g, "");
+    const cStripped = c.replace(/[-_.\s]/g, "");
+    if (cStripped === stripped || cStripped.startsWith(stripped) || stripped.startsWith(cStripped)) {
+      return candidate;
+    }
+    // Fallback: length-difference heuristic as a light distance proxy.
+    if (cStripped.includes(stripped) || stripped.includes(cStripped)) {
+      const score = Math.abs(cStripped.length - stripped.length);
+      if (score < bestScore) {
+        bestScore = score;
+        best = candidate;
+      }
+    }
+  }
+  return best;
+}
+
+function validatePlatform(value) {
+  if (value === undefined || value === null || value === "") {
+    return { ok: true, normalized: "" };
+  }
+  const normalized = normalizePlatform(value);
+  if (KNOWN_PLATFORMS.has(normalized)) {
+    return { ok: true, normalized };
+  }
+  const valid = [...KNOWN_PLATFORMS].sort();
+  const suggestion = nearestKnownKey(value, [...Object.keys(platformAliases), ...KNOWN_PLATFORMS]);
+  const suggestionText = suggestion ? ` Did you mean "${normalizePlatform(suggestion) || suggestion}"?` : "";
+  return {
+    ok: false,
+    normalized,
+    message: `Unknown platform "${value}". Valid: ${valid.join(", ")}.${suggestionText}`
+  };
+}
+
+function validateEdition(value) {
+  if (value === undefined || value === null || value === "") {
+    return { ok: true, normalized: "" };
+  }
+  // Normalize first so documented aliases the tool schema advertises
+  // ("server/desktop", "desktop") and platform-implied editions ("python")
+  // are accepted rather than rejected as unknown.
+  const normalized = normalizeEdition(value);
+  if (KNOWN_EDITIONS.has(normalized)) {
+    return { ok: true, normalized };
+  }
+  const valid = [...KNOWN_EDITIONS];
+  const suggestion = nearestKnownKey(value, valid);
+  const suggestionText = suggestion ? ` Did you mean "${suggestion}"?` : "";
+  return {
+    ok: false,
+    normalized,
+    message: `Unknown edition "${value}". Valid: ${valid.join(", ")} (aliases like server/desktop, desktop are accepted).${suggestionText}`
+  };
+}
+
 function inferProductFromQuery(query) {
   if (!query) return "";
   const normalized = query.toLowerCase();
@@ -347,5 +420,9 @@ export {
   isServerPlatform,
   isWebFrameworkPlatform,
   isWebPlatform,
-  inferProductFromQuery
+  inferProductFromQuery,
+  KNOWN_PLATFORMS,
+  KNOWN_EDITIONS,
+  validatePlatform,
+  validateEdition
 };

package/src/server/public-offerings.js

@@ -35,6 +35,14 @@ const HYDRATION_PRODUCT_MAP = {
 
 const PUBLIC_OFFERINGS_TEXT = "dbr, dwt, ddv, mrz, or mds";
 
+// Shared lineup-policy wording for tool descriptions and input-schema notes.
+// Single source: when the lineup changes (e.g. a product gains an edition),
+// edit here and the long-form server `instructions` in create-server.js.
+const WEB_ONLY_OMIT_NOTE = "DWT/DDV/MRZ/MDS are web/JS-only (omit for them).";
+const DBR_ONLY_EDITIONS_NOTE = `Only DBR has multiple editions; ${WEB_ONLY_OMIT_NOTE}`;
+const API_LEVEL_NOTE = "high-level or low-level. DBR mobile ONLY; ignored for web/server/other products.";
+const PRODUCT_SELECTION_GUIDANCE = "DBR is the only product with multiple editions (mobile/web/server). DWT, DDV, MRZ, and MDS are web/JavaScript-only here, so do not ask the user which platform or language for them. api_level (high-level/low-level) applies only to DBR mobile.";
+
 function normalizePublicOffering(product) {
   if (!product) return "";
   const normalized = product.trim().toLowerCase();
@@ -64,6 +72,10 @@ function buildUnknownPublicProductResponse(requestedProduct) {
 export {
   PUBLIC_OFFERING_PRODUCTS,
   PUBLIC_OFFERINGS_TEXT,
+  WEB_ONLY_OMIT_NOTE,
+  DBR_ONLY_EDITIONS_NOTE,
+  API_LEVEL_NOTE,
+  PRODUCT_SELECTION_GUIDANCE,
   normalizePublicOffering,
   getHydrationProduct,
   isKnownPublicOffering,

package/src/server/resource-index/builders.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { DDV_PREFERRED_ENTRY_FILES } from "./config.js";
-import { PUBLIC_OFFERING_PRODUCTS } from "../public-offerings.js";
+import { PRODUCT_SELECTION_GUIDANCE, PUBLIC_OFFERING_PRODUCTS } from "../public-offerings.js";
 
 const MRZ_MATCHER = /(?:\bmrz\b|machine[-\s]?readable[-\s]?zone|passport)/i;
 const MDS_MATCHER = /(?:document[-\s]scan|document scanner|document scanning|document normalizer|document normalization|normaliz|auto[-\s]?capture|crop|cropping|deskew)/i;
@@ -36,18 +36,45 @@ function countDiscoveredSamplesByPlatforms(platforms, discoverSamplesForPlatform
 function getDcvScenarioTags(sampleName) {
   const normalized = String(sampleName || "").toLowerCase();
   const tags = [];
-  if (normalized.includes("mrz")) {
+  if (normalized.includes("mrz") || normalized.includes("passport")) {
     tags.push("mrz", "passport", "id-card", "machine-readable-zone");
   }
-  if (normalized.includes("driver") || normalized.includes("license")) {
+  if (normalized.includes("driver") || normalized.includes("license") || normalized.includes("licence") || normalized.includes("dl")) {
     tags.push("driver-license", "id-card", "dl", "aamva");
   }
-  if (normalized.includes("document")) {
+  if (normalized.includes("document") || normalized.includes("normaliz") || normalized.includes("deskew") || normalized.includes("scan-a-document")) {
     tags.push("document-scan", "document-normalization", "auto-capture", "cropping", "deskew");
   }
   if (normalized.includes("gs1")) {
     tags.push("gs1", "application-identifiers", "ai");
   }
+  if (normalized.includes("qr")) {
+    tags.push("qr", "qrcode", "qr-code");
+  }
+  if (normalized.includes("pdf417") || normalized.includes("pdf-417")) {
+    tags.push("pdf417");
+  }
+  if (normalized.includes("datamatrix") || normalized.includes("data-matrix")) {
+    tags.push("datamatrix", "data-matrix");
+  }
+  if (normalized.includes("vin")) {
+    tags.push("vin", "vehicle-identification");
+  }
+  if (normalized.includes("pdf")) {
+    tags.push("pdf", "multi-page");
+  }
+  if (normalized.includes("image") || normalized.includes("file")) {
+    tags.push("image", "still-image", "file", "upload");
+  }
+  if (normalized.includes("camera") || normalized.includes("video") || normalized.includes("webcam") || normalized.includes("scan-a-single") || normalized.includes("scan-single")) {
+    tags.push("camera", "webcam", "video", "live");
+  }
+  if (normalized.includes("hello") || normalized.includes("getting-started") || normalized.includes("quickstart")) {
+    tags.push("hello-world", "getting-started", "quickstart");
+  }
+  if (normalized.includes("multiple") || normalized.includes("batch")) {
+    tags.push("multiple", "batch");
+  }
   return Array.from(new Set(tags));
 }
 
@@ -194,6 +221,16 @@ function addMarkdownDocResources({
     const platform = article.platform || defaultPlatform;
     const tags = [...baseTags, platform];
     if (article.breadcrumb) tags.push(...article.breadcrumb.toLowerCase().split(/\s*>\s*/));
+    // Fold frontmatter keywords into tags so domain-vocabulary search hits (#142).
+    if (Array.isArray(article.keywords)) {
+      for (const kw of article.keywords) {
+        const norm = String(kw).toLowerCase().trim();
+        if (norm && !tags.includes(norm)) tags.push(norm);
+      }
+    }
+    // Prefer the frontmatter description as the summary (distinct per doc) over
+    // the breadcrumb (identical across sibling docs) (#142).
+    const baseSummary = article.description || article.breadcrumb || defaultSummary;
 
     addPublicResourceToIndex(addResourceToIndex, {
       id: `${idPrefix}-${i}`,
@@ -204,12 +241,13 @@ function addMarkdownDocResources({
       platform,
       version,
       majorVersion,
+      url: article.url,
       title: product === "mrz" || product === "mds"
         ? rewritePublicTitle(article.title, product)
         : article.title,
       summary: product === "mrz" || product === "mds"
-        ? rewritePublicSummary(article.breadcrumb || defaultSummary, product)
-        : (article.breadcrumb || defaultSummary),
+        ? rewritePublicSummary(baseSummary, product)
+        : baseSummary,
       embedText: article.content,
       mimeType: "text/markdown",
       tags,
@@ -356,35 +394,47 @@ function buildIndexData({
 
     return {
       productSelection: {
+        guidance: PRODUCT_SELECTION_GUIDANCE,
         publicOfferings: [...PUBLIC_OFFERING_PRODUCTS],
         offerings: {
           dwt: {
             name: "Dynamic Web TWAIN",
             abbreviation: "DWT",
-            whenToUse: ["Browser-based document acquisition and scanner control."]
+            webOnly: true,
+            platforms: ["js"],
+            whenToUse: ["Browser-based document acquisition and scanner control. Web/JavaScript only."]
           },
           ddv: {
             name: "Dynamsoft Document Viewer",
             abbreviation: "DDV",
-            whenToUse: ["Standalone viewing plus extension paths for mobile, annotation, multi-page handling, and PDF output."]
+            webOnly: true,
+            platforms: ["js"],
+            whenToUse: ["Standalone viewing plus annotation, multi-page handling, and PDF output. Web/JavaScript only."]
           },
           dbr: {
             name: "Dynamsoft Barcode Reader",
             abbreviation: "DBR",
+            webOnly: false,
+            editions: ["mobile", "web", "server"],
             whenToUse: [
-              "Barcode workflows across server/desktop, web, and mobile.",
-              "Use the foundational API by default on web; BarcodeScanner RTU is a minimal-simplicity option; mobile supports both foundational API and BarcodeScanner RTU."
+              "Barcode workflows across server/desktop, web, and mobile. The only product with multiple editions.",
+              "Web uses a foundational-first flow (BarcodeScanner RTU also available); this is not selected via api_level.",
+              "api_level (high-level = BarcodeScanner RTU, low-level = foundational) applies only to DBR mobile."
             ]
           },
           mrz: {
             name: "MRZ Scanner",
             abbreviation: "MRZ",
-            whenToUse: ["Passport and machine-readable-zone workflows on public web/mobile solution or RTU paths."]
+            webOnly: true,
+            platforms: ["js"],
+            whenToUse: ["Passport and machine-readable-zone workflows. Served here as web/JavaScript only; mobile/server scopes return official reference links."]
           },
           mds: {
             name: "Mobile Document Scanner",
             abbreviation: "MDS",
-            whenToUse: ["Document scan and normalization workflows on the public web-only solution or RTU path."]
+            webOnly: true,
+            platforms: ["js"],
+            whenToUse: ["Document scan and normalization workflows. Served here as web/JavaScript only; mobile/server scopes return official reference links."]
           }
         }
       },
@@ -422,7 +472,9 @@ function buildIndexData({
 
   return {
     productSelection: {
-      dcvSupersetSummary: "Dynamsoft Capture Vision (DCV) aggregates Dynamsoft Barcode Reader (DBR), Dynamsoft Label Recognizer (DLR), Dynamsoft Document Normalizer (DDN), Dynamsoft Code Parser (DCP), and Dynamsoft Camera Enhancer (DCE) into one pipeline.",
+      guidance: PRODUCT_SELECTION_GUIDANCE,
+      publicOfferings: [...PUBLIC_OFFERING_PRODUCTS],
+      dcvSupersetSummary: "Dynamsoft Capture Vision (DCV) aggregates Dynamsoft Barcode Reader (DBR), Dynamsoft Label Recognizer (DLR), Dynamsoft Document Normalizer (DDN), Dynamsoft Code Parser (DCP), and Dynamsoft Camera Enhancer (DCE) into one pipeline. DCV is internal only and is not a selectable public product.",
       useDbrWhen: [
         "Barcode-only workflows where DCV-specific workflows are not required."
       ],
@@ -985,12 +1037,20 @@ function buildResourceIndex({
         version: dbrWebVersion,
         majorVersion: LATEST_MAJOR.dbr,
         title: `Web sample: ${sampleName} (${category})`,
-        summary: `DBR web sample ${category}/${sampleName}.`,
+        summary: `DBR web ${category} sample: ${sampleName.replace(/[-_]/g, " ")}.`,
         mimeType: "text/html",
-        tags: ["sample", "dbr", "web", category, sampleName],
+        tags: ["sample", "dbr", "web", category, sampleName, ...getDcvScenarioTags(sampleName)],
+        embedText: `DBR web ${category} sample ${sampleName.replace(/[-_]/g, " ")} ${getDcvScenarioTags(sampleName).join(" ")}`,
         loadContent: async () => {
           const samplePath = getWebSamplePath(category, sampleName);
-          const content = samplePath && existsSync(samplePath) ? readCodeFile(samplePath) : "Sample not found";
+          let content = "Sample not found";
+          if (samplePath && existsSync(samplePath)) {
+            // Full-project samples (frameworks/*) resolve to a directory; point
+            // to get_sample_files rather than reading a directory as a file.
+            content = statSync(samplePath).isDirectory()
+              ? `This is a multi-file ${category} project. Use get_sample_files with sample_id ${category}/${sampleName} to retrieve all files.`
+              : readCodeFile(samplePath);
+          }
           return { text: content, mimeType: "text/html" };
         }
       });

package/src/server/resource-index/config.js

@@ -63,12 +63,14 @@ const DOCS_CONFIG = {
   mrzWeb: {
     urlBase: "https://www.dynamsoft.com/mrz-scanner/docs/web/",
     excludeDirs: [".git", ".github", ".vscode", ".vs", "_data", "_includes", "_layouts", "assets"],
-    excludeFiles: ["README.md", "search.md", "error.md"]
+    // Current MRZ docs are v3.x; exclude the legacy v1.x/v2.x guides and any private drafts (#144).
+    excludeFiles: ["README.md", "search.md", "error.md", "*-v1.1.md", "*-v2.0.md", "*-v2.1.md", "*private*"]
   },
   mdsWeb: {
     urlBase: "https://www.dynamsoft.com/mobile-document-scanner/docs/web/",
     excludeDirs: [".git", ".github", ".vscode", ".vs", "_data", "_includes", "_layouts", "assets"],
-    excludeFiles: ["README.md", "search.md", "error.md"]
+    // Exclude internal "private" draft docs (bodies are HTML comments) (#144).
+    excludeFiles: ["README.md", "search.md", "error.md", "*private*"]
   },
   dcvMobile: {
     urlBase: "https://www.dynamsoft.com/capture-vision/docs/mobile/",

package/src/server/resource-index/docs-loader.js

@@ -59,9 +59,20 @@ function buildBreadcrumbFromPath(relativePath) {
 function collectMarkdownFiles(rootDir, options = {}) {
   const files = [];
   const excludeDirs = new Set(options.excludeDirs || []);
-  const excludeFiles = new Set(options.excludeFiles || []);
+  const rawExcludeFiles = options.excludeFiles || [];
+  // Exact names go in a Set; entries containing '*' become glob regexes so
+  // configs can exclude stale/internal docs like '*-v1.1.md' or '*private*' (#144).
+  const excludeFiles = new Set(rawExcludeFiles.filter((f) => !f.includes("*")));
+  const excludePatterns = rawExcludeFiles
+    .filter((f) => f.includes("*"))
+    .map((f) => new RegExp("^" + f.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$", "i"));
   const includeDirNames = new Set(options.includeDirNames || []);
 
+  function isExcludedFile(name) {
+    if (excludeFiles.has(name)) return true;
+    return excludePatterns.some((re) => re.test(name));
+  }
+
   function walk(dir) {
     if (!existsSync(dir)) return;
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -72,7 +83,7 @@ function collectMarkdownFiles(rootDir, options = {}) {
         continue;
       }
       if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-        if (excludeFiles.has(entry.name)) continue;
+        if (isExcludedFile(entry.name)) continue;
         files.push(join(dir, entry.name));
       }
     }
@@ -100,11 +111,20 @@ function loadMarkdownDocs({ rootDir, urlBase, includeDirNames = [], excludeDirs
     const title = parsed.meta.title || getHeadingTitle(parsed.body) || formatSegmentLabel(relativePath.replace(/\.md$/i, "").split("/").pop());
     if (!title) continue;
     const breadcrumb = parsed.meta.breadcrumbText || buildBreadcrumbFromPath(relativePath) || title;
+    // Frontmatter description/keywords are the docs' own human summaries and
+    // search vocabulary — previously parsed and discarded (issue #142).
+    const description = typeof parsed.meta.description === "string" ? parsed.meta.description.trim() : "";
+    const keywordsRaw = parsed.meta.keywords;
+    const keywords = Array.isArray(keywordsRaw)
+      ? keywordsRaw.map((k) => String(k).trim()).filter(Boolean)
+      : (typeof keywordsRaw === "string" ? keywordsRaw.split(",").map((k) => k.trim()).filter(Boolean) : []);
     articles.push({
       title,
       url: markdownPathToUrl(urlBase, relativePath),
       content: parsed.body.trim(),
       breadcrumb,
+      description,
+      keywords,
       path: relativePath
     });
   }

package/src/server/resource-index/samples.js

@@ -265,17 +265,19 @@ function getDcvWebFrameworkPlatforms() {
 }
 
 function discoverWebSamples() {
-  const categories = { root: [], frameworks: [], scenarios: [] };
+  const categories = { root: [], basics: [], frameworks: [], scenarios: [] };
   const webPath = getDbrWebSamplesRoot();
   if (!webPath || !existsSync(webPath)) return categories;
 
   for (const entry of readdirSync(webPath, { withFileTypes: true })) {
-    if (entry.isFile() && entry.name.endsWith(".html")) {
+    // README.html / index.html at the repo root are navigation shells, not
+    // samples — indexing them wastes result slots and a fetch (issue #140).
+    if (entry.isFile() && entry.name.endsWith(".html") && entry.name !== "index.html" && entry.name.toLowerCase() !== "readme.html") {
       categories.root.push(entry.name.replace(".html", ""));
     }
   }
 
-  for (const subdir of ["frameworks", "scenarios"]) {
+  for (const subdir of ["basics", "frameworks", "scenarios"]) {
     const subdirPath = join(webPath, subdir);
     if (!existsSync(subdirPath)) continue;
     for (const entry of readdirSync(subdirPath, { withFileTypes: true })) {
@@ -363,6 +365,10 @@ function getWebSamplePath(category, sampleName) {
       for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
         if (entry.isFile() && entry.name.endsWith(".html")) return join(dirPath, entry.name);
       }
+      // Full-project sample (e.g. frameworks/react, a Vite app) with no
+      // top-level html: return the directory so get_sample_files can walk it,
+      // making the URI search emits actually fetchable (issue #130).
+      return dirPath;
     }
     const htmlPath = join(webPath, category, `${sampleName}.html`);
     if (existsSync(htmlPath)) return htmlPath;
@@ -415,6 +421,16 @@ function discoverDwtSamples() {
   const categories = {};
   if (!existsSync(SAMPLE_ROOTS.dwt)) return categories;
 
+  // Root-level *.html samples (e.g. edit-image.html, localstorage.html) were
+  // previously skipped because only directories were scanned (issue #140).
+  const rootSamples = [];
+  for (const entry of readdirSync(SAMPLE_ROOTS.dwt, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".html") && entry.name !== "index.html" && entry.name.toLowerCase() !== "readme.html") {
+      rootSamples.push(entry.name.replace(".html", ""));
+    }
+  }
+  if (rootSamples.length > 0) categories.root = rootSamples;
+
   for (const entry of readdirSync(SAMPLE_ROOTS.dwt, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
     const categoryPath = join(SAMPLE_ROOTS.dwt, entry.name);
@@ -594,6 +610,11 @@ function getDbrServerSamplePath(platform, sampleName) {
 
 function getDwtSamplePath(category, sampleName) {
   const fileName = sampleName.endsWith(".html") ? sampleName : `${sampleName}.html`;
+  // "root" maps to a top-level *.html directly under the DWT samples root.
+  if (category === "root") {
+    const rootFile = getExistingPath(join(SAMPLE_ROOTS.dwt, fileName));
+    return rootFile || null;
+  }
   const categoryPath = getExistingPath(join(SAMPLE_ROOTS.dwt, category));
   if (!categoryPath) return null;