> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/zilliztech/claude-context) · [上游 README](https://github.com/zilliztech/claude-context/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
> 🆕 **需要为 Claude Code 提供持久记忆？** 不妨看看 [memsearch Claude Code plugin](https://github.com/zilliztech/memsearch#for-claude-code-users) —— 一款以 Markdown 为先的记忆系统，能让你的 AI agent 在多个会话间拥有长期记忆。
### 整个代码库作为 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)
**Claude Context** 是一款 MCP 插件，可为 Claude Code 及其他 AI 编程 agent 添加语义化代码搜索，让它们从你的整个代码库中获得深度上下文。
🧠 **整个代码库作为上下文**：Claude Context 通过语义搜索从数百万行代码中找出所有相关内容。无需多轮探索，结果可直接进入 Claude 的上下文。
💰 **大型代码库的经济实惠之选**：与其在每次请求时把整个目录载入 Claude（费用可能很高），Claude Context 会将代码库高效存入向量数据库，并仅在上下文中使用相关代码，从而控制成本。
---
## 🚀 演示
Model Context Protocol（MCP）可让你将 Claude Context 与喜爱的 AI 编程助手集成，例如 Claude Code。
## 快速入门
### 前置条件
在 Zilliz Cloud 上获取免费向量数据库 👈
Claude Context 需要向量数据库。你可以在 Zilliz Cloud [注册](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) 以获取 API 密钥。
复制你的 Personal Key，并在配置示例中替换 `your-zilliz-cloud-api-key`。
获取用于 embedding 模型的 OpenAI API Key
你需要 OpenAI API 密钥来运行 embedding 模型。可在 [OpenAI](https://platform.openai.com/api-keys). 注册获取。
你的 API 密钥格式如下：始终以 `sk-` 开头。
复制密钥，并在下方配置示例中将其用作 `your-openai-api-key`。
### 为 Claude Code 配置 MCP
**系统要求：**
- Node.js >= 20.0.0
#### 配置
使用命令行界面添加 Claude Context MCP 服务器：
```bash
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 MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) 了解更多 MCP 服务器管理细节。
### 其他 MCP 客户端配置
OpenAI Codex CLI
Codex CLI 使用 TOML 配置文件：
1. 创建或编辑 `~/.codex/config.toml` 文件。
2. 添加以下配置：
```toml
# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[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" }
# Optional: override the default 10s startup timeout
startup_timeout_ms = 20000
```
3. 保存文件并重启 Codex CLI 以使更改生效。
Gemini CLI
Gemini CLI 需要通过 JSON 文件手动配置：
1. 创建或编辑 `~/.gemini/settings.json` 文件。
2. 添加以下配置：
```json
{
"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` 文件，并添加以下配置：
```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
前往：`Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
建议将以下配置粘贴到 Cursor 的 `~/.cursor/mcp.json` 文件中。你也可以在特定项目中安装：在项目文件夹中创建 `.cursor/mcp.json`。更多信息请参阅 [Cursor MCP docs](https://cursor.com/docs/context/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"
}
}
}
}
```
Void
前往：`Settings` -> `MCP` -> `Add MCP Server`
在 Void MCP 设置中添加以下配置：
```json
{
"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 配置：
```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"
}
}
}
}
```
Windsurf
Windsurf 支持通过 JSON 文件进行 MCP 配置。在 Windsurf 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"
}
}
}
}
```
VS Code
可通过支持 MCP 的扩展在 VS Code 中使用 Claude Context MCP 服务器。将以下配置添加到你的 VS Code 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"
}
}
}
}
```
Cherry Studio
Cherry Studio 允许通过其设置界面以可视化方式配置 MCP 服务器。虽然它不直接支持手动 JSON 配置，但你可以通过 GUI 添加新服务器：
1. 前往 **Settings → MCP Servers → Add Server**。
2. 填写服务器详情：
- **Name**：`claude-context`
- **Type**：`STDIO`
- **Command**：`npx`
- **Arguments**：`["-y", "@zilliz/claude-context-mcp@latest"]`
- **Environment Variables**：
- `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 Servers** 图标。
2. 选择 **Installed** 选项卡，然后点击 **Advanced MCP Settings**。
3. 在 `cline_mcp_settings.json` 文件中添加以下配置：
```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. 选择 **Settings**。
3. 前往 **Tools** 部分。
4. 点击 **+ Add MCP** 按钮。
5. 输入以下命令：
```
npx @zilliz/claude-context-mcp@latest
```
6. 为 MCP 命名：**Claude Context**。
7. 点击 **Add** 按钮。
------
#### **B. 手动配置**
1. 按 Cmd/Ctrl Shift P，或在 Augment 面板中打开汉堡菜单
2. 选择 Edit Settings
3. 在 Advanced 下，点击 Edit in settings.json
4. 将服务器配置添加到 `augment.advanced` 对象中的 `mcpServers` 数组
```json
"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，前往 **Settings → MCP Servers → Edit Global Config**。
2. 在 `mcp_settings.json` 文件中添加以下配置：
```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` 按钮
```json
{
"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).
Other MCP Clients
该服务器使用 stdio 传输并遵循标准 MCP 协议。可通过运行以下命令将其与任何兼容 MCP 的客户端集成：
```bash
npx @zilliz/claude-context-mcp@latest
```
---
### 在代码库中使用
1. **打开 Claude Code**
```
cd your-project-directory
claude
```
2. **为代码库建立索引**：
```
Index this codebase
```
3. **检查索引状态**：
```
Check the indexing status
```
4. **开始搜索**：
```
Find functions that handle user authentication
```
🎉 **就是这样！** 你现在可以在 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% 的 token 缩减。这在生产环境中可带来显著的成本与时间节省。这也意味着，在 token 上下文长度受限的情况下，使用 Claude Context 可获得更好的检索与回答效果。
有关详细的评估方法与结果，请参阅[评估目录](evaluation/)。
---
## 🏗️ 架构
### 🔧 实现细节
- 🔍 **混合代码搜索（Hybrid Code Search）**：提出诸如*“查找处理用户认证的函数”*之类的问题，通过先进的混合搜索（BM25 + 稠密向量）即时获取相关且上下文丰富的代码。
- 🧠 **上下文感知（Context-Aware）**：探索大型代码库，理解代码库不同部分之间的关联，即使代码量达到数百万行。
- ⚡ **增量索引（Incremental Indexing）**：使用 Merkle 树高效地仅重新索引已变更的文件。
- 🧩 **智能代码分块（Intelligent Code Chunking）**：基于抽象语法树（Abstract Syntax Trees，AST）分析代码并进行分块。
- 🗄️ **可扩展（Scalable）**：与 Zilliz Cloud 集成，实现可扩展的向量搜索，无论代码库规模多大。
- 🛠️ **可定制（Customizable）**：配置文件扩展名、忽略模式以及嵌入模型。
### 核心组件
Claude Context 是一个 monorepo，包含三个主要包：
- **`@zilliz/claude-context-core`**：核心索引引擎，支持嵌入（embedding）与向量数据库集成
- **VSCode Extension**：适用于 Visual Studio Code 的语义代码搜索（Semantic Code Search）扩展
- **`@zilliz/claude-context-mcp`**：用于 AI 智能体集成的 Model Context Protocol（MCP）服务器
### 支持的技术
- **Embedding Providers**： [OpenAI](https://openai.com), [VoyageAI](https://voyageai.com), [Ollama](https://ollama.com), [Gemini](https://gemini.google.com)
- **Vector Databases**： [Milvus](https://milvus.io) 或 [Zilliz Cloud](https://zilliz.com/cloud)(fully 托管向量数据库即服务）
- **Code Splitters**：基于 AST 的分割器（含自动回退）、LangChain 基于字符的分割器
- **Languages**：TypeScript、JavaScript、Python、Java、C++、C#、Go、Rust、PHP、Ruby、Swift、Kotlin、Scala、Markdown
- **Development Tools**：VSCode、Model Context Protocol
---
## 📦 使用 Claude Context 的其他方式
虽然 MCP 是将 Claude Context 与 AI 助手配合使用的推荐方式，你也可以直接使用它，或通过 VSCode 扩展使用。
### 使用核心包构建应用
`@zilliz/claude-context-core` 包提供代码索引与语义搜索的基础功能。
```typescript
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 Extension
将 Claude Context 直接集成到你的 IDE 中，提供直观的语义代码搜索与导航界面。
1. **直接链接**： [从 VS Code Marketplace 安装](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
2. **手动搜索**：
- 在 VSCode 中打开扩展视图（Windows/Linux：Ctrl+Shift+X；Mac：Cmd+Shift+X）
- 搜索 "Semantic Code Search"
- 点击 Install
---
## 🛠️ 开发
### 搭建开发环境
#### 前置要求
- Node.js 20.x、22.x 或 24.x
- pnpm（推荐的包管理器）
#### 跨平台搭建
```bash
# Clone repository
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Start development mode
pnpm dev
```
#### Windows 专属搭建
在 Windows 上，请确保已具备：
- **Git for Windows**，并正确配置行尾（line ending）
- 通过官方安装程序或包管理器安装的 **Node.js**
- 全局安装的 **pnpm**：`npm install -g pnpm`
```powershell
# Windows PowerShell/Command Prompt
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
# Configure git line endings (recommended)
git config core.autocrlf false
# Install dependencies
pnpm install
# Build all packages (uses cross-platform scripts)
pnpm build
# Start development mode
pnpm dev
```
### 构建
```bash
# Build all packages (cross-platform)
pnpm build
# Build specific package
pnpm build:core
pnpm build:vscode
pnpm build:mcp
# Performance benchmarking
pnpm benchmark
```
#### Windows 构建说明
- 所有构建脚本均通过 rimraf 实现跨平台兼容
- 已启用构建缓存，以加快后续构建
- 可使用 PowerShell 或 Command Prompt，两者效果相同
### 运行示例
```bash
# Development with file watching
cd examples/basic-usage
pnpm dev
```
---
## 📖 示例
查看 `/examples` 目录获取完整使用示例：
- **Basic Usage**：简单的索引与搜索示例
---
## ❓ FAQ
**常见问题：**
- **[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)**
❓ 如需详细解答及更多故障排除技巧，请参阅我们的 [FAQ 指南](docs/troubleshooting/faq.md)。
🔧 **遇到问题？** 访问我们的 [故障排除指南](docs/troubleshooting/troubleshooting-guide.md) 获取分步解决方案。
📚 **需要更多帮助？** 查看我们的 [完整文档](docs/) 获取详细指南与故障排除技巧。
---
## 🤝 贡献
欢迎贡献！请参阅我们的 [贡献指南](CONTRIBUTING.md) 了解如何开始。
**各包的贡献指南：**
- [Core Package Contributing](packages/core/CONTRIBUTING.md)
- [MCP Server Contributing](packages/mcp/CONTRIBUTING.md)
- [VSCode Extension Contributing](packages/vscode-extension/CONTRIBUTING.md)
---
## 🗺️ 路线图
- [x] 基于 AST 的代码分析，以提升理解能力
- [x] 支持更多 embedding 提供商
- [ ] 基于智能体的交互式搜索模式
- [x] 增强的代码分块策略
- [ ] 搜索结果排序优化
- [ ] 完善的 Chrome Extension
---
## 📄 许可证
本项目采用 MIT License 许可——详见 [LICENSE](LICENSE) 文件。
---
## 🔗 链接
- [GitHub Repository](https://github.com/zilliztech/claude-context)
- [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=zilliz.semanticcodesearch)
- [Milvus Documentation](https://milvus.io/docs)
- [Zilliz Cloud](https://zilliz.com/cloud)