AmanMCP

探索

Amanmcp

AmanMCP是一個隱私優先、零配置的本地代碼庫檢索增強生成(RAG)工具，通過MCP協議與Claude AI集成，提供混合搜索功能，完全在本地運行，無需網絡連接。

開發者工具搜索工具 #本地RAG #代碼搜索 #隱私優先 #混合檢索 .Go

評分 : 2.5分

下載量 : 4.8K

更新時間 : 2026-03-12

打開站點

什麼是 AmanMCP?

AmanMCP 是一個專為開發者設計的本地代碼搜索助手。它就像您代碼庫的智能大腦，能夠理解您的代碼結構和語義。當您向 Claude AI 提問時，AmanMCP 會從您的代碼庫中找到最相關的代碼片段作為上下文，幫助 Claude 給出更準確的答案。整個過程完全在您的電腦上運行，您的代碼永遠不會離開您的設備。

如何使用 AmanMCP?

使用 AmanMCP 非常簡單：1) 安裝 Ollama 和 AmanMCP；2) 在您的項目目錄中運行初始化命令；3) 重啟 Claude Code；4) 開始用自然語言提問。AmanMCP 會自動索引您的代碼，並在後臺與 Claude 通信，無需您手動管理。

適用場景

AmanMCP 特別適合以下場景： • 探索不熟悉的代碼庫：快速找到相關函數和類 • 代碼審查：查找特定功能的實現 • 重構代碼：瞭解代碼依賴關係 • 學習項目結構：理解大型項目的架構 • 日常開發：快速定位需要修改的代碼位置

主要功能

混合搜索技術

結合關鍵詞搜索（BM25）和語義搜索（向量），既能精確匹配關鍵詞，又能理解查詢意圖。例如搜索'登錄功能'時，既能找到包含'login'的代碼，也能找到處理認證但不含該關鍵詞的代碼。

智能代碼分塊

基於抽象語法樹（AST）分析代碼結構，確保函數、類等邏輯單元保持完整，不會在中間被切斷，提高搜索結果的準確性。

隱私優先設計

所有處理都在本地完成，無需網絡連接，不收集任何用戶數據，您的代碼永遠不會上傳到雲端。

多語言支持

支持 30+ 編程語言，包括 Go、Python、JavaScript、TypeScript、Java、C++ 等主流語言。

快速查詢響應

查詢響應時間通常小於 100 毫秒，幾乎感覺不到延遲，提供流暢的開發體驗。

零配置啟動

只需一個命令即可初始化項目，自動檢測代碼結構，無需手動配置。

優勢

完全本地運行，保護代碼隱私和安全

無需網絡連接，離線可用

響應速度快，查詢延遲低

支持自然語言查詢，無需記憶具體函數名

自動索引，無需手動維護

開源免費，可自定義擴展

侷限性

Alpha 版本，可能存在穩定性問題

需要本地安裝 Ollama 和模型，佔用磁盤空間

首次索引大型代碼庫需要時間

目前主要支持 macOS 和 Linux，Windows 支持有限

需要 Claude Code 編輯器配合使用

如何使用

安裝前提條件

首先需要安裝 Ollama，這是運行本地 AI 模型的工具。在 macOS 上可以使用 Homebrew 安裝：

安裝 AmanMCP

通過 Homebrew 安裝 AmanMCP：

初始化項目

進入您的項目目錄，運行初始化命令。這會自動啟動 Ollama、下載必要的 AI 模型，並開始索引您的代碼：

重啟 Claude Code

重啟 Claude Code 編輯器，它會自動檢測並連接到 AmanMCP。

開始提問

在 Claude Code 中，像平常一樣提問，AmanMCP 會自動提供代碼上下文。

使用案例

探索新代碼庫

當您接手一個新項目時，可以使用 AmanMCP 快速瞭解代碼結構。

查找特定功能

當您需要修改某個功能但不確定具體位置時。

代碼審查輔助

在審查代碼時，瞭解相關代碼的上下文。

常見問題

AmanMCP 需要網絡連接嗎？

我的代碼會被上傳到雲端嗎？

支持哪些編程語言？

索引大型代碼庫需要多長時間？

可以在團隊中共享索引嗎？

如果 Ollama 服務停止會怎樣？

🚀 AmanMCP

AmanMCP 是一款用於代碼庫的本地檢索增強生成（RAG）工具，無需配置，注重隱私保護。

🚀 快速開始

前提條件：已安裝 Ollama（可使用 brew install ollama 進行安裝）。

# 安裝
brew tap Aman-CERP/tap && brew install amanmcp

# 初始化（自動啟動 Ollama，拉取模型並建立索引）
cd your-project && amanmcp init

# 重啟 Claude Code，完成配置

向 Claude 提問：“Search my codebase for authentication”

✨ 主要特性

混合搜索：結合 BM25 和語義搜索，提供更精準的搜索結果。
AST 感知分塊：智能分塊代碼，保留語義邊界。
多語言支持：支持多種編程語言。
快速查詢：查詢響應時間小於 100 毫秒。

