simple-dynamsoft-mcp 7.1.1 → 7.2.1

package/.env.example

@@ -1,115 +1,47 @@
-# Runtime profile selection (recommended)
-# MCP_PROFILE: lite | semantic-local | semantic-gemini
-#   - lite: lightweight defaults for broad compatibility (no model download)
-#   - semantic-local: local embeddings via @xenova/transformers
-#   - semantic-gemini: remote embeddings via Google Gemini
-MCP_PROFILE=lite
+# Minimal configuration
+# - If GEMINI_API_KEY is set: provider=gemini, fallback=lexical, hydration_mode=eager
+# - If GEMINI_API_KEY is unset: provider=lexical, fallback=none, hydration_mode=lazy
 
-# RAG provider selection (optional explicit override)
-# RAG_PROVIDER: lexical | gemini | local | fuse
-#   - lexical: hybrid lexical retrieval (BM25 + Fuse)
-#   - gemini: remote embeddings via Google Gemini
-#   - local: local embeddings via @xenova/transformers
-#   - fuse: compatibility fallback (fuzzy-only, no embeddings)
-RAG_PROVIDER=lexical
+# GEMINI_API_KEY=your_key_here
 
-# RAG_FALLBACK: none | lexical | fuse | local
-#   - none: do not fall back if primary fails
-#   - lexical: hybrid lexical fallback (recommended for no-model fallback)
-#   - fuse: fuzzy search fallback (fast, no embeddings)
-#   - local: local embeddings fallback (if primary is gemini)
-RAG_FALLBACK=none
-
-# Gemini remote embeddings (required when RAG_PROVIDER=gemini)
-# * GEMINI_API_KEY: your Gemini API key (never commit to git)
-# * GEMINI_EMBED_MODEL: models/embedding-001 | models/gemini-embedding-001 | gemini-embedding-001
-# * GEMINI_API_BASE_URL: override for proxies (default https://generativelanguage.googleapis.com)
-# * GEMINI_EMBED_BATCH_SIZE: batch size for Gemini embedding requests
-# * GEMINI_RETRY_MAX_ATTEMPTS: max retry attempts for retryable Gemini errors
-# * GEMINI_RETRY_BASE_DELAY_MS: base delay for exponential backoff
-# * GEMINI_RETRY_MAX_DELAY_MS: max delay cap for exponential backoff
-# * GEMINI_REQUEST_THROTTLE_MS: fixed delay between Gemini requests
-# GEMINI_API_KEY=your_key
-# GEMINI_EMBED_MODEL=gemini-embedding-001
-# GEMINI_API_BASE_URL=https://generativelanguage.googleapis.com
-# GEMINI_EMBED_BATCH_SIZE=16
-# GEMINI_RETRY_MAX_ATTEMPTS=5
-# GEMINI_RETRY_BASE_DELAY_MS=500
-# GEMINI_RETRY_MAX_DELAY_MS=10000
-# GEMINI_REQUEST_THROTTLE_MS=0
-
-# Local embeddings (used when RAG_PROVIDER=local or fallback=local)
-# * RAG_LOCAL_MODEL: Hugging Face model id (default Xenova/all-MiniLM-L6-v2)
-# * RAG_LOCAL_QUANTIZED: true|false (smaller/faster model download when true)
-# RAG_LOCAL_MODEL=Xenova/all-MiniLM-L6-v2
-# RAG_LOCAL_QUANTIZED=true
+# Optional: explicit cache directories
+# MCP_DATA_DIR=
+# MCP_DATA_CACHE_DIR=
+# RAG_CACHE_DIR=
+# RAG_MODEL_CACHE_DIR=
 
-# Cache locations
-# * RAG_CACHE_DIR: vector index cache (default data/.rag-cache)
-# * RAG_MODEL_CACHE_DIR: local model cache (default data/.rag-cache/models)
-# RAG_CACHE_DIR=data/.rag-cache
-# RAG_MODEL_CACHE_DIR=data/.rag-cache/models
+# Optional: startup behavior
+# MCP_DATA_AUTO_DOWNLOAD=true
+# MCP_DATA_REFRESH_ON_START=false
 
