可可索引代码MCP服务器

Name: 可可索引代码MCP服务器
Author: aanno

作者：aanno11 星标更新：2025-11-15

安装使用来源：spider==github.com

项目介绍

CocoIndex Code MCP Server

一个基于模型上下文协议（MCP）的服务器，提供了一个结合向量相似性和关键词元数据搜索的混合搜索能力的RAG（检索增强生成）工具，用于代码检索。该服务器基于CocoIndex数据转换框架，并支持多种编程语言。

此RAG MCP服务器使AI工具（如大型语言模型LLMs）能够从大型代码库中高效且实时地检索相关代码片段，利用CocoIndex的增量索引、基于tree-sitter的分块以及智能的语言特定嵌入。通过虚拟扩展AI模型可用的上下文窗口，它增强了代码生成、代码补全和代码理解的性能。

当前使用PostgreSQL + pgvector作为向量数据库后端，但可以适应CocoIndex支持的其他后端。

快速开始

1. 克隆仓库（可选）

git clone --recursive https://github.com/aanno/cocoindex-code-mcp-server.git
cd cocoindex-code-mcp-server

如果你只是想使用MCP服务器，克隆源代码并不是严格必要的，因为它可以从PyPI安装。然而，有一些脚本例如启动pgvector数据库的脚本在PyPI包中是缺失的。

2. 安装

使用maturin从源码构建：

# 从PyPI安装依赖
uv sync
uv sync --all-extras

# 并从源码构建
maturin develop

或者简单地从PyPI安装：

pip install cocoindex-code-mcp-server

我提供了许多系统（包括Linux、Windows和MacOS）的原生轮子（wheels）在PyPI上，因此大多数情况下不需要构建。cocoindex-code-mcp-server需要Python 3.11+（并且我倾向于构建abi3轮子以获得更好的兼容性）。

3. 启动PostgreSQL数据库

在本地机器的一个终端中，启动pgvector数据库：

cd cocoindex-code-mcp-server
./scripts/cocoindex-postgresql.sh
# 可能你需要一次性安装pgvector扩展
./scripts/install-pgvector.py

使用这些脚本是可选的，但是你需要一个正在运行的PostgreSQL + pgvector数据库才能让MCP服务器工作。

4. 配置MCP服务器（数据库连接）

cocoindex_code_mcp_server使用COCOINDEX_DATABASE_URL环境变量来连接到数据库。如果存在的话，它会读取当前目录下的.env文件。你可以复制提供的.env.template到.env并根据需要调整连接字符串。

当前目录不需要是你想要扫描的目录（详情见“命令行参数”部分）。

cp .env.template .env

5. 启动MCP服务器

在另一个终端中，启动cocoindex_code_mcp_server：

cd cocoindex-code-mcp-server
python -m cocoindex_code_mcp_server.main_mcp_server --rescan --port 3033 <path_to_code_directory>

服务器将索引指定目录中的代码并开始处理请求。这可能需要一些时间。当看到类似以下内容时，表示服务器已准备好：

CodeEmbedding.files (batch update): 1505 source rows NO CHANGE

PyPI包提供了使用cocoindex-code-mcp-server <options> <root-source-dir>启动服务器的方法。记住你需要一个正在运行的PostgreSQL + pgvector数据库才能正常工作。

6. 使用MCP服务器

你现在可以使用在http://localhost:3033运行的RAG服务器作为一个流式HTTP MCP服务器。例如，在你的.mcp.json文件中的"mcpServers"部分使用以下片段与Claude Code配合使用：

{
  "cocoindex-rag": {
    "command": "pnpm",
    "args": [
      "dlx",
      "mcp-remote@next",
      "http://localhost:3303/mcp"
    ]
  }
}

命令行参数

参数	类型	默认值	描述
`paths`	位置参数	-	要索引的代码目录路径（可以指定多个）
`--paths`	选项	-	指定路径的另一种方式（可以多次使用）
`--no-live`	标志	false	禁用实时更新模式
`--poll`	整数	60	实时更新的轮询间隔（秒）
`--default-embedding`	标志	false	使用默认的CocoIndex嵌入而不是智能嵌入
`--default-chunking`	标志	false	使用默认的CocoIndex分块而不是tree-sitter/AST分块
`--default-language-handler`	标志	false	使用默认的CocoIndex语言处理器
`--chunk-factor-percent`	整数	100	分块大小缩放因子百分比（100=默认，<100=更小，>100=更大）
`--port`	整数	3000	HTTP监听端口
`--log-level`	字符串	INFO	日志级别（DEBUG, INFO, WARNING, ERROR）
`--json-response`	标志	false	启用JSON响应而不是SSE流
`--rescan`	标志	false	在启动前清除数据库和跟踪表以强制重新索引

