localrag-mcp — Local Document RAG Retrieval Plugin (DeepSeek Harness)

An MCP tool plugin that provides local knowledge retrieval capabilities for agents in DeepSeek Harness: agents can directly call tools such as mcp__localrag__search during conversations, performing semantic retrieval with source citations on local documents.

Ecosystem contribution: This is a practical project following the "Create and share plugins" section in the official DeepSeek Harness contribution guide. After publishing it on GitHub with the dsh-plugin topic, it can be discovered by the community.

Architecture

DeepSeek Harness (dsh web)
   │  --patch localrag.cordis.yml
   ▼
@deepseek-ai/dsh-mcp-client  (官方通用 MCP 客户端)
   │  启动 stdio 子进程
   ▼
server.py  (Python, FastMCP)
   ├── index_documents(path)   # 扫描目录，分块 + 向量化，写入 Chroma
   ├── search(query, k)        # 语义检索，返回文本 + 来源路径 + 分数
   └── list_documents()        # 列出知识库中的文档
   │
   ├── 向量模型：fastembed / BAAI/bge-small-zh-v1.5（本地 ONNX，无需 API key）
   └── 向量库：Chroma（持久化到 ./data/chroma）

Related MCP server: Notebook Library MCP Server

Quick Start

# 1. 安装依赖（Python 3.10+）
cd localrag-mcp
pip install -r requirements.txt

# 2. 独立冒烟测试（不依赖 Harness）
python test-client.py
# 预期输出：tools: [...]; index: indexed 2 files, N chunks; search: 命中结果

# 3. 接入 DeepSeek Harness（在 harness 仓库根目录）
pnpm dsh web --patch D:\programing\python\LangChain\models\localrag-mcp\localrag.cordis.yml
# 首次会下载 bge-small-zh 模型（约 95MB，仅一次）

# 4. 在对话里使用
#    "先索引 D:\...\docs，然后检索：LangGraph 多 agent 是怎么协作的？"
#    agent 会依次调用 index_documents → search，并基于检索结果回答

✅ Verification Results (Actual Run)

Standalone test (python test-client.py):

tools: ['index_documents', 'search', 'list_documents']
index: indexed 2 files, 4 chunks into 'documents'
search: 命中 langgraph-multiagent.md（top score 0.537，带 source 路径）

Harness integration (pnpm dsh web --patch localrag.cordis.yml) actual test: the agent sequentially calls index_documents → search as prompted, and the final answer includes source and score citations:

Main source: langgraph-multiagent.md (chunks 0, 1, retrieval score 0.4851 / 0.2863) Supplementary background: langchain-basics.md (score 0.1219)

Tool List (agent perspective)

Design Highlights

• Retrieval with sources: Each chunk records source (absolute file path), enabling agent answers to be traced back — this is the key capability distinguishing it from ordinary chat

• Fully local operation: Embedding uses ONNX local inference, no dependency on external embedding API, no keys required

• Chunking strategy: 512-character sliding window + 64 overlap, friendly for Chinese documents (v2 can upgrade to semantic chunking)

• Incremental indexing: upsert deduplicates by file, re-indexing the same directory will not produce duplicate vectors

Roadmap (v2)

• PDF / Word support (pdfplumber + python-docx)

• Semantic chunking (based on paragraphs/headings, not fixed window)

• Wrap with LangChain into a standard RAG pipeline (multi-path recall + reranking)

• Integration with multi-agent deep research system (retrieval worker reuses this plugin)

• Evaluation: Score retrieval quality with RAGAS

Resume Usage

Developed a dsh-plugin for the DeepSeek Harness ecosystem: a local document RAG retrieval MCP plugin (Python + Chroma + fastembed)

• Implemented three MCP tools: index, search, list. Agents can call them directly in conversations, with source citations in retrieval results.

• Fully local vectorization (bge-small-zh, ONNX) and persistent storage, no external API required.

• Mounted via the official --patch mechanism, and completed standalone smoke testing and Harness integration verification.

Related Links

• DeepSeek Harness official contribution guide (plugin sharing path): https://github.com/deepseek-ai/deepseek-harness

• Community plugin pitfalls summary: Discusion #380

• MCP universal client: @deepseek-ai/dsh-mcp-client