localrag-mcp — 로컬 문서 RAG 검색 플러그인 (DeepSeek Harness)

DeepSeek Harness의 agent에 로컬 지식 검색 기능을 제공하는 MCP 도구 플러그인: agent는 대화 중에 mcp__localrag__search 등의 도구를 직접 호출하여 로컬 문서에 대해 의미 검색을 수행하고 출처를 인용한 답변을 제공할 수 있습니다.

생태계 기여: 이는 DeepSeek Harness 공식 기여 가이드의 "플러그인 생성 및 공유" 실습 프로젝트로, GitHub에 게시한 후 dsh-plugin 태그를 추가하면 커뮤니티에서 발견할 수 있습니다.

아키텍처

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

빠른 시작

# 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，并基于检索结果回答

✅ 검증 결과 (실제 실행)

독립 테스트 (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 통합 (pnpm dsh web --patch localrag.cordis.yml) 실제 측정: agent가 프롬프트에 따라 순서대로 index_documents → search를 호출하며, 최종 답변에 출처 및 점수 인용을 포함합니다:

주요 출처: langgraph-multiagent.md (chunk 0, 1, 검색 점수 0.4851 / 0.2863) 추가 배경: langchain-basics.md (점수 0.1219)

도구 목록 (agent 관점)

설계 포인트

• 검색 시 출처 포함: 각 청크에 source(파일 절대 경로)를 기록하여 agent 답변의 추적 가능성 확보 — 이는 일반 채팅과의 핵심 차별점

• 전체 로컬 실행: 임베딩은 ONNX 로컬 추론을 사용, 외부 임베딩 API에 의존하지 않으며, API 키 불필요

• 청크 전략: 512자 슬라이딩 윈도우 + 64자 중첩, 한글 문서에 친화적 (v2에서는 의미 기반 청크로 업그레이드 가능)

• 증분 인덱싱: upsert로 파일별 중복 제거, 동일 디렉토리 재인덱싱 시 중복 벡터 생성 방지

로드맵 (v2)

• PDF / Word 지원 (pdfplumber + python-docx)

• 의미 기반 청크 (고정 윈도우 대신 문단/제목 기반)

• LangChain으로 표준 RAG 파이프라인 캡슐화 (다중 경로 검색 + 재순위화)

• 다중 agent 심층 연구 시스템과 통합 (검색 worker가 본 플러그인 재사용)

• 평가: RAGAS로 검색 품질 평가

이력서 활용

DeepSeek Harness 생태계를 위한 dsh-plugin 개발: 로컬 문서 RAG 검색 MCP 플러그인 (Python + Chroma + fastembed)

• index/search/list 세 가지 MCP 도구 구현, agent 대화에서 직접 호출 가능, 검색 결과에 출처 인용 포함

• 전체 로컬 벡터화 (bge-small-zh, ONNX) 및 영구 저장, 외부 API 불필요

• 공식 --patch 메커니즘을 통해 마운트, 독립 스모크 테스트 및 Harness 통합 검증 완료

관련 링크

• DeepSeek Harness 공식 기여 가이드 (플러그인 공유 경로): https://github.com/deepseek-ai/deepseek-harness

• 커뮤니티 플러그인 경험 정리: Discussion #380

• MCP 범용 클라이언트: @deepseek-ai/dsh-mcp-client