示例

# 对单个目录进行实时更新索引
python -m cocoindex_code_mcp_server.main_mcp_server /path/to/code

# 对多个目录进行索引
python -m cocoindex_code_mcp_server.main_mcp_server /path/to/code1 /path/to/code2

# 强制重新索引并自定义端口
python -m cocoindex_code_mcp_server.main_mcp_server --rescan --port 3033 /path/to/code

# 禁用实时更新（一次性索引）
python -m cocoindex_code_mcp_server.main_mcp_server --no-live /path/to/code

# 自定义分块大小（50%更小的分块）
python -m cocoindex_code_mcp_server.main_mcp_server --chunk-factor-percent 50 /path/to/code

功能

CocoIndex后端：使用CocoIndex作为嵌入和向量数据库后端，结合PostgreSQL + pgvector
多语言支持：针对20多种编程语言提供专门支持，包括语言特定解析器和嵌入
流式HTTP MCP服务器：通过HTTP上的模型上下文协议实现实时代码检索
代码变更检测：增量索引，自动检测文件变更
Tree-sitter分块：使用tree-sitter AST进行高级代码解析和分块，以更好地理解代码
智能嵌入：根据编程语言自动选择多个嵌入模型（参见智能嵌入）
混合搜索：结合向量相似性搜索和关键词/元数据过滤以获得精确结果
- 向量搜索：使用语言特定代码嵌入进行语义相似性搜索
- 关键词搜索：在元数据字段上进行精确匹配（函数、类、导入等）
- 混合搜索：两种方法的加权组合，权重可配置

支持的语言

服务器支持多种编程语言，具有不同程度的集成：

语言	扩展名	嵌入模型	AST分块	Tree-sitter	备注
Python	`.py`	GraphCodeBERT	✅ astchunk	✅ python	自定义（不使用访问者），<br/>元数据提取：`language_handlers/python_handler.py`，<br/>分析器：`lang/python/tree_sitter_python_analyzer.py`，<br/>(备用：`lang/python/python_code_analyzer.py`)，<br/>TODO：统一使用访问者方法
Rust	`.rs`	UniXcoder	?	✅ rust	完整元数据支持，专用访问者：`language_handlers/rust_visitor.py`
JavaScript	`.js`, `.mjs`, `.cjs`	GraphCodeBERT	?astchunk?	✅ javascript	完整元数据支持，专用访问者：`language_handlers/javascript_visitor.py`
TypeScript	`.ts`	UniXcoder	✅ astchunk	✅ typescript	扩展JavaScript访问者：`language_handlers/typescript_visitor.py`
TSX	`.tsx`	UniXcoder	✅ astchunk	?typescript?	?参见TypeScript?
Java	`.java`	GraphCodeBERT	✅ astchunk	✅ java	完整元数据支持，专用访问者：`language_handlers/java_visitor.py`
Kotlin	`.kt`, `.kts`	UniXcoder	?	✅ kotlin	完整元数据支持，专用访问者：`language_handlers/kotlin_visitor.py`
C	`.c`, `.h`	GraphCodeBERT	?	✅ c	完整元数据支持，专用访问者：`language_handlers/c_visitor.py`
C++	`.cpp`, `.cc`, `.cxx`,`.hpp`	GraphCodeBERT	?	✅ cpp	扩展C访问者：`language_handlers/cpp_visitor.py`
C#	`.cs`	UniXcoder	✅ astchunk	❌	仅使用Tree-sitter解析/分块
Haskell	`.hs`, `.lhs`	all-mpnet-base-v2	✅	✅	自定义maturin扩展，专用访问者，<br/>分块器：`lang/haskell/haskell_ast_chunker.py`，<br/>元数据提取：`language_handlers/haskell_handler.py`
其他语言	查看`mappers.py`	all-mpnet-base-v2	❌	❌ ?正则表达式?	CocoIndex默认设置（基线）

图例

嵌入模型：根据语言自动选择的嵌入模型
AST分块：使用ASTChunk或自定义实现的高级分块（基于ASTChunk的想法，并使用语言的tree-sitter进行分块）。
Tree-sitter：语言配置了用于AST分析的tree-sitter解析器。（除了Haskell使用基于Rust绑定的Maturin/Rust扩展外，其余使用Python的tree-sitter绑定）。
备注：关于支持级别的额外说明
其他语言：识别文件但仅应用基本文本嵌入和分块（CocoIndex默认设置）。<br/> 这包括：Go, PHP, Ruby, Swift, Scala, Dart, CSS, HTML, JSON, Markdown, YAML, TOML, SQL, R, Fortran, Pascal, XML

