Claude Context 入门: 让 AI 真正理解你的整个代码库

Claude Context 是一个开源的 MCP（Model Context Protocol）插件，由向量数据库厂商 Zilliz 开发。它的核心定位很清晰：为 AI 编码助手注入整个代码库的语义理解能力。

传统工作流里，当你想让 AI 帮你理解一个陌生的代码库时，你得手动复制文件路径、描述项目结构、解释模块关系——这些本该是 AI 自己完成的事。Claude Context 通过语义搜索技术，让 AI 能够直接查询代码库中的函数、类、数据结构，不再依赖你手动的上下文注入。

这个项目在 GitHub 上托管于 zilliztech/claude-context，采用 MIT 许可证，代码完全开源。

---

难度/时长/收获

入门级 | 约 20 分钟 | 你将掌握如何用 2 条命令为任何编码工具赋予百万行代码语义理解能力，同时降低约 40% 的 token 消耗。

---

目标读者

• 日常使用 Claude Code、Cursor、Windsurf、Cline 等 AI 编程工具的开发者
• 对 RAG（检索增强生成）和向量搜索有基础认知，希望深入实践
• 希望降低 token 成本、提升 AI 回复准确性的团队

---

核心依赖与环境

系统要求

• Node.js >= 20.0.0 且 < 24.0.0
• 操作系统：macOS、Windows、Linux 均可

服务依赖

• Zilliz Cloud（免费额度足够个人使用）：提供向量数据库后端
• OpenAI API Key：用于 embedding 模型生成向量（也可以替换为其他支持的 embedding 提供商）

---

完整项目结构树

Claude Context 是一个纯 npm 包，不需要你克隆或构建任何本地代码。安装后它会管理自己的存储结构：

~/.claude/
└── plugins/
    └── claude-context/          # MCP 插件目录
        └── [索引数据文件]        # 增量 Merkle 树快照

如果你使用 Core 包直接集成到应用中，结构如下：

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # 存放 API Key
└── your-codebase/              # 待索引的代码

---

手把手步骤

第 1 步：注册 Zilliz Cloud，获取向量数据库凭证

Claude Context 的向量存储依赖 Zilliz Cloud（或自托管 Milvus）。这一步需要你创建一个免费账号。

打开 zilliz.com/cloud，使用邮箱或 GitHub 账号注册。登录后在控制台创建一个新的 Serverless Cluster：

1. 点击 Create Cluster
2. 选择 Serverless 类型（免费额度完全够用）
3. 选择最近区域（AWS us-west-2 或新加坡都常用）
4. 命名你的集群，比如 claude-context

集群创建完成后，进入集群详情页，找到 Connection Info，复制以下两个值备用：

• Public Endpoint：形如 https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key：形如 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第 2 步：获取 OpenAI API Key

Claude Context 使用 embedding 模型将代码片段转为向量。你需要准备一个 OpenAI API Key 来驱动默认的 text-embedding-3-small 模型。

打开 platform.openai.com/api-keys，点击 Create new secret key，复制生成的值（格式为 sk-xxxxxxxx...）。

第 3 步：将 Claude Context MCP 安装到 Claude Code

现在我们在 Claude Code 中注册这个 MCP 服务器。打开终端，进入任意项目目录，执行以下命令：

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

替换以下占位符为你的实际值：

• sk-your-openai-api-key → 你的 OpenAI API Key
• your-zilliz-cloud-api-key → 你的 Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → 你的 Zilliz Public Endpoint

命令执行成功后会看到 MCP 服务器已注册。验证安装：

claude mcp list

应该看到 claude-context 在列表中且状态为 running。

如果你使用的是其他 AI 编码工具，配置方式略有不同。几个常见场景：

Cursor（推荐配置文件方式）：

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf（同样使用 JSON 配置）：

// ~/.windsurf/mcp_settings.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

第 4 步：索引你的第一个代码库

安装完成后，进入你的项目目录，启动 Claude Code：

cd your-project-directory
claude

在对话中输入以下命令，触发索引：

Index this codebase

Claude Context 会立即开始分析代码库。整个过程分两个阶段：

1. 文件扫描：遍历目录，根据扩展名过滤出需要处理的代码文件
2. 向量嵌入：对每个代码文件进行 AST（抽象语法树）分块，调用 embedding 模型生成向量，存入向量数据库

索引过程中你可以随时询问进度：

Check the indexing status

返回结果会告诉你当前索引进度百分比，以及已完成文件数量。

第 5 步：验证搜索效果并理解返回结果

索引完成后，就可以开始语义搜索了。以下是几个典型查询场景：

查找特定功能的实现：