📦 安裝指南

安裝方式	命令
Homebrew	`brew tap Aman-CERP/tap && brew install amanmcp`
腳本安裝	`curl -sSL https://raw.githubusercontent.com/Aman-CERP/amanmcp/main/scripts/install.sh \| sh`
從源碼安裝	`git clone ... && make install-local`
離線安裝	`amanmcp init --offline`（僅使用 BM25，無需模型）

💻 使用示例

基礎用法

向 Claude 提問：“Search my codebase for authentication”

高級用法

可根據不同的需求，使用不同的工具進行代碼搜索。例如，使用 search_code 工具查找函數、類和類型：

"Find the function that handles database connections"

📚 詳細文檔

文檔導航

需求	文檔鏈接
逐步入門	快速入門指南
查看所有 CLI 命令	命令參考
配置設置	配置文檔
使用 MLX（Apple Silicon）	MLX 設置指南
瞭解搜索工作原理	混合搜索指南
貢獻代碼	貢獻指南

文檔分類

文章 - 深度剖析與洞察

文檔	主題	問題	關鍵洞察
AI 工程指南	學習路線圖	如何高效學習 AI/ML 工程？	採用 80/20 方法，專注於跨工具通用的基礎知識。
AI 原生項目管理	人機協作	當 AI 完成大部分編碼時，如何管理項目？	採用人類主導 / AI 執行的模型，結合上下文管理和會話工作流。
AI 原生文檔經驗教訓	文檔策略	如何防止文檔氾濫？	內部文檔積累速度可能超過其實際用途，整合策略很重要。
黑盒架構案例研究	模塊化設計	如何構建可擴展且可維護的系統？	遵循 Eskil Steenberg 的原則：穩定的接口 + 隱藏的複雜性 = 數十年的耐用性。
Claude 代碼搜索與 AmanMCP 基準測試	工具比較	何時使用內置工具，何時使用專業搜索工具？	工具是互補的，各有優勢。
調試 MCP 協議	協議調試	為什麼 MCP 集成會神秘失敗？	標準輸出汙染會破壞協議，MCP 使用標準輸入輸出進行通信。
小模型，更好的搜索	模型選擇	在資源受限的情況下，如何選擇嵌入模型？	0.6B 模型通過質量聚焦調優，在特定任務上可優於 8B 模型。
靜態嵌入解釋	回退模式	何時使用靜態嵌入，何時使用動態嵌入？	零依賴嵌入可實現即時啟動和優雅降級。
零摩擦經驗教訓	開發者用戶體驗	如何實現“即插即用”的理念？	每個手動步驟都是一個有漏洞的抽象，自動檢測優於配置。

→ 文章文檔概述

概念 - 核心思想與理論

文檔	主題	問題	關鍵洞察
混合搜索	搜索基礎	為什麼要結合關鍵字和語義搜索？	BM25 用於精確匹配，向量搜索用於查找語義，融合兩者可獲得優勢。
MCP 協議	AI 集成	AmanMCP 如何與 Claude 通信？	模型上下文協議通過 JSON-RPC 實現結構化的 AI 工具通信。
Tree-sitter 指南	代碼解析	如何在不使用特定語言解析器的情況下解析代碼？	AST 感知分塊可在 30 多種語言中保留語義邊界。
兩階段檢索	搜索優化	為什麼要進行兩次搜索而不是一次？	先進行快速過濾（候選），再進行精確排序，可平衡速度和準確性。
向量搜索概念	語義搜索	語義搜索實際是如何工作的？	嵌入將文本轉換為數字，以幾何方式捕捉語義。

→ 概念文檔概述

指南 - 逐步指導

文檔	主題	問題	關鍵洞察
首次用戶指南	入門	如何從頭開始設置 AmanMCP？	五個步驟：安裝 Ollama、安裝 AmanMCP、初始化項目、重啟 Claude、查詢。
Homebrew 設置指南	安裝	如何在 macOS 上通過 Homebrew 安裝？	Homebrew 提供自動更新和依賴管理。
MLX 設置	性能	如何在 Apple Silicon 上獲得更快的嵌入？	MLX 生成本地嵌入的速度比 Ollama 快 16 倍。
後端切換	配置	如何在 Ollama 和 MLX 嵌入之間切換？	通過簡單的配置更改即可比較不同後端的性能。
自動重新索引	工作流	如何使搜索索引與代碼更改保持同步？	文件監控可實現即時增量更新，無需手動重新索引。
熱管理	優化	如何在索引過程中降低 CPU 熱量？	通過批量大小和併發調整優化 CPU 溫度。

→ 指南文檔概述

研究 - 調查與決策