智能嵌入

服务器使用语言感知代码嵌入，根据编程语言自动选择最优嵌入模型。这种方法相比通用文本嵌入提供了更好的代码语义理解。

工作原理

智能嵌入系统使用不同的专门模型优化不同编程语言：

GraphCodeBERT (microsoft/graphcodebert-base)
- 优化于：Python, Java, JavaScript, PHP, Ruby, Go, C, C++
- 在这些语言的代码上预训练，基于图的代码理解
- 最适合具有明确结构和常见模式的语言
UniXcoder (microsoft/unixcoder-base)
- 优化于：Rust, TypeScript, C#, Kotlin, Scala, Swift, Dart
- 多语言统一跨语言模型
- 最适合现代静态类型语言
备用模型 (sentence-transformers/all-mpnet-base-v2)
- 用于：未被代码模型特别支持的语言
- 通用文本嵌入，适用于更广泛的语言支持
- 768维嵌入匹配代码特定模型

自动选择

嵌入模型根据文件扩展名自动选择：

# 示例：Python文件自动使用GraphCodeBERT
文件：main.py → 语言：python → 模型：microsoft/graphcodebert-base

# 示例：Rust文件自动使用UniXcoder
文件：lib.rs → 语言：rust → 模型：microsoft/unixcoder-base

# 示例：Haskell文件使用备用模型
文件：Main.hs → 语言：haskell → 模型：sentence-transformers/all-mpnet-base-v2

优点

更好的代码理解：代码特定模型比通用文本模型更好地理解编程构造
语言特定优化：每种语言都使用在其语言上训练的模型嵌入
一致的搜索质量：同一种语言中的相似代码片段产生相似的嵌入
零配置：自动模型选择无需手动配置

实现细节

智能嵌入系统作为CocoIndex的SentenceTransformerEmbed函数的外部包装实现，位于python/cocoindex_code_mcp_server/smart_code_embedding.py。这种做法：

不修改CocoIndex源代码
将CocoIndex作为纯依赖项使用
提供与现有工作流程的无缝兼容性
可以独立轻松更新

更多技术细节，请参阅：

开发

前提条件

Rust（最新稳定版本）
Python 3.11+
Maturin（用于Rust中Python扩展的构建工具）
PostgreSQL带pgvector扩展
Tree-sitter语言解析器（通过pyproject.toml自动安装）

运行测试

# 运行测试以验证安装
pytest -c pytest.ini tests/

代码质量

项目使用mypy进行类型检查。使用提供的脚本：

# 检查主源代码类型
./scripts/mypy-check.sh

# 检查测试类型
./scripts/mypy-check-tests.sh

项目结构

python/cocoindex_code_mcp_server/：主要MCP服务器实现
- main_mcp_server.py：MCP服务器入口点
- cocoindex_config.py：CocoIndex流程配置
- smart_code_embedding.py：语言感知嵌入选择
- mappers.py：语言和字段映射
- tree_sitter_parser.py：Tree-sitter解析实用程序
- db/：数据库抽象层
  - pgvector/：PostgreSQL + pgvector后端
- lang/：语言特定处理器
  - python/：Python代码分析器
  - haskell/：Haskell支持（通过Rust扩展）
tests/：Pytest测试套件
docs/：文档
- claude/：开发笔记和架构文档
- cocoindex/：CocoIndex特定文档
- instructions/：任务指令和指南
rust/：Rust组件
- src/lib.rs：Haskell tree-sitter Rust扩展
astchunk/：用于高级代码分块的ASTChunk子模块

运行测试

# 运行所有测试
pytest -c pytest.ini tests/

# 运行特定测试文件
pytest -c pytest.ini tests/test_hybrid_search_integration.py

# 带覆盖率运行
pytest -c pytest.ini tests/ --cov=python/cocoindex_code_mcp_server --cov-report=html

贡献

欢迎贡献！请在GitHub仓库上打开问题和拉取请求。

开发工作流程

分叉仓库
创建功能分支
添加测试并进行更改
运行类型检查：./scripts/mypy-check.sh
运行测试：pytest tests/
提交拉取请求

贡献领域

额外的语言支持（解析器、嵌入、分块）
现有语言的增强元数据提取
性能优化
文档改进
错误修复和问题解决

许可证

AGPL-3.0或更高版本

链接

CocoIndex框架：https://cocoindex.io
GitHub仓库：https://github.com/aanno/cocoindex-code-mcp-server
模型上下文协议：https://modelcontextprotocol.io
ASTChunk：https://github.com/codelion/astchunk

致谢

基于优秀的CocoIndex框架进行增量数据转换，以及用于AI工具集成的模型上下文协议。