Cocoindex Code MCP Server

CocoIndex代码MCP服务器

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

这个RAG MCP服务器使AI工具（LLM）能够高效、实时地从大型代码库中检索相关代码片段，利用CocoIndex的增量索引、基于树的分块和智能语言特定的嵌入。它通过虚拟地扩大AI模型可用的上下文窗口，提高了代码生成、代码完成和代码理解的性能。

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

目录

• 快速入门
• 命令行参数
• 特性
• 支持的语言
• 智能嵌入
• 发展
• 贡献

快速入门

1.克隆存储库（可选）

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

检查来源是 _不_ 如果您只想使用MCP服务器，这是绝对必要的，因为它可以安装 来自PyPI。然而，PyPI中缺少一些脚本，例如用于启动pgvector数据库的脚本 包裹。

2.安装

使用maturin从源代码构建：

# Install dependencies from PyPI
uv sync
uv sync --all-extras

# And build from source
maturin develop

或者从PyPI简单安装：

pip install cocoindex-code-mcp-server

我在PyPI上为许多系统（包括Linux、Windows和MacOS）提供了原生轮子，所以不需要构建 在大多数情况下。cocoindex代码mcp服务器需要Python 3.11+（为了更好，我更喜欢构建abi3 wheels 兼容性）。

3.启动PostgreSQL数据库

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

cd cocoindex-code-mcp-server
./scripts/cocoindex-postgresql.sh
# Maybe you need to install pgvector extension once
./scripts/install-pgvector.py

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

4.配置MCP服务器（DB连接）

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 

服务器将对指定目录中的代码进行索引，并开始处理请求。这需要一些时间。当你看到以下内容时，它就准备好了：

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

PyPI包确实为启动服务器提供了 cocoindex-code-mcp-server 记住 你需要一个正在运行的PostgreSQL+pgvector数据库才能正常工作。

6.使用MCP服务器

现在，您可以使用运行在以下位置的RAG服务器 http://localhost:3033 作为流式HTTP MCP服务器。例如，对于Claude Code，在以下代码段中使用 "mcpServers" 在你的 .mcp.json 文件：

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

命令行参数

文件过滤

包括图案

默认情况下，服务器使用一个广泛的内置包含列表（约70个源代码文件模式，全部在 **/ 表单，以便它们在任何目录深度都匹配）。当 --include 被给予，它 替换 内置的包含列表是完整的——只有您指定的模式才会被索引。

排除模式和 .gitignore 支持

.gitignore 在扫描树中的任何位置找到的文件是 自动尊重 并优先考虑：

• 随着 .gitignore：gitignore派生模式取代了内置的排除列表。它们是该项目排除的权威来源。
• 没有 .gitignore：内置的排除列表（常见构建工件、隐藏目录、依赖文件夹等）用作回退。

在这两种情况下，通过以下方式给出的模式 --exclude 附在顶部。使用 --no-gitignore 禁用 .gitignore 完全处理（然后像往常一样应用内置的回退列表）。

模式转换

所有模式都遵循 吉丁诺雷规则 并自动转换为CocoIndex使用的globset格式：

否定(!)不支持，将发出警告并跳过。

过时的结果过滤

当图案 跑步间隙变窄 （无 --rescan)，数据库可能仍然包含来自之前更广泛扫描的索引条目。为了防止查询中出现过时的结果，服务器应用 查询后路径筛选器 适用于所有三种搜索类型（关键字、矢量、混合）。路径不再与当前包含/排除模式匹配的任何结果都会被静默删除并记录在 INFO 水平。这意味着缩小你的模式会立即生效，而不需要 --rescan.

注意：扩展模式的作用方向相反——新文件在下一次更新时由CocoIndex的增量索引器拾取。

示例

# Index a single directory with live updates
python -m cocoindex_code_mcp_server.main_mcp_server /path/to/code

# Index multiple directories
python -m cocoindex_code_mcp_server.main_mcp_server /path/to/code1 /path/to/code2

# Force re-indexing with custom port
python -m cocoindex_code_mcp_server.main_mcp_server --rescan --port 3033 /path/to/code

# Disable live updates (one-time indexing)
python -m cocoindex_code_mcp_server.main_mcp_server --no-live /path/to/code

# Custom chunk size (50% smaller chunks)
python -m cocoindex_code_mcp_server.main_mcp_server --chunk-factor-percent 50 /path/to/code

# Index only Nix and Dhall files (replaces built-in include list)
python -m cocoindex_code_mcp_server.main_mcp_server --include '*.nix' --include '*.dhall' /path/to/code

# Exclude test directories and lock files (on top of .gitignore / built-in excludes)
python -m cocoindex_code_mcp_server.main_mcp_server --exclude '**/tests/**' --exclude '*.lock' /path/to/code

# Disable .gitignore-based exclusion (built-in fallback list takes over)
python -m cocoindex_code_mcp_server.main_mcp_server --no-gitignore /path/to/code

特性

• CocoIndex后端：用途 CocoIndex PostgreSQL+pgvector作为嵌入式和矢量数据库后端
• 多语言支持：专门支持20多种编程语言，具有特定语言的解析器和嵌入
• 流式HTTP MCP服务器：通过HTTP上的模型上下文协议进行实时代码检索
• 代码更改检测：增量索引，自动检测文件更改
• 树保姆Chunking：使用树型AST进行高级代码解析和分块，以更好地理解代码
• 智能嵌入：根据编程语言自动选择多个嵌入模型（参见 智能嵌入)
• 混合搜索：将向量相似性搜索与关键字/元数据过滤相结合，以获得精确的结果

- 向量搜索：使用特定语言的代码嵌入实现语义相似性 - 关键字搜索：元数据字段（函数、类、导入等）的精确匹配 - 混合搜索：两种方法的加权组合，具有可配置的权重

