Cocode (Hrayleung)

科科德

用于语义代码库搜索的MCP服务器，由 CocoIndex 用于实时增量索引和智能排名。

在语义上搜索你的代码库，而不必记住确切的函数名——找到“HTTP错误处理程序”并获取所有错误处理逻辑，即使它不包含这些确切的关键字。

基于CocoIndex构建

Cocode利用 CocoIndex，为AI应用程序设计的数据转换框架。CocoIndex提供：

• 增量处理：只重新索引更改的文件，而不是整个代码库——以最少的计算进行实时更新
• 树保姆集成：基于语法结构（不是任意换行符）的智能代码分块，用于语法连贯的嵌入
• 自动同步：使向量索引与长时间范围内的源代码更改保持同步
• AI集成：为AI代理和开发工具提供代码上下文

这种组合实现了快速、准确的语义搜索，随着代码的发展而保持最新。

主要特点

混合搜索架构

• 向量相似性：用于语义理解的pg向量余弦相似性
• BM25关键字搜索：PostgreSQL全文搜索以精确匹配术语
• 互惠排名融合：智能地将多种搜索策略与可配置的权重相结合
• 符号级索引：函数、类和方法分别用精确的行号索引

智能排名

• 基于图的中心性：PageRank算法识别结构上重要的文件（例如，许多模块导入的核心实用程序）
• 类别提升：实现代码优先于测试/docs/config（可配置权重）
• 多跳图遍历：通过导入依赖关系查找相关文件（默认情况下最多3个跃点）
• 可选的Cohere重新排名：rerank-v3.5以提高相关性（当提供API密钥时）

多个嵌入提供程序

• 姓名 （默认）：后期分块保留跨块上下文
• 米斯特拉尔：Codestral Embed专门针对代码进行了优化
• 开放人工智能：text-embedding-3-large，带有上下文标题

实时增量索引

• 文件级别更改检测：仅根据时间戳重新索引已修改的文件
• 自动索引更新：第一次搜索触发索引；后续搜索使用缓存结果
• 符号级别更新：文件更改时函数/类的UPSERT操作
• 图形缓存无效：当依赖关系更改时，导入图形会自动刷新

安装

先决条件

• Python 3.10+
• PostgreSQL与 pgvector (vector)扩展（服务器也将尝试启用 pgcrypto 对于UUID）
• 至少一个嵌入提供程序的API密钥
• 防锈工具链 （仅适用于从源头构建）：

- 通过安装 生锈: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - 包含 cargo 以及Rust编译器

快速安装（推荐）

使用以下命令从PyPI安装 pip, uvx，或 pipx:

# Using pip
pip install cocode-mcp

# Or using uvx (isolated environment, no global install)
uvx --from cocode-mcp cocode

# Or using pipx (isolated environment with global command)
pipx install cocode-mcp

# Verify installation
cocode --help

来源

标准安装

# Clone the repository
git clone https://github.com/hrayleung/Cocode.git
cd Cocode

# Install dependencies and build Rust extensions (requires Rust toolchain)
# This single command installs Python deps and builds the Rust extension in release mode
maturin develop --release

# Create .env file
cp .env.example .env
# Edit .env with your API keys

NixOS/Nix薄片

# Clone repository
git clone https://github.com/hrayleung/Cocode.git
cd Cocode

# Enter dev shell (includes Python 3.11, PostgreSQL 16, and dependencies)
nix develop

# Install dependencies and build Rust extensions (requires Rust toolchain)
maturin develop --release

# Create .env file (automatically copied by shellHook)
# Edit .env with your API keys

Nix薄片会自动：

• 在中设置PostgreSQL 16（通过Unix套接字） .postgres/
• 在中创建Python虚拟环境 venv/
• 自动激活venv
• 副本 .env.example 到 .env 如果它不存在

所需的环境变量

# PostgreSQL (requires pgvector; server also attempts to CREATE EXTENSION pgcrypto)
COCOINDEX_DATABASE_URL=postgresql://localhost:5432/cocode

# Embeddings (choose one)
OPENAI_API_KEY=sk-...          # Required unless using Jina late chunking
JINA_API_KEY=jina_...          # Can run without OpenAI if USE_LATE_CHUNKING=true
MISTRAL_API_KEY=...            # Optional (requires OPENAI_API_KEY as fallback)

# Select provider: jina, mistral, or openai (default: jina)
EMBEDDING_PROVIDER=jina
USE_LATE_CHUNKING=true

