AmanMCP
本地RAG用于您的代码库。零配置。隐私第一。
______________________________________________________________________
阿尔法软件 -使用风险自负。 完整免责声明
______________________________________________________________________
快速开始
先决条件： 奥拉玛 已安装(brew install ollama)
# Install
brew tap Aman-CERP/amanmcp && brew install --cask amanmcp
# Initialize (auto-starts Ollama, pulls model, indexes)
cd your-project && amanmcp init
# Restart Claude Code. Done.问克劳德： “搜索我的代码库以进行身份验证”
______________________________________________________________________
它做什么
flowchart LR
subgraph Local["Your Machine (100% Local)"]
Code[(Codebase)]
AmanMCP["AmanMCP
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主要特点： 混合搜索（BM25+语义）|AST感知分块|多语言|\<100ms查询
______________________________________________________________________
基本命令
| 命令 | 描述 |
|---|---|
amanmcp init | 初始化项目 |
amanmcp search "query" | 搜索代码库 |
amanmcp doctor | 解决问题 |
amanmcp status | 检查索引运行状况 |
______________________________________________________________________
克劳德能做什么
当通过MCP连接时，Claude有以下工具：
| 工具 | 目的 |
|---|---|
search | 跨代码库的混合搜索 |
search_code | 查找函数、类、类型 |
search_docs | 搜索文档 |
尝试： “查找处理数据库连接的函数”
______________________________________________________________________
文档
浏览文档
浏览我们按主题组织的全面文档。每个类别都突出显示了关键文档，以帮助您快速找到所需内容。
______________________________________________________________________
条款 -深度挖掘与洞察
| 文档 | 主题 | 问题/疑问 | 关键见解 |
|---|---|---|---|
| 人工智能工程指南 | 学习路线图 | 如何高效学习AI/ML工程？ | 80/20方法-专注于跨工具传递的基本原理 |
| AI原生项目管理 | 人工智能协作 | 当人工智能进行大部分编码时，如何管理项目？ | 具有上下文管理和会话工作流的人工智能执行器模型 |
| AI原生文档课程 | 文档策略 | 如何防止文档泛滥？ | 内部文档的积累速度可能快于其有用性——整合策略很重要 |
| 黑盒架构案例研究 | 模块化设计 | 如何构建可大规模维护的系统？ | Eskil Steenberg的原则-稳定的接口+隐藏的复杂性=数十年的耐用性 |
| Claude代码搜索与AmanMCP基准测试 | 工具比较 | 什么时候使用内置工具与专业搜索？ | 工具是互补的，而不是竞争的——每种工具都有优势 |
| 调试MCP协议 | 协议调试 | 为什么MCP集成神秘失败？ | 标准污染违反协议-MCP使用标准指令进行通信 |
| 更小的型号，更好的搜索 | 模型选择 | 如何在资源约束下选择嵌入模型？ | 通过以质量为中心的调优，0.6B模型在特定任务上的表现优于8B |
| 静态嵌入解释 | 回退模式 | 什么时候应该使用静态嵌入和动态嵌入？ | 零依赖嵌入实现即时启动和优雅降级 |
| 零摩擦课程 | 开发人员用户体验 | 如何实现“它只是工作”的理念？ | 每个手动步骤都是一个有漏洞的抽象——自动检测优于配置 |
______________________________________________________________________
概念 -核心思想与理论
| 文档 | 主题 | 问题/疑问 | 关键见解 |
|---|---|---|---|
| 混合搜索 | 搜索基础 | 为什么要结合关键字和语义搜索？ | BM25找到精确匹配，向量找到意义——融合得到两种优势 |
| MCP协议 | 人工智能集成 | AmanMCP如何与Claude沟通？ | 模型上下文协议通过JSON-RPC实现结构化AI工具通信 |
| 树保姆指南 | 代码解析 | 如何在没有特定语言解析器的情况下解析代码？ | AST感知分块保留了30多种语言的语义边界 |
| 两阶段检索 | 搜索优化 | 为什么搜索两次而不是一次？ | 快速筛选（候选人），然后精确排名平衡速度和准确性 |
| 矢量搜索概念 | 语义搜索 | 语义搜索实际上是如何工作的？ | 嵌入将文本转化为数字，以几何方式捕捉意义 |
______________________________________________________________________
指南 -分步说明
| 文档 | 主题 | 问题/疑问 | 关键见解 |
|---|---|---|---|
| 首次用户指南 | 入门 | 如何从头开始设置AmanMCP？五个步骤：安装Ollama，安装AmanMCP，初始化项目，重启Claude，查询 | |
| 自制咖啡设置指南 | 安装 | 如何在macOS上通过Homebrew进行安装？Homebrew提供自动更新和依赖关系管理 | |
| MLX设置 | 性能 | 如何在Apple Silicon上更快地嵌入？ | MLX在本地嵌入生成方面比Ollama快16倍 |
| 后端切换 | 配置 | 如何在Ollama和MLX嵌入之间切换？ | 简单的配置更改可以比较工作负载的后端 |
| 自动重新索引 | 工作流 | 如何使搜索索引与代码更改保持同步？ | 文件监视可实现实时增量更新，无需手动重新索引 |
| 热管理 | 优化 | 如何在索引过程中减少CPU热量？ | 通过批量大小和并发调优优化CPU温度 |
______________________________________________________________________
研究 -调查与决策
| 文档 | 主题 | 问题/疑问 | 关键见解 |
|---|---|---|---|
| 搜索质量改进系列 | 综合 | 如何全面解决词汇不匹配问题？ | 矢量上下文检索+BM25查询扩展将通过率从60%提高到92% |
| 上下文检索决策 | 搜索增强 | 如何弥合查询和代码之间的词汇不匹配？ | 在嵌入之前，使用模式回退将LLM生成的上下文预存到块中 |
| 上下文检索回归 | 质量分析 | 增强功能如何导致退化？ | 小型嵌入模型+上下文前缀可以在嵌入空间中聚集 |
| 查询扩展不对称 | 查询处理 | 我们是否应该扩展所有搜索后端的查询？ | 仅扩展到BM25-扩展有助于关键字搜索，但会稀释嵌入 |
| RRF融合原理 | 搜索融合 | 如何将BM25和矢量搜索结果结合起来？ | 互易秩融合（k=60）提供简单、有效的组合，无需训练 |
| 词汇不匹配分析 | 搜索质量 | 为什么代码的语义搜索失败？ | 用户说“搜索功能”，代码说 func Search -40%故障的根本原因 |
| 狗食法 | 质量验证 | 如何验证RAG搜索质量？ | 具有5个为什么根本原因分析的分层查询系统捕捉到了语义差距 |
| 嵌入模型 | 模型选择 | 代码搜索的嵌入模型是什么？ | qwen3-0.6b平衡质量和资源；代码专用模型提高了7-8%的检索效率 |
| 嵌入后端演进 | 后端选择 | 默认情况下是哪个嵌入后端？ | Ollama默认（较低的RAM），MLX选择加入（快16倍）-RAM对开发更重要 |
| 嵌入优化 | 性能 | 如何优化嵌入性能？ | MLX与TEI基准测试揭示了批处理大小调整和GPU利用率模式 |
| 嵌入模型演化 | 进化 | 我们的嵌入选择是如何进化的？ | nomic→ 雨果→ Qwen3-每一次转变都教会了我们如何权衡 |
| SQLite vs Bleve | 存储后端 | 哪个BM25后端用于并发访问？ | SQLite FTS5支持并发访问（WAL模式）-纯Go，经过生产验证 |
| 矢量数据库选择 | 矢量存储 | 哪个矢量数据库首先用于本地？ | US搜索→ coder/hnsw-纯Go，可扩展到300K+向量 |
| 专业化vs泛化 | 模型策略 | 我们应该使用专业模型还是通用模型？ | 专业模型在领域中表现出色，但通用模型提供了更好的回退 |
| 树保姆Chunking | 代码解析 | 如何智能地分块代码？ | AST感知边界保留语义单元-需要CGO，但值得 |
| MLX迁移案例研究 | 性能迁移 | 如何计划和执行性能迁移？ | 实施前验证，始终有回退，更喜欢自动检测 |
| RAG的可观测性 | 操作 | 如何观察RAG系统？RAG与代理的区别需要结构化的日志记录和搜索质量指标 |
______________________________________________________________________
贡献 -开发者资源
| 文档 | 主题 | 问题/疑问 | 关键见解 |
|---|---|---|---|
| 代码规范 | 代码风格 | 我在贡献时应该遵循哪些标准？ | 错误包装、资源清理和配置驱动行为是不可协商的 |
| 测试指导 | 质量保证 | 我如何为AmanMCP编写测试？ | 使用黄金文件进行确定性验证的表驱动测试 |
| TDD基本原理 | 开发过程 | 为什么AmanMCP需要测试优先开发？ | 测试作为规范可以防止返工，并实现无所畏惧的重构 |
______________________________________________________________________
参考 -技术规格
| 文档 | 主题 | 问题/疑问 | 关键见解 |
|---|---|---|---|
| 命令 | CLI用法 | AmanMCP中提供了哪些命令？ | 六个核心命令处理初始化、搜索、健康检查和维护 |
| 配置 | 设置 | 如何自定义AmanMCP行为？ | YAML配置控制路径、模型、权重和排除 |
| 建筑 | 系统设计 | AmanMCP的内部结构是怎样的？ | 清洁分离：MCP层、搜索引擎、存储、嵌入管道 |
| 术语表 | 术语 | RRF和HNSW等技术术语是什么意思？ | 搜索、嵌入和MCP概念的快速参考 |
______________________________________________________________________
路线图
| 状态 | 功能 |
|---|---|
| 现在 | 适用于Mac/Linux的生产就绪本地RAG |
| 下一步 | Windows支持，Rust/Java语言支持 |
| 稍后 | IDE插件、远程团队搜索、云同步 |
欢迎捐款 在 优先领域.
______________________________________________________________________
隐私
- 100%本地 -安装后不需要互联网
- 无遥测 -我们不收集任何数据
- 无云 -你的代码永远不会离开你的机器
______________________________________________________________________
安装选项
| 方法 | 命令 | |
|---|---|---|
| 家酿 | brew tap Aman-CERP/amanmcp && brew install --cask amanmcp | |
| 脚本 | `curl -sSL https://raw.githubusercontent.com/Aman-CERP/amanmcp/main/scripts/install.sh \ | sh` （macOS arm64发布工件） |
| 来源 | git clone ... && make install-local | |
| 离线 | amanmcp init --offline （仅BM25，无需型号） |
______________________________________________________________________
技术
| 组件 | 选择 |
|---|---|
| 语言 | 转到1.25.9+ |
| 协议 | MCP 2025-11-25 |
| 关键字搜索 | SQLite FTS5 BM25（纯Go） |
| 矢量搜索 | 编码器/hnsw |
| 代码解析 | 树保姆 |
| 嵌入件 | 奥拉玛 （默认）/MLX（苹果硅） |
______________________________________________________________________
贡献
看 贡献.md 用于开发设置和指南。
优先领域： 语言支持、Windows支持、性能。
______________________________________________________________________
许可证
Apache 2.0许可证-请参阅 许可证
______________________________________________________________________
免责声明
AmanMCP是正在积极开发的实验软件。通过使用此软件，您承认这是alpha/beta质量的软件，对任何问题承担全部责任，并理解开发人员对数据丢失、系统问题或其他问题不承担责任。
______________________________________________________________________
致谢
模型上下文协议 通过Anthropic| 编码器/hnsw | 奥拉玛 | 树保姆 | 通义
______________________________________________________________________
AmanERP团队精心制作 · *“它只是起作用。”*