Codebase Indexing MCP

代码库索引MCP服务器

一种模型上下文协议（MCP）服务器，为AI代理提供语义代码库搜索和索引功能。该服务器使任何兼容MCP的AI客户端都可以使用向量嵌入和相似性匹配来执行智能代码搜索。

特性

• 🔍 语义搜索：根据含义查找代码，而不仅仅是关键字
• 📦 多嵌入器支持：OpenAI、Ollama、Gemini、Mistral等
• 🚀 向量存储：由Qdrant提供支持，实现高效的相似性搜索
• 📁 60多种语言：支持所有主要编程语言
• ⚡ 批处理：高效的嵌入生成和索引
• 🎯 路径筛选：将搜索限制到特定目录
• 💾 缓存：避免重新处理未更改的文件

建筑

基于Roo Code久经考验的索引系统：

• 嵌入器：生成代码的矢量表示
• 解析器：将代码分块为语义块
• 扫描仪：递归处理文件和目录
• 矢量存储：基于Qdrant的相似性搜索
• 缓存管理器：用于增量更新的SHA-256文件哈希

安装

bun install

配置

创建一个 .env 包含以下变量的文件：

# Qdrant Configuration
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_qdrant_key  # Optional for local

# Embedder Configuration
EMBEDDER_PROVIDER=openai  # openai, ollama, gemini, mistral, vercel-ai-gateway
EMBEDDER_API_KEY=your_api_key  # Or OPENAI_API_KEY
EMBEDDER_MODEL_ID=text-embedding-3-small  # Optional, defaults per provider
EMBEDDER_MODEL_DIMENSION=1536  # Optional, auto-detected for known models

# Search Configuration
SEARCH_MIN_SCORE=0.5  # Minimum similarity score (0-1)
SEARCH_MAX_RESULTS=10  # Maximum results to return

# Performance Configuration
EMBEDDING_BATCH_SIZE=60  # Segments per batch
MAX_FILE_SIZE=1048576  # 1MB in bytes

用法

运行服务器

# Development
bun run dev

# Production
bun run build
bun run start

MCP客户端配置

