金大哥 - amanmcp MCP 详情

article

README

🚀 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

📄 许可证

本项目采用 Apache 2.0 许可证，请参阅 LICENSE 了解详细信息。

免责声明

AmanMCP 是处于积极开发中的实验性软件。使用此软件即表示您承认这是 alpha/beta 质量的软件，您将对任何问题承担全部责任，并理解开发者不对数据丢失、系统问题或其他问题负责。

致谢

由 AmanERP 团队精心打造 · “即插即用”

amanmcp