simple-dynamsoft-mcp 6.4.0 → 7.0.1

package/README.md

@@ -1,600 +1,251 @@
 # Dynamsoft MCP Server
 
-MCP (Model Context Protocol) server that enables AI assistants to write correct code with Dynamsoft SDKs. It provides actual working code snippets, documentation links, and API guidance for:
+MCP server that helps AI assistants generate accurate code and guidance for Dynamsoft SDKs.
 
-- **Dynamsoft Capture Vision (DCV)** - Unified workflows for VIN, MRZ, document normalization, driver license parsing, and more
-- **Dynamsoft Barcode Reader Mobile** - Android (Java/Kotlin) and iOS (Swift)
-- **Dynamsoft Barcode Reader Server/Desktop** - Python, .NET, Java, C++, Node.js
-- **Dynamsoft Barcode Reader Web** - JavaScript/TypeScript barcode scanning
-- **Dynamic Web TWAIN** - Document scanning from TWAIN/WIA/ICA/SANE scanners
-- **Dynamsoft Document Viewer** - Web document viewing and annotation
+Supported products:
+- Dynamsoft Capture Vision (DCV)
+- Dynamsoft Barcode Reader (DBR): mobile, web, server/desktop
+- Dynamic Web TWAIN (DWT)
+- Dynamsoft Document Viewer (DDV)
+
+Default transport is `stdio`. Native Streamable HTTP is also supported at `/mcp`.
 
 ## Demo Video
+
 https://github.com/user-attachments/assets/cc1c5f4b-1461-4462-897a-75abc20d62a6
 
+## Two Supported Usage Scenarios
 
-## Features
+This project is intentionally documented for two real-world usage paths:
 
-- **Code Snippets**: Real, working source code from official Dynamsoft samples
-- **Trial License Included**: Ready-to-use trial license for quick testing
-- **Multiple SDKs**: Capture Vision + Barcode Reader (Mobile/Web/Server) + Dynamic Web TWAIN + Document Viewer
-- **Multiple API Levels**: High-level (simple) and low-level (advanced) options
-- **Stdio MCP server**: Runs on stdio. Works with any MCP-capable client.
-- **Resource-efficient discovery**: Resources are discovered via tools (semantic RAG search with fuzzy fallback + resource links). Only a small pinned set is listed by default; heavy content is fetched on-demand with `resources/read`.
-- **Submodule-backed resources**: Samples and docs are pulled from official upstream repositories under `data/samples/` and `data/documentation/`.
-- **Dual-mode data loading**: local clone uses submodules; `npx simple-dynamsoft-mcp` auto-downloads pinned archives into a local cache when submodules are unavailable.
-- **Latest-major policy**: The server only serves the latest major versions; older major requests are refused with legacy links when available.
+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
 
-## Available Tools
+If you need deep operator/dev settings, see `AGENTS.md` and `.env.example`.
 
-| Tool | Description |
-|------|-------------|
-| `get_index` | Compact index of products, editions, versions, samples, and docs |
-| `search` | Unified search across docs and samples; returns resource links |
-| `list_samples` | List available sample IDs and URIs for a scope |
-| `resolve_sample` | Resolve a sample_id (or sample URI) to matching sample URIs |
-| `resolve_version` | Resolve a concrete latest-major version for a product/edition |
-| `get_quickstart` | Opinionated quickstart for a target stack |
-| `generate_project` | Assemble a project structure from a sample (no AI generation) |
+## Scenario 1: Local Usage (Recommended Default)
 
-`npx simple-dynamsoft-mcp` is supported. If bundled submodule data is missing, the server auto-downloads pinned data archives on first run (network required).
+For most users, this is enough.
 
-## MCP Client Configuration
+Command:
 
-### OpenCode
-Location: 
-- **macOS**: `~/.config/opencode/opencode.json`
-- **Windows**: `%USERPROFILE%\.config\opencode\opencode.json`
+```bash
+npx -y simple-dynamsoft-mcp@latest
+```
 