添加到MCP客户端的配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "codebase-indexing": {
      "command": "bun",
      "args": ["run", "/path/to/codebase-indexing-mcp/src/index.ts"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

可用工具

1.搜索_降级

在索引代码库中执行语义搜索。

参数：

• query （必填）：自然语言搜索查询
• path （可选）：限制搜索范围的目录路径

退货：

{
  "query": "user authentication",
  "results": [
    {
      "filePath": "src/auth/login.ts",
      "score": 0.87,
      "startLine": 15,
      "endLine": 45,
      "codeChunk": "function authenticateUser() { ... }"
    }
  ],
  "resultCount": 1
}

2.指数_贬值

索引代码库目录以启用语义搜索。

参数：

• workspacePath （必填）：代码库目录的路径
• force （可选）：即使已经索引，也强制重新索引

退货：

{
  "success": true,
  "message": "Successfully indexed 150 files and 2500 code blocks",
  "indexedFiles": 150,
  "indexedBlocks": 2500
}

3.获取索引状态

检查工作区的当前索引状态。

参数：

• workspacePath （必填）：工作区路径

退货：

{
  "state": "Indexed",
  "message": "Index up-to-date",
  "isIndexed": true,
  "workspacePath": "/path/to/project"
}

4.clear_index

清除工作区的所有索引数据。

参数：

• workspacePath （必填）：工作区路径

退货：

{
  "success": true,
  "message": "Index cleared successfully"
}

支持的嵌入器提供程序

开放人工智能

EMBEDDER_PROVIDER=openai
OPENAI_API_KEY=sk-...
EMBEDDER_MODEL_ID=text-embedding-3-small  # or text-embedding-3-large

模型：

• text-embedding-3-small （1536个维度）
• text-embedding-3-large （3072个尺寸）
• text-embedding-ada-002 （1536个维度）

Ollama（当地）

EMBEDDER_PROVIDER=ollama
EMBEDDER_BASE_URL=http://localhost:11434
EMBEDDER_MODEL_ID=nomic-embed-text

模型：

• nomic-embed-text （768尺寸）
• nomic-embed-code （3584个尺寸）
• mxbai-embed-large （1024个维度）

双子座

EMBEDDER_PROVIDER=gemini
EMBEDDER_API_KEY=your-gemini-key
EMBEDDER_MODEL_ID=text-embedding-004

米斯特拉尔

EMBEDDER_PROVIDER=mistral
EMBEDDER_API_KEY=your-mistral-key
EMBEDDER_MODEL_ID=codestral-embed-2505

Vercel人工智能网关

EMBEDDER_PROVIDER=vercel-ai-gateway
EMBEDDER_API_KEY=your-vercel-key
EMBEDDER_MODEL_ID=openai/text-embedding-3-large

Nebius人工智能工作室

EMBEDDER_PROVIDER=nebius
EMBEDDER_API_KEY=your-nebius-key
EMBEDDER_MODEL_ID=Qwen/Qwen3-Embedding-8B

为什么是奈比乌斯？

• 4096维（最高质量）
• 32K上下文窗口（最大）
• 每100万代币0.01美元（非常实惠）
• 600K TPM，10K RPM（慷慨的限制）

支持的文件类型

60多种语言，包括：

• JavaScript/TTypeScript（.js、.ts、.jsx、.tsx）
• Python（.py）
• Java（.Java）
• 去（.去）
• 锈蚀（.rs）
• C/C++（.C、.cpp、.h）
• Ruby（.rb）
• PHP（.PHP）
• Swift（.Swift）
• 科特林（.kt）
• Scala（.scale）
• 还有更多。..

需求

• 包子 运行时
• Qdrant 矢量数据库（本地或云端）
• 所选嵌入程序提供商的API密钥

设置Qdrant

本地（Docker）

docker run -p 6333:6333 qdrant/qdrant

云

注册地址： cloud.qdrant.io 并且使用所提供的URL和API密钥。

运作原理

1. 索引：扫描程序递归处理文件，将其解析为语义块，生成嵌入，并将其存储在Qdrant中
2. 缓存：文件哈希防止对未更改的文件进行冗余处理
3. 搜索：使用余弦相似度嵌入查询文本并将其与存储的向量进行比较
4. 过滤：可选路径前缀将结果限制到特定目录
5. 排名：按相似性得分排序的结果，按最小阈值过滤

演出

• 并行文件处理 -最多可同时处理50个文件（默认值：10）
• 优化的批量大小 -所有提供程序的每个API调用100个代码块
• 智能缓存 -SHA-256文件哈希跳过未更改的文件
• 增量更新 -仅处理已更改的文件
• 异步流水线 -重叠I/O操作以实现最大吞吐量
• 提供者不可知 -针对OpenAI、Nebius、Ollama、Gemini、Mistral等进行了优化

性能调整

通过环境变量进行配置：

EMBEDDING_BATCH_SIZE=100    # Segments per batch (default: 100)
PARALLEL_FILES=10            # Concurrent file processing (default: 10)
MAX_FILE_SIZE=1048576        # Max file size in bytes (default: 1MB)

预期性能：

• 小项目（\<100个文件）：~30-60秒
• 中型项目（100-500个文件）：约2-5分钟
• 大型项目（500多个文件）：约10-20分钟

*性能取决于提供商API延迟、文件大小和网络速度。*

示例用法

// In your MCP client (e.g., Claude Desktop)

// 1. Index a codebase
await use_mcp_tool("codebase-indexing", "index_codebase", {
  workspacePath: "/path/to/your/project"
});

// 2. Search for code
await use_mcp_tool("codebase-indexing", "search_codebase", {
  query: "user authentication and password hashing",
  path: "src/auth"  // Optional: limit to auth directory
});

// 3. Check status
await use_mcp_tool("codebase-indexing", "get_index_status", {
  workspacePath: "/path/to/your/project"
});

故障排除

“Qdrant连接失败”

• 确保Qdrant正在运行： docker ps 应显示qdrant/qdrant
• 检查QDRANT_URL是否正确
• 验证防火墙/网络设置

“嵌入程序验证失败”

• 验证API密钥是否正确
• 检查供应商的具体要求
• 确保型号ID对提供程序有效

“索引未就绪”

• 跑 index_codebase 搜索前
• 检查索引状态 get_index_status
• 在状态中查找错误消息

发展

# Run in development mode
bun run dev

# Build for production
bun run build

# Run tests
bun test

许可证

麻省理工学院

鸣谢

基于代码库索引系统 Roo代码，适合用作独立的MCP服务器。