-# Indexing + retrieval tuning
-# * RAG_CHUNK_SIZE: max chars per chunk when embedding doc content
-# * RAG_CHUNK_OVERLAP: overlap between chunks (helps context continuity)
-# * RAG_MAX_CHUNKS_PER_DOC: cap chunks per doc to control index size
-# * RAG_MAX_TEXT_CHARS: max chars per embedding input
-# * RAG_MIN_SCORE: minimum cosine similarity to keep a hit (0 disables filtering). Default 0.2.
-# * RAG_INCLUDE_SCORE: include similarity score in search results (debugging)
-# RAG_CHUNK_SIZE=1200
-# RAG_CHUNK_OVERLAP=200
-# RAG_MAX_CHUNKS_PER_DOC=6
-# RAG_MAX_TEXT_CHARS=4000
-# RAG_MIN_SCORE=0.2
-# RAG_INCLUDE_SCORE=false
+# Optional: force hydration mode override
+# MCP_DATA_HYDRATION_MODE=eager
 
-# Cache/boot controls
-# * 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 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
+# Optional: prebuilt Gemini index behavior
 # 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
-# * DATA_SYNC_ON_START: true to fetch + fast-forward configured submodules
-# * DATA_SYNC_TIMEOUT_MS: timeout per git operation in milliseconds
-# DATA_SYNC_ON_START=false
-# DATA_SYNC_TIMEOUT_MS=30000
+# Optional: prewarm behavior
+# RAG_PREWARM=true
+# RAG_PREWARM_BLOCK=false
 
-# Data bootstrap mode (for npm/npx installs without submodules)
-# * MCP_DATA_DIR: explicit existing data root (must contain metadata/, samples/, documentation/)
-# * MCP_DATA_AUTO_DOWNLOAD: auto-download pinned sample/doc archives when local data is missing
-# * MCP_DATA_CACHE_DIR: where downloaded data is stored
-# * MCP_DATA_REFRESH_ON_START: force re-download even when cache matches lock manifest
-# * MCP_DATA_HYDRATION_MODE: eager (download all repos at startup) | lazy (metadata-first, hydrate repos on demand)
-# * MCP_DATA_DOWNLOAD_TIMEOUT_MS: timeout per archive download request in milliseconds
-# * MCP_DATA_DOWNLOAD_RETRY_MAX_ATTEMPTS: max retry attempts for retryable archive download failures
-# * MCP_DATA_DOWNLOAD_RETRY_BASE_DELAY_MS: exponential backoff base delay in milliseconds
-# * MCP_DATA_DOWNLOAD_RETRY_MAX_DELAY_MS: exponential backoff max delay in milliseconds
-# MCP_DATA_DIR=
-# MCP_DATA_AUTO_DOWNLOAD=true
-# MCP_DATA_CACHE_DIR=
-# MCP_DATA_REFRESH_ON_START=false
-# MCP_DATA_HYDRATION_MODE=lazy
+# Optional: Gemini request tuning
+# GEMINI_EMBED_MODEL=gemini-embedding-001
+# GEMINI_API_BASE_URL=https://generativelanguage.googleapis.com
+# GEMINI_EMBED_BATCH_SIZE=16
+# GEMINI_RETRY_MAX_ATTEMPTS=5
+# GEMINI_RETRY_BASE_DELAY_MS=500
+# GEMINI_RETRY_MAX_DELAY_MS=10000
+# GEMINI_REQUEST_THROTTLE_MS=0
+
+# Optional: data download retry tuning
 # MCP_DATA_DOWNLOAD_TIMEOUT_MS=180000
 # MCP_DATA_DOWNLOAD_RETRY_MAX_ATTEMPTS=3
 # MCP_DATA_DOWNLOAD_RETRY_BASE_DELAY_MS=500
 # MCP_DATA_DOWNLOAD_RETRY_MAX_DELAY_MS=5000
 
-# Observability logs
-# * MCP_VERBOSE_LOGS: true to include debug-level diagnostics
-# * MCP_LOG_LEVEL: info | debug (debug enables verbose logs)
+# Optional: observability
 # MCP_VERBOSE_LOGS=false
 # MCP_LOG_LEVEL=info

package/README.md

@@ -14,146 +14,167 @@ Default transport is `stdio`. Native Streamable HTTP is also supported at `/mcp`
 
 https://github.com/user-attachments/assets/cc1c5f4b-1461-4462-897a-75abc20d62a6
 
