zilliztech/claude-context
GitHub: zilliztech/claude-context
为 Claude Code 提供的 MCP 插件，将整个代码库以语义向量方式注入上下文，实现高效、低成本的代码检索。
Stars: 6174 | Forks: 541
### 你的整个代码库作为Claude的上下文
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](docs/)
[](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
[](https://www.npmjs.com/package/@zilliz/claude-context-core)
[](https://www.npmjs.com/package/@zilliz/claude-context-mcp)
[](https://twitter.com/zilliz_universe)
[](https://deepwiki.com/zilliztech/claude-context)
在 Zilliz Cloud 获取免费向量数据库 👈
Claude Context 需要一个向量数据库。你可以在 [Zilliz Cloud](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) 注册以获取 API 密钥。
将你的个人密钥复制并替换配置示例中的 `your-zilliz-cloud-api-key`。
获取 OpenAI API 密钥用于嵌入模型
你需要 OpenAI API 密钥来使用嵌入模型。你可以在 [OpenAI](https://platform.openai.com/api-keys) 注册获取。
你的 API 密钥将如下所示：始终以 `sk-` 开头。
复制你的密钥并在下面的配置示例中使用它作为 `your-openai-api-key`。
### 为 Claude Code 配置 MCP
**系统要求：**
- Node.js >= 20.0.0 且 < 24.0.0
#### 配置
使用命令行界面添加 Claude Context MCP 服务器：
```
claude mcp add claude-context \
-e OPENAI_API_KEY=sk-your-openai-api-key \
-e MILVUS_TOKEN=your-zilliz-cloud-api-key \
-- npx @zilliz/claude-context-mcp@latest
```
有关 MCP 服务器管理的更多详细信息，请参阅 [Claude Code MCP 文档](https://docs.anthropic.com/en/docs/claude-code/mcp)。
### 其他 MCP 客户端配置
OpenAI Codex CLI
Codex CLI 使用 TOML 配置文件：
1. 创建或编辑 `~/.codex/config.toml` 文件。
2. 添加以下配置：
```
# mcp_servers
[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" }
# 可选：覆盖默认的 10 秒启动超时
startup_timeout_ms = 20000
```
3. 保存文件并重启 Codex CLI 以应用更改。
Gemini CLI
Gemini CLI 需要通过 JSON 文件手动配置：
1. 创建或编辑 `~/.gemini/settings.json` 文件。
2. 添加以下配置：
```
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"MILVUS_TOKEN": "your-zilliz-cloud-api-key"
}
}
}
}
```
3. 保存文件并重启 Gemini CLI 以应用更改。
Qwen Code
创建或编辑 `~/.qwen/settings.json` 文件并添加以下配置：
```
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@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"
}
}
}
}
```
Cursor
前往：`设置` -> `Cursor 设置` -> `MCP` -> `添加新的全局 MCP 服务器`
将以下配置粘贴到你的 Cursor `~/.cursor/mcp.json` 文件中是推荐的方法。你也可以通过在工作区文件夹中创建 `.cursor/mcp.json` 来在特定项目中安装。请参阅 [Cursor MCP 文档](https://cursor.com/docs/context/mcp) 获取更多信息。
```
{
"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"
}
}
}
}
```
Void
前往：`设置` -> `MCP` -> `添加 MCP 服务器`
将以下配置添加到你的 Void MCP 设置中：
```
{
"mcpServers": {
"code-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"
}
}
}
}
```
Claude Desktop
添加到你的 Claude Desktop 配置中：
```
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@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
Windsurf 支持通过 JSON 文件进行 MCP 配置。将以下配置添加到你的 Windsurf MCP 设置中：
```
{
"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"
}
}
}
}
```
VS Code
Claude Context MCP 服务器可以通过与 MCP 兼容的扩展在 VS Code 中使用。将以下配置添加到你的 VS Code MCP 设置中：
```
{
"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"
}
}
}
}
```
Cherry Studio
Cherry Studio 允许通过其设置界面进行可视化的 MCP 服务器配置。虽然它不直接支持手动 JSON 配置，但你可以通过 GUI 添加新服务器：
1. 导航到 **设置 → MCP 服务器 → 添加服务器**。
2. 填写服务器详细信息：
- **名称**：`claude-context`
- **类型**：`STDIO`
- **命令**：`npx`
- **参数**：`["@zilliz/claude-context-mcp@latest"]`
- **环境变量**：
- `OPENAI_API_KEY`: `your-openai-api-key`
- `MILVUS_ADDRESS`: `your-zilliz-cloud-public-endpoint`
- `MILVUS_TOKEN`: `your-zilliz-cloud-api-key`
3. 保存配置以激活服务器。
Cline
Cline 使用 JSON 配置文件来管理 MCP 服务器。要集成提供的 MCP 服务器配置：
1. 打开 Cline 并点击顶部导航栏中的 **MCP 服务器** 图标。
2. 选择 **已安装** 选项卡，然后点击 **高级 MCP 设置**。
3. 在 `cline_mcp_settings.json` 文件中添加以下配置：
```
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@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. 保存文件。
Augment
要在 Augment Code 中配置 Claude Context MCP，可以使用图形界面或手动配置。
#### **A. 使用 Augment Code UI**
1. 点击汉堡菜单。
2. 选择 **设置**。
3. 导航到 **工具** 部分。
4. 点击 **+ 添加 MCP**。
5. 输入以下命令：
npx @zilliz/claude-context-mcp@latest
6. 将 MCP 命名为：**Claude Context**。
7. 点击 **添加** 按钮。
#### **B. 手动配置**
1. 按下 Cmd/Ctrl Shift P 或前往汉堡菜单中的编辑设置。
2. 选择 **编辑设置**。
3. 在 **高级** 部分，点击 **编辑 settings.json**。
4. 将服务器配置添加到 `mcpServers` 数组中的 `augment.advanced` 对象。
```
"augment.advanced": {
"mcpServers": [
{
"name": "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"
}
}
]
}
```
Roo Code
Roo Code 使用 JSON 配置文件来管理 MCP 服务器：
1. 打开 Roo Code 并导航到 **设置 → MCP 服务器 → 编辑全局配置**。
2. 在 `mcp_settings.json` 文件中添加以下配置：
```
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["@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"
}
}
}
}
```
3. 保存文件以激活服务器。
Zencoder
Zencoder 在其 JetBrains 和 VS Code 插件版本中支持 MCP 工具和服务器。
1. 进入 Zencoder 菜单（...）。
2. 从下拉菜单中选择 `Tools`。
3. 点击 `Add Custom MCP`。
4. 添加名称（即 `Claude Context`）和以下服务器配置，并确保点击 `Install` 按钮。
```
{
"command": "npx",
"args": ["@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"
}
}
```
5. 通过点击 `Install` 按钮保存服务器。
LangChain/LangGraph
有关 LangChain/LangGraph 集成示例，请参阅 [此示例](https://github.com/zilliztech/claude-context/blob/643796a0d30e706a2a0dff3d55621c9b5d831807/evaluation/retrieval/custom.py#L88)。
其他 MCP 客户端
该服务器使用 stdio 传输并遵循标准 MCP 协议。它可以与任何兼容 MCP 的客户端集成，方法是运行：
```
npx @zilliz/claude-context-mcp@latest
```
### 在你的代码库中使用
1. **打开 Claude Code**
cd your-project-directory
claude
2. **索引你的代码库**：
索引此代码库
3. **检查索引状态**：
检查索引状态
4. **开始搜索**：
查找处理用户认证的函数
🎉 **完成了！** 现在你可以在 Claude Code 中进行语义代码搜索。
### 环境变量配置
有关更详细的 MCP 环境变量配置，请参阅我们的 [环境变量指南](docs/getting-started/environment-variables.md)。
### 使用不同的嵌入模型
要配置自定义嵌入模型（例如 OpenAI 的 `text-embedding-3-large` 或 VoyageAI 的 `voyage-code-3`），请参阅 [MCP 配置示例](packages/mcp/README.md#embedding-provider-configuration) 获取每个提供商的详细设置说明。
### 文件包含与排除规则
有关文件包含和排除规则的详细说明以及如何自定义它们，请参阅我们的 [文件包含与排除规则](docs/dive-deep/file-inclusion-rules.md)。
### 可用工具
#### 1. `index_codebase`
为混合搜索（BM25 + 密集向量）索引代码库目录。
#### 2. `search_code`
使用自然语言查询对已索引的代码库进行混合搜索（BM25 + 密集向量）。
#### 3. `clear_index`
清除特定代码库的搜索索引。
#### 4. `get_indexing_status`
获取代码库的当前索引状态。显示正在进行索引的代码库的进度百分比以及已索引代码库的完成状态。
## 📊 评估
我们的控制评估表明，Claude Context MCP 在同等检索质量条件下实现了约 40% 的令牌减少。这在生产环境中带来了显著的成本和时间节省。这也意味着，在有限的令牌上下文长度约束下，使用 Claude Context 可以获得更好的检索和回答结果。
有关详细的评估方法和结果，请参阅 [评估目录](evaluation/)。
## 🏗️ 架构
### 🔧 实现细节
- 🔍 **混合代码搜索**：询问类似 *"查找处理用户认证的函数"* 的问题，并使用高级混合搜索（BM25 + 密集向量）即时获取相关且内容丰富的代码。
- 🧠 **上下文感知**：发现大型代码库，理解代码库各部分之间的关系，即使跨数百万行代码。
- ⚡ **增量索引**：使用 Merkle 树高效地仅重新索引已更改的文件。
- 🧩 **智能代码分块**：分析代码的抽象语法树（AST）进行分块。
- 🗄️ **可扩展性**：与 Zilliz Cloud 集成以实现可扩展的向量搜索，无论代码库多大。
- 🛠️ **可定制性**：配置文件扩展名、忽略模式和嵌入模型。
### 核心组件
Claude Context 是一个包含三个主要包的 monorepo：
- **`@zilliz/claude-context-core`**：核心索引引擎，包含嵌入和向量数据库集成
- **VSCode 扩展**：Visual Studio Code 的语义代码搜索扩展
- **`@zilliz/claude-context-mcp`**：用于 AI 代理集成的模型上下文协议（MCP）服务器
### 支持的技术
- **嵌入提供者**：[OpenAI](https://openai.com)、[VoyageAI](https://voyageai.com)、[Ollama](https://ollama.com)、[Gemini](https://gemini.google.com)
- **向量数据库**：[Milvus](https://milvus.io) 或 [Zilliz Cloud](https://zilliz.com/cloud)（全托管向量数据库即服务）
- **代码拆分器**：AST 拆分器（带自动回退）、LangChain 字符拆分器
- **语言**：TypeScript、JavaScript、Python、Java、C++、C#、Go、Rust、PHP、Ruby、Swift、Kotlin、Scala、Markdown
- **开发工具**：VSCode、模型上下文协议
## 📦 其他使用 Claude Context 的方式
虽然 MCP 是使用 Claude Context 与 AI 助手集成的推荐方式，但你也可以直接使用它或通过 VSCode 扩展使用。
### 使用核心包构建应用程序
`@zilliz/claude-context-core` 包提供代码索引和语义搜索的基本功能。
```
import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';
// Initialize embedding provider
const embedding = new OpenAIEmbedding({
apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
model: 'text-embedding-3-small'
});
// Initialize vector database
const vectorDatabase = new MilvusVectorDatabase({
address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});
// Create context instance
const context = new Context({
embedding,
vectorDatabase
});
// Index your codebase with progress tracking
const stats = await context.indexCodebase('./your-project', (progress) => {
console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);
// Perform semantic search
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)}...`);
});
```
### VSCode 扩展
直接集成 Claude Context 到你的 IDE。提供语义代码搜索和导航的直观界面。
1. **直接链接**：[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
2. **手动搜索**：
- 在 VSCode 中打开扩展视图（Ctrl+Shift+X 或 Cmd+Shift+X）
- 搜索 "Semantic Code Search"
- 点击安装
## 
## 🛠️ 开发
### 设置开发环境
#### 前置条件
- Node.js 20.x 或 22.x
- pnpm（推荐的包管理器）
#### 跨平台设置
```
# 克隆仓库
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
# 安装依赖
pnpm install
# 构建所有包
pnpm build
# 启动开发模式
pnpm dev
```
#### Windows 特定设置
在 Windows 上，请确保具备以下条件：
- **Git for Windows** 并正确配置行尾
- **Node.js** 通过官方安装程序或包管理器安装
- **pnpm** 全局安装：`npm install -g pnpm`
```
# Windows PowerShell/Command Prompt
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
# 配置 Git 行结束符（推荐）
git config core.autocrlf false
# 安装依赖
pnpm install
# 构建所有包（使用跨平台脚本）
pnpm build
# 启动开发模式
pnpm dev
```
### 构建
```
# 构建所有包（跨平台）
pnpm build
# 构建特定包
pnpm build:core
pnpm build:vscode
pnpm build:mcp
# 性能基准测试
pnpm benchmark
```
#### Windows 构建说明
- 所有构建脚本均使用 rimraf 跨平台兼容
- 构建缓存已启用，可加快后续构建速度
- 使用 PowerShell 或命令提示符 - 两者均适用
### 运行示例
```
# 开发时启用文件监视
cd examples/basic-usage
pnpm dev
```
## 📖 示例
在 `/examples` 目录中查看完整的用法示例：
- **基础用法**：简单的索引和搜索示例
## ❓ 常见问题
**常见问题：**
- **[Claude Context 决定嵌入哪些文件？](docs/troubleshooting/faq.md#q-what-files-does-claude-context-decide-to-embed)**
- **[能否使用完全本地化的部署方案？](docs/troubleshooting/faq.md#q-can-i-use-a-fully-local-deployment-setup)**
- **[它是否支持多个项目/代码库？](docs/troubleshooting/faq.md#q-does-it-support-multiple-projects--codebases)**
- **[Claude Context 与其他编码工具相比如何？](docs/troubleshooting/faq.md#q-how-does-claude-context-compare-to-other-coding-tools-like-serena-context7-or-deepwiki)**
❓ 有关详细解答和更多故障排除提示，请参阅我们的 [常见问题指南](docs/troubleshooting/faq.md)。
🔧 **遇到问题？** 请访问我们的 [故障排除指南](docs/troubleshooting/troubleshooting-guide.md) 获取分步解决方案。
📚 **需要更多帮助？** 请查看我们的 [完整文档](docs/) 获取详细指南和故障排除提示。
## 🤝 贡献
我们欢迎贡献！请参阅我们的 [贡献指南](CONTRIBUTING.md) 了解如何开始。
**特定于包的贡献指南：**
- [核心包贡献指南](packages/core/CONTRIBUTING.md)
- [MCP 服务器贡献指南](packages/mcp/CONTRIBUTING.md)
- [VSCode 扩展贡献指南](packages/vscode-extension/CONTRIBUTING.md)
## 🗺️ 路线图
- [x] 基于 AST 的代码分析以提升理解能力
- [x] 支持更多嵌入提供者
- [ ] 代理交互式搜索模式
- [x] 增强的代码分块策略
- [ ] 搜索结果排名优化
- [ ] 强大的 Chrome 扩展
## 📄 许可证
本项目根据 MIT 许可证授权 - 请参阅 [LICENSE](LICENSE) 文件了解详情。
## 🔗 链接
- [GitHub 仓库](https://github.com/zilliztech/claude-context)
- [VS Code 市场](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
- [Milvus 文档](https://milvus.io/docs)
- [Zilliz Cloud](https://zilliz.com/cloud)标签：AI编码代理, AI编程助手, Claude Code, GNU通用公共许可证, MCP插件, MITM代理, Node.js, npm包, SOC Prime, VS Code扩展, 代码库上下文, 代码搜索, 多轮对话, 大型代码库, 大模型上下文, 开发工具, 成本优化, 数据可视化, 自动化攻击, 语义代码搜索, 语义搜索, 逆向工具