simple-dynamsoft-mcp 6.3.0 → 6.4.0

package/.env.example

@@ -60,14 +60,18 @@ RAG_FALLBACK=fuse
 # * RAG_REBUILD: true to ignore cache and rebuild on startup/search
 # * RAG_PREWARM: true to build the embedding index at startup
 # * RAG_PREWARM_BLOCK: true to block startup until prewarm completes
-# * RAG_PREBUILT_INDEX_AUTO_DOWNLOAD: auto-download prebuilt local index when local embeddings are selected
-# * RAG_PREBUILT_INDEX_URL: override prebuilt index archive URL (default GitHub release asset for current package version)
+# * RAG_PREBUILT_INDEX_AUTO_DOWNLOAD: auto-download prebuilt index when local or gemini embeddings are selected
+# * RAG_PREBUILT_INDEX_URL: global override URL for prebuilt index archive (applies to both local and gemini providers)
+# * RAG_PREBUILT_INDEX_URL_LOCAL: provider-specific URL override for local prebuilt index archive
+# * RAG_PREBUILT_INDEX_URL_GEMINI: provider-specific URL override for gemini prebuilt index archive
 # * RAG_PREBUILT_INDEX_TIMEOUT_MS: timeout for prebuilt index download request
 # RAG_REBUILD=false
 # RAG_PREWARM=false
 # RAG_PREWARM_BLOCK=false
 # RAG_PREBUILT_INDEX_AUTO_DOWNLOAD=true
 # RAG_PREBUILT_INDEX_URL=
+# RAG_PREBUILT_INDEX_URL_LOCAL=
+# RAG_PREBUILT_INDEX_URL_GEMINI=
 # RAG_PREBUILT_INDEX_TIMEOUT_MS=180000
 
 # Optional data submodule sync on server startup

package/README.md

@@ -185,8 +185,10 @@ Example:
 Commonly used settings:
 - `RAG_PROVIDER`: `auto` | `gemini` | `local` | `fuse`
 - `RAG_FALLBACK`: `fuse` | `local` | `none`
-- `RAG_PREBUILT_INDEX_AUTO_DOWNLOAD`: `true` by default; auto-fetch prebuilt local index when local embeddings are selected
-- `RAG_PREBUILT_INDEX_URL`: override release asset URL for prebuilt index archive
+- `RAG_PREBUILT_INDEX_AUTO_DOWNLOAD`: `true` by default; auto-fetch prebuilt index when local or gemini embeddings are selected
+- `RAG_PREBUILT_INDEX_URL`: global override release asset URL for prebuilt index archive
+- `RAG_PREBUILT_INDEX_URL_LOCAL`: override release asset URL for local prebuilt index archive
+- `RAG_PREBUILT_INDEX_URL_GEMINI`: override release asset URL for gemini prebuilt index archive
 - `RAG_PREBUILT_INDEX_TIMEOUT_MS`: download timeout for prebuilt index fetch
 - `MCP_DATA_DIR`: use a preloaded local data folder (`metadata/`, `samples/`, `documentation/`)
 - `MCP_DATA_AUTO_DOWNLOAD`: allow startup archive download when bundled data is unavailable
