Railyard CocoIndex MCP 服务器

关键词

语义搜索向量检索OverlayJSON-RPC脚手架
  • 项目简介
    • 该仓库包含一个用 Python 实现的 MCP 服务器，用于 CocoIndex 的语义代码搜索和 Overlay 索引管理。服务器以每个引擎为单位运行，通过 MCP 提供搜索、overlay 状态查询和 overlay 刷新等工具，结合 PostgreSQL 的 pgvector 实现向量检索，并按引擎和 Track 提供上下文隔离与安全性。
    • MCP 服务器核心能力包括：向客户端提供基于向量的代码搜索、查询 Overlay 索引状态、触发 Overlay 索引重建等工具；服务器端负责会话/身份的确认、能力声明，以及可扩展的传输协议支持（默认通过 stdio/JSON-RPC 进行通信，未来可切换到 SSE/WebSocket 等传输）。
  • 主要功能点
    • 双表检索与去重合并：对主索引和 Overlay 索引进行并行查询，Overlay 优先并基于文件名和位置信息进行去重合并。
    • MCP 工具注册：包括 search_code（语义搜索）、overlay_status（Overlay 状态获取）、overlay_refresh（Overlay 重建/刷新）。
    • 引擎级身份与上下文：使用环境变量来识别引擎、跟踪和工作区，确保跨引擎数据隔离与安全性。
    • 自带的测试覆盖：仓库中包含多组针对 MCP 服务器相关功能的单元测试，覆盖配置加载、查询、合并、数据库交互等关键路径。
    • 运行模式与依赖：在没有安装 mcp 包时仍能通过 ImportError 的处理进行测试适配；若有 MCP 客户端框架，能够通过 FastMCP 提供的接口实现 JSON-RPC 的远程对话。
  • 安装与运行
    • 安装与依赖
      • 需要 Python3 环境，相关依赖通过 Python 模块导入与运行时加载。
      • 可选依赖：mcp 包（用于正式的 FastMCP 服务器），用于 STDIO 以外的 JSON-RPC 传输。
    • 运行服务器的基本步骤
      • 设定环境变量（示例，实际按需调整）：
        • COCOINDEX_DATABASE_URL：PostgreSQL 数据库连接字符串（含 pgvector 支持）。
        • COCOINDEX_ENGINE_ID：当前引擎的唯一标识，例如 eng-a1b2c3d4。
        • COCOINDEX_MAIN_TABLE：主向量表名（如 main_backend_embeddings），若为多表跨 Track 使用 main_tables。
        • COCOINDEX_OVERLAY_TABLE：Overlay 表名（如 ovl_eng_a1b2c3d4），如无则可为空。
        • COCOINDEX_TRACK：Track 名称（如 backend）。
        • COCOINDEX_WORKTREE：工作树路径（用于 Overlay 构建/路径定位）。
      • 启动命令（示意，实际路径可能不同）：
        • python3 cocoindex_mcp_server.py 说明：该脚本会读取环境变量并在默认配置下创建一个 MCP 服务器实例，提供 search_code、overlay_status、overlay_refresh 三个工具，供 MCP 客户端通过 JSON-RPC 调用。
    • MCP 客户端配置（示例 JSON，供 MCP 客户端加载并发起连接） { "server_name": "railyard-cocoindex", "command": ["python3", "cmd/ry/cocoindex_mcp_server.py"], "description": "CocoIndex MCP 服务器：为 Eng-实例提供语义代码搜索与 Overlay 管理", "args": [], "environment": { "COCOINDEX_DATABASE_URL": "postgresql://cocoindex:cocoindex@localhost:5481/cocoindex", "COCOINDEX_ENGINE_ID": "eng-abc123", "COCOINDEX_MAIN_TABLE": "main_backend_embeddings", "COCOINDEX_OVERLAY_TABLE": "ovl_eng_abc123", "COCOINDEX_TRACK": "backend", "COCOINDEX_WORKTREE": "/path/to/worktree" } // 说明： // - server_name 与 command/args 指定 MCP 客户端启动时需要执行的服务名称及命令。 // - environment 中的变量用于让服务器在初始化阶段识别目标引擎、索引表和工作区。 // - 客户端在与 MCP 服务器建立连接时并不需要额外的代码，只需要提供上述启动信息和环境变量即可进入通信协程。 }
  • 基本使用方法
    • 启动前确保数据库与 pgvector 模块就绪，然后用上述环境变量配置好服务器。
    • MCP 客户端连接 MCP 服务器时，读取 server_name、command、args，并以 JSON-RPC 方式向服务器请求：例如执行语义搜索、查询 Overlay 状态、触发 Overlay 刷新等操作。
    • 常用操作示例（由 MCP 客户端发起，服务器端接收并返回 JSON-RPC 响应）：
      • 请求代码搜索：传入自然语言查询，服务器返回若干高相关的代码片段及元数据。
      • 请求 Overlay 状态：查询当前引擎的 Overlay 状态信息（已索引的文件数、块数、最后一次提交等）。
      • 请求 Overlay 刷新：触发 Overlay 重建，返回构建结果与耗时信息。
    • 调试与运维
      • 通过日志与返回的 JSON 结果核对搜索精度、覆盖率与合并策略；
      • 如遇环境变量缺失或表名冲突等问题，参考服务器日志和错误信息进行排错。

服务器信息

访问项目