使用说明
RAG MCP Server
專為 Claude CLI 設計的本地 RAG（檢索增強生成）MCP Server，讓 Claude 能搜尋專案原始碼與第三方函式庫，同時最小化 Token 消耗。
更新歷史
| 負責人 | 日期 | 摘要 |
|---|---|---|
| aries.hong | 2026/03/05 | 文件建立 |
| aries.hong | 2026/03/06 | - 取消白名單機制 - 新增支援語言javascript、typescript和rust |
| aries.hong | 2026/03/10 | 新增支援索引目標：.xml、Dockerfile、.launch、.sh |
| aries.hong | 2026/03/11 | 新增支援索引目標：.ipynb（Jupyter Notebook） |
| aries.hong | 2026/03/13 | Library 改用共享 third_party collection，以 metadata 區分 |
運行環境
- Python 3.13.5
- Git for Windows（git hook 必須）
- Embedding 模型（本地執行，不需要 API key）
- 第三方函式庫：BAAI/bge-base-en-v1.5
- 專案程式碼：jinaai/jina-embeddings-v2-base-code
- 模型於首次使用時自動下載並快取至本地（由 fastembed 管理）
安裝依賴：
cd rag-mcp-server
pip install -r requirements.txt
快速開始
- 安裝依賴（首次執行時 fastembed 會自動下載 embedding 模型）
- 將 MCP server 註冊到 Claude CLI
# For Windows. `--scope` can specify the setting scope. Use `user` can apply the setting to global scope
> claude mcp add --scope user rag_mcp_server D:\path\to\python.exe D:\path\to\rag-mcp-server\server\main.py
# For linux (not test yet)
$ claude mcp add --scope user rag_mcp_server /path/to/.venv/bin/python3 /path/to/server/main.py
- 測試MCP Server
> claude mcp list
# Successful if "Connected" is shown.
rag_mcp_server: .\.venv\Scripts\python.exe .\server\main.py - ✓ Connected
- 每個專案：複製 git hook 並填寫設定(詳情請見索引專案（git hook, Not tested yet）)
- 手動對第三方函式庫執行
index_library.py(詳情請見索引第三方函式庫(Not tested yet)) - 開啟 Claude CLI — ChromaDB 自動啟動
自訂設定
編輯 config.py 調整伺服器行為：
# ChromaDB 連線設定（預設：localhost:8000）
CHROMA_CONFIG = ChromaConfig(host="localhost", port=8000)
# 不索引的目錄
BLACKLIST_DIRS = frozenset({"build", ".git", "node_modules"})
# 不索引的副檔名
BLACKLIST_EXTENSIONS = frozenset({".so", ".dll", ".a", ".lib"})
ChromaDB 資料存放於 rag-mcp-server/chroma_data/。
索引專案（git hook, Not tested yet）
每次 git commit 後自動觸發 hook，僅處理本次變動的檔案。
範例：新增 JavaScript 專案
# 建立專案目錄
mkdir -p D:/path/to/workspace/projects/javascript/myapp
cd D:/path/to/workspace/projects/javascript/myapp
git init
# 複製 hook
cp D:/path/to/workspace/rag-mcp-server/hooks/post-commit .git/hooks/post-commit
chmod +x .git/hooks/post-commit
編輯 .git/hooks/post-commit — 填入以下設定區塊：
# =========================================================
# USER CONFIGURATION
# =========================================================
PROJECT_TYPE="javascript"
PROJECT_NAME="myapp"
RAG_SERVER_DIR="/d/path/to/workspace/rag-mcp-server" # Git Bash 路徑格式
PYTHON="python"
# =========================================================
Windows 路徑格式： Git Bash 使用
/d/Aries/...而非D:\Aries\...。 若使用虛擬環境：PYTHON="$RAG_SERVER_DIR/.venv/Scripts/python"
下次 git commit 後，collection javascript 即自動建立，專案名稱 myapp 記錄於 metadata。
索引第三方函式庫
[注意] 執行前必須確保在
rag-mcp-server目錄底下
支援的檔案類型：
| 副檔名 | 語言 |
|---|---|
.c |
C |
.cpp .h .hpp |
C++ |
.py |
Python |
.rs |
Rust |
.js .jsx |
JavaScript |
.ts .tsx |
TypeScript |
.md |
Markdown |
.txt |
純文字 |
.xml |
XML |
Dockerfile |
Docker |
.launch |
ROS Launch |
.sh |
Shell Script |
.ipynb |
Jupyter Notebook |
單個函式庫：
python -m indexer.index_library --path D:\path\to\third_party\react
→ 存入 collection third_party，metadata library=react
多個函式庫 — 每個分別執行：
python -m indexer.index_library --path D:\path\to\third_party\react
python -m indexer.index_library --path D:\path\to\third_party\lodash
強制重建索引 — 函式庫內容有更新時使用：
python -m indexer.index_library --path third_party/react --force
--force 會刪除該 library 的所有 chunks（以 metadata 過濾），再重新索引。
MCP Tools
| Tool | 說明 |
|---|---|
list_collections() |
列出所有可用的 collection |
search_library(lib_name, query) |
搜尋第三方函式庫（以 metadata 過濾指定 library） |
search_project(project_type, project_name, query) |
搜尋單一專案（project_type 為 collection 名稱，project_name 以 metadata 過濾） |
search_all_projects(query) |
跨所有專案搜尋，回傳全域 top 5 |
每筆結果包含：檔案路徑、函式／類別名稱、相似度分數、原始碼。
以 javascript/myapp 為例的完整使用流程：
# 查看已索引的 collection
list_collections()
→ javascript, third_party
# 搜尋專案內的程式碼
search_project("javascript", "myapp", "handle click event")
# 搜尋函式庫
search_library("react", "useState with async")
# 跨所有專案搜尋
search_all_projects("debounce function")
常見問題：
| 問題 | 解決方式 |
|---|---|
chroma: command not found |
確認已安裝：pip install chromadb |
| 首次啟動下載模型很慢 | fastembed 模型只下載一次，後續快取於本地 |
| Hook 未觸發 | 確認 chmod +x .git/hooks/post-commit 及路徑格式 |
| Collection 找不到 | 執行 list_collections() 確認正確的 collection 名稱 |