-## Two Supported Usage Scenarios
+## Two Core Usage Modes
 
-This project is intentionally documented for two real-world usage paths:
+1. Remote MCP over HTTP (recommended)
+2. Local MCP via `npx`
 
-1. Local usage with `npx -y simple-dynamsoft-mcp@latest` and minimal config
-2. HTTP deployment on Ubuntu with full data + prebuilt indexes + Gemini embeddings
+### 1) Remote (Recommended)
 
-If you need deep operator/dev settings, see `AGENTS.md` and `.env.example`.
+Use this endpoint directly:
 
-## Scenario 1: Local Usage (Recommended Default)
+- `https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp`
 
-For most users, this is enough.
-
-Command:
+### 2) Local
 
 ```bash
 npx -y simple-dynamsoft-mcp@latest
 ```
 
-Notes:
-- No explicit environment variables are required for the default path.
-- Default profile is lightweight (`lite`) and avoids local embedding model downloads.
-- If local data is missing, the package can bootstrap pinned data from cache/download sources.
+## Deployment Guides
 
-## Scenario 2: Ubuntu HTTP Deployment (Full Data + Gemini)
+- Azure Container Apps runbook: `docs/deployment/azure-container-apps.md`
+- Self-hosting (Ubuntu/any server): `docs/deployment/self-hosting.md`
 
-Use this when you host the server remotely and expose MCP over HTTP.
+## MCP Client Configuration
 
-### 1) Prepare host
+Use one of the following client configs. Remote is recommended.
 
-```bash
-sudo apt update
-sudo apt install -y git curl
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-sudo apt install -y nodejs
-node -v
-npm -v
-```
+### OpenCode
 
-### 2) Clone and install
+<details>
+<summary>OpenCode Config</summary>
 
-```bash
-git clone --recurse-submodules https://github.com/yushulx/simple-dynamsoft-mcp.git
-cd simple-dynamsoft-mcp
-npm ci
-```
+Remote (recommended):
 
-If you did not clone with submodules:
+Location:
+- macOS: `~/.config/opencode/opencode.json`
+- Windows: `%USERPROFILE%\.config\opencode\opencode.json`
 
-```bash
-npm run data:bootstrap
-npm run data:sync
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "dynamsoft": {
+      "type": "remote",
+      "url": "https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp"
+    }
+  }
+}
 ```
 
-### 3) Configure environment
+Local:
 
-Create `.env` in repo root:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "dynamsoft": {
+      "type": "local",
+      "command": ["npx", "-y", "simple-dynamsoft-mcp@latest"]
+    }
+  }
+}
+```
 
-```dotenv
-GEMINI_API_KEY=your_key_here
+</details>
 
-MCP_PROFILE=semantic-gemini
-RAG_PROVIDER=gemini
-RAG_FALLBACK=lexical
+### Claude Desktop
 
-MCP_DATA_HYDRATION_MODE=eager
-MCP_DATA_AUTO_DOWNLOAD=true
-MCP_DATA_REFRESH_ON_START=false
+<details>
+<summary>Claude Desktop Config</summary>
 
-RAG_PREBUILT_INDEX_AUTO_DOWNLOAD=true
+Location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Remote (recommended):
 
-MCP_LOG_LEVEL=info
+```json
+{
+  "mcpServers": {
+    "dynamsoft": {
+      "url": "https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp"
+    }
+  }
+}
 ```
 
-### 4) Start HTTP server
+Local:
 
-```bash
-node src/index.js --transport=http --host=0.0.0.0 --port=3333
+```json
+{
+  "mcpServers": {
+    "dynamsoft": {
+      "command": "npx",
+      "args": ["-y", "simple-dynamsoft-mcp@latest"]
+    }
+  }
+}
 ```
 
-Endpoint:
-- `http://<server-ip>:3333/mcp`
+</details>
 
-### 5) Optional: systemd service
+### VS Code with GitHub Copilot
 
-Example `/etc/systemd/system/simple-dynamsoft-mcp.service`:
+<details>
+<summary>VS Code MCP Config</summary>
 
