AmanMCP

探索

Amanmcp

AmanMCP是一个隐私优先、零配置的本地代码库检索增强生成(RAG)工具，通过MCP协议与Claude AI集成，提供混合搜索功能，完全在本地运行，无需网络连接。

开发者工具搜索工具 #本地RAG #代码搜索 #隐私优先 #混合检索 .Go

评分 : 2.5分

下载量 : 3.7K

更新时间 : 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