-Configuration:
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "dynamsoft": {
-      "type": "local",
-      "command": [
-        "npx",
-        "simple-dynamsoft-mcp"
-      ]
-    }
-  }
-}
+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.
+
+## Scenario 2: Ubuntu HTTP Deployment (Full Data + Gemini)
+
+Use this when you host the server remotely and expose MCP over HTTP.
+
+### 1) Prepare host
+
+```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
 ```
 
-### Claude Desktop
+### 2) Clone and install
 
-Location:
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+```bash
+git clone --recurse-submodules https://github.com/yushulx/simple-dynamsoft-mcp.git
+cd simple-dynamsoft-mcp
+npm ci
+```
 
-Configuration:
-```json
-{
-  "mcpServers": {
-    "dynamsoft": {
-      "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp"]
-    }
-  }
-}
+If you did not clone with submodules:
+
+```bash
+npm run data:bootstrap
+npm run data:sync
 ```
 
-### VS Code with GitHub Copilot
+### 3) Configure environment
 
-Global Location:
+Create `.env` in repo root:
 
-- **macOS**: `~/Library/Application Support/Code/User/mcp.json`
-- **Windows**: `%APPDATA%\Code\User\mcp.json`
+```dotenv
+GEMINI_API_KEY=your_key_here
 
-```json
-{
-  "servers": {
-    "dynamsoft": {
-      "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp"]
-    }
-  }
-}
+MCP_PROFILE=semantic-gemini
+RAG_PROVIDER=gemini
+RAG_FALLBACK=lexical
+
+MCP_DATA_HYDRATION_MODE=eager
+MCP_DATA_AUTO_DOWNLOAD=true
+MCP_DATA_REFRESH_ON_START=false
+
+RAG_PREBUILT_INDEX_AUTO_DOWNLOAD=true
+
+MCP_LOG_LEVEL=info
 ```
 
-Or create workspace-specific `.vscode/mcp.json`:
+### 4) Start HTTP server
 
-```json
-{
-  "servers": {
-    "dynamsoft": {
-      "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp"]
-    }
-  }
-}
+```bash
+node src/index.js --transport=http --host=0.0.0.0 --port=3333
 ```
 
-### Cursor
+Endpoint:
+- `http://<server-ip>:3333/mcp`
+
+### 5) Optional: systemd service
+
+Example `/etc/systemd/system/simple-dynamsoft-mcp.service`:
+
+```ini
+[Unit]
+Description=Simple Dynamsoft MCP Server
+After=network.target
+
+[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
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable simple-dynamsoft-mcp
+sudo systemctl start simple-dynamsoft-mcp
+sudo systemctl status simple-dynamsoft-mcp
+```
+
+## MCP Client Configuration
+
+Use one of the following client configs.
 
-Location: 
-- **macOS**: `~/.cursor/mcp.json`
-- **Windows**: `%USERPROFILE%\.cursor\mcp.json`
+### OpenCode
 
-Configuration:
+Location:
+- macOS: `~/.config/opencode/opencode.json`
+- Windows: `%USERPROFILE%\.config\opencode\opencode.json`
 
 ```json
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "dynamsoft": {
-      "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp"]
+      "type": "local",
+      "command": ["npx", "-y", "simple-dynamsoft-mcp@latest"]
     }
   }
 }
 ```
 
-### Windsurf
+### Claude Desktop
 
 Location:
-
-- **macOS**: `~/.codeium/windsurf/mcp_config.json`
-- **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "dynamsoft": {
       "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp"]
