grepika — 基于 MCP 的代码检索服务器

关键词

代码检索BM25三元组索引FTS5并发查询

使用说明（Markdown 格式）

  • 项目简介

    • grepika 是一个基于 MCP 的后端服务器，专注于代码检索相关的上下文服务。它把资源、工具、Prompts 等核心能力以 MCP 的约定暴露给 LLM 客户端，支持通过 JSON-RPC 进行请求/响应，并提供多种传输方式（如 Stdio、SSE、WebSocket 等）。
    • 主要目标是为 LLM 客户端提供高效、可扩展的上下文能力，包括对代码的全文检索、文件读取、结构提取、上下文摘取等能力，并在后端实现了会话管理、能力声明和安全边界。

  • 主要功能点

    • MCP 服务器端实现：实现基于 rmcp 的服务器框架，注册并暴露多种工具（如 search、get、outline、toc、context、stats、refs、index、diff、add_workspace 等），并通过工具路由进行调用。
    • 资源与工具管理：对代码库中的资源进行索引、管理，提供对文件内容、文件结构、目录树等的访问工具。
    • 提示与模板：支持 PROMPT/模板的渲染与渲染缓存，优化 LLM 交互。
    • JSON-RPC 交互：服务器接收来自 LLM 客户端的请求，返回标准的 JSON-RPC 响应，支持会话与通知。
    • 安全边界与合规：实现了路径遍历保护、敏感文件阻止、ReDoS（正则表达式防护）等安全特性，防止模型误用服务器暴露文件系统。
    • 增量索引与 Trigram 索引：结合 FTS5、Grep 与 Trigram 三元组索引实现高效的查询后端，并支持增量更新。
    • 多工作区模式：全局模式（全局工作区由 LLM 指定工作目录）和单工作区模式（通过 --root 指定工作区根目录）。
    • 容错与鲁棒性：包含并发访问、锁定/解锁、断点续传、以及对异常的错误码/错误数据封装，便于 MCP 客户端对错误进行处理。

  • 安装与运行步骤

    • 安装与构建
      • 获取源码后，在具备 Rust 环境的机器上编译：使用 cargo 构建整个仓库。
    • 运行方式（两种模式）
      • 全局 MCP 服务器模式（全局模式）：
        • 以无 --root 启动，LLM 需要先通过工具添加工作区（add_workspace）再使用工具。
      • 单工作区 MCP 服务器模式（带 --root 的模式）：
        • 直接提供工作区根路径，服务器在启动时加载该工作区并建立索引。
    • 服务器启动示例（概念性描述，不给出直接的命令行代码块）
      • 全局模式：以 MCP 服务监听 stdin/stdout 的 JSON-RPC，LLM 客户端通过 RMCP 协议连接。
      • 单工作区模式：启动时指定 --root 指向代码库根目录，服务器建立索引并对外暴露 MCP 工具。
    • 重要提示
      • MCP 客户端需要提供启动服务器的命令与参数信息，以便在本地/云端环境中对接。
      • 该实现包含多种工具，LLM 客户端可以按需调用：搜索、读取文件、提取结构、目录树、上下文、差异等。

  • 服务器配置（JSON，供 MCP 客户端参考配置，实际连接参数由客户端使用）

    • server_name: "grepika"
    • command: "npx"
    • args: ["-y", "@agentika/grepika", "--mcp"]
    • 注释（说明性文字，非代码）：以上配置描述了如何在支持 MCP 的工具链中启动 grepika 的 MCP 服务器。客户端在实际连接时需要知道服务器名称、启动命令及参数以建立 JSON-RPC 通道。若你希望单工作区运行，请在命令中添加 --root <项目路径>，以便服务器启动时直接加载该工作区并建立索引。客户端本身不执行代码，而仅使用这些信息去启动并连接到服务器。

  • 基本使用方法

    1. 启动方式选择
      • 全局模式：启动时不提供具体根目录，LLM 通过 add_workspace 注册工作区后即可使用工具。
      • 单工作区模式：通过 --root 指定代码库路径，服务器在启动时直接加载并索引。
    2. 调用工具
      • 通过 MCP 客户端对接，发送 JSON-RPC 请求，调用诸如 search、get、outline、toc、context、stats、refs、index、diff 等工具，获取结构化响应与必要的边界信息。
    3. 安全与鲁棒性
      • 服务器对用户路径进行了严格的路径验证，阻止路径遍历和访问敏感文件，正则表达式也进行了防 ReDoS 的限制，以保护服务端与代码库。

  • 运行结果与表现

    • 服务器实现了 MCP 的核心能力（资源、工具、提示的注册、执行与渲染），具备完整的服务器端实现、可运行的 MCP 服务，以及在测试中涉及的各种边界情况的处理逻辑。

  • 补充信息

    • 该仓库还包含丰富的单元测试、并发测试、基准测试等，覆盖从数据库、索引、搜索、Trigram、到工具执行的多方面场景，帮助验证 MCP 服务在实际场景中的可用性与鲁棒性。

关键字（3-5 个，以逗号分隔）：代码检索, BM25, 三元组索引, FTS5, 并发查询 分类ID：6

服务器信息

访问项目