-```ini
-[Unit]
-Description=Simple Dynamsoft MCP Server
-After=network.target
+Global location:
+- macOS: `~/Library/Application Support/Code/User/mcp.json`
+- Windows: `%APPDATA%\Code\User\mcp.json`
 
-[Service]
-Type=simple
-WorkingDirectory=/opt/simple-dynamsoft-mcp
-ExecStart=/usr/bin/node /opt/simple-dynamsoft-mcp/src/index.js --transport=http --host=0.0.0.0 --port=3333
-EnvironmentFile=/opt/simple-dynamsoft-mcp/.env
-Restart=always
-RestartSec=3
+Workspace alternative: `.vscode/mcp.json`
+
+Remote (recommended):
 
-[Install]
-WantedBy=multi-user.target
+```json
+{
+  "servers": {
+    "dynamsoft": {
+      "url": "https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp"
+    }
+  }
+}
 ```
 
-Enable and start:
+Local:
 
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable simple-dynamsoft-mcp
-sudo systemctl start simple-dynamsoft-mcp
-sudo systemctl status simple-dynamsoft-mcp
+```json
+{
+  "servers": {
+    "dynamsoft": {
+      "command": "npx",
+      "args": ["-y", "simple-dynamsoft-mcp@latest"]
+    }
+  }
+}
 ```
 
-## MCP Client Configuration
+</details>
 
-Use one of the following client configs.
+### Cursor
 
-### OpenCode
+<details>
+<summary>Cursor MCP Config</summary>
 
 Location:
-- macOS: `~/.config/opencode/opencode.json`
-- Windows: `%USERPROFILE%\.config\opencode\opencode.json`
+- macOS: `~/.cursor/mcp.json`
+- Windows: `%USERPROFILE%\.cursor\mcp.json`
+
+Remote (recommended):
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
+  "mcpServers": {
     "dynamsoft": {
-      "type": "local",
-      "command": ["npx", "-y", "simple-dynamsoft-mcp@latest"]
+      "url": "https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp"
     }
   }
 }
 ```
 
-### Claude Desktop
-
-Location:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+Local:
 
 ```json
 {
@@ -166,15 +187,34 @@ Location:
 }
 ```
 
-### VS Code with GitHub Copilot
+</details>
 
