Claude Context:让 AI 编程助手真正读懂你的代码库

项目卡片

• 项目：Claude Context^[1]
• 状态：v0.1.0 / 11.8k Star / 870 Fork / MIT 许可证
• 一句话判断：通过 MCP 协议为 AI 编程助手添加语义代码搜索，比传统 grep 方案节省 40% token 消耗。

AI 编程助手处理大型代码库，通常两种思路：目录加载和 grep 搜索。目录加载把整个目录塞进上下文，token 消耗巨大；grep 依赖关键词匹配，经常漏掉语义相关但措辞不同的代码。

Claude Context 用向量数据库存储代码嵌入，通过语义搜索找到真正相关的代码片段。实测数据：token 消耗减少 39.4%，工具调用次数减少 36.3%。

第一步：获取 API Key

你需要两个 API Key：

1. OpenAI API Key：用于生成代码嵌入，从 OpenAI Platform^[2] 获取
2. Zilliz Cloud API Key：用于存储向量数据，从 Zilliz Cloud^[3] 免费注册获取

第二步：配置 Claude Code

在终端执行一条命令：

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -- npx @zilliz/claude-context-mcp@latest

第三步：索引代码库

打开 Claude Code，进入你的项目目录：

cd your-project-directory
claude

然后告诉 Claude 索引代码库：

Index this codebase

索引过程在后台异步进行，你可以随时检查进度：

Check the indexing status

第四步：开始搜索

索引完成后，用自然语言搜索代码：

Find functions that handle user authentication

Claude Context 会返回语义相关的代码片段，包含文件路径、行号和相似度评分。

Claude Context 通过 MCP 协议集成，支持几乎所有主流 AI 编程助手：

每个 IDE 的配置格式略有不同，但核心都是指定 npx @zilliz/claude-context-mcp@latest 作为命令，加上环境变量。详细配置可以参考官方文档^[4]。

使用 Claude Context 的成本主要来自两部分：

1. 嵌入模型 API 调用：首次索引时产生，后续增量索引成本很低
2. 向量数据库存储：Zilliz Cloud 免费额度通常够个人项目使用

对于大型代码库（10 万行以上），首次索引可能需要几分钟和几美元的 API 调用费用。但后续每次查询的成本极低，因为只搜索不索引。相比把整个目录塞进上下文的方案，长期来看成本优势明显。

Claude Context 支持 4 种嵌入提供商，各有特点：

OpenAI（默认）

• 模型：text-embedding-3-small（默认）、text-embedding-3-large
• 优点：质量稳定，生态成熟
• 缺点：需要 API 调用，有成本

VoyageAI

• 模型：voyage-code-3（专为代码优化）
• 优点：代码语义理解更好
• 缺点：需要单独的 API Key

Gemini

• 模型：gemini-embedding-001、gemini-embedding-2
• 优点：多语言支持好
• 缺点：需要 Google API Key

Ollama（本地部署）

• 模型：nomic-embed-text 等
• 优点：完全本地，数据不出境
• 缺点：需要本地 GPU，性能依赖硬件

切换嵌入模型只需修改环境变量：

# 使用 VoyageAI
EMBEDDING_PROVIDER=VoyageAI
VOYAGEAI_API_KEY=pa-your-voyageai-api-key
EMBEDDING_MODEL=voyage-code-3

# 使用本地 Ollama
EMBEDDING_PROVIDER=Ollama
OLLAMA_HOST=http://127.0.0.1:11434
EMBEDDING_MODEL=nomic-embed-text

Claude Context 的索引过程值得深入了解，因为它直接影响使用体验。

AST 智能分块

默认使用 AST（抽象语法树）分析代码，按语法结构切分，而不是简单的字符分割。这保证了代码片段的语义完整性——一个函数不会被从中间切断。

如果 AST 分析失败（比如遇到不支持的语言），会自动回退到 LangChain 的字符分割器。

混合搜索

搜索采用 BM25 + 密集向量的混合模式：

• BM25：基于关键词的精确匹配
• 密集向量：基于语义的相似度匹配

两者结合，既保证了精确查询的准确性，又覆盖了语义相关的代码。

增量索引

使用 Merkle 树追踪文件变更，只重新索引修改过的文件。大型代码库的首次索引可能需要几分钟，但后续更新通常在几秒内完成。

异步工作流

索引过程完全异步，不会阻塞你的工作：

1. 调用 index_codebase 后立即返回
2. 后台处理文件、生成嵌入、写入向量数据库
3. 索引过程中可以搜索（返回部分结果）
4. 通过 get_indexing_status 查看进度

全局环境变量

为了避免在每个 IDE 中重复配置，可以创建全局配置文件：

mkdir -p ~/.context
cat > ~/.context/.env << 'EOF'
EMBEDDING_PROVIDER=OpenAI
OPENAI_API_KEY=sk-your-openai-api-key
EMBEDDING_MODEL=text-embedding-3-small
MILVUS_TOKEN=your-zilliz-cloud-api-key
EOF

这样在 Cursor、Windsurf 等 IDE 中，MCP 配置可以简化为：

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"]
    }
  }
}

自定义文件过滤

默认索引支持的文件类型包括 TypeScript、JavaScript、Python、Java、C++、Go、Rust 等主流语言。可以通过环境变量扩展：

# 添加 Vue、Svelte、Astro 文件
CUSTOM_EXTENSIONS=.vue,.svelte,.astro

# 排除临时文件和私有目录
CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**

也可以在索引时动态指定：

Index this codebase, and include .vue, .svelte files

本地完全部署

如果不想依赖云服务，可以完全本地部署：

1. 向量数据库：用 Docker 运行 Milvus

   docker run -p 19530:19530 milvusdb/milvus:latest
   

2. 嵌入模型：用 Ollama 运行本地模型

   ollama pull nomic-embed-text
   ollama serve
   

3. 配置环境变量

   EMBEDDING_PROVIDER=Ollama
   OLLAMA_HOST=http://127.0.0.1:11434
   MILVUS_ADDRESS=127.0.0.1:19530
   

Q：索引状态显示 0 files, 0 chunks？ A：这通常是本地快照元数据过期。运行 clear_index 后重新索引即可。

Q：索引进度条跳得很快？ A：进度是按阶段计算的，不是文件比例。10% 代表从准备阶段进入文件处理阶段。

Q：支持多个项目吗？ A：支持。Claude Context 按绝对路径区分项目，切换目录时自动识别。

Q：和 DeepWiki、Context7 有什么区别？ A：Claude Context 专注代码索引和语义搜索；DeepWiki 生成文档；Context7 提供最新文档。三者定位不同。

1. 首次使用：先用小项目测试，熟悉索引和搜索流程
2. 大型代码库：考虑使用 text-embedding-3-large 提升精度，但会增加成本
3. 隐私敏感：使用 Ollama 本地部署，数据不出境
4. 团队协作：共享 Zilliz Cloud 集合，避免重复索引
5. 持续更新：利用 Merkle 树增量索引，保持索引与代码同步

Claude Context 解决了 AI 编程助手在大型代码库上的上下文瓶颈。通过语义搜索，AI 能真正理解代码意图，而不是机械地匹配关键词。对于经常使用 AI 编程助手的开发者，这是一个值得尝试的工具。

这里会继续拆真实可用的开发者工具：少讲概念，多看入口、成本和坑点。你只需要判断一件事——它值不值得放进自己的工作流。

引用链接