+      "args": ["-y", "simple-dynamsoft-mcp@latest"]
     }
   }
 }
 ```
 
+### VS Code with GitHub Copilot
 
-### Alternative: Run from Local Clone
-
-If you prefer running from source:
+Global location:
+- macOS: `~/Library/Application Support/Code/User/mcp.json`
+- Windows: `%APPDATA%\Code\User\mcp.json`
 
 ```json
 {
-  "command": "node",
-  "args": ["/absolute/path/to/simple-dynamsoft-mcp/src/index.js"]
+  "servers": {
+    "dynamsoft": {
+      "command": "npx",
+      "args": ["-y", "simple-dynamsoft-mcp@latest"]
+    }
+  }
 }
 ```
 
-## Environment Variables in MCP Clients
+Workspace alternative: `.vscode/mcp.json`
 
-When using `npx`, you can still configure the server by passing environment variables in your MCP client config.
+### Cursor
 
-Example:
+Location:
+- macOS: `~/.cursor/mcp.json`
+- Windows: `%USERPROFILE%\.cursor\mcp.json`
 
 ```json
 {
   "mcpServers": {
     "dynamsoft": {
       "command": "npx",
-      "args": ["-y", "simple-dynamsoft-mcp"],
-      "env": {
-        "RAG_PROVIDER": "auto",
-        "MCP_DATA_AUTO_DOWNLOAD": "true",
-        "MCP_DATA_REFRESH_ON_START": "false"
-      }
+      "args": ["-y", "simple-dynamsoft-mcp@latest"]
     }
   }
 }
 ```
 
-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 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
-- `MCP_DATA_REFRESH_ON_START`: force re-download of pinned archives on startup
-- `MCP_DATA_CACHE_DIR`: customize downloaded data cache location
-
-If you want no embedding/model/network dependency for search, set `RAG_PROVIDER=fuse`.
-
-For the complete list and defaults, see `.env.example` and the sections `Submodule Setup` and `RAG Configuration` below.
-
-## Use Release Assets In A Local Project
-
-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-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 you plan to use:
-- Keep `simple-dynamsoft-mcp-<version>.tgz` as-is for `npx --package`.
-- 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`):
+### Windsurf
+
+Location:
+- macOS: `~/.codeium/windsurf/mcp_config.json`
+- Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "dynamsoft": {
       "command": "npx",
-      "args": [
-        "-y",
-        "--package",
-        ".tools/simple-dynamsoft-mcp/simple-dynamsoft-mcp-<version>.tgz",
-        "simple-dynamsoft-mcp"
-      ],
-      "env": {
-        "RAG_PROVIDER": "auto",
-        "RAG_FALLBACK": "local",
-        "RAG_REBUILD": "false",
-        "RAG_LOCAL_MODEL": "Xenova/all-MiniLM-L6-v2",
-        "RAG_LOCAL_QUANTIZED": "true",
-        "RAG_CACHE_DIR": ".tools/simple-dynamsoft-mcp/prebuilt-rag/local/cache"
-      }
+      "args": ["-y", "simple-dynamsoft-mcp@latest"]
     }
   }
 }
 ```
 
-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 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 or gemini embeddings (primary or fallback).
-
-## Supported SDKs
-
-### Dynamsoft Capture Vision (DCV)
-
-DCV is a superset architecture that aggregates DBR, DLR, DDN, DCP, and DCE into one pluggable pipeline.
-
-Use **DBR** when you only need barcode decoding.
-Use **DCV** when your workflow includes VIN, MRZ/passport/ID, driver license parsing, document detection/normalization/auto-capture/cropping, or multi-task capture-vision pipelines.
-
-**DCV editions covered in this MCP server:**
-- **Core docs** - architecture and cross-product concepts
-- **Web (JavaScript)**
-- **Server/Desktop** - Python, .NET, Java, C++, Node.js
-- **Mobile** - Android, iOS, Flutter, React Native, .NET MAUI (+ SPM package sample)
-
-### Dynamsoft Barcode Reader Mobile (latest)
-
-**Platforms:** Android, iOS, Flutter, React Native, .NET MAUI
-
-**API Levels:**
-- **High-Level (BarcodeScanner)**: Simple ready-to-use barcode scanning UI
-- **Low-Level (CaptureVisionRouter)**: Full control over the scanning pipeline
-
-**Android Samples:**
-- ScanSingleBarcode, ScanMultipleBarcodes, ScenarioOrientedSamples
-- DecodeWithCameraEnhancer, DecodeWithCameraX, DecodeFromAnImage
-- GeneralSettings, DriversLicenseScanner, TinyBarcodeDecoding, ReadGS1AI
-
-**iOS Samples:**
-- ScanSingleBarcode, ScanMultipleBarcodes, ScanSingleBarcodeSwiftUI
-- DecodeWithCameraEnhancer, DecodeWithAVCaptureSession, DecodeFromAnImage
-
-### Dynamsoft Barcode Reader Server/Desktop (latest)
-
-**Platforms:** Python, .NET, Java, C++, Node.js
-
-**Python installation:** `pip install dynamsoft-barcode-reader-bundle`
-
-**Server/Desktop samples:** Pulled from platform-specific sample repositories in `data/samples/`.
-
-### Dynamsoft Barcode Reader Web (latest)
-
-**Installation:** `npm install dynamsoft-barcode-reader-bundle`
-
-**CDN:** `https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@latest/dist/dbr.bundle.min.js`
-
-**Samples:**
-- **hello-world** - Basic barcode scanning from camera
-- **read-an-image** - Decode from image files
-- **frameworks/** - React, Vue, Angular, Next.js, PWA samples
-- **scenarios/** - Multi-image reading, localize an item, driver license parsing
-
-### Dynamic Web TWAIN (latest)
-
-**Installation:** `npm install dwt`
-
-**CDN:** `https://cdn.jsdelivr.net/npm/dwt@latest/dist/dynamsoft.webtwain.min.js`
-
-**Sample Categories:**
-- **scan** - Basic document scanning (basic-scan, read-barcode, etc.)
-- **input-options** - Load from files, URLs, local drive
-- **output-options** - Save, upload, convert to PDF/Base64/Blob
-- **classification** - Document classification and tagging
-- **UI-customization** - Customize viewer and scan UI
-
-### Dynamsoft Document Viewer (latest)
-
-**Installation:** `npm install dynamsoft-document-viewer`
-
-**CDN:** `https://cdn.jsdelivr.net/npm/dynamsoft-document-viewer@latest/dist/ddv.js`
-
-**Samples:**
-- **hello-world** - Basic viewer setup
-- **angular**, **react-vite**, **vue**, **next** - Framework starter samples
-
-## Trial License
-https://www.dynamsoft.com/customer/license/trialLicense/?product=dcv&package=cross-platform
-
-## Example AI Prompts
-
-After connecting the MCP server, you can ask your AI assistant:
-
-### Mobile Barcode Scanner
-- "Create an Android app that scans a single barcode"
-- "Show me how to use CaptureVisionRouter in iOS Swift"
-- "Get the Gradle configuration for Dynamsoft Barcode Reader"
-- "How do I initialize the Dynamsoft license in Kotlin?"
-
-### Server/Desktop Barcode Reader
-- "Show me how to read barcodes from an image in Python"
-- "Get me a Node.js barcode reader sample"
-- "List DBR .NET samples and generate one project"
-
-### Web Barcode Reader
-- "Create a web page that scans barcodes from a camera"
-- "Show me the web barcode reader hello world sample"
-- "Get the React sample for web barcode scanning"
-- "How do I decode barcodes from an image in JavaScript?"
-
-### Capture Vision (DCV)
-- "Find a DCV sample for MRZ scanning in Python"
-- "Get a VIN scanning sample for Java or C++"
-- "Show me DCV document normalization samples for mobile"
-- "I need driver license parsing; should I use DBR or DCV?"
-- "List DCV server samples and generate a project from MRZScanner"
-
-### Dynamic Web TWAIN
-- "Create a web page that scans documents from a TWAIN scanner"
-- "Show me how to save scanned documents as PDF"
-- "Get the DWT sample for reading barcodes from scanned documents"
-- "Search the DWT docs for how to load images from files"
-- "Get the DWT documentation about OCR"
-- "How do I configure the PDF rasterizer in DWT?"
+## Available Tools
 