-Global location:
-- macOS: `~/Library/Application Support/Code/User/mcp.json`
-- Windows: `%APPDATA%\Code\User\mcp.json`
+### Windsurf
+
+<details>
+<summary>Windsurf MCP Config</summary>
+
+Location:
+- macOS: `~/.codeium/windsurf/mcp_config.json`
+- Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+
+Remote (recommended):
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
+    "dynamsoft": {
+      "url": "https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp"
+    }
+  }
+}
+```
+
+Local:
+
+```json
+{
+  "mcpServers": {
     "dynamsoft": {
       "command": "npx",
       "args": ["-y", "simple-dynamsoft-mcp@latest"]
@@ -183,30 +223,29 @@ Global location:
 }
 ```
 
-Workspace alternative: `.vscode/mcp.json`
+</details>
 
-### Cursor
+### Cline
+
+<details>
+<summary>Cline MCP Config</summary>
 
 Location:
-- macOS: `~/.cursor/mcp.json`
-- Windows: `%USERPROFILE%\.cursor\mcp.json`
+- VS Code settings JSON for Cline MCP integration
+
+Remote (recommended):
 
 ```json
 {
   "mcpServers": {
     "dynamsoft": {
-      "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp@latest"]
+      "url": "https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp"
     }
   }
 }
 ```
 
-### Windsurf
-
-Location:
-- macOS: `~/.codeium/windsurf/mcp_config.json`
-- Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+Local:
 
 ```json
 {
@@ -219,6 +258,38 @@ Location:
 }
 ```
 
+</details>
+
+### Continue
+
+<details>
+<summary>Continue MCP Config</summary>
+
+Location:
+- `~/.continue/config.yaml` (or workspace Continue config)
+
+Remote (recommended):
+
+```yaml
+mcpServers:
+  dynamsoft:
+    transport: streamable-http
+    url: https://simple-dynamsoft-mcp.wonderfulwave-69908b91.eastus2.azurecontainerapps.io/mcp
+```
+
+Local:
+
+```yaml
+mcpServers:
+  dynamsoft:
+    command: npx
+    args:
+      - -y
+      - simple-dynamsoft-mcp@latest
+```
+ 
+</details>
+
 ## Available Tools
 
 The server exposes this minimal tool surface:
@@ -230,25 +301,6 @@ The server exposes this minimal tool surface:
 - `get_quickstart` -- opinionated quickstart: picks a sample by scenario, returns code + install instructions
 - `get_sample_files` -- get full project files for a known sample (discovered via list_samples or search)
 
-## Companion: Dynamsoft SDK Skills
-
-For AI agents that support skills (Claude Code, OpenCode, Codex), install [dynamsoft-sdk-skills](https://github.com/user/dynamsoft-sdk-skills) for guided integration workflows:
-
-    npx dynamsoft-sdk-skills install --all
-
-- **Skills** provide integration patterns, gotchas, and decision trees (loaded into agent context)
-- **MCP Server** provides runtime tools: version resolution, doc search, sample browsing, and retrieval of full sample project files
-
-Both work independently, but together the skills guide agents to use MCP tools at the right moments.
-
-## Quick Troubleshooting
-
-- If startup says data is incomplete, run `npm run data:bootstrap` and `npm run data:sync` in clone-based deployments.
-- For HTTP deployments, check service logs first:
-  - `journalctl -u simple-dynamsoft-mcp -f`
-- For Gemini mode, confirm `GEMINI_API_KEY` is present in service environment.
-- Structured startup logs include `[data]`, `[transport]`, and `[rag]` event lines.
-
 ## Advanced Configuration And Operator Docs
 
 Advanced settings, CI/runbook details, and maintenance workflows live in:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.1.1",
+  "version": "7.2.1",
   "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": {
@@ -26,8 +26,6 @@
     "test": "npm run test:lite",
     "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
-    "test:fuse": "npm run test:lite",
-    "test:local": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",
     "test:stdio": "node --test test/integration/stdio.test.js",

package/scripts/prebuild-rag-index.mjs

@@ -13,7 +13,7 @@ function fileHash(path) {
 }
 
 function ensureEnvDefaults() {
-  process.env.RAG_PROVIDER = process.env.RAG_PROVIDER || "local";
+  process.env.RAG_PROVIDER = process.env.RAG_PROVIDER || "gemini";
   process.env.RAG_FALLBACK = process.env.RAG_FALLBACK || "none";
   process.env.RAG_PREWARM = process.env.RAG_PREWARM || "true";
   process.env.RAG_PREWARM_BLOCK = process.env.RAG_PREWARM_BLOCK || "true";
@@ -50,10 +50,10 @@ if (cacheFiles.length === 0) {
 
 let indexSignature = "";
 let indexCacheKey = "";
-const localCacheFile = cacheFiles.find((path) => /rag-local-.*\.json$/i.test(path));
-if (localCacheFile) {
+const geminiCacheFile = cacheFiles.find((path) => /rag-gemini-.*\.json$/i.test(path));
+if (geminiCacheFile) {
   try {
-    const parsed = JSON.parse(readFileSync(localCacheFile, "utf8"));
+    const parsed = JSON.parse(readFileSync(geminiCacheFile, "utf8"));
     indexSignature = String(parsed?.meta?.signature || "");
     indexCacheKey = String(parsed?.cacheKey || "");
   } catch {
@@ -65,7 +65,7 @@ const manifest = {
   packageVersion: pkg.version,
   generatedAt: new Date().toISOString(),
   ragProvider: ragConfig.provider,
-  ragModel: ragConfig.provider === "gemini" ? ragConfig.geminiModel : ragConfig.localModel,
+  ragModel: ragConfig.geminiModel,
   indexSignature,
   indexCacheKey,
   cacheDir: toPosixPath(cacheDir),

package/scripts/run-gemini-tests.mjs

@@ -8,8 +8,6 @@ const child = spawn(
     stdio: "inherit",
     env: {
       ...process.env,
-      RUN_FUSE_PROVIDER_TESTS: "false",
-      RUN_LOCAL_PROVIDER_TESTS: "false",
       RUN_GEMINI_PROVIDER_TESTS: "true"
     }
   }
@@ -22,4 +20,3 @@ child.on("exit", (code, signal) => {
   }
   process.exit(code ?? 1);
 });
-

package/src/data/hydration-mode.js

@@ -3,9 +3,23 @@ function normalizeEnvValue(value) {
   return String(value).trim().toLowerCase();
 }
 
+function resolveEffectiveProvider(env = process.env) {
+  const explicitProvider = normalizeEnvValue(env.RAG_PROVIDER);
+  const hasGeminiKey = normalizeEnvValue(env.GEMINI_API_KEY) !== "";
+  if (explicitProvider === "gemini" || explicitProvider === "lexical") {
+    return explicitProvider;
+  }
+  if (explicitProvider === "auto") {
+    return hasGeminiKey ? "gemini" : "lexical";
+  }
+  return hasGeminiKey ? "gemini" : "lexical";
+}
+
 function resolveHydrationMode(env = process.env) {
   const mode = normalizeEnvValue(env.MCP_DATA_HYDRATION_MODE);
-  if (!mode) return "lazy";
+  if (!mode) {
+    return resolveEffectiveProvider(env) === "gemini" ? "eager" : "lazy";
+  }
   if (mode === "lazy" || mode === "eager") return mode;
   return "eager";
 }

package/src/rag/config.js

@@ -13,8 +13,6 @@ 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`
 };