# Optional: Cohere reranking
COHERE_API_KEY=...
ENABLE_RERANKER=true  # enabled by default when COHERE_API_KEY is set

MCP配置

Cocode支持多个MCP客户端。选择与您的工作流程相匹配的设置。

Claude Desktop

Claude Desktop从以下位置读取其配置 claude_desktop_config.json:

配置文件位置:

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

配置示例:

{
  "mcpServers": {
    "cocode": {
      "command": "cocode",
      "args": [],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgresql://localhost:5432/cocode",
        "JINA_API_KEY": "jina_...",
        "EMBEDDING_PROVIDER": "jina",
        "USE_LATE_CHUNKING": "true",
        "COHERE_API_KEY": "your_cohere_key_optional"
      }
    }
  }
}

重要提示:

• 使用 绝对路径 在 args 如有需要
• 避免 尾随逗号 JSON格式（导致无声故障）
• 完全重新启动克劳德桌面 配置更改后（不仅仅是关闭窗口）
• 克劳德桌面 不 支持 ${VAR_NAME} 环境变量替换（使用文字值代替）。其他客户，如VS Code和 .mcp.json 配置支持 ${VAR_NAME} 或 ${env:VAR} 语法

替代方案：使用紫外线进行隔离:

{
  "mcpServers": {
    "cocode": {
      "command": "uvx",
      "args": ["--from", "cocode-mcp", "cocode"],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgresql://localhost:5432/cocode",
        "JINA_API_KEY": "jina_..."
      }
    }
  }
}

*注意：在发布PyPI之前，请使用 "args": ["--from", "git+https://github.com/hrayleung/Cocode.git", "cocode"] 从源代码安装。*

Claude Code CLI

选项1：通过CLI添加（推荐）

# Add to your user config (available across all projects)
claude mcp add --scope user cocode -- cocode

# Or add to current project only
claude mcp add --scope project cocode -- cocode

# With environment variables baked in
claude mcp add --scope user \
  -e COCOINDEX_DATABASE_URL=postgresql://localhost:5432/cocode \
  -e JINA_API_KEY="${JINA_API_KEY}" \
  -e EMBEDDING_PROVIDER=jina \
  -e USE_LATE_CHUNKING=true \
  cocode -- cocode

选项2：项目配置

创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "cocode": {
      "command": "cocode",
      "args": [],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgresql://localhost:5432/cocode",
        "JINA_API_KEY": "${JINA_API_KEY}",
        "EMBEDDING_PROVIDER": "jina",
        "USE_LATE_CHUNKING": "true"
      }
    }
  }
}

选项3：独立运行

cocode
# or
python -m src.server

验证安装

在克劳德代码中：

/mcp

VS Code (GitHub Copilot)

VS Code通过工作区或用户设置支持MCP服务器。

工作空间配置 (.vscode/settings.json):

{
  "github.copilot.chat.mcp.servers": {
    "cocode": {
      "command": "cocode",
      "args": [],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgresql://localhost:5432/cocode",
        "JINA_API_KEY": "${env:JINA_API_KEY}",
        "EMBEDDING_PROVIDER": "jina",
        "USE_LATE_CHUNKING": "true"
      }
    }
  }
}

用户配置 （全局设置）：

1. 打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P)
2. 搜索“首选项：打开用户设置（JSON）”
3. 添加相同内容 github.copilot.chat.mcp.servers 对象

使用输入变量作为秘密:

{
  "github.copilot.chat.mcp.servers": {
    "cocode": {
      "command": "cocode",
      "args": [],
      "env": {
        "COCOINDEX_DATABASE_URL": "${input:databaseUrl}",
        "JINA_API_KEY": "${input:jinaApiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "databaseUrl",
      "type": "promptString",
      "description": "PostgreSQL database URL"
    },
    {
      "id": "jinaApiKey",
      "type": "promptString",
      "password": true,
      "description": "Jina API Key"
    }
  ]
}

Codex CLI

Codex将MCP服务器配置存储在 ~/.codex/config.toml.

选项1：通过CLI添加（Codex）

# Add the server (stdio transport)
codex mcp add cocode \
  --env COCOINDEX_DATABASE_URL=postgresql://localhost:5432/cocode \
  --env JINA_API_KEY="${JINA_API_KEY}" \
  --env EMBEDDING_PROVIDER=jina \
  --env USE_LATE_CHUNKING=true \
  -- cocode

# Verify
codex mcp list
codex mcp get cocode

选项2：编辑 ~/.codex/config.toml

[mcp_servers.cocode]
command = "cocode"
args = []

[mcp_servers.cocode.env]
COCOINDEX_DATABASE_URL = "postgresql://localhost:5432/cocode"
JINA_API_KEY = "jina_..."
EMBEDDING_PROVIDER = "jina"
USE_LATE_CHUNKING = "true"

Warp Terminal

Warp通过其设置UI支持MCP服务器。

设置步骤:

1. 通过以下方式打开扭曲设置：

- Settings > MCP Servers，或 - Warp Drive > Personal > MCP Servers，或 - 命令面板：搜索“打开MCP服务器”，或 - Settings > AI > Manage MCP servers

1. 点击 + Add 按钮
2. 选择配置类型：

- CLI服务器（命令）：用于本地可执行文件 - 流式HTTP/SSE服务器（URL）：用于远程服务器

CLI服务器配置:

{
  "command": "cocode",
  "args": [],
  "env": {
    "COCOINDEX_DATABASE_URL": "postgresql://localhost:5432/cocode",
    "JINA_API_KEY": "jina_...",
    "EMBEDDING_PROVIDER": "jina",
    "USE_LATE_CHUNKING": "true"
  },
  "working_directory": "/path/to/your/project"
}

多个服务器：将JSON粘贴到 mcpServers 按键：

{
  "mcpServers": {
    "cocode": {
      "command": "cocode",
      "args": [],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgresql://localhost:5432/cocode",
        "JINA_API_KEY": "jina_..."
      }
    }
  }
}

Troubleshooting MCP Setup

服务器未出现

1. 检查配置语法:

- 验证JSON（无尾随逗号） - 在中使用绝对路径 args 如有需要 - 确保环境变量是带引号的字符串

1. 重新启动客户端:

- Claude Desktop：完全退出（不仅仅是关闭窗口） - VS代码：重新加载窗口或重新启动 - 翘曲：重新启动终端

1. 验证服务器安装:

# Check if cocode is in PATH
which cocode

# Test server directly
cocode

连接失败

1. 检查PostgreSQL:

# Test database connection
psql postgresql://localhost:5432/cocode

# Verify pgvector extension
psql -d cocode -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

1. 验证API密钥:

- 确保密钥有效且未过期 - 检查一下 EMBEDDING_PROVIDER 与您提供的密钥匹配 - 对于Jina： USE_LATE_CHUNKING=true 必须设置

1. 检查日志:

- 克劳德桌面版：检查应用程序中的MCP日志 - VS Code：查看输出面板→ 选择“MCP”频道 - 曲速：在MCP设置中查看服务器日志

常见错误

“无法连接到服务器”:

• 验证服务器命令是否正确以及是否在PATH中
• 检查是否设置了所有必需的环境变量
• 确保PostgreSQL正在运行

“数据库连接失败”:

• 确认PostgreSQL正在运行： pg_isready
• 验证数据库URL格式： postgresql://user:pass@host:port/dbname
• 确保数据库存在： createdb cocode

“缺少API密钥”:

• 至少设置一个嵌入提供程序密钥
• 如果使用Jina：设置两者 JINA_API_KEY 和 USE_LATE_CHUNKING=true
• 如果使用Mistral：同时设置 MISTRAL_API_KEY 和 OPENAI_API_KEY （回退）

无声故障:

• 检查JSON配置中的尾随逗号
• 使用linter验证JSON
• 查看应用程序日志中的特定错误消息

性能问题:

• 对于大型代码库，首次索引可能需要几分钟的时间
• 如果索引速度非常慢，请检查PostgreSQL内存设置
• 考虑启用图形缓存：默认情况下自动启用

MCP工具

结果格式

codebase_retrieval_full 返回一个对象：

• files：排名关键文件（带类别+行提示）
• dependencies：导入返回文件之间的边
• symbols：最相关函数/类/方法的完整代码实现

查询示例

"Where is user authentication implemented?"
"How does the payment processing work?"
"Find all database connection code"

运作原理

1.索引阶段（首次搜索时自动）

当你第一次搜索代码库时，Cocode：

1. 存储库注册：使用路径哈希创建元数据条目以处理重复的文件夹名称
2. CocoIndex加工:

- 扫描存储库以查找支持的文件类型(.py, .ts, .js, .go, .rs等等） - 使用Tree sitter AST解析智能地分块代码（尊重函数/类边界） - 使用您选择的提供程序为每个块生成嵌入 - 使用HNSW矢量索引存储块以进行快速相似性搜索

1. 符号提取 （平行）：

- 使用Tree sitter解析函数、类和方法 - 提取签名、文档字符串、可见性和分类 - 具有精确行号和单独嵌入的存储

1. 导入图构造:

- 分析所有文件中的导入语句 - 构建双向依赖图（导入+imported_by） - 计算PageRank中心性得分 - 用于快速遍历的缓存图

后续搜索重用索引，仅重新索引已更改的文件（通过mtime比较）。

2.搜索阶段（实时）

查询代码库时：

1. 查询嵌入：使用所选提供程序将自然语言查询转换为向量
2. 并行搜索执行 （具有3个工作线程的ThreadPoolExecutor）：

- 向量搜索：块嵌入中的pg向量余弦相似度 - BM25搜索：PostgreSQL全文搜索 ts_rank_cd 评分 - 符号搜索：函数/类/方法上的Vector+BM25

1. 互惠排名融合：将结果与可配置权重相结合（向量=0.6，bm25=0.4，符号=0.7）
2. 排名管道:

- 集中度提升：放大结构重要文件的分数（PageRank） - 类别提升：优先考虑实施>文档>配置>测试 - Cohere-Rerank （可选）：基于LLM的重新排名，以提高相关性

1. 后处理:

- 文件聚合：按文件分组，每个文件保持前3名 - 图扩展：BFS遍历通过导入查找相关文件（最多3跳） - 分层结果：前3名包含完整代码摘录，其余为紧凑签名

3.增量更新（透明）

在后续搜索中，Cocode会自动：

1. 变化检测：将文件修改时间与上次索引时间进行比较
2. 选择性重新索引：仅处理更改/新建/删除的文件
3. 符号更新：通过以下方式进行UPSERT操作 ON CONFLICT 约束
4. 图形缓存刷新：使受影响的导入关系无效
5. 中心度重新计算：如果图形拓扑结构发生变化，则更新PageRank分数

这确保了您的搜索结果始终以最小的延迟反映代码库的当前状态。

建筑

config/
└── settings.py              # Environment-driven configuration

src/
├── server.py                # FastMCP entry point (2 tools)
│
├── indexer/                 # CocoIndex Integration
│   ├── service.py           # IndexerService singleton - orchestrates indexing
│   ├── flow.py              # CocoIndex flows for chunking/embedding
│   ├── repo_manager.py      # Repository metadata and status tracking
│   ├── symbol_indexing.py   # AST-based function/class extraction
│   └── call_graph_indexing.py # (Experimental) call edge extraction
│
├── retrieval/               # Hybrid Search Pipeline
│   ├── service.py           # SearchService singleton - orchestrates search
│   ├── hybrid.py            # RRF fusion + parallel execution
│   ├── vector_search.py     # pgvector cosine similarity
│   ├── bm25_search.py       # PostgreSQL FTS with ts_rank_cd
│   ├── symbol_search.py     # Symbol-level search (vector + BM25)
│   ├── file_categorizer.py  # Category-based score boosting
│   ├── centrality.py        # PageRank computation and boosting
│   ├── graph_expansion.py   # Multi-hop import traversal (BFS)
│   ├── graph_cache.py       # Import graph caching (30-50% faster)
│   ├── fts_setup.py         # Lazy FTS index creation
│   └── reranker.py          # Cohere rerank-v3.5 integration
│
├── parser/                  # AST-Based Code Analysis
│   ├── ast_parser.py        # Tree-sitter import parsing (8 languages)
│   ├── symbol_extractor.py  # Symbol metadata extraction (Python, Go)
│   └── call_extractor.py    # Function call extraction (Python, Go)
│
├── embeddings/              # Multi-Provider Support
│   ├── backend.py           # Provider selection + API key validation
│   ├── provider.py          # Base provider interface (singleton pattern)
│   ├── jina.py              # Jina late chunking implementation
│   ├── mistral.py           # Codestral Embed implementation
│   └── openai.py            # OpenAI embeddings implementation
│
└── storage/                 # Database Layer
    ├── schema.py            # PostgreSQL table definitions
    └── postgres.py          # Connection pooling + query helpers

搜索管道

Query → Embedding
         ↓
       [Parallel Search - ThreadPoolExecutor]
       ├─ Vector search (pgvector cosine)
       ├─ BM25 search (PostgreSQL FTS)
       └─ Symbol search (functions/classes)
         ↓
       Reciprocal Rank Fusion (weights: vector=0.6, bm25=0.4, symbol=0.7)
         ↓
       Centrality Boost (PageRank)
         ↓
       Category Boost (impl=1.0, docs=0.7, config=0.6, tests=0.3)
         ↓
       Cohere Rerank (optional)
         ↓
       Aggregate by File (top 3 chunks per file)
         ↓
       Graph Expansion (related files via imports)

配置

嵌入提供者

搜索调谐

索引

数据库模式

全局表（公共架构）

回购协议 -存储库元数据

• 核心： id, name, path, status (pending/indexing/ready/failed)
• 时间戳： created_at, last_indexed
• 统计数据： file_count, chunk_count
• 错误： error_message

{repo}\_centrality -PageRank分数（按需创建）

• filename （PK）， score （浮动）
• 导入图形拓扑更改时更新

每个存储库表（架构=经过净化的存储库名称）

代码索引\_{repo}\_\_{repo}\_chunks -CocoIndex管理的块存储

• 内容： filename, location （字符范围）， content, embedding （矢量）
• 指数：HNSW on embedding 用于矢量搜索
• BM25： content_tsv （tsvector）+GIN索引在首次搜索时缓慢添加
• 完全由CocoIndex管理（增量更新、缓存）

代码索引\_{repo}\_\_cocoindex_tracking -CocoIndex内部状态

• 跟踪文件哈希值、块边界和增量处理的行为版本
• 由CocoIndex自动维护

｛schema｝.符号 -函数/类/方法

• 元数据： symbol_name, symbol_type （函数/类/方法）， signature, docstring
• 地点： filename, line_start, line_end （1-索引，包括在内）
• 背景： parent_symbol, visibility （公共/私人/内部）， category （实现/测试/api/config）
• 搜索： embedding （矢量）+HNSW， content_tsv （tsvector）+GIN
• 唯一约束： (filename, symbol_name, line_start) 用于UPSERT支持
• 时间戳： created_at, updated_at

｛schema｝.edges -调用图关系（实验）

• 关系： source_symbol_id, target_symbol_id, edge_type （“呼叫”、“工具”等）
• 地点： source_file, source_line, target_file, target_line
• 信心： 1.0 （完全匹配）， 0.7 （部分）， 0.5 （未解决/外部）
• 上下文：“循环”、“条件”、“递归”等。
• 删除符号时删除CASCADE

{schema}.graph_cache -导入图形缓存

• filename （PK）， imports （JSONB）， imported_by （JSONB）
• 统计数据： symbol_count, edge_count
• 在增量索引过程中自动失效
• 与即时解析相比，图形查询速度提高了30-50%

所有从存储库文件夹名称+路径哈希派生的表名（用于处理重复项）。

支持的语言

基于AST的特征（树保姆）

导入解析+图形扩展：Python、Go、Rust、C、C++、JavaScript、TypeScript、TSX

• 解析import/include语句以构建依赖关系图
• 处理动态导入、有条件导入、别名导入
• 如果Tree sitter不可用，则返回正则表达式

符号提取：Python，Go

• 提取带有签名和文档字符串的函数、类、方法
• 检测可见性（公共/私人/内部）
• 分类为实现/测试/api/config
• 精确的行号范围（包括1-索引）

索引文件类型（分块+可搜索）

所有这些扩展都被分块和嵌入，用于语义+关键字搜索：

.py .rs .ts .tsx .js .jsx .go .java .cpp .c .h .hpp .rb .php .swift .kt .scala .md .mdx

索引过程中会忽略与这些扩展名不匹配的文件。

发展

运行测试

# All tests
pytest

# Verbose output with details
pytest -v

# Single test file
pytest tests/test_file_categorizer.py -v

# Single test method
pytest tests/test_file_categorizer.py::TestFileCategorizerDetection::test_python_test_files -v

# Pattern matching
pytest -k "test_python"

# With coverage
pytest --cov=src --cov-report=html

项目结构说明

• Singleton服务: IndexerService 和 SearchService 使用单例模式来防止重复连接
• CocoIndex集成：将块存储委托给CocoIndex；直接管理符号/图形存储
• 线程安全：对并发搜索请求使用锁
• 错误处理：搜索后端失败时的优雅回退（例如，仅当BM25失败时才使用向量）

了解更多

• CocoIndex框架: https://cocoindex.io/
• CocoIndex GitHub:
• 使用CocoIndex构建代码库RAG: https://cocoindex.io/blogs/index-code-base-for-rag
• 实时代码库索引: https://cocoindex.io/docs/examples/code_index

许可证

麻省理工学院

______________________________________________________________________

问题或议题？ 在GitHub上打开一个问题。