-## SDK Documentation
+The server exposes this minimal tool surface:
 
-- **DCV Core**: https://www.dynamsoft.com/capture-vision/docs/core/
-- **DCV Mobile**: https://www.dynamsoft.com/capture-vision/docs/mobile/
-- **DCV Server/Desktop**: https://www.dynamsoft.com/capture-vision/docs/server/
-- **DCV Web**: https://www.dynamsoft.com/capture-vision/docs/web/
-- **Mobile Android**: https://www.dynamsoft.com/barcode-reader/docs/mobile/programming/android/user-guide.html
-- **Mobile iOS**: https://www.dynamsoft.com/barcode-reader/docs/mobile/programming/objectivec-swift/user-guide.html
-- **Python**: https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/user-guide.html
-- **Web JavaScript**: https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/index.html
-- **Dynamic Web TWAIN**: https://www.dynamsoft.com/web-twain/docs/introduction/index.html
+- `get_index`
+- `search`
+- `list_samples`
+- `resolve_sample`
+- `resolve_version`
+- `get_quickstart`
+- `generate_project`
 
-## Data Repository Structure
+## Quick Troubleshooting
 
-```
-data/
-|-- metadata/
-|   |-- dynamsoft_sdks.json
-|   `-- data-manifest.json               # Pinned repo commits for runtime bootstrap
-|-- samples/                             # Git submodules
-|   |-- dynamsoft-barcode-reader
-|   |-- dynamsoft-barcode-reader-mobile
-|   |-- dynamsoft-barcode-reader-maui
-|   |-- dynamsoft-barcode-reader-react-native
-|   |-- dynamsoft-barcode-reader-flutter
-|   |-- dynamsoft-barcode-reader-python
-|   |-- dynamsoft-barcode-reader-dotnet
-|   |-- dynamsoft-barcode-reader-java
-|   |-- dynamsoft-barcode-reader-c-cpp
-|   |-- dynamsoft-capture-vision-nodejs
-|   |-- dynamsoft-capture-vision-c-cpp
-|   |-- dynamsoft-capture-vision-dotnet
-|   |-- dynamsoft-capture-vision-java
-|   |-- dynamsoft-capture-vision-python
-|   |-- dynamsoft-capture-vision-mobile
-|   |-- dynamsoft-capture-vision-javascript
-|   |-- dynamsoft-capture-vision-react-native
-|   |-- dynamsoft-capture-vision-maui
-|   |-- dynamsoft-capture-vision-flutter
-|   |-- dynamsoft-capture-vision-spm
-|   |-- dynamic-web-twain
-|   `-- dynamsoft-document-viewer
-|-- documentation/                       # Git submodules
-|   |-- barcode-reader-docs-js
-|   |-- barcode-reader-docs-mobile
-|   |-- barcode-reader-docs-server
-|   |-- capture-vision-docs
-|   |-- capture-vision-docs-js
-|   |-- capture-vision-docs-server
-|   |-- capture-vision-docs-mobile
-|   |-- web-twain-docs
-|   `-- document-viewer-docs
-`-- .rag-cache/
-```
+- 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.
 