@@ -199,17 +201,19 @@ For the complete list and defaults, see `.env.example` and the sections `Submodu
 
 ## Use Release Assets In A Local Project
 
-Use this when you want to run from a built `.tgz` package and reuse a prebuilt local RAG index.
+Use this when you want to run from a built `.tgz` package and reuse prebuilt RAG indexes.
 
 1. Download release assets from GitHub Releases for the same version:
 - `simple-dynamsoft-mcp-<version>.tgz`
-- `prebuilt-rag-index-<version>.tar.gz`
+- `prebuilt-rag-index-local-<version>.tar.gz`
+- `prebuilt-rag-index-gemini-<version>.tar.gz` (only needed if `RAG_PROVIDER=gemini`)
 2. In your project folder, create a local tools folder, for example:
 - `<project>/.tools/simple-dynamsoft-mcp/`
-3. Copy assets into that folder and extract the prebuilt index:
+3. Copy assets into that folder and extract the prebuilt index you plan to use:
 - Keep `simple-dynamsoft-mcp-<version>.tgz` as-is for `npx --package`.
-- Extract `prebuilt-rag-index-<version>.tar.gz`.
-- Expected cache output path: `<project>/.tools/simple-dynamsoft-mcp/prebuilt-rag/cache/*.json`.
+- Extract `prebuilt-rag-index-local-<version>.tar.gz` for local embeddings.
+- Extract `prebuilt-rag-index-gemini-<version>.tar.gz` for gemini embeddings.
+- Expected cache output path: `<project>/.tools/simple-dynamsoft-mcp/prebuilt-rag/<provider>/cache/*.json`.
 4. Configure project-local `.vscode/mcp.json` to use the local package and cache path.
 
 Example (`.vscode/mcp.json`):
@@ -231,7 +235,7 @@ Example (`.vscode/mcp.json`):
         "RAG_REBUILD": "false",
         "RAG_LOCAL_MODEL": "Xenova/all-MiniLM-L6-v2",
         "RAG_LOCAL_QUANTIZED": "true",
-        "RAG_CACHE_DIR": ".tools/simple-dynamsoft-mcp/prebuilt-rag/cache"
+        "RAG_CACHE_DIR": ".tools/simple-dynamsoft-mcp/prebuilt-rag/local/cache"
       }
     }
   }
@@ -242,9 +246,11 @@ Notes:
 - Use absolute paths if your MCP client does not resolve relative paths from workspace root.
 - `RAG_REBUILD` must stay `false` to reuse prebuilt cache files.
 - Runtime auto-download is enabled by default (`RAG_PREBUILT_INDEX_AUTO_DOWNLOAD=true`) when provider resolution reaches local embeddings (primary or fallback).
-- Default prebuilt URL pattern: `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v<version>/prebuilt-rag-index-<version>.tar.gz`.
+- Default prebuilt URL patterns:
+- `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v<version>/prebuilt-rag-index-local-<version>.tar.gz`
+- `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v<version>/prebuilt-rag-index-gemini-<version>.tar.gz`
 - Downloaded prebuilt cache is accepted when package version matches (with provider/model/payload sanity checks).
-- Prebuilt cache is used whenever provider execution resolves to local embeddings (primary or fallback).
+- Prebuilt cache is used whenever provider execution resolves to local or gemini embeddings (primary or fallback).
 
 ## Supported SDKs
 
@@ -502,7 +508,7 @@ At startup, the server logs data mode/path to stderr:
 - Release workflow: `.github/workflows/release.yml`
 - Release behavior:
 - Creates GitHub release when `package.json` version changes on `main`
-- Attaches `npm pack` artifact and prebuilt RAG index artifact (release workflow requires `GEMINI_API_KEY` for gemini prebuild path)
+- Attaches `npm pack` artifact plus separate prebuilt RAG index archives for local and gemini providers (release workflow requires `GEMINI_API_KEY` for gemini prebuild path)
 - Publishes the package to npm from the release workflow (OIDC trusted publishing)
 
 ## Testing
@@ -546,7 +552,9 @@ Key env vars:
 - `RAG_LOCAL_MODEL`: default `Xenova/all-MiniLM-L6-v2`
 - `RAG_CACHE_DIR`: default `data/.rag-cache`
 - `RAG_PREBUILT_INDEX_AUTO_DOWNLOAD`: default `true`
-- `RAG_PREBUILT_INDEX_URL`: override release prebuilt index asset URL
+- `RAG_PREBUILT_INDEX_URL`: global override for release prebuilt index asset URL
+- `RAG_PREBUILT_INDEX_URL_LOCAL`: override for local prebuilt index asset URL
+- `RAG_PREBUILT_INDEX_URL_GEMINI`: override for gemini prebuilt index asset URL
 - `RAG_PREBUILT_INDEX_TIMEOUT_MS`: default `180000`
 
 Local embeddings download the model on first run and cache under `data/.rag-cache/models`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "6.3.0",
+  "version": "6.4.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": {
@@ -40,6 +40,7 @@
     "data:verify-versions:strict": "node scripts/update-sdk-versions.mjs --check --strict",
     "data:lock": "node scripts/update-data-lock.mjs",
     "data:verify-lock": "node scripts/verify-data-lock.mjs",
+    "data:verify-docs": "node scripts/verify-doc-resources.mjs",
     "rag:prebuild": "node scripts/prebuild-rag-index.mjs"
   },
   "keywords": [

package/scripts/verify-doc-resources.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { resourceIndex, readResourceContent } from "../src/resource-index.js";
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+
+async function main() {
+  const concurrency = parsePositiveInt(process.env.DOC_VERIFY_CONCURRENCY, 8);
+  const docs = resourceIndex.filter((entry) => entry.type === "doc");
+  const total = docs.length;
+
+  console.log(`[doc-verify] start total_docs=${total} concurrency=${concurrency}`);
+
+  if (total === 0) {
+    console.log("[doc-verify] no docs found; skipping");
+    return;
+  }
+
+  let index = 0;
+  let checked = 0;
+  const failures = [];
+  const workers = [];
+
+  const runOne = async () => {
+    while (true) {
+      const current = index;
+      index += 1;
+      if (current >= total) return;
+
+      const entry = docs[current];
+      try {
+        const content = await readResourceContent(entry.uri);
+        if (!content) {
+          throw new Error("readResourceContent returned null");
+        }
+        const hasText = typeof content.text === "string" && content.text.length > 0;
+        const hasBlob = typeof content.blob === "string" && content.blob.length > 0;
+        if (!hasText && !hasBlob) {
+          throw new Error("resource content is empty");
+        }
+      } catch (error) {
+        failures.push({
+          uri: entry.uri,
+          error: error?.message || String(error)
+        });
+      } finally {
+        checked += 1;
+        if (checked % 250 === 0 || checked === total) {
+          console.log(`[doc-verify] progress checked=${checked}/${total} failures=${failures.length}`);
+        }
+      }
+    }
+  };
+
+  for (let i = 0; i < Math.min(concurrency, total); i += 1) {
+    workers.push(runOne());
+  }
+  await Promise.all(workers);
+
+  if (failures.length > 0) {
+    console.error(`[doc-verify] failed count=${failures.length}`);
+    for (const failure of failures.slice(0, 20)) {
+      console.error(`[doc-verify] error uri=${failure.uri} message=${failure.error}`);
+    }
+    if (failures.length > 20) {
+      console.error(`[doc-verify] ... truncated ${failures.length - 20} additional failures`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`[doc-verify] success checked=${checked}`);
+}
+
+await main();

package/src/rag.js

@@ -32,8 +32,14 @@ const dataRoot = getResolvedDataRoot();
 
 const pkgUrl = new URL("../package.json", import.meta.url);
 const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
-const defaultPrebuiltIndexUrl =
+const legacyPrebuiltIndexUrl =
   `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v${pkg.version}/prebuilt-rag-index-${pkg.version}.tar.gz`;
+const defaultPrebuiltIndexUrls = {
+  local:
+    `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v${pkg.version}/prebuilt-rag-index-local-${pkg.version}.tar.gz`,
+  gemini:
+    `https://github.com/yushulx/simple-dynamsoft-mcp/releases/download/v${pkg.version}/prebuilt-rag-index-gemini-${pkg.version}.tar.gz`
+};
 
 // ============================================================================
 // RAG configuration
@@ -88,7 +94,9 @@ const ragConfig = {
   prewarm: readBoolEnv("RAG_PREWARM", false),
   prewarmBlock: readBoolEnv("RAG_PREWARM_BLOCK", false),
   prebuiltIndexAutoDownload: readBoolEnv("RAG_PREBUILT_INDEX_AUTO_DOWNLOAD", true),
-  prebuiltIndexUrl: readEnvValue("RAG_PREBUILT_INDEX_URL", defaultPrebuiltIndexUrl),
+  prebuiltIndexUrl: readEnvValue("RAG_PREBUILT_INDEX_URL", ""),
+  prebuiltIndexUrlLocal: readEnvValue("RAG_PREBUILT_INDEX_URL_LOCAL", defaultPrebuiltIndexUrls.local),
+  prebuiltIndexUrlGemini: readEnvValue("RAG_PREBUILT_INDEX_URL_GEMINI", defaultPrebuiltIndexUrls.gemini),
   prebuiltIndexTimeoutMs: readIntEnv("RAG_PREBUILT_INDEX_TIMEOUT_MS", 180000),
   geminiApiKey: readEnvValue("GEMINI_API_KEY", ""),
   geminiModel: normalizeGeminiModel(readEnvValue("GEMINI_EMBED_MODEL", "models/gemini-embedding-001")),
@@ -325,25 +333,45 @@ function readSignaturePackageVersion(signatureRaw) {
   }
 }
 
-function listDownloadedCacheCandidates(extractRoot, expectedCacheFileName, cacheKey) {
+function listDownloadedCacheCandidatesByProvider(extractRoot, expectedCacheFileName, cacheKey, provider) {
   const allFiles = listFilesRecursive(extractRoot).filter((path) => path.toLowerCase().endsWith(".json")).sort();
   const expectedPath = allFiles.find((path) => basename(path) === expectedCacheFileName);
 
   const cachePrefix = cacheKey.slice(0, 12);
   const prefixPath = allFiles.find((path) => {
     const name = basename(path);
-    return name.startsWith("rag-local-") && name.endsWith(`-${cachePrefix}.json`);
+    return name.startsWith(`rag-${provider}-`) && name.endsWith(`-${cachePrefix}.json`);
   });
 
-  const ragLocalFiles = allFiles.filter((path) => basename(path).startsWith("rag-local-"));
+  const providerFiles = allFiles.filter((path) => basename(path).startsWith(`rag-${provider}-`));
   const unique = [];
-  for (const path of [expectedPath, prefixPath, ...ragLocalFiles]) {
+  for (const path of [expectedPath, prefixPath, ...providerFiles]) {
     if (!path) continue;
     if (!unique.includes(path)) unique.push(path);
   }
   return unique;
 }
 
+function resolvePrebuiltIndexUrlCandidates(provider) {
+  const override = String(ragConfig.prebuiltIndexUrl || "").trim();
+  if (override) return [override];
+
+  const candidates = [];
+  if (provider === "local") {
+    candidates.push(String(ragConfig.prebuiltIndexUrlLocal || "").trim());
+  } else if (provider === "gemini") {
+    candidates.push(String(ragConfig.prebuiltIndexUrlGemini || "").trim());
+  }
+  candidates.push(legacyPrebuiltIndexUrl);
+
+  const deduped = [];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (!deduped.includes(candidate)) deduped.push(candidate);
+  }
+  return deduped;
+}
+
 async function downloadPrebuiltArchive(url, outputPath, timeoutMs) {
   const source = String(url || "").trim();
   if (!source) {
@@ -376,88 +404,102 @@ async function downloadPrebuiltArchive(url, outputPath, timeoutMs) {
 }
 
 async function maybeDownloadPrebuiltVectorIndex({ provider, model, cacheKey, signature, cacheFile }) {
-  if (provider !== "local") {
-    return { downloaded: false, reason: "provider_not_local" };
+  if (!["local", "gemini"].includes(provider)) {
+    return { downloaded: false, reason: "provider_not_supported" };
   }
   if (!ragConfig.prebuiltIndexAutoDownload) {
     return { downloaded: false, reason: "auto_download_disabled" };
   }
 
-  const sourceUrl = String(ragConfig.prebuiltIndexUrl || "").trim();
-  if (!sourceUrl) {
+  const sourceUrls = resolvePrebuiltIndexUrlCandidates(provider);
+  if (sourceUrls.length === 0) {
     return { downloaded: false, reason: "url_not_set" };
   }
 
-  const attemptKey = `${provider}:${cacheKey}:${sourceUrl}`;
+  const attemptKey = `${provider}:${cacheKey}:${sourceUrls.join("|")}`;
   if (prebuiltDownloadAttempts.has(attemptKey)) {
     return prebuiltDownloadAttempts.get(attemptKey);
   }
 
   const expectedCacheFileName = makeCacheFileName(provider, model, cacheKey);
   const attempt = (async () => {
-    const tempRoot = join(tmpdir(), `simple-dynamsoft-mcp-rag-prebuilt-${Date.now()}-${Math.random().toString(16).slice(2)}`);
-    const archivePath = join(tempRoot, "prebuilt-rag-index.tar.gz");
-    const extractRoot = join(tempRoot, "extract");
-
-    ensureDirectory(extractRoot);
-    try {
-      logRag(`prebuilt index download start provider=${provider} url=${sourceUrl} timeout_ms=${ragConfig.prebuiltIndexTimeoutMs}`);
-      const downloaded = await downloadPrebuiltArchive(sourceUrl, archivePath, ragConfig.prebuiltIndexTimeoutMs);
-      logRag(
-        `prebuilt index downloaded provider=${provider} source=${downloaded.sourceType} size=${downloaded.size}B`
+    let lastReason = "not_attempted";
+    for (const sourceUrl of sourceUrls) {
+      const tempRoot = join(
+        tmpdir(),
+        `simple-dynamsoft-mcp-rag-prebuilt-${Date.now()}-${Math.random().toString(16).slice(2)}`
       );
+      const archivePath = join(tempRoot, "prebuilt-rag-index.tar.gz");
+      const extractRoot = join(tempRoot, "extract");
 
-      await tar.x({
-        file: archivePath,
-        cwd: extractRoot,
-        strict: true
-      });
-
-      const candidateFiles = listDownloadedCacheCandidates(extractRoot, expectedCacheFileName, cacheKey);
-      if (candidateFiles.length === 0) {
-        throw new Error(`cache_file_not_found expected=${expectedCacheFileName}`);
-      }
+      ensureDirectory(extractRoot);
+      try {
+        logRag(
+          `prebuilt index download start provider=${provider} url=${sourceUrl} timeout_ms=${ragConfig.prebuiltIndexTimeoutMs}`
+        );
+        const downloaded = await downloadPrebuiltArchive(sourceUrl, archivePath, ragConfig.prebuiltIndexTimeoutMs);
+        logRag(
+          `prebuilt index downloaded provider=${provider} source=${downloaded.sourceType} size=${downloaded.size}B url=${sourceUrl}`
+        );
 
-      for (const sourceCacheFile of candidateFiles) {
-        const candidateCache = loadVectorIndexCache(sourceCacheFile, {
-          provider,
-          model
+        await tar.x({
+          file: archivePath,
+          cwd: extractRoot,
+          strict: true
         });
-        if (!candidateCache.hit) {
-          continue;
-        }
 
-        const cachePackageVersion = readSignaturePackageVersion(candidateCache.payload?.meta?.signature);
-        if (!cachePackageVersion || cachePackageVersion !== pkg.version) {
-          continue;
+        const candidateFiles = listDownloadedCacheCandidatesByProvider(
+          extractRoot,
+          expectedCacheFileName,
+          cacheKey,
+          provider
+        );
+        if (candidateFiles.length === 0) {
+          throw new Error(`cache_file_not_found expected=${expectedCacheFileName}`);
         }
 
-        const migratedPayload = {
-          ...candidateCache.payload,
-          cacheKey,
-          meta: {
-            ...(candidateCache.payload.meta || {}),
+        for (const sourceCacheFile of candidateFiles) {
+          const candidateCache = loadVectorIndexCache(sourceCacheFile, {
             provider,
-            model,
-            signature
+            model
+          });
+          if (!candidateCache.hit) {
+            continue;
           }
-        };
-        saveVectorIndexCache(cacheFile, migratedPayload);
-        logRag(
-          `prebuilt index installed provider=${provider} cache_file=${cacheFile} source=${basename(sourceCacheFile)} mode=version_only_compat version=${cachePackageVersion}`
+
+          const cachePackageVersion = readSignaturePackageVersion(candidateCache.payload?.meta?.signature);
+          if (!cachePackageVersion || cachePackageVersion !== pkg.version) {
+            continue;
+          }
+
+          const migratedPayload = {
+            ...candidateCache.payload,
+            cacheKey,
+            meta: {
+              ...(candidateCache.payload.meta || {}),
+              provider,
+              model,
+              signature
+            }
+          };
+          saveVectorIndexCache(cacheFile, migratedPayload);
+          logRag(
+            `prebuilt index installed provider=${provider} cache_file=${cacheFile} source=${basename(sourceCacheFile)} mode=version_only_compat version=${cachePackageVersion}`
+          );
+          return { downloaded: true, reason: "installed_version_only_compat" };
+        }
+
+        throw new Error(
+          `no_compatible_cache expected=${expectedCacheFileName} found=${candidateFiles.map((path) => basename(path)).join(",")}`
         );
-        return { downloaded: true, reason: "installed_version_only_compat" };
+      } catch (error) {
+        lastReason = `${sourceUrl} => ${error.message}`;
+        logRag(`prebuilt index unavailable provider=${provider} url=${sourceUrl} reason=${error.message}`);
+      } finally {
+        rmSync(tempRoot, { recursive: true, force: true });
       }
-
-      throw new Error(
-        `no_compatible_cache expected=${expectedCacheFileName} found=${candidateFiles.map((path) => basename(path)).join(",")}`
-      );
-    } catch (error) {
-      logRag(`prebuilt index unavailable provider=${provider} reason=${error.message}`);
-      return { downloaded: false, reason: error.message };
-    } finally {
-      rmSync(tempRoot, { recursive: true, force: true });
     }
+    return { downloaded: false, reason: lastReason };
   })();
 
   prebuiltDownloadAttempts.set(attemptKey, attempt);
@@ -822,28 +864,26 @@ async function createVectorProvider({ name, model, embedder, batchSize }) {
         }
         logRag(`cache miss provider=${name} file=${cacheFile} reason=${cacheState.reason}`);
 
-        if (name === "local") {
-          const downloadResult = await maybeDownloadPrebuiltVectorIndex({
-            provider: name,
-            model,
-            cacheKey,
-            signature,
-            cacheFile
-          });
-          if (downloadResult.downloaded) {
-            cacheState = loadVectorIndexCache(cacheFile, expectedCacheState);
-            if (cacheState.hit) {
-              const cached = cacheState.payload;
-              logRag(
-                `cache hit provider=${name} file=${cacheFile} source=prebuilt_download items=${cached.items.length} vectors=${cached.vectors.length}`
-              );
-              return {
-                items: cached.items,
-                vectors: cached.vectors
-              };
-            }
-            logRag(`cache miss provider=${name} file=${cacheFile} source=prebuilt_download reason=${cacheState.reason}`);
+        const downloadResult = await maybeDownloadPrebuiltVectorIndex({
+          provider: name,
+          model,
+          cacheKey,
+          signature,
+          cacheFile
+        });
+        if (downloadResult.downloaded) {
+          cacheState = loadVectorIndexCache(cacheFile, expectedCacheState);
+          if (cacheState.hit) {
+            const cached = cacheState.payload;
+            logRag(
+              `cache hit provider=${name} file=${cacheFile} source=prebuilt_download items=${cached.items.length} vectors=${cached.vectors.length}`
+            );
+            return {
+              items: cached.items,
+              vectors: cached.vectors
+            };
           }
+          logRag(`cache miss provider=${name} file=${cacheFile} source=prebuilt_download reason=${cacheState.reason}`);
         }
       } else {
         logRag(`cache bypass provider=${name} file=${cacheFile} reason=rebuild_true`);
@@ -1024,6 +1064,8 @@ function logRagConfigOnce() {
   logRag(
     `config provider=${ragConfig.provider} fallback=${ragConfig.fallback} prewarm=${ragConfig.prewarm} rebuild=${ragConfig.rebuild} ` +
     `cache_dir=${ragConfig.cacheDir} prebuilt_auto_download=${ragConfig.prebuiltIndexAutoDownload} ` +
+    `prebuilt_url_override=${ragConfig.prebuiltIndexUrl ? "set" : "empty"} prebuilt_url_local=${ragConfig.prebuiltIndexUrlLocal ? "set" : "empty"} ` +
+    `prebuilt_url_gemini=${ragConfig.prebuiltIndexUrlGemini ? "set" : "empty"} ` +
     `prebuilt_timeout_ms=${ragConfig.prebuiltIndexTimeoutMs} gemini_retry_max_attempts=${ragConfig.geminiRetryMaxAttempts} ` +
     `gemini_retry_base_delay_ms=${ragConfig.geminiRetryBaseDelayMs} gemini_retry_max_delay_ms=${ragConfig.geminiRetryMaxDelayMs} ` +
     `gemini_request_throttle_ms=${ragConfig.geminiRequestThrottleMs}`

package/src/resource-index.js

@@ -399,9 +399,49 @@ function getPinnedResources() {
   return resourceIndex.filter((entry) => entry.pinned);
 }
 
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function buildResourceLookupCandidates(uri) {
+  const candidates = [];
+  if (typeof uri !== "string" || uri.length === 0) return candidates;
+  candidates.push(uri);
+
+  if (!uri.includes("://")) return candidates;
+  const [scheme, rest] = uri.split("://");
+  if (scheme !== "doc") return candidates;
+
+  const parts = String(rest || "").split("/").filter(Boolean);
+  if (parts.length < 5) return candidates;
+
+  const head = parts.slice(0, 4);
+  const slugRaw = parts.slice(4).join("/");
+  const decodedOnce = safeDecodeURIComponent(slugRaw);
+  const decodedTwice = safeDecodeURIComponent(decodedOnce);
+
+  for (const slug of [decodedOnce, decodedTwice]) {
+    const canonical = `${scheme}://${head.join("/")}/${encodeURIComponent(slug)}`;
+    if (!candidates.includes(canonical)) {
+      candidates.push(canonical);
+    }
+  }
+
+  return candidates;
+}
+
 async function readResourceContent(uri) {
-  const resource = resourceIndexByUri.get(uri);
+  let resource = null;
+  for (const candidate of buildResourceLookupCandidates(uri)) {
+    resource = resourceIndexByUri.get(candidate);
+    if (resource) break;
+  }
   if (!resource) return null;
+
   const content = await resource.loadContent();
   return {
     uri,