mcp-local-rag/setup

安装与排障

---

安装

全局安装（推荐）

npm install -g @damoqiongqiu/mcp-local-rag

按需运行

不安装也行，通过 npx @damoqiongqiu/mcp-local-rag 按需拉取运行。

WorkBuddy 配置

在 WorkBuddy 中配置为 MCP Connector（stdio transport），按需设置环境变量即可。无需额外安装步骤。

推荐配置（代码项目）：

{
  "mcpServers": {
    "mcp-local-rag": {
      "command": "npx",
      "args": ["-y", "@damoqiongqiu/mcp-local-rag"],
      "env": {
        "BASE_DIR": "/path/to/your/project",
        "RAG_HYBRID_WEIGHT": "0.7"
      }
    }
  }
}

RAG_HYBRID_WEIGHT: 0.7 是代码场景的推荐值——在语义理解和精确符号匹配之间取得平衡。纯文档场景可降至 0.4。

---

首次运行与模型下载

首次 ingest_file 或 query_documents 调用会触发模型下载：

• Embedding 模型：Xenova/all-MiniLM-L6-v2（默认），约 80MB
• VLM 模型（可选）：
  • fast：HuggingFaceTB/SmolVLM-256M-Instruct，约 250MB
  • quality：onnx-community/Qwen2.5-VL-3B-Instruct-ONNX，约 2.9GB
• 缓存位置：CACHE_DIR（默认 ./models/），模型下载后缓存复用，不再需要联网

模型仅在首次使用时下载，后续离线可用。

---

🇨🇳 国内网络注意事项

mcp-local-rag 依赖 HuggingFace（huggingface.co）下载模型。国内网络环境下可能无法直接访问。v0.18.5 提供了三层保障：

⚡ 推荐：配置代理（最简单可靠）

如果你已经在本地运行 ClashX / V2Ray 等代理工具，只需设置 HTTPS_PROXY，一切自动工作：

export HTTPS_PROXY=http://127.0.0.1:7890

在 MCP connector 配置中：

{
  "mcpServers": {
    "mcp-local-rag": {
      "command": "npx",
      "args": ["-y", "@damoqiongqiu/mcp-local-rag"],
      "env": {
        "BASE_DIR": "/path/to/your/project",
        "HTTPS_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}

💡 v0.18.5 改进：Node.js 22 内置的 undici HTTP 库默认不读取 HTTPS_PROXY。v0.18.5 通过 setGlobalDispatcher 全局注入代理，确保所有模型下载请求都走代理，无需额外配置。

🔄 自动镜像回退（无需代理）

如果你没有本地代理，mcp-local-rag 自带三级镜像链，首次下载前自动探测：

1. huggingface.co (官方) → 3s 超时
2. hf-mirror.com (社区镜像) → 文件下载 + API 双重验证
3. modelscope.cn (魔搭社区) → 完整托管所有 ONNX 权重文件

整个过程会清晰打印日志：

Embedder: Using proxy "http://127.0.0.1:7890" for all network requests
Embedder: Downloading model from https://huggingface.co ...

如果代理未设置且直连失败：

Embedder: huggingface.co is unreachable, auto-switching to mirror https://hf-mirror.com
Embedder: Mirror https://hf-mirror.com is reachable but Hub API is unavailable
Embedder: Auto-switching to mirror https://modelscope.cn