simple-dynamsoft-mcp 7.3.53 → 7.4.0

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

@@ -1,7 +1,13 @@
 import { existsSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { z } from "zod";
-import { buildUnknownPublicProductResponse, isKnownPublicOffering } from "../public-offerings.js";
+import {
+  buildUnknownPublicProductResponse,
+  isKnownPublicOffering,
+  API_LEVEL_NOTE,
+  DBR_ONLY_EDITIONS_NOTE,
+  WEB_ONLY_OMIT_NOTE
+} from "../public-offerings.js";
 import { buildUnsupportedPublicScopeResponse } from "./public-routing.js";
 
 export function registerQuickstartTools({
@@ -25,8 +31,54 @@ export function registerQuickstartTools({
   getDdvSamplePath,
   readCodeFile,
   getMainCodeFile,
-  getWebSamplePath
+  getWebSamplePath,
+  getMrzWebSamplePath,
+  getMdsWebSamplePath,
+  getSampleSuggestions,
+  getSampleIdFromUri,
+  formatScopeLabel
 }) {
+  // Actionable miss response: instead of a bare "Sample not found", surface
+  // related samples the agent can fetch next (mirrors get_sample_files). (#151)
+  async function buildQuickstartMissResponse({ reason, product, edition, platform, scenario }) {
+    const lines = [reason];
+    let suggestions = [];
+    if (typeof getSampleSuggestions === "function") {
+      try {
+        suggestions = await getSampleSuggestions({
+          query: [scenario, product, edition, platform].filter(Boolean).join(" "),
+          product,
+          edition,
+          platform,
+          limit: 5
+        });
+      } catch {
+        suggestions = [];
+      }
+    }
+    const content = [{
+      type: "text",
+      text: suggestions.length
+        ? `${reason}\nRelated samples you can fetch with get_sample_files or open with get_quickstart:`
+        : `${reason}\nCall get_index to see valid product/edition/platform combinations, or search for a scenario.`
+    }];
+    for (const entry of suggestions) {
+      const versionLabel = entry.version ? `v${entry.version}` : "n/a";
+      const scopeLabel = typeof formatScopeLabel === "function" ? formatScopeLabel(entry) : `${entry.product}/${entry.edition}`;
+      const sampleId = entry.type === "sample" && typeof getSampleIdFromUri === "function" ? getSampleIdFromUri(entry.uri) : "";
+      const sampleHint = sampleId ? ` | sample_id: ${sampleId}` : "";
+      content.push({
+        type: "resource_link",
+        uri: entry.uri,
+        name: entry.title,
+        description: `${entry.type.toUpperCase()} | ${scopeLabel} | ${versionLabel} - ${entry.summary}${sampleHint}`,
+        mimeType: entry.mimeType,
+        annotations: { audience: ["assistant"], priority: 0.6 }
+      });
+    }
+    return { isError: true, content };
+  }
+
   function getPublicWebQuickstartLinks(product) {
     if (product === "mrz") {
       return {
@@ -94,11 +146,11 @@ export function registerQuickstartTools({
         "",
         "PARAMETERS:",
         "- product (required): dbr, dwt, ddv, mrz, or mds.",
-        "- 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.",
+        `- edition: core, mobile, web, or server. ${DBR_ONLY_EDITIONS_NOTE} Inferred from platform if omitted.`,
+        `- platform: only DBR spans multiple platforms (android, ios, js, python, cpp, java, dotnet, nodejs, react, vue, angular, flutter, react-native, maui, etc.). ${WEB_ONLY_OMIT_NOTE}`,
         "- 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.",
+        `- api_level: ${API_LEVEL_NOTE}`,
         "- scenario: MRZ, document scan, camera, image, single, multiple, react, vue, angular, etc. DBR web defaults to foundational guidance; MRZ and MDS return public workflow guidance where available.",
         "",
         "RETURNS: A formatted text block with SDK version, trial license key, install commands, and sample code. Ready to copy-paste.",
@@ -107,11 +159,11 @@ export function registerQuickstartTools({
       ].join("\n"),
       inputSchema: {
         product: z.string().trim().min(1, "Product is required.").describe("Product: dbr, dwt, ddv, mrz, mds"),
-        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"),
+        edition: z.string().optional().describe(`Edition: core, mobile, web, server/desktop. ${DBR_ONLY_EDITIONS_NOTE}`),
+        platform: z.string().optional().describe(`Platform (DBR only spans multiple): 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. ${WEB_ONLY_OMIT_NOTE}`),
         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)"),
+        api_level: z.string().optional().describe(`API level: ${API_LEVEL_NOTE}`),
         scenario: z.string().optional().describe("Scenario: camera, image, single, multiple, MRZ, document scan/normalization, driver license, react, etc.")
       },
       annotations: {
@@ -281,7 +333,44 @@ export function registerQuickstartTools({
         if (effectiveEdition === "web") {
           const sdkEntry = registry.sdks["dcv-web"];
           if (isPublicDcvProduct) {
+            // Serve the hydrated hello-world sample inline instead of link-only.
+            // The dedicated web sample repos ship runnable starters (#136).
             const publicLinks = getPublicWebQuickstartLinks(normalizedProduct);
+            const getDedicated = normalizedProduct === "mrz" ? getMrzWebSamplePath : getMdsWebSamplePath;
+            let dedicatedSample = "hello-world";
+            if (normalizedProduct === "mds" && (scenarioLower.includes("pdf"))) dedicatedSample = "scanning-to-pdf";
+            else if (scenarioLower.includes("image") || scenarioLower.includes("file")) {
+              dedicatedSample = normalizedProduct === "mrz" ? "use-file-input" : "image-file-scanning";
+            }
+            const dedicatedPath = typeof getDedicated === "function" ? getDedicated("root", dedicatedSample) : "";
+            // Guard against a directory result (the resolver can return a dir when a
+            // sample lacks a single html entry): readCodeFile would throw EISDIR.
+            if (dedicatedPath && existsSync(dedicatedPath) && statSync(dedicatedPath).isFile()) {
+              const dedicatedContent = readCodeFile(dedicatedPath);
+              const mrzFields = normalizedProduct === "mrz"
+                ? "\n**Result fields** (`result.data`): firstName, lastName, documentNumber, dateOfExpiry, dateOfBirth, nationality, sex, issuingState.\n"
+                : "";
+              return {
+                content: [{
+                  type: "text",
+                  text: [
+                    `# Quick Start: ${publicProductLabel} Web`,
+                    "",
+                    `**SDK Version:** ${sdkEntry.version}`,
+                    `**Trial License:** \`${registry.trial_license}\``,
+                    mrzFields,
+                    `## Sample: ${dedicatedSample}.html`,
+                    "```html",
+                    dedicatedContent,
+                    "```",
+                    "",
+                    `Docs: ${publicLinks.docsUrl}`,
+                    `More samples: ${publicLinks.samplesUrl}`
+                  ].filter(Boolean).join("\n")
+                }]
+              };
+            }
+            // Fall back to reference links only if the sample is not hydrated.
             return buildPublicReferenceQuickstart({
               product: normalizedProduct,
               edition: effectiveEdition,
@@ -386,36 +475,80 @@ export function registerQuickstartTools({
       if (normalizedProduct === "dbr" && normalizedEdition === "server") {
         const sdkEntry = registry.sdks["dbr-server"];
         const scenarioLower = (scenario || "").toLowerCase();
-        const sampleName = scenarioLower.includes("video") ? "video_decoding" : "read_an_image";
-        const samplePath = getDbrServerSamplePath("python", sampleName);
+        const targetPlatform = normalizePlatform(normalizedPlatform) || "python";
+
+        // Per-platform "hello world" sample names (repos differ in convention).
+        const SERVER_DEFAULT_SAMPLE = {
+          python: scenarioLower.includes("video") ? "video_decoding" : "read_an_image",
+          nodejs: "express",
+          java: scenarioLower.includes("video") ? "VideoDecoding" : "HelloWorld",
+          cpp: scenarioLower.includes("video") ? "VideoDecoding" : "HelloWorld",
+          dotnet: "HelloWorld"
+        };
+        const sampleName = SERVER_DEFAULT_SAMPLE[targetPlatform];
+        if (!sampleName) {
+          return await buildQuickstartMissResponse({
+            reason: `DBR server quickstart is not available for platform "${targetPlatform}". Supported: python, nodejs, java, cpp, dotnet.`,
+            product: "dbr", edition: "server", platform: targetPlatform, scenario
+          });
+        }
 
-        if (!existsSync(samplePath)) {
-          return { isError: true, content: [{ type: "text", text: `Sample not found: ${sampleName}.` }] };
+        const samplePath = getDbrServerSamplePath(targetPlatform, sampleName);
+        if (!samplePath || !existsSync(samplePath)) {
+          return await buildQuickstartMissResponse({
+            reason: `DBR server sample "${sampleName}" not found for ${targetPlatform}.`,
+            product: "dbr", edition: "server", platform: targetPlatform, scenario
+          });
         }
 
-        const content = readCodeFile(samplePath);
+        // java/cpp/dotnet/nodejs samples are project directories; python is a file.
+        let contentFileName = sampleName;
+        let contentPath = samplePath;
+        if (statSync(samplePath).isDirectory()) {
+          const codeFiles = findCodeFilesInSample(samplePath);
+          const main = codeFiles.find((f) => /^(main|program|hello|read|index|app|server)/i.test(f.filename)) || codeFiles[0];
+          if (!main) {
+            return await buildQuickstartMissResponse({
+              reason: `Found the ${sampleName} project for ${targetPlatform} but no primary source file inside it.`,
+              product: "dbr", edition: "server", platform: targetPlatform, scenario
+            });
+          }
+          contentPath = main.path;
+          contentFileName = main.relativePath || main.filename;
+        }
+        const content = readCodeFile(contentPath);
+        const platformLabel = { python: "Python", nodejs: "Node.js", java: "Java", cpp: "C++", dotnet: ".NET" }[targetPlatform] || targetPlatform;
+        const installLines = [];
+        const installObj = sdkEntry.platforms?.[targetPlatform]?.installation;
+        if (installObj && typeof installObj === "object") {
+          for (const value of Object.values(installObj)) {
+            if (typeof value === "string" && value.trim()) installLines.push(value);
+          }
+        }
+        const fence = { python: "python", nodejs: "javascript", java: "java", cpp: "cpp", dotnet: "csharp" }[targetPlatform] || "text";
 
         return {
           content: [{
             type: "text",
             text: [
-              "# Quick Start: DBR Server (Python)",
+              `# Quick Start: DBR Server (${platformLabel})`,
               "",
               `**SDK Version:** ${sdkEntry.version}`,
               `**Trial License:** \`${registry.trial_license}\``,
               "",
-              "## Install",
-              "```bash",
-              sdkEntry.platforms.python.installation.pip,
-              "```",
-              "",
-              `## ${sampleName}.py`,
-              "```python",
+              installLines.length ? "## Install" : "",
+              installLines.length ? "```bash" : "",
+              ...installLines,
+              installLines.length ? "```" : "",
+              installLines.length ? "" : "",
+              `## ${sampleName} — ${contentFileName}`,
+              "```" + fence,
               content,
               "```",
               "",
-              `Docs: ${sdkEntry.platforms.python.docs["user-guide"]}`
-            ].join("\n")
+              `Full project files: get_sample_files product=dbr edition=server platform=${targetPlatform} sample_id=${sampleName}`,
+              `Docs: ${sdkEntry.platforms?.[targetPlatform]?.docs?.["user-guide"] || "N/A"}`
+            ].filter(Boolean).join("\n")
           }]
         };
       }
@@ -423,14 +556,106 @@ export function registerQuickstartTools({
       if (normalizedProduct === "dbr" && normalizedEdition === "web") {
         const sdkEntry = registry.sdks["dbr-web"];
         const scenarioLower = (scenario || "").toLowerCase();
-        const sampleName = scenarioLower.includes("hello") ? "hello-world" : "read-an-image";
-        const samplePath = getWebSamplePath("root", sampleName);
+
+        // Framework-specific starter: if the caller named a JS framework that ships
+        // a project under frameworks/, serve runnable foundational code inline AND
+        // point to the full framework project via get_sample_files. Framework
+        // samples are multi-file Vite/CLI projects, so a single inlined file is not
+        // standalone-runnable — the fetch pointer is how the agent gets the rest
+        // (issue #134).
+        const DBR_WEB_FRAMEWORKS = new Set(["react", "angular", "vue", "next", "nuxt", "svelte", "electron", "capacitor", "blazor", "es6", "native-ts", "pwa", "requirejs", "webview"]);
+        if (normalizedPlatform && DBR_WEB_FRAMEWORKS.has(normalizedPlatform)) {
+          const foundationalPath = getWebSamplePath("basics", "scan-a-single-barcode")
+            || getWebSamplePath("basics", "hello-world");
+          const foundationalCode = foundationalPath && existsSync(foundationalPath) ? readCodeFile(foundationalPath) : "";
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `# Quick Start: DBR Web (${normalizedPlatform})`,
+                "",
+                `**SDK Version:** ${sdkEntry.version}`,
+                `**Trial License:** \`${registry.trial_license}\``,
+                `**Starter profile:** ${normalizedPlatform} framework project available`,
+                "",
+                "## Install (npm)",
+                "```bash",
+                sdkEntry.platforms.web.installation.npm,
+                "```",
+                "",
+                `## Full ${normalizedPlatform} project`,
+                `A ready-to-run ${normalizedPlatform} sample ships with this MCP. Fetch all its files with:`,
+                "```",
+                `get_sample_files product=dbr edition=web platform=${normalizedPlatform} sample_id=frameworks/${normalizedPlatform}`,
+                "```",
+                foundationalCode ? "" : null,
+                foundationalCode ? "## Foundational reference (vanilla JS — the same CaptureVisionRouter flow the framework sample wraps)" : null,
+                foundationalCode ? "```html" : null,
+                foundationalCode || null,
+                foundationalCode ? "```" : null,
+                "",
+                `Docs: ${sdkEntry.platforms.web.docs["user-guide"]}`
+              ].filter((line) => line !== null).join("\n")
+            }]
+          };
+        }
+
+        // Map the scenario to a foundational sample under basics/. Web has no
+        // high-level vs low-level API split (api_level is a mobile-only concept),
+        // so it is intentionally not consulted here.
+        let sampleName;
+        // The camera scenario fallback below substitutes a differently-named
+        // scenarios/* sample, so it is only appropriate for the generic
+        // camera/single/default request — not for requests that named a
+        // specific starter (hello) or a different intent (image/file, which is
+        // camera-based nowhere in scenarios/*). Those hard-error honestly when
+        // their sample is absent.
+        let allowCameraFallback = false;
+        if (scenarioLower.includes("hello")) {
+          sampleName = "hello-world";
+        } else if (scenarioLower.includes("image") || scenarioLower.includes("file")) {
+          sampleName = "read-an-image";
+        } else {
+          sampleName = "scan-a-single-barcode"; // camera / single / default
+          allowCameraFallback = true;
+        }
+
+        // Foundational samples now live under basics/ upstream; getWebSamplePath
+        // falls back to the repo root when basics/ is absent, so this stays
+        // compatible with older sample sets that kept them at the root.
+        let samplePath = getWebSamplePath("basics", sampleName);
+        let fallbackSample = null;
+
+        // Graceful degradation: a deployment may serve an older sample data set
+        // that predates the foundational samples. Rather than hard-erroring,
+        // fall back to a reliably-present camera scenario sample — but only when
+        // the request is camera-intent (see allowCameraFallback above).
+        if ((!samplePath || !existsSync(samplePath)) && allowCameraFallback) {
+          for (const candidate of ["scan-common-1D-and-2D", "scan-qr-code"]) {
+            const candidatePath = getWebSamplePath("scenarios", candidate);
+            if (candidatePath && existsSync(candidatePath)) {
+              samplePath = candidatePath;
+              fallbackSample = candidate;
+              break;
+            }
+          }
+        }
 
         if (!samplePath || !existsSync(samplePath)) {
-          return { isError: true, content: [{ type: "text", text: `Sample not found: ${sampleName}.` }] };
+          return await buildQuickstartMissResponse({
+            reason: `DBR web sample "${sampleName}" not found in the served sample set.`,
+            product: "dbr", edition: "web", platform: normalizedPlatform, scenario
+          });
         }
 
         const content = readCodeFile(samplePath);
+        const displaySample = fallbackSample || sampleName;
+        const sampleHeading = fallbackSample
+          ? `## Sample: ${displaySample} (camera scenario fallback)`
+          : `## Foundational sample: ${displaySample}`;
+        const fallbackNoteLines = fallbackSample
+          ? [`> Note: \`${sampleName}\` was not available in the served sample set; showing the \`${fallbackSample}\` camera scenario instead.`, ""]
+          : [];
 
         return {
           content: [{
@@ -443,7 +668,9 @@ export function registerQuickstartTools({
               "**Starter profile:** Foundational-first",
               "",
               "Use the foundational web flow first so capture and decoding remain explicit and easier to adapt.",
+              "api_level does not apply to DBR web (it is a mobile-only distinction).",
               "",
+              ...fallbackNoteLines,
               "## Option 1: CDN",
               "```html",
               `<script src="${sdkEntry.platforms.web.installation.cdn}"></script>`,
@@ -454,7 +681,7 @@ export function registerQuickstartTools({
               sdkEntry.platforms.web.installation.npm,
               "```",
               "",
-              `## Foundational sample: ${sampleName}.html`,
+              sampleHeading,
               "```html",
               content,
               "```",
@@ -471,24 +698,73 @@ export function registerQuickstartTools({
         const level = normalizeApiLevel(api_level || scenario);
         const scenarioLower = (scenario || "").toLowerCase();
 
-        let sampleName = "ScanSingleBarcode";
-        if (scenarioLower.includes("multiple") || scenarioLower.includes("batch")) sampleName = "ScanMultipleBarcodes";
-        else if (scenarioLower.includes("image") || scenarioLower.includes("file")) sampleName = "DecodeFromAnImage";
+        const isCrossPlatform = ["flutter", "react-native", "maui"].includes(targetPlatform);
+        const wantsImage = scenarioLower.includes("image") || scenarioLower.includes("file");
+        const wantsDriverLicense = scenarioLower.includes("driver") || scenarioLower.includes("license") || scenarioLower.includes("licence");
 
-        if (level === "low-level") {
-          if (sampleName === "ScanSingleBarcode" || sampleName === "ScanMultipleBarcodes") {
-            sampleName = "DecodeWithCameraEnhancer";
+        let sampleName;
+        if (isCrossPlatform) {
+          // Cross-platform repos use different sample names than Android/iOS. There
+          // is no still-image decode sample in these editions (#132, #159).
+          if (wantsImage) {
+            return {
+              content: [{
+                type: "text",
+                text: [
+                  `# DBR ${targetPlatform}: still-image decoding`,
+                  "",
+                  `The ${targetPlatform} edition ships camera-stream barcode scanning, not a still-image/gallery decode sample.`,
+                  "",
+                  "Nearest options:",
+                  "- Use the camera-based scanner below (ScanBarcodes_ReadyToUseComponent).",
+                  "- For decoding a picked/gallery image, use the native Android/iOS `DecodeFromAnImage` sample (get_quickstart product=dbr edition=mobile platform=android scenario=image) and bridge it, or call the foundational API on a captured frame.",
+                  "",
+                  `Docs: ${sdkEntry.platforms[targetPlatform]?.docs?.[level]?.["user-guide"] || sdkEntry.platforms[targetPlatform]?.docs?.["high-level"]?.["user-guide"] || "N/A"}`
+                ].join("\n")
+              }]
+            };
+          }
+          sampleName = wantsDriverLicense
+            ? "ScanDriversLicense"
+            : (level === "low-level" ? "ScanBarcodes_FoundationalAPI" : "ScanBarcodes_ReadyToUseComponent");
+        } else {
+          sampleName = "ScanSingleBarcode";
+          if (scenarioLower.includes("multiple") || scenarioLower.includes("batch")) sampleName = "ScanMultipleBarcodes";
+          else if (wantsImage) sampleName = "DecodeFromAnImage";
+
+          if (level === "low-level") {
+            if (sampleName === "ScanSingleBarcode" || sampleName === "ScanMultipleBarcodes") {
+              sampleName = "DecodeWithCameraEnhancer";
+            }
           }
         }
 
-        const samplePath = getMobileSamplePath(targetPlatform, level, sampleName);
+        // Prefer a Kotlin variant when the caller asked for Kotlin (#135).
+        const wantsKotlin = String(language || "").toLowerCase() === "kotlin";
+        let samplePath = "";
+        let servedVariant = sampleName;
+        if (wantsKotlin && targetPlatform === "android") {
+          const ktPath = getMobileSamplePath(targetPlatform, level, `${sampleName}Kt`);
+          if (existsSync(ktPath)) {
+            samplePath = ktPath;
+            servedVariant = `${sampleName}Kt`;
+          }
+        }
+        if (!samplePath) samplePath = getMobileSamplePath(targetPlatform, level, sampleName);
+
         if (!existsSync(samplePath)) {
-          return { isError: true, content: [{ type: "text", text: `Sample not found: ${sampleName}.` }] };
+          return await buildQuickstartMissResponse({
+            reason: `DBR mobile sample "${sampleName}" not found for ${targetPlatform}.`,
+            product: "dbr", edition: "mobile", platform: targetPlatform, scenario
+          });
         }
 
         const mainFile = getMainCodeFile(targetPlatform, samplePath);
         if (!mainFile) {
-          return { isError: true, content: [{ type: "text", text: "Could not find main code file." }] };
+          return await buildQuickstartMissResponse({
+            reason: `Found the ${servedVariant} sample for ${targetPlatform} but could not locate its main code file.`,
+            product: "dbr", edition: "mobile", platform: targetPlatform, scenario
+          });
         }
 
         const content = readCodeFile(mainFile.path);
@@ -521,7 +797,7 @@ dependencies {
 \`\`\`xml
 <uses-permission android:name="android.permission.CAMERA" />
 \`\`\``;
-        } else {
+        } else if (targetPlatform === "ios") {
           deps = `
 ## Dependencies
 
@@ -540,13 +816,41 @@ end
 <key>NSCameraUsageDescription</key>
 <string>Camera access for barcode scanning</string>
 \`\`\``;
+        } else if (targetPlatform === "flutter") {
+          deps = `
+## Dependencies
+
+**pubspec.yaml**
+\`\`\`yaml
+dependencies:
+  dynamsoft_barcode_reader_bundle: ^${sdkEntry.version}
+\`\`\`
+Then run \`flutter pub get\`. Add camera usage permissions to AndroidManifest.xml and Info.plist.`;
+        } else if (targetPlatform === "react-native") {
+          deps = `
+## Dependencies
+
+\`\`\`bash
+npm install dynamsoft-capture-vision-react-native
+\`\`\`
+Add camera permissions to AndroidManifest.xml and Info.plist, then rebuild the app.`;
+        } else if (targetPlatform === "maui") {
+          deps = `
+## Dependencies
+
+\`\`\`xml
+<PackageReference Include="Dynamsoft.BarcodeReaderBundle.Maui" Version="${sdkEntry.version}" />
+\`\`\`
+Add camera permissions in Platforms/Android/AndroidManifest.xml and Platforms/iOS/Info.plist.`;
         }
 
         const output = [
           "# Quick Start: DBR Mobile",
           "",
+          `**Platform:** ${targetPlatform}`,
           `**SDK Version:** ${sdkEntry.version}`,
           `**API Level:** ${level}`,
+          servedVariant !== sampleName ? `**Variant:** ${servedVariant} (Kotlin)` : "",
           `**Trial License:** \`${registry.trial_license}\``,
           "",
           deps,
@@ -556,8 +860,9 @@ end
           content,
           "```",
           "",
-          `Docs: ${sdkEntry.platforms[targetPlatform]?.docs[level]?.["user-guide"] || "N/A"}`
-        ];
+          `Full project files: get_sample_files product=dbr edition=mobile platform=${targetPlatform} sample_id=${servedVariant}`,
+          `Docs: ${sdkEntry.platforms[targetPlatform]?.docs?.[level]?.["user-guide"] || "N/A"}`
+        ].filter(Boolean);
 
         return { content: [{ type: "text", text: output.join("\n") }] };
       }
@@ -681,7 +986,19 @@ end
 
       return {
         isError: true,
-        content: [{ type: "text", text: "Unsupported product/edition for quickstart." }]
+        content: [{
+          type: "text",
+          text: [
+            `Unsupported product/edition for quickstart: product="${normalizedProduct || product}", edition="${normalizedEdition || edition || "(inferred)"}".`,
+            "Supported combinations:",
+            "- dbr: web (js + react/angular/vue/next/...), mobile (android/ios/flutter/react-native/maui), server (python/nodejs/java/cpp/dotnet)",
+            "- dwt: web",
+            "- ddv: web",
+            "- mrz: web",
+            "- mds: web",
+            "Call get_index to see valid product/edition/platform combinations."
+          ].join("\n")
+        }]
       };
     }
   );

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

@@ -1,5 +1,10 @@
 import { z } from "zod";
-import { buildUnknownPublicProductResponse, isKnownPublicOffering } from "../public-offerings.js";
+import {
+  buildUnknownPublicProductResponse,
+  isKnownPublicOffering,
+  DBR_ONLY_EDITIONS_NOTE,
+  WEB_ONLY_OMIT_NOTE
+} from "../public-offerings.js";
 import { buildUnsupportedPublicScopeResponse } from "./public-routing.js";
 
 export function registerSampleTools({
@@ -34,8 +39,8 @@ export function registerSampleTools({
         "",
         "PARAMETERS:",
         "- product: dbr, dwt, ddv, mrz, or mds. Omit to list across all public offerings.",
-        "- 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.",
+        `- edition: core, mobile, web, or server. ${DBR_ONLY_EDITIONS_NOTE} Omit to list across all editions.`,
+        `- platform: only DBR spans multiple platforms (android, ios, js, python, cpp, java, dotnet, nodejs, react, vue, angular, flutter, react-native, maui, etc.). ${WEB_ONLY_OMIT_NOTE}`,
         "- 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.",
@@ -46,8 +51,8 @@ export function registerSampleTools({
       ].join("\n"),
       inputSchema: {
         product: z.string().optional().describe("Product: dbr, dwt, ddv, mrz, mds"),
-        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"),
+        edition: z.string().optional().describe(`Edition: core, mobile, web, server/desktop. ${DBR_ONLY_EDITIONS_NOTE}`),
+        platform: z.string().optional().describe(`Platform (DBR only spans multiple): 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. ${WEB_ONLY_OMIT_NOTE}`),
         limit: z.number().int().min(1).max(200).optional().describe("Max results (default 50)")
       },
       annotations: {

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

@@ -1,5 +1,10 @@
 import { z } from "zod";
-import { buildUnknownPublicProductResponse, isKnownPublicOffering } from "../public-offerings.js";
+import {
+  buildUnknownPublicProductResponse,
+  isKnownPublicOffering,
+  DBR_ONLY_EDITIONS_NOTE,
+  WEB_ONLY_OMIT_NOTE
+} from "../public-offerings.js";
 
 export function registerVersionTools({
   server,
@@ -64,8 +69,8 @@ export function registerVersionTools({
         "",
         "PARAMETERS:",
         "- product (required): dbr, dwt, ddv, mrz, or mds.",
-        "- 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.",
+        `- edition: core, mobile, web, or server. ${DBR_ONLY_EDITIONS_NOTE} Omit to see all editions for the product.`,
+        `- platform: only DBR spans multiple platforms (android, ios, js, python, cpp, java, dotnet, nodejs, etc.). ${WEB_ONLY_OMIT_NOTE} 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.",
         "",
@@ -77,8 +82,8 @@ export function registerVersionTools({
       ].join("\n"),
       inputSchema: {
         product: z.string().trim().min(1, "Product is required.").describe("Product: dbr, dwt, ddv, mrz, mds"),
-        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"),
+        edition: z.string().optional().describe(`Edition: core, mobile, web, server/desktop. ${DBR_ONLY_EDITIONS_NOTE}`),
+        platform: z.string().optional().describe(`Platform (DBR only spans multiple): 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. ${WEB_ONLY_OMIT_NOTE}`),
         constraint: z.string().optional().describe("Version constraint, e.g., latest, 11.x, 10"),
         feature: z.string().optional().describe("Optional feature hint")
       },