simple-dynamsoft-mcp 7.1.1 → 7.2.0

package/.env.example

@@ -1,35 +1,31 @@
-# 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
+# Optional: explicit cache directories
+# MCP_DATA_DIR=
+# MCP_DATA_CACHE_DIR=
+# RAG_CACHE_DIR=
+# RAG_MODEL_CACHE_DIR=
+
+# Optional: startup behavior
+# MCP_DATA_AUTO_DOWNLOAD=true
+# MCP_DATA_REFRESH_ON_START=false
 
-# 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
+# Optional: force hydration mode override
+# MCP_DATA_HYDRATION_MODE=eager
+
+# Optional: shared state path for runtime shard loading
+# Set to state/current.json mounted with shard files for all workers.
+# RAG_SHARED_STATE_PATH=/mnt/mcp-cache/state/current.json
+
+# Optional: prewarm behavior
+# RAG_PREWARM=true
+# RAG_PREWARM_BLOCK=false
+
+# Optional: Gemini request tuning
 # GEMINI_EMBED_MODEL=gemini-embedding-001
 # GEMINI_API_BASE_URL=https://generativelanguage.googleapis.com
 # GEMINI_EMBED_BATCH_SIZE=16
@@ -38,78 +34,12 @@ RAG_FALLBACK=none
 # 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
-
-# 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
-
-# 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
-
-# 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
-# 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
-
-# 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: 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,168 @@ 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 (two-lane release/data architecture): `docs/deployment/azure-container-apps.md`
+- Shared Azure data/index sync runbook: `docs/deployment/data-sync-azure.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 +188,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 +224,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 +259,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 +302,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.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": {
@@ -24,10 +24,8 @@
   "scripts": {
     "start": "node src/index.js",
     "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:unit": "node --test test/unit/gemini-retry.test.js test/unit/providers.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/rag-logger.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/shared-state.test.js test/unit/vector-cache.test.js test/unit/compute-repo-signatures.test.js test/unit/data-sync-azure.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",
@@ -67,7 +65,6 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@xenova/transformers": "^2.17.2",
     "dotenv": "^16.4.5",
     "extract-zip": "^2.0.1",
     "fuse.js": "^7.0.0",