Codebase Search MCP

代码库搜索mcp

语义代码搜索由向量嵌入和MCP（模型上下文协议）提供支持。按含义搜索代码库，而不仅仅是关键字。

最初提取自 Roo代码 项目。

特性

• 🔍 语义搜索：通过描述代码的功能来查找代码，而不仅仅是匹配文本
• 🚀 MCP服务器：与Claude和其他MCP兼容工具集成
• 📦 CLI摄入：用于索引代码库的简单命令行界面
• 🔄 增量更新：仅重新索引更改的文件
• 🌳 智能解析：使用Tree sitter进行基于AST的代码分块
• 💾 Qdrant矢量存储：快速且可扩展的向量相似性搜索
• 🤖 OpenAI嵌入：采用最先进的语言模型

先决条件

• Qdrant：用于存储嵌入的矢量数据库

- 在本地运行： docker run -p 6333:6333 qdrant/qdrant - 或使用 Qdrant云

• OpenAI API密钥：用于生成嵌入

- 得到一个在 platform.openai.com

安装

# Install the package
npm install -g codebase-search-mcp

# Or use npx to run directly
npx codebase-search-mcp --help

快速开始

1.索引您的代码库

npx codebase-search-mcp ingest /path/to/your/project \
  --openai-api-key sk-... \
  --qdrant-url http://localhost:6333

或者使用环境变量：

export OPENAI_API_KEY=sk-...
export QDRANT_URL=http://localhost:6333

npx codebase-search-mcp ingest /path/to/your/project

2.启动MCP服务器

添加到您的MCP客户端配置中（例如，Claude Desktop的 claude_desktop_config.json):

{
  "mcpServers": {
    "codebase-search": {
      "command": "npx",
      "args": ["codebase-search-mcp", "serve"],
      "env": {
        "WORKSPACE_PATH": "/path/to/your/project",
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

3.搜索您的代码

在您的MCP客户端（例如Claude）中，您现在可以使用 search_codebase 工具：

{
  "query": "user authentication and password hashing",
  "path": "backend/auth",  // optional: limit to specific directory
  "minScore": 0.7,        // optional: similarity threshold
  "maxResults": 15        // optional: max results
}

CLI参考

摄入指令

为语义搜索的代码库建立索引：

npx codebase-search-mcp ingest  [options]

选项：

• --openai-api-key ：OpenAI API密钥（或使用 OPENAI_API_KEY 任何人）
• --qdrant-url ：Qdrant服务器URL（默认值： http://localhost:6333)
• --qdrant-api-key ：Qdrant API密钥（可选，用于云实例）
• --model ：嵌入模型（默认值： text-embedding-3-small)
• `--cache-dir

：缓存目录（默认： ~/.codebase-search-cache`)

• --batch-size ：嵌入的批量大小（默认值：60）

例子：

npx codebase-search-mcp ingest ./my-project \
  --openai-api-key sk-proj-... \
  --model text-embedding-3-large \
  --batch-size 100

MCP服务器

在stdio上运行MCP服务器：

npx codebase-search-mcp serve

服务器通常由MCP客户端启动。有关配置，请参阅快速入门部分。

环境变量

支持的文件类型

Tree sitter支持以下语言：

• 网络：JavaScript、TypeScript、JSX、TSX、HTML、CSS、Vue
• 后端：Python、Go、Rust、Java、C、C++、C#、Ruby、PHP
• 功能的： OCaml， Elixir， Elisp
• 其他Swift、Kotlin、Lua、Scala、Solidity、Zig、TOML、Markdown

尊重 .gitignore 图案自动。

建筑

┌─────────────────┐
│   MCP Client    │
│  (Claude, etc)  │
└────────┬────────┘
         │ MCP Protocol
┌────────▼─────────────────────┐
│   MCP Server                 │
│  (search_codebase tool)      │
└────────┬─────────────────────┘
         │
┌────────▼─────────────────────┐
│   Search Service             │
│  • Query embedding           │
│  • Vector similarity search  │
└──┬──────────────────────┬────┘
   │                      │
┌──▼──────────┐  ┌────────▼──────┐
│   OpenAI    │  │    Qdrant     │
│  Embeddings │  │ Vector Store  │
└─────────────┘  └───────────────┘

┌─────────────────┐
│   CLI Ingest    │
└────────┬────────┘
         │
┌────────▼─────────────────────┐
│   Directory Scanner          │
│  • File discovery            │
│  • Incremental updates       │
│  • Parallel processing       │
└──┬──────────────────────┬────┘
   │                      │
┌──▼──────────┐  ┌────────▼──────┐
│   Parser    │  │     Cache     │
│ Tree-sitter │  │  File hashes  │
└──┬──────────┘  └───────────────┘
   │
┌──▼──────────┐
│  Embedder   │
│   + Store   │
└─────────────┘

高级用法

程序化API

import {
  OpenAiEmbedder,
  QdrantVectorStore,
  SearchService,
} from 'codebase-search-mcp'

// Initialize components
const embedder = new OpenAiEmbedder(apiKey, 'text-embedding-3-small')
const vectorStore = new QdrantVectorStore(workspacePath, qdrantUrl, 1536)
const searchService = new SearchService(embedder, vectorStore)

// Initialize
await vectorStore.initialize()

// Search
const results = await searchService.search({
  query: 'HTTP request handler middleware',
  directoryPrefix: 'src/api',
  minScore: 0.75,
  maxResults: 10,
})

console.log(results)

自定义嵌入模型

支持的OpenAI模型：

• text-embedding-3-small （1536个尺寸，默认）
• text-embedding-3-large （3072个维度，更高质量）
• text-embedding-ada-002 （1536个维度，传统）

npx codebase-search-mcp ingest . \
  --model text-embedding-3-large

故障排除

未找到索引数据

确保运行 ingest 启动MCP服务器前的命令：

npx codebase-search-mcp ingest /path/to/project

Qdrant连接失败

确保Qdrant正在运行：

docker run -p 6333:6333 qdrant/qdrant

检查URL是否正确（默认值： http://localhost:6333).

OpenAI API错误

请验证您的API密钥是否有效以及是否有足够的信用。如果您正在处理大型代码库，请检查速率限制。

矢量维度不匹配

如果更改嵌入模型，向量存储将自动检测维度不匹配并重新创建集合。您需要重新运行摄取命令。

性能提示

1. 批量大小：增加 --batch-size 更快的索引（使用更多内存）
2. 模型选择: text-embedding-3-small 比 large
3. 增量更新：缓存确保只有更改的文件才会被重新索引
4. Qdrant云：将托管的Qdrant实例用于生产工作负载

许可证

阿帕奇-2.0

贡献

欢迎投稿！请随时提交拉取请求。

鸣谢

此包最初是从 Roo代码 项目，并改编为独立的MCP服务器。