Find functions that handle user authentication

返回结果会包含相关函数名、文件路径、代码片段和相关性评分（0-1 之间，越高越相关）。

理解模块间关系：

How does the payment module connect to the order module?

快速定位配置相关代码：

Where is the database connection pool configured?

返回结果的格式如下：

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

如果你想清理索引重新开始，执行：

Clear the index for this codebase

---

常见问题排查

Q1: Node.js 版本不兼容，命令执行报错

症状：claude mcp add 报错或 MCP 服务器启动后立即退出。

原因：Claude Context 目前不支持 Node.js 24.x。

解决：

# 检查当前 Node 版本
node -v

# 如果是 24.x，降级到 20.x（LTS）
nvm install 20
nvm use 20

Q2: 环境变量配置错误，索引失败

症状：Index this codebase 无响应或返回错误 Milvus connection failed。

检查步骤：

1. 确认 MILVUS_ADDRESS 不带 https:// 前缀，直接使用主机名部分
2. 确认 MILVUS_TOKEN 与 Zilliz Cloud 控制台显示的 API Key 完全一致
3. 确认 OPENAI_API_KEY 以 sk- 开头

正确格式示例：

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Q3: 索引进度卡住，没有进展

症状：索引命令发出后一直没有响应。

解决：

1. 先执行 Check the indexing status 确认当前状态
2. 检查网络连接（需要访问 OpenAI API 和 Zilliz Cloud）
3. 如果集群创建不久，端点可能还在初始化，等待 1-2 分钟后再试

Q4: 搜索结果为空或完全不相关

症状：查询应该匹配的内容却返回空结果。

原因：索引文件可能不完整，或者查询表述与代码中的命名差异较大。

解决：

1. 先检查索引状态：Check the indexing status
2. 尝试更具体的查询（用代码中实际存在的变量名或函数名）
3. 如果确认代码存在但搜索不到，清除索引后重新索引：

Clear the index for this codebase
Index this codebase

Q5: 增量索引未生效，修改后的代码没有被检索到

症状：修改了某个文件，但语义搜索结果仍然指向旧版本。

原因：Claude Context 使用 Merkle 树快照来检测文件变更。如果你手动删除了快照文件，增量检测可能失效。

解决：清除索引重新开始即可：

Clear the index for this codebase
Index this codebase

Q6: MCP 连接失败，工具不可用

症状：工具列表中看不到 search_code、index_codebase 等工具。

解决：

1. 重启 Claude Code（有时 MCP 服务器需要重新加载）
2. 确认 MCP 配置没有语法错误（JSON 格式注意逗号、引号）
3. 检查 claude mcp list 中该插件状态是否为 running

claude mcp list

如果状态为 stopped，手动重启：

claude mcp remove claude-context
# 然后重新执行第 3 步的安装命令

---

扩展阅读 / 进阶方向

使用自定义 Embedding 模型

OpenAI 的 text-embedding-3-small 是默认选择，但 Claude Context 支持多种 embedding 提供商，可以实现完全本地化的部署：

使用 Ollama（本地模型）：

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

使用 VoyageAI：

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

接入 LangChain/LangGraph 实现高级 RAG

如果你想在自己的应用中直接集成 Claude Context 的能力，可以使用 Core 包：

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// 初始化 embedding 和向量数据库
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

const context = new Context({ embedding, vectorDatabase });

// 索引代码库，监听进度
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// 执行语义搜索
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

详细示例可参考 evaluation/retrieval/custom.py。

VSCode 可视化搜索

如果你更习惯在 IDE 中操作，可以安装 Semantic Code Search 插件，在 VS Code 内直接进行语义搜索，无需启动 Claude Code。

多代码库管理策略

Claude Context 支持同时管理多个代码库。只需在不同目录下分别调用 Index this codebase，每个目录会维护独立的索引。你可以指定目录名来区分：

# 工作目录 A
cd ~/projects/frontend && claude
# 在对话中执行 Index this codebase

# 工作目录 B
cd ~/projects/backend && claude
# 在对话中执行 Index this codebase

AST 分块原理与 Merkle 树增量索引

Claude Context 的代码理解能力建立在两个核心技术之上：

• AST-based Chunking：使用抽象语法树分析代码结构，按函数、类、模块边界进行分块，而不是简单按行数切分。这样保证每个 chunk 都是语义完整的代码单元。
• Merkle 树增量索引：每个文件变更后，通过 Merkle 树比对只重新索引变更的文件，而不是全量重建。极大降低了大代码库的维护成本。

如果你对这两个技术的实现细节感兴趣，可以查看 zilliztech/claude-context 仓库中的 packages/core 源码。