JinDaGe - claude-context MCP Details

article

README

🚀 Claude Context

Claude Context 是一款 MCP 插件，它为 Claude Code 及其他 AI 编码助手增添了语义代码搜索功能，能让这些工具从整个代码库中获取深度上下文信息。

🧠 以整个代码库为上下文：Claude Context 借助语义搜索，能够从数百万行代码中找出所有相关代码，无需进行多轮探索，直接将搜索结果纳入 Claude 的上下文。

💰 大型代码库的经济之选：相较于每次请求都将整个目录加载到 Claude 中（这可能成本高昂），Claude Context 能高效地将代码库存储在向量数据库中，仅在上下文中使用相关代码，从而有效控制成本。

🚀 快速开始

前提条件

在 Zilliz Cloud 上获取免费向量数据库 👈

Claude Context 需要一个向量数据库。你可以在 Zilliz Cloud 上注册，以获取 API 密钥。

注册并获取 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` 而非 `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" }
# 可选：覆盖默认的 10 秒启动超时时间
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-key
  - MILVUS_ADDRESS：your-zilliz-cloud-public-endpoint
  - MILVUS_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 可获得更好的检索和回答结果。

MCP 效率分析

有关详细的评估方法和结果，请参阅评估目录。

🏗️ 架构

架构图

🔧 实现细节

🔍 混合代码搜索：提出诸如 "查找处理用户认证的函数" 之类的问题，借助先进的混合搜索（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"
- 点击安装

VSCode 扩展

🛠️ 开发

设置开发环境

前提条件

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

# Windows PowerShell/命令提示符
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 目录，获取完整的使用示例：

基本用法：简单的索引和搜索示例

❓ 常见问题解答

常见问题：

❓ 如需详细答案和更多故障排除提示，请参阅我们的常见问题解答指南。

🔧 遇到问题了吗？ 访问我们的故障排除指南，获取分步解决方案。

📚 需要更多帮助？ 查看我们的完整文档，获取详细指南和故障排除提示。

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南，了解如何开始贡献。

特定包的贡献指南：

🗺️ 路线图

[x] 基于 AST 的代码分析，以提高理解能力
[x] 支持更多嵌入提供商
[ ] 基于代理的交互式搜索模式
[x] 增强代码分块策略
[ ] 搜索结果排名优化
[ ] 强大的 Chrome 扩展

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

claude-context

README

🚀 Claude Context

🚀 快速开始

前提条件

为 Claude Code 配置 MCP

配置

其他 MCP 客户端配置

A. 使用 Augment Code 用户界面

B. 手动配置

在你的代码库中使用

环境变量配置

使用不同的嵌入模型

文件包含与排除规则

可用工具

1. index_codebase

2. search_code

3. clear_index

4. get_indexing_status

📊 评估

🏗️ 架构

🔧 实现细节

核心组件

支持的技术

📦 使用 Claude Context 的其他方式

使用核心包构建应用程序

VSCode 扩展

🛠️ 开发

设置开发环境

前提条件

跨平台设置

Windows 特定设置

构建

Windows 构建注意事项

运行示例

📖 示例

❓ 常见问题解答

🤝 贡献

🗺️ 路线图

📄 许可证

🔗 链接

Runtime guide

Hosted runtime

Local runtime / other methods

1. `index_codebase`

2. `search_code`

3. `clear_index`

4. `get_indexing_status`