codebase-rag-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
codebase-rag-mcp
把 local-codebase-rag 的檢索能力包成 MCP Server,提供一個 search_codebase tool。接上之後,Claude Code、Claude Desktop 等 MCP host 可以直接查詢遊戲前端專案的程式碼,回答時引用 檔案:行號。
In English: an MCP server that exposes local-codebase-rag's retrieval pipeline as one read-only tool,
search_codebase. The tool returns excerpts withpath:start-end; the host's model reads them and writes the answer. The server is a thin stdio process that calls the backend's retrieval-onlyPOST /searchendpoint over HTTP and depends only on the MCP Python SDK. Design records are indocs/decisions/, the learning journal indocs/learning/, next steps indocs/roadmap.md.
目錄
Related MCP server: Codebase Copilot MCP Server
為什麼要做
local-codebase-rag 已經有網頁介面,但回答是由本機的 qwen2.5-coder 寫的。做成 MCP Server 之後:
回答交給更強的模型:tool 只回傳取回的程式碼片段,由 host 的模型(例如 Claude)閱讀後回答,不經過第二個模型轉述(ADR 0001)。
在工作流程裡直接用:在 Claude Code 寫程式時就能問「這個數值在哪裡設定」,不用切到瀏覽器。
檢索設定只有一份:MCP Server 不自己做檢索,
HYBRID_SEARCH、SPLIT_RETRIEVAL等開關與評估結果完全沿用後端。
架構
flowchart LR
subgraph host["MCP host(Claude Code/Claude Desktop)"]
model["模型"] --> client["MCP client"]
end
client -- "stdio(JSON-RPC)<br/>tools/list、tools/call" --> mcp["codebase-rag-mcp<br/>search_codebase"]
mcp -- "HTTP POST /search<br/>只檢索、不呼叫 LLM" --> be["local-codebase-rag 後端<br/>127.0.0.1:8000"]
be <--> qd[("Qdrant")]
be -- "embedding" --> ollama["Ollama"]一次呼叫的流程:
Host 啟動
codebase-rag-mcp子行程,透過 stdin/stdout 交換 JSON-RPC 訊息,先initialize協商能力。Host 呼叫
tools/list,取得search_codebase的名稱、描述與 JSON Schema,放進模型的 context。模型決定要查時送出
tools/call;server 呼叫後端POST /search,把片段整理成 Markdown(給模型讀)與結構化資料(給程式用)回傳(ADR 0003)。
前置條件
local-codebase-rag 已啟動並建立索引(
./scripts/setup.sh --index)。後端包含
POST /search端點。目前要先套用patches/local-codebase-rag-search-endpoint.patch,之後會合併進 local-codebase-rag。Python 3.11 以上,建議安裝 uv。
確認後端可用:
curl -s http://localhost:8000/search -H 'Content-Type: application/json' \
-d '{"question": "INVINCIBLE_MS 在哪裡設定", "top_k": 2}'安裝與接上 MCP host
git clone https://github.com/alelcold/codebase-rag-mcp.gitcd codebase-rag-mcp && uv sync --extra devClaude Code
在要使用的專案根目錄建立 .mcp.json(路徑改成你的 clone 位置):
{
"mcpServers": {
"codebase-rag": {
"command": "uv",
"args": ["run", "--directory", "/絕對路徑/codebase-rag-mcp", "codebase-rag-mcp"],
"env": { "CODEBASE_RAG_URL": "http://localhost:8000" }
}
}
}或用指令加入:
claude mcp add codebase-rag -e CODEBASE_RAG_URL=http://localhost:8000 -- uv run --directory /絕對路徑/codebase-rag-mcp codebase-rag-mcp在 Claude Code 裡輸入 /mcp 可以看到連線狀態。
Claude Desktop
把同樣的 mcpServers 區塊加進 claude_desktop_config.json,重新啟動 Claude Desktop。
用 MCP Inspector 手動測試
npx @modelcontextprotocol/inspector uv run --directory . codebase-rag-mcp瀏覽器會打開 Inspector,可以看到 initialize 的回應、tool 清單,並手動呼叫 search_codebase。
Tool 規格
search_codebase(readOnlyHint: true、openWorldHint: false)
參數 | 型別 | 說明 |
| string(1–4000 字) | 自然語言(中文或英文)或識別字,例如 |
| integer(1–30,選填) | 回傳片段數,預設 |
回傳:
text:每個片段一個標題
## [1] src/config/gameConfig.ts:3-9 \INVINCIBLE_MS``,加上程式碼區塊。structuredContent:
{query, results: [{ref, location, file_path, start_line, end_line, symbol, kind, language, score, matched_by, truncated, text}]},格式由outputSchema定義。後端連不上、逾時、尚未索引時回傳
isError: true,訊息說明原因與修正方式,讓模型能轉告使用者。
設定
都在 MCP host 設定的 env 區塊裡設定。
變數 | 預設 | 說明 |
|
| local-codebase-rag 後端位址 |
|
| 等待 |
|
| 模型沒指定時的片段數 |
|
| 每個片段最多保留的字元數,控制 tool 結果佔用的 context |
開發與測試
uv run pytest測試不需要後端:MCP 層用 SDK 的記憶體內 Client 走完整的 initialize → tools/list → tools/call;HTTP client 對一個本機假後端測試。
注意:stdio 模式下 stdout 專門傳 JSON-RPC,任何 print() 都會破壞協定。記錄請用 logging(預設輸出到 stderr)。
文件導覽
文件 | 內容 |
ADR:為什麼這樣設計、考慮過哪些方案 | |
開發日誌:問題 → 原因 → 解法 | |
MCP 學習筆記與待探討問題 | |
後續發展階段 | |
要套用到 local-codebase-rag 的修改 |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Search verified Claude Code plugins and skills; fetch portable SKILL.md sources. Read-only.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes Cursor's semantic code search through MCP, enabling tools like codebase_search to query indexed repos.1-
- FlicenseNot gradedqualityDmaintenanceExposes code search and file reading tools over the Model Context Protocol, enabling any MCP-compatible client to query a codebase with natural language.-
- AlicenseAqualityCmaintenanceEnables Claude Code to perform fuzzy and semantic codebase search via a query_codebase tool.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients such as Claude Desktop and Claude Code to query an indexed source repository through path-guarded tools for hybrid keyword-and-vector code search, file snippets, symbol explanations, reference lookups, and test-skeleton suggestions. Serves those results over stdio with cited file:line locations so agents can answer questions about a codebase and drive grounded code review.MIT