文檔	主題	問題	關鍵洞察
搜索質量改進系列	綜合	如何全面解決詞彙不匹配問題？	向量的上下文檢索 + BM25 的查詢擴展將通過率從 60% 提高到 92%。
上下文檢索決策	搜索增強	如何彌合查詢和代碼之間的詞彙不匹配？	在嵌入之前，使用模式回退將大語言模型生成的上下文添加到分塊中。
上下文檢索迴歸	質量分析	增強功能如何導致迴歸？	小嵌入模型 + 上下文前綴可能在嵌入空間中聚類。
查詢擴展非對稱	查詢處理	是否應該為所有搜索後端擴展查詢？	僅為 BM25 擴展查詢，擴展有助於關鍵字搜索，但會稀釋嵌入。
RRF 融合原理	搜索融合	如何結合 BM25 和向量搜索結果？	互惠排名融合（k = 60）提供了一種簡單有效的組合方式，無需訓練。
詞彙不匹配分析	搜索質量	為什麼語義搜索在代碼搜索中失敗？	用戶說“search function”，代碼中是 `func Search`，這是 40% 失敗的根本原因。
內部測試方法	質量驗證	如何驗證 RAG 搜索質量？	採用分層查詢系統和 5 個為什麼根本原因分析，捕捉語義差距。
嵌入模型	模型選擇	用於代碼搜索的嵌入模型是哪個？	qwen3 - 0.6b 平衡了質量和資源，代碼專用模型可將檢索性能提高 7 - 8%。
嵌入後端演變	後端選擇	默認使用哪個嵌入後端？	Ollama 默認（低內存），MLX 可選（快 16 倍），內存對於開發更重要。
嵌入優化	性能	如何優化嵌入性能？	MLX 與 TEI 基準測試揭示了批量大小調整和 GPU 利用率模式。
嵌入模型演變	演變	我們的嵌入選擇是如何演變的？	nomic → Hugot → Qwen3，每次過渡都帶來了關於權衡的經驗教訓。
SQLite 與 Bleve	存儲後端	用於併發訪問的 BM25 後端是哪個？	SQLite FTS5 支持併發訪問（WAL 模式），純 Go 實現，經過生產驗證。
向量數據庫選擇	向量存儲	本地優先的向量數據庫是哪個？	USearch → coder/hnsw，純 Go 實現，可擴展到 300K+ 向量。
專業化與泛化	模型策略	應該使用專業化模型還是通用模型？	專業化模型在特定領域表現出色，通用模型提供更好的回退。
Tree-sitter 分塊	代碼解析	如何智能分塊代碼？	AST 感知邊界保留語義單元，雖然需要 CGO，但值得。
MLX 遷移案例研究	性能遷移	如何規劃和執行性能遷移？	在實施前進行驗證，始終有回退方案，優先使用自動檢測。
RAG 可觀測性	操作	如何觀察 RAG 系統？	RAG 與代理的區別需要結構化日誌記錄和搜索質量指標。

→ 研究文檔概述

貢獻 - 開發者資源

文檔	主題	問題	關鍵洞察
代碼規範	代碼風格	貢獻代碼時應遵循哪些標準？	錯誤包裝、資源清理和配置驅動的行為是不可協商的。
測試指南	質量保證	如何為 AmanMCP 編寫測試？	使用表驅動測試和黃金文件進行確定性驗證。
TDD 原理	開發過程	為什麼 AmanMCP 需要測試優先開發？	測試作為規範可防止返工，實現無畏重構。

→ 查看所有 3 篇貢獻文檔

參考 - 技術規範

文檔	主題	問題	關鍵洞察
命令	CLI 使用	AmanMCP 有哪些可用命令？	六個核心命令處理初始化、搜索、健康檢查和維護。
配置	設置	如何自定義 AmanMCP 的行為？	YAML 配置控制路徑、模型、權重和排除項。
架構	系統設計	AmanMCP 內部是如何結構的？	清晰分離：MCP 層、搜索引擎、存儲、嵌入管道。
術語表	術語	RRF 和 HNSW 等技術術語是什麼意思？	搜索、嵌入和 MCP 概念的快速參考。

🔧 技術細節

核心命令

命令	描述
`amanmcp init`	初始化項目
`amanmcp search "query"`	搜索代碼庫
`amanmcp doctor`	排查問題
`amanmcp status`	檢查索引健康狀態

完整命令參考 →

Claude 可用工具

當通過 MCP 連接時，Claude 可以使用以下工具：

工具	用途
`search`	對代碼庫進行混合搜索
`search_code`	查找函數、類和類型
`search_docs`	搜索文檔

技術架構

flowchart LR
    subgraph Local["Your Machine (100% Local)"]
        Code[(Codebase)]
        AmanMCP["AmanMCP<br/>BM25 + Vector"]
    end

    Claude["Claude AI"]

    Code -->|index| AmanMCP
    Claude <-->|query| AmanMCP
    AmanMCP -->|context| Claude

    style Local fill:#d5f4e6,color:#000
    style AmanMCP fill:#27ae60,color:#fff
    style Claude fill:#3498db,color:#fff