支持的语言

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

元数据提取： language_handlers/python_handler.py, 分析仪： lang/python/tree_sitter_python_analyzer.py, （回退： lang/python/python_code_analyzer.py), TODO：将其与访问者方法统一起来| | 锈 | .rs |UniXcoder |？ | ✅ rust |通过专业访问者提供完整的元数据支持： language_handlers/rust_visitor.py | | JavaScript | .js, .mjs, .cjs |GraphCodeBERT |？阿斯托克？ | ✅ javascript|专门访问者完全支持元数据： language_handlers/javascript_visitor.py | | TypeScript | .ts |UniXcoder |✅ astchunk |✅ typescript|扩展javascript访问者： language_handlers/typescript_visitor.py | | TSX | .tsx |UniXcoder |✅ astchunk |？打字稿？ | ?看到打字稿了吗？ | | 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 |❌ | 仅适用于树保姆解析/分块| | 哈斯克尔 | .hs, .lhs |全mpnet-base-v2 |✅ | ✅ | 定制maturin扩展与专门的访客， 碎料机： lang/haskell/haskell_ast_chunker.py, 元数据提取： language_handlers/haskell_handler.py | | 其他语言 |看 mappers.py |全mpnet-base-v2 |❌ | ❌ ?正则表达式？| cocoindex默认值（基线）|

传说

• 嵌入模型：为语言自动选择的嵌入模型
• AST分块：使用高级组块 ASTChunk 或者定制实现（基于ASTChunk的想法，并使用树形图作为语言）。
• 树保姆：语言配置了树型解析器用于AST分析。（python树保姆绑定，Haskell除外，它使用基于Rust绑定cargos的Maturin/Rust扩展 tree-sitter 和 tree-sitter-haskell.)
• 备注：关于支持级别的附加说明
• 其他语言：文件被识别，但只应用了基本的文本嵌入和分块（cocoindex默认值）。

这包括：Go、PHP、Ruby、Swift、Scala、Dart、CSS、HTML、JSON、Markdown、YAML、TOML、SQL、R、Fortran、Pascal、XML

智能嵌入

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

运作原理

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

1. GraphCodeBERT (microsoft/graphcodebert-base)

- 针对以下方面进行了优化： Python、Java、JavaScript、PHP、Ruby、Go、C、C++ - 通过基于图的代码理解对这些语言的代码进行预训练 - 最适合具有显式结构和常见模式的语言

1. Unixcoder。 (microsoft/unixcoder-base)

- 针对以下方面进行了优化： Rust、TypeScript、C#、Kotlin、Scala、Swift、Dart - 多种语言的统一跨语言模型 - 最适合现代静态类型语言

1. 后备模型 (sentence-transformers/all-mpnet-base-v2)

- 用于：代码模型不特别支持的语言 - 通用文本嵌入，提供更广泛的语言支持 - 768个与特定代码模型匹配的维度嵌入

自动选择

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

# Example: Python file automatically uses GraphCodeBERT
file: main.py → language: python → model: microsoft/graphcodebert-base

# Example: Rust file automatically uses UniXcoder
file: lib.rs → language: rust → model: microsoft/unixcoder-base

# Example: Haskell file uses fallback model
file: Main.hs → language: haskell → model: sentence-transformers/all-mpnet-base-v2

好处

• 更好的代码理解：特定于代码的模型比通用文本模型更了解编程构造
• 语言特定优化：每种语言都从用该语言训练的模型中嵌入
• 一致的搜索质量：同一语言中的类似代码片段会产生类似的嵌入
• 零配置：自动模型选择不需要手动配置

实现细节

智能嵌入系统是作为CocoIndex的外部包装器实现的 SentenceTransformerEmbed 功能，位于 python/cocoindex_code_mcp_server/smart_code_embedding.py这种方法：

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

有关更多技术细节，请参阅：

• docs/claude/Embedding-Selection.md
• docs/cocoindex/smart-embedding.md

发展

先决条件

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

运行测试

# Run tests to verify installation
pytest -c pytest.ini tests/

uv run --with pytest --with pytest-asyncio --with pytest-mock pytest tests/test_pattern_utils.py -v --tb=short 2>&1 | tail -20

代码质量

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

# Type check main source code
./scripts/mypy-check.sh

# Type check tests
./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：树保姆解析实用程序 - db/：数据库抽象层 - pgvector/：PostgreSQL+pgvector后端 - lang/：特定语言的处理程序 - python/：Python代码分析器 - haskell/：Haskell支持（通过Rust扩展）

• tests/：Pytest测试套件
• docs/：文件

- claude/：开发说明和架构文档 - cocoindex/：CocoIndex特定文档 - instructions/：任务说明和指南

• rust/：生锈的组件

- src/lib.rs：Haskell树保姆Rust扩展

• astchunk/：用于高级代码分块的ASTChunk子模块

运行测试

# Run all tests
pytest -c pytest.ini tests/

# Run specific test file
pytest -c pytest.ini tests/test_hybrid_search_integration.py

# Run with coverage
pytest -c pytest.ini tests/ --cov=python/cocoindex_code_mcp_server --cov-report=html

贡献

欢迎投稿！请打开问题并拉取请求 .

开发流程

1. 分叉存储库
2. 创建要素分支
3. 通过测试进行更改
4. 运行类型检查： ./scripts/mypy-check.sh
5. 运行测试： pytest tests/
6. 提交拉取请求

贡献领域

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

许可证

AGPL-3.0或更高版本

链接

• CocoIndex框架:
• GitHub存储库:
• 模型上下文协议:
• ASTChunk:

致谢

建立在优秀之上 CocoIndex 增量数据转换框架和 模型上下文协议 用于AI工具集成。