使用说明

MCP代码库索引

一个强大的模型上下文协议（MCP）服务器，使AI助手能够使用语义搜索来搜索和理解您的代码库。使用自然语言查询（如“身份验证逻辑”或“数据库连接处理”）而不是精确的文本匹配来查找代码。

特性

🔍 语义代码搜索 -使用自然语言搜索，而不仅仅是关键字
🌐 多语言支持 -TypeScript、JavaScript、Python、Java、Go、Rust、C/C++、C#、Ruby、PHP等
🎯 智能代码解析 -使用Tree sitter了解函数、类和代码结构
🔄 实时更新 -文件更改或分支切换时自动重新索引
🚀 多个嵌入提供程序 -使用谷歌Gemini（免费）、OpenAI或当地Ollama模型
☁️ 灵活存储 -适用于Qdrant Cloud（免费层）或自托管实例

安装

npm install -g mcp-codebase-index

或与npx一起使用（无需安装）：

npx mcp-codebase-index

快速开始

1.建立Qdrant矢量数据库

选择一个选项：

选项A:Qdrant Cloud（建议初学者使用）

免费注册 Qdrant云
创建集群（可用空闲层）
获取API URL和密钥

选项B：本地Docker

docker run -p 6333:6333 qdrant/qdrant

2.获取嵌入提供程序API密钥

选择一个选项：

选项A：谷歌双子座（免费）

在获取免费API密钥谷歌人工智能工作室

选项B:OpenAI

在获取API密钥 OpenAI平台

选项C：Ollama（本地，免费）

安装奥拉玛
拉一个模型： ollama pull nomic-embed-text

3.配置IDE/编辑器

选择您的IDE或编辑器，并按照设置说明进行操作：

Claude Desktop

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["-y", "mcp-codebase-index"],
      "env": {
        "CODEBASE_PATH": "/absolute/path/to/your/repository",
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "your-api-key-here",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

对于Qdrant Cloud：

{
  "mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["-y", "mcp-codebase-index"],
      "env": {
        "CODEBASE_PATH": "/absolute/path/to/your/repository",
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "your-api-key-here",
        "QDRANT_URL": "https://your-cluster.cloud.qdrant.io",
        "QDRANT_API_KEY": "your-qdrant-api-key"
      }
    }
  }
}

保存配置后重新启动Claude Desktop。

Claude Code (VS Code Extension)

打开VS代码设置（Cmd/Ctrl+，）
搜索“克劳德代码：MCP服务器”
点击“在settings.json中编辑”
添加此配置：

{
  "claude-code.mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["-y", "mcp-codebase-index"],
      "env": {
        "CODEBASE_PATH": "/absolute/path/to/your/repository",
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "your-api-key-here",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

保存后重新加载VS代码。

Cursor

Cursor通过其AI设置支持MCP服务器：

打开光标设置（Cmd/Ctrl+，）
导航到“功能”→ "AI"
滚动到“模型上下文协议”
点击“编辑配置”或找到配置文件：
- macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
- 视窗: %APPDATA%/Cursor/User/globalStorage/mcp.json
- Linux: ~/.config/Cursor/User/globalStorage/mcp.json
添加此配置：

{
  "mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["-y", "mcp-codebase-index"],
      "env": {
        "CODEBASE_PATH": "/absolute/path/to/your/repository",
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "your-api-key-here",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

保存后重新启动Cursor。

VS Code with Continue Extension

如果你正在使用继续扩展名：

打开继续配置文件：
- macOS/Linux: ~/.continue/config.json
- 视窗: %USERPROFILE%\.continue\config.json
添加到 experimental.modelContextProtocolServers 章节：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "codebase-index",
        "command": "npx",
        "args": ["-y", "mcp-codebase-index"],
        "env": {
          "CODEBASE_PATH": "/absolute/path/to/your/repository",
          "EMBEDDING_PROVIDER": "gemini",
          "GEMINI_API_KEY": "your-api-key-here",
          "QDRANT_URL": "http://localhost:6333"
        }
      }
    ]
  }
}

保存后重新加载VS代码。

Windsurf Editor

Windsurf原生支持MCP服务器：

打开风帆设置
导航到MCP设置或找到配置文件：
- macOS: ~/Library/Application Support/Windsurf/mcp_config.json
- 视窗: %APPDATA%/Windsurf/mcp_config.json
- Linux: ~/.config/Windsurf/mcp_config.json
添加此配置：

