zilliztech--claude-context/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

🆕 需要为 Claude Code 提供持久记忆？ 不妨看看 memsearch Claude Code plugin —— 一款以 Markdown 为先的记忆系统，能让你的 AI agent 在多个会话间拥有长期记忆。

整个代码库作为 Claude 的上下文

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 注册 以获取 API 密钥。

复制你的 Personal Key，并在配置示例中替换 your-zilliz-cloud-api-key。

获取用于 embedding 模型的 OpenAI API Key

你需要 OpenAI API 密钥来运行 embedding 模型。可在 OpenAI. 注册获取。

你的 API 密钥格式如下：始终以 sk- 开头。
复制密钥，并在下方配置示例中将其用作 your-openai-api-key。

为 Claude Code 配置 MCP

系统要求：

• Node.js >= 20.0.0

配置

使用命令行界面添加 Claude Context MCP 服务器：

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 了解更多 MCP 服务器管理细节。

其他 MCP 客户端配置

OpenAI Codex CLI

Codex CLI 使用 TOML 配置文件：

1. 创建或编辑 ~/.codex/config.toml 文件。

2. 添加以下配置：

# 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. 添加以下配置：

{
  "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

前往：Settings -> Cursor Settings -> MCP -> Add new global MCP server

建议将以下配置粘贴到 Cursor 的 ~/.cursor/mcp.json 文件中。你也可以在特定项目中安装：在项目文件夹中创建 .cursor/mcp.json。更多信息请参阅 Cursor MCP docs。

{
  "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 设置中添加以下配置：

{
  "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

可通过支持 MCP 的扩展在 VS Code 中使用 Claude Context MCP 服务器。将以下配置添加到你的 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. 前往 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 文件中添加以下配置：

{
  "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 数组

"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 文件中添加以下配置：

{
  "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 集成示例，请参阅此示例.

Other MCP Clients

该服务器使用 stdio 传输并遵循标准 MCP 协议。可通过运行以下命令将其与任何兼容 MCP 的客户端集成：

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 环境变量配置，请参阅我们的环境变量指南。

使用不同的嵌入模型

要配置自定义嵌入模型（例如 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% 的 token 缩减。这在生产环境中可带来显著的成本与时间节省。这也意味着，在 token 上下文长度受限的情况下，使用 Claude Context 可获得更好的检索与回答效果。

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

---

🏗️ 架构

🔧 实现细节

• 🔍 混合代码搜索（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, VoyageAI, Ollama, Gemini
• Vector Databases： Milvus 或 Zilliz 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 包提供代码索引与语义搜索的基础功能。

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 安装
2. 手动搜索：
   • 在 VSCode 中打开扩展视图（Windows/Linux：Ctrl+Shift+X；Mac：Cmd+Shift+X）
   • 搜索 "Semantic Code Search"
   • 点击 Install

🛠️ 开发

搭建开发环境

前置要求

• Node.js 20.x、22.x 或 24.x
• pnpm（推荐的包管理器）

跨平台搭建

# 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

# 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

构建

# 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，两者效果相同

运行示例

# Development with file watching
cd examples/basic-usage
pnpm dev

---

📖 示例

查看 /examples 目录获取完整使用示例：

• Basic Usage：简单的索引与搜索示例

---

❓ FAQ

常见问题：

• Claude Context 会决定嵌入哪些文件？
• 能否使用完全本地化的部署方案？
• 是否支持多个项目 / 代码库？
• Claude Context 与其他编码工具有何区别？

❓ 如需详细解答及更多故障排除技巧，请参阅我们的 FAQ 指南。

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

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

---

🤝 贡献

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

各包的贡献指南：

• Core Package Contributing
• MCP Server Contributing
• VSCode Extension Contributing

---

🗺️ 路线图

• 基于 AST 的代码分析，以提升理解能力
• 支持更多 embedding 提供商
• 基于智能体的交互式搜索模式
• 增强的代码分块策略
• 搜索结果排序优化
• 完善的 Chrome Extension

---

📄 许可证

本项目采用 MIT License 许可——详见 LICENSE 文件。

---

🔗 链接

• GitHub Repository
• VSCode Marketplace
• Milvus Documentation
• Zilliz Cloud