🚀 Claude Context
Claude Context 是一款 MCP 插件，它为 Claude Code 及其他 AI 编码助手增添了语义代码搜索功能，能让这些工具从整个代码库中获取深度上下文信息。
🧠 以整个代码库为上下文：Claude Context 借助语义搜索，能够从数百万行代码中找出所有相关代码，无需进行多轮探索，直接将搜索结果纳入 Claude 的上下文。
💰 大型代码库的经济之选：相较于每次请求都将整个目录加载到 Claude 中（这可能成本高昂），Claude Context 能高效地将代码库存储在向量数据库中，仅在上下文中使用相关代码，从而有效控制成本。
🚀 快速开始
前提条件
在 Zilliz Cloud 上获取免费向量数据库 👈
Claude Context 需要一个向量数据库。你可以在 Zilliz Cloud 上注册，以获取 API 密钥。
复制你的个人密钥，在配置示例中替换 your-zilliz-cloud-api-key。
获取 OpenAI 嵌入模型的 API 密钥
你需要一个 OpenAI API 密钥来使用嵌入模型。你可以在 OpenAI 上注册获取。
你的 API 密钥格式通常以 sk- 开头。
复制你的密钥，并在以下配置示例中使用它替换 your-openai-api-key。
为 Claude Code 配置 MCP
系统要求：
- Node.js >= 20.0.0 且 < 24.0.0
Claude Context 与 Node.js 24.0.0 不兼容，如果你的 Node 版本大于或等于 24，需要先进行降级。
配置
使用命令行界面添加 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 文档。
其他 MCP 客户端配置
OpenAI Codex CLI
Codex CLI 使用 TOML 配置文件：
- 创建或编辑
~/.codex/config.toml 文件。
- 添加以下配置：
[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" }
startup_timeout_ms = 20000
- 保存文件并重启 Codex CLI 以应用更改。
Gemini CLI
Gemini CLI 需要通过 JSON 文件进行手动配置：
- 创建或编辑
~/.gemini/settings.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"
}
}
}
}
- 保存文件并重启 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
点击链接：安装 MCP
前往：设置 -> Cursor 设置 -> MCP -> 添加新的全局 MCP 服务器
建议将以下配置粘贴到你的 Cursor ~/.cursor/mcp.json 文件中。你也可以通过在项目文件夹中创建 .cursor/mcp.json 文件，在特定项目中进行安装。有关更多信息，请参阅 Cursor 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 配置，但你可以通过图形用户界面添加新服务器：
- 导航到 设置 → MCP 服务器 → 添加服务器。
- 填写服务器详细信息：
- 名称：
claude-context
- 类型：
STDIO
- 命令：
npx
- 参数：
["@zilliz/claude-context-mcp@latest"]
- 环境变量：
OPENAI_API_KEY：your-openai-api-keyMILVUS_ADDRESS：your-zilliz-cloud-public-endpointMILVUS_TOKEN：your-zilliz-cloud-api-key
- 保存配置以激活服务器。
Cline
Cline 使用 JSON 配置文件来管理 MCP 服务器。要集成提供的 MCP 服务器配置：
- 打开 Cline，点击顶部导航栏中的 MCP 服务器 图标。
- 选择 已安装 标签，然后点击 高级 MCP 设置。
- 在
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"
}
}
}
}
- 保存文件。
Augment
要在 Augment Code 中配置 Claude Context MCP，你可以使用图形界面或手动配置。
A. 使用 Augment Code 用户界面
- 点击汉堡菜单。
- 选择 设置。
- 导航到 工具 部分。
- 点击 + 添加 MCP 按钮。
- 输入以下命令：
npx @zilliz/claude-context-mcp@latest
- 将 MCP 命名为：Claude Context。
- 点击 添加 按钮。
B. 手动配置
- 按下 Cmd/Ctrl + Shift + P 或在 Augment 面板中点击汉堡菜单。
- 选择编辑设置。
- 在高级设置下，点击在 settings.json 中编辑。
- 将服务器配置添加到
augment.advanced 对象中的 mcpServers 数组中。
"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 服务器：
- 打开 Roo Code，导航到 设置 → MCP 服务器 → 编辑全局配置。
- 在
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"
}
}
}
}
- 保存文件以激活服务器。
Zencoder
Zencoder 在其 JetBrains 和 VS Code 插件版本中都支持 MCP 工具和服务器。
- 转到 Zencoder 菜单 (...)
- 从下拉菜单中选择
工具
- 点击
添加自定义 MCP
- 添加名称（例如
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"
}
}
- 点击
安装 按钮保存服务器配置。
LangChain/LangGraph
有关 LangChain/LangGraph 集成示例，请参阅 此示例。
其他 MCP 客户端
该服务器使用标准输入输出传输，并遵循标准 MCP 协议。通过运行以下命令，它可以与任何支持 MCP 的客户端集成：
npx @zilliz/claude-context-mcp@latest
在你的代码库中使用
- 打开 Claude Code
cd your-project-directory
claude
- 为你的代码库建立索引：
Index this codebase
- 检查索引状态：
Check the indexing status
- 开始搜索：
Find functions that handle user authentication
🎉 就是这么简单！ 现在你可以在 Claude Code 中使用语义代码搜索了。
环境变量配置
有关更详细的 MCP 环境变量配置，请参阅我们的 环境变量指南。
使用不同的嵌入模型
要配置自定义嵌入模型（例如，OpenAI 的 text-embedding-3-large，VoyageAI 的 voyage-code-3），请参阅 MCP 配置示例，了解每个提供商的详细设置说明。
文件包含与排除规则
有关文件包含和排除规则的详细解释，以及如何自定义这些规则，请参阅我们的 文件包含与排除规则。
可用工具
1. index_codebase
为代码库目录建立混合搜索（BM25 + 密集向量）索引。
2. search_code
使用自然语言查询，通过混合搜索（BM25 + 密集向量）在已索引的代码库中进行搜索。
3. clear_index
清除特定代码库的搜索索引。
4. get_indexing_status
获取代码库的当前索引状态。对于正在进行索引的代码库，显示进度百分比；对于已完成索引的代码库，显示完成状态。
📊 评估
我们的对照评估表明，在检索质量相当的情况下，Claude Context MCP 可实现约 40% 的令牌减少。这意味着在生产环境中，能够显著节省成本和时间。这也意味着，在有限的令牌上下文长度约束下，使用 Claude Context 可获得更好的检索和回答结果。
有关详细的评估方法和结果，请参阅 评估目录。
🏗️ 架构
🔧 实现细节
- 🔍 混合代码搜索：提出诸如 "查找处理用户认证的函数" 之类的问题，借助先进的混合搜索（BM25 + 密集向量），立即获取相关且上下文丰富的代码。
- 🧠 上下文感知：深入探索大型代码库，理解代码库不同部分之间的关系，即使代码量达到数百万行也不在话下。
- ⚡ 增量索引：利用 Merkle 树高效地仅对更改的文件重新建立索引。
- 🧩 智能代码分块：通过抽象语法树（AST）分析对代码进行分块。
- 🗄️ 可扩展性：与 Zilliz Cloud 集成，实现可扩展的向量搜索，无论代码库规模多大都能应对。
- 🛠️ 可定制性：配置文件扩展名、忽略模式和嵌入模型。
核心组件
Claude Context 是一个包含三个主要包的单仓库项目：
@zilliz/claude-context-core：核心索引引擎，集成了嵌入和向量数据库功能。- VSCode 扩展：为 Visual Studio Code 提供语义代码搜索扩展。
@zilliz/claude-context-mcp：用于 AI 代理集成的模型上下文协议服务器。
支持的技术
- 嵌入提供商：OpenAI、VoyageAI、Ollama、Gemini
- 向量数据库：Milvus 或 Zilliz 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';
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)}...`);
});
VSCode 扩展
将 Claude Context 直接集成到你的 IDE 中，为你提供直观的语义代码搜索和导航界面。
- 直接链接：从 VS Code 市场安装
- 手动搜索：
- 在 VSCode 中打开扩展视图（Ctrl+Shift+X 或 Mac 上的 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 上，请确保你具备以下条件：
- 适用于 Windows 的 Git，并进行了正确的换行符配置
- 通过官方安装程序或包管理器安装的 Node.js
- 全局安装的 pnpm：
npm install -g pnpm
git clone https://github.com/zilliztech/claude-context.git
cd claude-context
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 如何决定嵌入哪些文件？
- 我可以使用完全本地部署的设置吗？
- 它支持多个项目/代码库吗？
- Claude Context 与其他编码工具相比如何？
❓ 如需详细答案和更多故障排除提示，请参阅我们的 常见问题解答指南。
🔧 遇到问题了吗？ 访问我们的 故障排除指南，获取分步解决方案。
📚 需要更多帮助？ 查看我们的 完整文档，获取详细指南和故障排除提示。
🤝 贡献
我们欢迎贡献！请参阅我们的 贡献指南，了解如何开始贡献。
特定包的贡献指南：
- 核心包贡献
- MCP 服务器贡献
- VSCode 扩展贡献
🗺️ 路线图
- [x] 基于 AST 的代码分析，以提高理解能力
- [x] 支持更多嵌入提供商
- [ ] 基于代理的交互式搜索模式
- [x] 增强代码分块策略
- [ ] 搜索结果排名优化
- [ ] 强大的 Chrome 扩展
📄 许可证
本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。
🔗 链接
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
