代码库搜索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/project2.启动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 100MCP服务器
在stdio上运行MCP服务器：
npx codebase-search-mcp serve服务器通常由MCP客户端启动。有关配置，请参阅快速入门部分。
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
OPENAI_API_KEY | OpenAI API密钥（必需） | - |
QDRANT_URL | Qdrant服务器URL | http://localhost:6333 |
QDRANT_API_KEY | Qdrant API密钥（可选） | - |
EMBEDDING_MODEL | OpenAI嵌入模型 | text-embedding-3-small |
WORKSPACE_PATH | 工作区根目录 | 当前目录 |
CACHE_DIR | 缓存目录路径 | ~/.codebase-search-cache |
支持的文件类型
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/projectQdrant连接失败
确保Qdrant正在运行：
docker run -p 6333:6333 qdrant/qdrant检查URL是否正确（默认值： http://localhost:6333).
OpenAI API错误
请验证您的API密钥是否有效以及是否有足够的信用。如果您正在处理大型代码库，请检查速率限制。
矢量维度不匹配
如果更改嵌入模型，向量存储将自动检测维度不匹配并重新创建集合。您需要重新运行摄取命令。
性能提示
- 批量大小：增加
--batch-size更快的索引（使用更多内存） - 模型选择:
text-embedding-3-small比large - 增量更新：缓存确保只有更改的文件才会被重新索引
- Qdrant云：将托管的Qdrant实例用于生产工作负载
许可证
阿帕奇-2.0
贡献
欢迎投稿！请随时提交拉取请求。
鸣谢
此包最初是从 Roo代码 项目，并改编为独立的MCP服务器。