{
  "mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["-y", "mcp-codebase-index"],
      "env": {
        "CODEBASE_PATH": "/absolute/path/to/your/repository",
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "your-api-key-here",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

保存后重新启动Windsurf。

Zed Editor

Zed具有实验性MCP支持：

打开Zed设置（Cmd/Ctrl+，）
添加到您的settings.json：

{
  "experimental": {
    "mcp_servers": {
      "codebase-index": {
        "command": "npx",
        "args": ["-y", "mcp-codebase-index"],
        "env": {
          "CODEBASE_PATH": "/absolute/path/to/your/repository",
          "EMBEDDING_PROVIDER": "gemini",
          "GEMINI_API_KEY": "your-api-key-here",
          "QDRANT_URL": "http://localhost:6333"
        }
      }
    }
  }
}

保存后重新启动Zed。

Other MCP-Compatible Clients

对于任何兼容MCP的客户端，请使用以下标准配置：

{
  "mcpServers": {
    "codebase-index": {
      "command": "npx",
      "args": ["-y", "mcp-codebase-index"],
      "env": {
        "CODEBASE_PATH": "/absolute/path/to/your/repository",
        "EMBEDDING_PROVIDER": "gemini",
        "GEMINI_API_KEY": "your-api-key-here",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

有关配置文件的确切位置，请参阅客户的文档。

4.重新启动IDE/编辑器

保存配置后，重新启动IDE/编辑器。服务器将在第一次运行时自动开始为您的代码库建立索引。

用法

配置后，您可以让您的AI助手搜索您的代码库：

示例查询：

“查找身份验证中间件”
“显示数据库连接代码”
“用户验证逻辑在哪里？”
“查找API终结点处理程序”
“显示错误处理实用程序”

高级用法：

“在TypeScript文件中搜索‘速率限制’”
“在/src/api目录中查找与支付处理相关的函数”
“显示最近的更改（先重新索引）”

可用工具

MCP服务器为您的AI助手提供以下工具：

`codebase_search`

使用自然语言或代码查询搜索您的代码库。

参数：

query （必填）-您的搜索查询
limit -结果数（默认值：10）
threshold -相似性阈值0-1（默认值：0.7）
fileTypes -按扩展名过滤（例如。， [".ts", ".js"])
paths -按路径过滤（例如。， ["src/api"])
includeContext -包含周围代码（默认值：true）

`indexing_status`

检查索引进度和统计数据。

`reindex`

重新索引你的代码库（在拉取更改后很有用）。

参数：

mode -“完整”、“增量”或“文件”
paths -要重新索引的特定文件（可选）
force -即使没有变化，也要强制重新索引

`configure_indexer`

在运行时更新索引器设置。

`validate_config`

测试您的配置和连接。

`clear_index`

清除所有索引数据并重新开始。

配置参考

必需设置

变量	描述	示例
`CODEBASE_PATH`	指向存储库的绝对路径	`/Users/you/projects/myapp`
`EMBEDDING_PROVIDER`	提供商使用	`gemini`, `openai`，或 `ollama`
`QDRANT_URL`	Qdrant实例URL	`http://localhost:6333`

提供商特定设置

双子座：

GEMINI_API_KEY=your-api-key

对于OpenAI：

OPENAI_API_KEY=your-api-key
OPENAI_MODEL=text-embedding-3-small  # or text-embedding-3-large

对于Ollama：

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=nomic-embed-text

可选设置

变量	描述	默认值
`COLLECTION_NAME`	Qdrant集合名称	`codebase_index`
`INDEX_BATCH_SIZE`	每批文件数	`50`
`INDEX_CONCURRENCY`	并行处理限制	`5`
`LOG_LEVEL`	日志记录详细信息	`info`
`QDRANT_API_KEY`	对于Qdrant Cloud	-

支持的语言

Types/JavaScript
python
Java
去
锈
C/C++
C
红宝石
PHP
标记语言

不支持的语言退回到智能文本分块。

故障排除

“找不到模块”错误

npm install -g mcp-codebase-index

索引速度慢

减少 INDEX_CONCURRENCY 或增加 INDEX_BATCH_SIZE 在您的配置中。

Qdrant的“连接被拒绝”

确保Qdrant正在运行： docker ps 或检查Qdrant Cloud状态
验证 QDRANT_URL 是正确的
对于云：确保 QDRANT_API_KEY 已设置

无搜索结果

使用检查索引状态 indexing_status 工具
尝试使用重新索引 reindex 工具
降低相似性 threshold 在您的搜索中

速率限制错误

如果使用免费的API层：

减少 INDEX_CONCURRENCY 1-2
增加 INDEX_BATCH_SIZE 以减少API调用

运作原理

代码解析：使用Tree sitter将代码解析为有意义的块（函数、类等）
嵌入生成：使用您选择的AI提供程序将代码转换为向量嵌入
矢量存储器：将嵌入存储在Qdrant中，以实现快速相似性搜索
语义搜索：通过比较查询嵌入和存储的代码嵌入来查找相关代码
实时更新：监视文件更改并自动重新索引

性能提示

适用于大型代码库（1000+个文件）：使用 INDEX_BATCH_SIZE=100 和 INDEX_CONCURRENCY=3
用于快速迭代：将Ollama与本地模型一起使用（无API调用）
为了获得最佳质量：使用OpenAI text-embedding-3-large 模型
免费使用：使用谷歌双子座（慷慨的免费等级）

隐私和安全

所有代码索引都在本地或您选择的基础架构中进行
API密钥仅用于嵌入生成
代码从不发送给第三方（嵌入生成除外）
自托管Ollama选项使所有内容都完全本地化

例子

示例1：查找身份验证码

You: "Find all authentication middleware in the codebase"
AI Assistant: [Uses codebase_search tool with query "authentication middleware"]

示例2：Git Pull后重新索引

You: "I just pulled new changes, please reindex"
AI Assistant: [Uses reindex tool with mode "incremental"]

示例3：搜索特定目录

You: "Search for error handlers in the src/api directory"
AI Assistant: [Uses codebase_search with query "error handlers" and paths ["src/api"]]

贡献

欢迎投稿！请访问我们的 GitHub存储库致：

报告问题
提交拉取请求
请求功能
提出问题

许可证

MIT许可证-请参阅许可证详细信息文件

支持

问题: GitHub问题
讨论: GitHub讨论

致谢

内置：

模型上下文协议通过Anthropic
树保姆用于代码解析
Qdrant 用于矢量存储