-## Source Code Structure
+## Advanced Configuration And Operator Docs
 
-```
-src/
-|-- index.js                            # MCP server + tool handlers
-|-- data-bootstrap.js                   # Runtime data resolver/downloader (npx mode)
-|-- data-root.js                        # Shared resolved data root selection
-|-- rag.js                              # Search provider selection and retrieval
-|-- normalizers.js                      # Product/platform/edition normalization
-|-- submodule-sync.js                   # Optional startup fast-forward sync
-|-- resource-index.js                   # Resource index composition layer
-`-- resource-index/                     # Split modules for maintainability
-    |-- config.js
-    |-- paths.js
-    |-- docs-loader.js
-    |-- samples.js
-    |-- uri.js
-    |-- version-policy.js
-    `-- builders.js
-scripts/
-|-- sync-submodules.mjs                 # CLI wrapper for data:sync
-|-- update-sdk-versions.mjs             # Sync SDK versions from docs structures
-|-- update-data-lock.mjs                # Generate data-manifest from submodule HEADs
-|-- verify-data-lock.mjs                # Verify manifest matches submodule HEADs
-`-- prebuild-rag-index.mjs              # Build local RAG index cache artifacts
-test/
-`-- integration/
-    |-- helpers.js                      # Shared MCP client/process helpers
-    |-- stdio.test.js                   # stdio integration tests
-    |-- http-gateway.test.js            # supergateway streamable HTTP integration tests
-    `-- package-runtime.test.js         # npm pack + package runtime integration test
-```
+Advanced settings, CI/runbook details, and maintenance workflows live in:
 
-`src/` contains runtime server code. `scripts/` contains operational helpers used by npm scripts.
-
-## Submodule Setup
-
-- Clone with submodules:
-  - `git clone --recurse-submodules <repo-url>`
-- If already cloned:
-  - `npm run data:bootstrap`
-- Check status:
-  - `npm run data:status`
-- Sync submodules to configured branches (fast-forward only):
-  - `npm run data:sync`
-- Refresh lock manifest after submodule updates:
-  - `npm run data:lock`
-- Verify lock manifest matches submodule HEADs:
-  - `npm run data:verify-lock`
-- Sync SDK versions from docs sources:
-  - `npm run data:versions`
-- Strict source-structure verification (fail on unresolved sources):
-  - `npm run data:verify-versions:strict`
-
-Optional startup sync:
-- `DATA_SYNC_ON_START=true`
-- `DATA_SYNC_TIMEOUT_MS=30000`
-
-Optional runtime data bootstrap (mainly for npm/npx installs):
-- `MCP_DATA_DIR=<existing data root>`
-- `MCP_DATA_AUTO_DOWNLOAD=true`
-- `MCP_DATA_CACHE_DIR=<cache path>`
-- `MCP_DATA_REFRESH_ON_START=false`
-
-Default cache location when `MCP_DATA_CACHE_DIR` is not set:
-- Windows: `%LOCALAPPDATA%\simple-dynamsoft-mcp\data`
-- Linux/macOS: `~/.cache/simple-dynamsoft-mcp/data`
-
-At startup, the server logs data mode/path to stderr:
-- `[data] mode=downloaded ... source=fresh-download|cache`
-- `[data] mode=bundled ...`
-- `[data] mode=custom ...`
-
-## Automation
-
-- CI workflow: `.github/workflows/ci.yml`
-- CI jobs:
-- `test_fuse` on `ubuntu-latest` runs `npm run test:fuse` (stdio + HTTP gateway + package-runtime with fuse provider)
-- `test_local_provider` on `ubuntu-latest` restores RAG caches, runs `npm run rag:prebuild`, then `npm run test:local`
-- `test_gemini_provider` on `ubuntu-latest` (when `GEMINI_API_KEY` secret exists) prebuilds gemini RAG cache, then runs `npm run test:gemini`
-- Daily data-lock refresh workflow: `.github/workflows/update-data-lock.yml`
-- Refresh schedule: daily at 08:00 UTC (`0 8 * * *`) and manual trigger supported.
-- Refresh workflow runs strict source checks (`data:versions:strict`, `data:verify-versions:strict`) to fail fast when external docs/sample structures drift.
-- Refresh workflow creates/updates PR `chore/daily-data-refresh` and enables auto-merge when checks pass (requires repo settings support).
-- Release workflow: `.github/workflows/release.yml`
-- Release behavior:
-- Creates GitHub release when `package.json` version changes on `main`
-- 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
-
-- `npm test`: default test entry (currently `npm run test:fuse`)
-- `npm run test:unit`: unit tests (retry/backoff/config helpers)
-- `npm run test:fuse`: integration coverage for fuse provider
-- `npm run test:local`: integration coverage for local provider
-- `npm run test:gemini`: integration coverage for gemini provider (requires `GEMINI_API_KEY`)
-- `npm run test:stdio`: stdio transport integration tests
-- `npm run test:http`: streamable HTTP (supergateway) integration tests
-- `npm run test:package`: `npm pack` + `npm exec --package` runtime test
-- Optional env toggles:
-- `RUN_FUSE_PROVIDER_TESTS=true|false`
-- `RUN_LOCAL_PROVIDER_TESTS=true|false`
-- `RUN_GEMINI_PROVIDER_TESTS=true|false`
-
-## Using Search-Based Discovery (Recommended)
-
-- On session start, let your client call `tools/list` and `resources/list` (pinned only, not exhaustive).
-- Read pinned `doc://product-selection` first to choose DBR vs DCV correctly for the scenario.
-- For any query, call `search`; it uses semantic RAG retrieval (with fuzzy fallback) and returns `resource_link` entries.
-- Read only the links you need via `resources/read` to avoid bloating the context window.
-- If unsure what to search, call `get_index` first to see what is available.
-
-## RAG Configuration
-
-Search providers are selected at runtime via environment variables (safe for public npm packages). Defaults to `auto` -> `gemini` if `GEMINI_API_KEY` is set, otherwise `local`, with `fuse` fallback on failure.
-
-To keep the legacy fuzzy search (no model download), set `RAG_PROVIDER=fuse`.
-
-Key env vars:
-- `RAG_PROVIDER`: `auto` | `gemini` | `local` | `fuse`
-- `RAG_FALLBACK`: `fuse` | `local` | `none`
-- `GEMINI_API_KEY`: required for remote embeddings
-- `GEMINI_EMBED_MODEL`: e.g. `models/embedding-001` or `models/gemini-embedding-001`
-- `GEMINI_RETRY_MAX_ATTEMPTS`: max retry attempts for retryable errors (default `5`)
-- `GEMINI_RETRY_BASE_DELAY_MS`: exponential backoff base delay (default `500`)
-- `GEMINI_RETRY_MAX_DELAY_MS`: exponential backoff max delay cap (default `10000`)
-- `GEMINI_REQUEST_THROTTLE_MS`: fixed delay between Gemini requests (default `0`)
-- `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`: 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`.
-Advanced tuning:
-- `RAG_CHUNK_SIZE`, `RAG_CHUNK_OVERLAP`, `RAG_MAX_CHUNKS_PER_DOC`, `RAG_MAX_TEXT_CHARS`
-- `RAG_MIN_SCORE`, `RAG_INCLUDE_SCORE`, `RAG_REBUILD`, `RAG_PREWARM`, `RAG_PREWARM_BLOCK`, `RAG_LOCAL_QUANTIZED`, `GEMINI_EMBED_BATCH_SIZE`, `RAG_MODEL_CACHE_DIR`
-
-Gemini hardening behavior:
-- Retryable responses (`429`, `503`, transient `5xx`) use exponential backoff with jitter.
-- Optional throttling can pace request bursts with `GEMINI_REQUEST_THROTTLE_MS`.
-- Batch embedding adaptively downgrades batch size on repeated rate-limit responses.
-- Index build progress is checkpointed to disk and resumes from checkpoints after failures.
-
-For local dev, you can also use a `.env` file (see `.env.example`).
-
-## Version Policy
-
-- This MCP server serves only the latest major version for each product (DCV, DBR, DWT, DDV).
-- DBR legacy docs are linked for v9 and v10. Requests below v9 are refused.
-- DCV has no legacy archive links in this server.
-- DWT archived docs are available for v16.1.1+ (specific versions are hardcoded).
-- DDV has no legacy archive links in this server.
-
-## Roadmap
-
-- Deferred release automation plan and implementation notes are tracked in `TODO.md`.
-- If you are continuing release pipeline work, start with the checklist in `TODO.md`.
-
-## Extending the Server
-
-### Add New Samples
-
-Update the corresponding submodule under `data/samples/`.
-
-### Update SDK Info
-
-Use `npm run data:versions` (or `npm run data:versions:strict`) to refresh SDK versions from docs sources.
-Edit `data/metadata/dynamsoft_sdks.json` manually only for non-version metadata updates (for example docs URLs, installation commands, or platform definitions).
+- `AGENTS.md`
+- `.env.example`
 
 ## License
 
 MIT
-