@@ -52,6 +50,7 @@ function normalizeGeminiModel(model) {
 }
 
 const profileConfig = resolveProfileConfig(process.env);
+const defaultPrewarm = profileConfig.provider === "gemini";
 
 const ragConfig = {
   profile: profileConfig.profile,
@@ -62,8 +61,6 @@ const ragConfig = {
   fallback: profileConfig.fallback,
   cacheDir: readEnvValue("RAG_CACHE_DIR", join(dataRoot, ".rag-cache")),
   modelCacheDir: readEnvValue("RAG_MODEL_CACHE_DIR", join(dataRoot, ".rag-cache", "models")),
-  localModel: readEnvValue("RAG_LOCAL_MODEL", "Xenova/all-MiniLM-L6-v2"),
-  localQuantized: readBoolEnv("RAG_LOCAL_QUANTIZED", true),
   chunkSize: readIntEnv("RAG_CHUNK_SIZE", 1200),
   chunkOverlap: readIntEnv("RAG_CHUNK_OVERLAP", 200),
   maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 6),
@@ -71,11 +68,10 @@ const ragConfig = {
   minScore: readFloatEnv("RAG_MIN_SCORE", 0.2),
   includeScore: readBoolEnv("RAG_INCLUDE_SCORE", false),
   rebuild: readBoolEnv("RAG_REBUILD", false),
-  prewarm: readBoolEnv("RAG_PREWARM", false),
+  prewarm: readBoolEnv("RAG_PREWARM", defaultPrewarm),
   prewarmBlock: readBoolEnv("RAG_PREWARM_BLOCK", false),
   prebuiltIndexAutoDownload: readBoolEnv("RAG_PREBUILT_INDEX_AUTO_DOWNLOAD", true),
   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", ""),

package/src/rag/index.js

@@ -69,6 +69,29 @@ const providerOrchestrator = createProviderOrchestrator({
   vectorCache
 });
 
+function classifyGeminiFailureReason(error) {
+  const status = Number(error?.status);
+  if (status === 401 || status === 403) return "invalid_auth";
+  if (status === 400 || status === 404) return "invalid_config";
+  const message = String(error?.message || "").toLowerCase();
+  if (message.includes("gemini_api_key") || message.includes("api key")) return "missing_api_key";
+  if (message.includes("embed model") || message.includes("model")) return "invalid_config";
+  return "runtime_error";
+}
+
+function logGeminiDegradedOnce({ reason, fallback, error, stage }) {
+  const key = `${stage}:${reason}:${fallback}`;
+  if (ragLogState.degradedNotices.has(key)) return;
+  ragLogState.degradedNotices.add(key);
+  logRag("provider_degraded", {
+    provider: "gemini",
+    fallback,
+    reason,
+    stage,
+    error: error?.message || String(error)
+  }, { level: "error" });
+}
+
 function refreshRagIndexes() {
   providerOrchestrator.refreshProviders();
   resetRagProviderLogState();
@@ -144,6 +167,13 @@ async function searchResources({ query, product, edition, platform, type, limit
         fallback: ragConfig.fallback,
         error: error.message
       }, { level: "error" });
+      if (name === "gemini") {
+        const reason = classifyGeminiFailureReason(error);
+        const hasFallback = providers.includes("lexical") && providers[0] === "gemini";
+        if (hasFallback) {
+          logGeminiDegradedOnce({ reason, fallback: "lexical", error, stage: "search" });
+        }
+      }
     }
   }
 
@@ -183,6 +213,10 @@ async function prewarmRagIndex() {
       fallback: ragConfig.fallback
     });
   } catch (error) {
+    if (primary === "gemini" && providers.includes("lexical")) {
+      const reason = classifyGeminiFailureReason(error);
+      logGeminiDegradedOnce({ reason, fallback: "lexical", error, stage: "prewarm" });
+    }
     logRag("prewarm_failed", {
       provider: primary,
       error: error.message

package/src/rag/logger.js

@@ -3,7 +3,7 @@ import { logEvent } from "../observability/logging.js";
 const ragLogState = {
   config: false,
   providerChain: false,
-  localEmbedderInit: false,
+  degradedNotices: new Set(),
   providerReady: new Set(),
   providerFirstUse: new Set(),
   fallbackUse: new Set()
@@ -23,7 +23,7 @@ function logRagConfigOnce(ragConfig) {
   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_override=${ragConfig.prebuiltIndexUrl ? "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} ` +
@@ -32,6 +32,7 @@ function logRagConfigOnce(ragConfig) {
 }
 
 function resetRagProviderLogState() {
+  ragLogState.degradedNotices.clear();
   ragLogState.providerReady.clear();
   ragLogState.providerFirstUse.clear();
   ragLogState.fallbackUse.clear();

package/src/rag/profile-config.js

@@ -1,48 +1,50 @@
-const PROFILE_DEFAULTS = {
-  lite: {
-    provider: "lexical",
-    fallback: "none"
-  },
-  "semantic-local": {
-    provider: "local",
-    fallback: "none"
-  },
-  "semantic-gemini": {
-    provider: "gemini",
-    fallback: "none"
-  }
-};
-
 function normalizeEnvValue(value) {
   if (value === undefined || value === null) return "";
   return String(value).trim().toLowerCase();
 }
 
-function resolveProfileConfig(env = process.env) {
-  const rawProfile = normalizeEnvValue(env.MCP_PROFILE);
-  const explicitProvider = normalizeEnvValue(env.RAG_PROVIDER);
-  const explicitFallback = normalizeEnvValue(env.RAG_FALLBACK);
+function hasGeminiKey(env) {
+  return normalizeEnvValue(env?.GEMINI_API_KEY) !== "";
+}
 
-  if (rawProfile && !PROFILE_DEFAULTS[rawProfile]) {
-    throw new Error(
-      `Invalid MCP_PROFILE "${rawProfile}". Expected one of: ${Object.keys(PROFILE_DEFAULTS).join(", ")}.`
-    );
+function resolveProvider(env) {
+  const explicit = normalizeEnvValue(env?.RAG_PROVIDER);
+  if (explicit === "gemini" || explicit === "lexical") {
+    return { value: explicit, source: "env" };
   }
+  return {
+    value: hasGeminiKey(env) ? "gemini" : "lexical",
+    source: "auto"
+  };
+}
 
-  const profile = rawProfile || "lite";
-  const defaults = PROFILE_DEFAULTS[profile];
+function resolveFallback(env, provider) {
+  const explicit = normalizeEnvValue(env?.RAG_FALLBACK);
+  if (explicit === "none" || explicit === "gemini" || explicit === "lexical") {
+    return { value: explicit, source: "env" };
+  }
+  return {
+    value: provider === "gemini" ? "lexical" : "none",
+    source: "auto"
+  };
+}
 
+function resolveProfileConfig(env = process.env) {
+  const provider = resolveProvider(env);
+  const fallback = resolveFallback(env, provider.value);
   return {
-    profile,
-    defaults,
-    provider: explicitProvider || defaults.provider,
-    fallback: explicitFallback || defaults.fallback,
-    providerSource: explicitProvider ? "env" : "profile-default",
-    fallbackSource: explicitFallback ? "env" : "profile-default"
+    profile: provider.value === "gemini" ? "semantic-gemini" : "lite",
+    defaults: {
+      provider: provider.value,
+      fallback: fallback.value
+    },
+    provider: provider.value,
+    fallback: fallback.value,
+    providerSource: provider.source,
+    fallbackSource: fallback.source
   };
 }
 
 export {
-  PROFILE_DEFAULTS,
   resolveProfileConfig
 };

package/src/rag/providers.js

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import {
   sleepMs,
@@ -10,16 +9,10 @@ import {
   executeWithGeminiRetry
 } from "./gemini-retry.js";
 
-function ensureDirectory(path) {
-  if (!existsSync(path)) {
-    mkdirSync(path, { recursive: true });
-  }
-}
-
 function resolveProviderChain(ragConfig) {
   let primary = ragConfig.provider;
   if (primary === "auto") {
-    primary = ragConfig.geminiApiKey ? "gemini" : "local";
+    primary = ragConfig.geminiApiKey ? "gemini" : "lexical";
   }
   const chain = [primary];
   if (ragConfig.fallback && ragConfig.fallback !== "none" && ragConfig.fallback !== primary) {
@@ -145,35 +138,8 @@ function createProviderOrchestrator({
 }) {
   let fuseSearch = utils.createFuseSearch(resourceIndex);
   const providerCache = new Map();
-  let localEmbedderPromise = null;
   let geminiEmbedderPromise = null;
 
-  async function getLocalEmbedder() {
-    if (localEmbedderPromise) return localEmbedderPromise;
-    localEmbedderPromise = (async () => {
-      const { pipeline, env } = await import("@xenova/transformers");
-      ensureDirectory(ragConfig.modelCacheDir);
-      if (!ragLogState.localEmbedderInit) {
-        ragLogState.localEmbedderInit = true;
-        logRag(
-          `init local embedder model=${ragConfig.localModel} quantized=${ragConfig.localQuantized} model_cache_dir=${ragConfig.modelCacheDir}`
-        );
-      }
-      env.cacheDir = ragConfig.modelCacheDir;
-      env.allowLocalModels = true;
-      const extractor = await pipeline("feature-extraction", ragConfig.localModel, {
-        quantized: ragConfig.localQuantized
-      });
-      return {
-        embed: async (text) => {
-          const output = await extractor(text, { pooling: "mean", normalize: true });
-          return Array.from(output.data);
-        }
-      };
-    })();
-    return localEmbedderPromise;
-  }
-
   async function getGeminiEmbedder() {
     if (!ragConfig.geminiApiKey) {
       throw new Error("GEMINI_API_KEY is required for gemini embeddings.");
@@ -537,16 +503,6 @@ function createProviderOrchestrator({
         entryMatchesScope: utils.entryMatchesScope,
         attachScore: utils.attachScore
       }));
-    } else if (name === "local") {
-      providerPromise = (async () => {
-        const embedder = await getLocalEmbedder();
-        return createVectorProvider({
-          name: "local",
-          model: ragConfig.localModel,
-          embedder,
-          batchSize: 1
-        });
-      })();
     } else if (name === "gemini") {
       providerPromise = (async () => {
         const embedder = await getGeminiEmbedder();

package/src/rag/vector-cache.js

@@ -154,9 +154,7 @@ function resolvePrebuiltIndexUrlCandidates(provider, ragConfig, legacyPrebuiltIn
   if (override) return [override];
 
   const candidates = [];
-  if (provider === "local") {
-    candidates.push(String(ragConfig.prebuiltIndexUrlLocal || "").trim());
-  } else if (provider === "gemini") {
+  if (provider === "gemini") {
     candidates.push(String(ragConfig.prebuiltIndexUrlGemini || "").trim());
   }
   candidates.push(legacyPrebuiltIndexUrl);
@@ -204,7 +202,7 @@ function createVectorCacheHelpers({ ragConfig, pkgVersion, legacyPrebuiltIndexUr
   const prebuiltDownloadAttempts = new Map();
 
   async function maybeDownloadPrebuiltVectorIndex({ provider, model, cacheKey, signature, cacheFile }) {
-    if (!["local", "gemini"].includes(provider)) {
+    if (provider !== "gemini") {
       return { downloaded: false, reason: "provider_not_supported" };
     }
     if (!ragConfig.prebuiltIndexAutoDownload) {