在 Claude Code 生态中，如何让 AI 真正「理解」整个代码库而非仅关注当前打开的文件，一直是工程实践的核心挑战。Zilliz 推出的 claude-context 作为专门面向 Claude Code 的 MCP（Model Context Protocol）代码搜索服务器，提供了一套完整的全代码库上下文注入方案。其核心思路是将语义检索与向量数据库能力深度整合，使 AI 能够在运行时按需获取整个代码库中最相关的上下文片段，而非一次性加载整个仓库到上下文窗口中。这种架构设计直接回应了大模型在代码理解场景下的 token 成本与召回精度双重痛点。
整体架构与核心组件
claude-context 的架构采用典型的双层设计：核心引擎层与 MCP 包装层分离。核心引擎由 @zilliz/claude-context-core npm 包提供，负责代码索引、语义搜索、忽略模式处理以及基于 Merkle 树的增量同步逻辑；MCP 包装层则负责将这些能力以标准化的 MCP 工具形式暴露给 Claude Code、Cursor、VS Code 等客户端。这种分层设计使得核心索引逻辑可以独立演进，同时也便于在不同 MCP 客户端之间复用。
从工具接口来看，该 MCP 服务器暴露了三个核心工具：index_codebase 用于建立或更新代码库的向量索引，支持传入路径、强制重建标志、自定义分块器、文件扩展名过滤以及忽略模式；search_code 接收自然语言查询并返回最相关的代码片段，支持结果数量限制；clear_index 则用于清理指定路径的索引数据。整个工具契约设计得极为简洁，使得客户端调用成本极低，同时将复杂的索引与检索逻辑完全封装在服务端。
语义检索与向量存储层
该工具的语义检索能力建立在向量数据库之上，默认使用 Zilliz Cloud（Milvus 的托管版本）作为存储后端。代码片段首先经过分块处理生成文本块，然后通过嵌入模型转换为向量表示，最后存入向量数据库进行相似度检索。值得注意的是，claude-context 支持多种嵌入 provider，包括 OpenAI、VoyageAI、Gemini 以及本地运行的 Ollama，这种灵活性使得用户可以根据隐私需求与成本考量选择合适的嵌入方案。
在检索策略上，该工具实现了混合搜索模式，即同时结合稀疏的词法检索（如 BM25）与密集的向量相似度检索。词法检索擅长处理精确的符号匹配与关键词查找，而向量检索则在语义相关性上表现更佳。两者的组合能够在召回率与精确率之间取得更好的平衡，尤其在代码库中存在大量同名变量或函数重载的场景下，混合策略的优势尤为明显。
AST 感知分块与增量索引
代码分块的质量直接决定了检索效果的上限。claude-context 采用了 AST（抽象语法树）感知的分块策略，这意味着分块边界不再依赖于简单的字符数或行数，而是尽可能保持完整的语法结构 —— 例如以函数、类或模块作为自然边界。这种策略确保检索返回的代码片段具有完整的语义上下文，避免了因截断导致的语法碎片化问题。
增量索引机制是该工具的另一个技术亮点。基于 Merkle 树的变更检测策略，使得工具能够识别出自上次索引以来哪些文件发生了实质性的修改，仅对这些文件进行重新分块与向量化，而无需对整个代码库重新处理。这一设计对于大型活跃代码库的持续运行至关重要，它将索引更新的时间成本与计算资源消耗控制在可接受范围内，同时保证检索结果的时效性。
Token 优化与上下文注入策略
从工程实践角度，claude-context 的核心价值在于提供了一种可控的上下文注入方式。传统做法是将整个代码库或大量源文件直接塞入上下文窗口，不仅消耗大量 token，更可能导致模型注意力分散，检索质量下降。claude-context 通过语义检索按需选取最相关的代码片段，本质上实现了一种「按需加载」的上下文管理策略。
在实际使用时，典型的配置流程包括：通过 npx 启动 MCP 服务器，配置 OPENAI_API_KEY（或其它嵌入 provider 的密钥）以及 MILVUS_TOKEN 作为环境变量，然后在 Claude Code 的配置文件中添加该 MCP 服务器。配置完成后，用户即可在对话中调用索引与搜索工具，让 AI 能够「看到」代码库中任意位置的上下文。
这种架构的关键工程参数包括：索引时每块代码的目标长度（建议基于函数或类的自然边界而非固定字符数）、搜索返回的结果数量上限（通常 5 到 10 条可覆盖大多数场景）、以及嵌入模型的选择（本地 Ollama 适合离线场景，OpenAI 则在精度上更有优势）。监控层面应关注索引完成度、检索延迟以及向量数据库的存储增长情况，以便在代码库规模扩大时及时调整资源配置。
claude-context 代表了一种将专业向量检索能力注入 AI 编码助手的工程范式。其价值不仅在于提供了开箱即用的代码搜索能力，更在于展示了一种可复制的上下文管理思路 —— 通过语义索引与按需检索，将有限的上下文窗口转化为对整个代码库的高效探索能力。
资料来源：该工具的架构细节与实现特性综合自 GitHub 官方仓库与 npm 包文档。