cqs 代码上下文 MCP 服务器

关键词

代码上下文服务本地嵌入向量检索JSON-RPCSSEHTTP 传输

使用说明

  • 项目简介
    • cqs 是一个本地的代码语义检索与嵌入服务平台。它实现了 MCP（Model Context Protocol）服务器端，能够以标准化的 JSON-RPC 方式向客户端提供上下文信息、资源数据访问、工具调用以及提示渲染等能力。服务器具备会话管理、能力声明，并支持多种传输通道（如 STDIO、SSE、WebSocket/HTTP 等）。
  • 主要功能点
    • MCP 请求/响应处理：实现 initialize、tools/list、tools/call 等核心 MCP 请求，并返回符合规范的 JSON-RPC 响应。
    • 资源与工具管理：对资源、嵌入索引、观看/更新等提供后端支持，以及对工具的注册、执行及返回内容。
    • 安全与扩展性：支持 API Key 认证、Origin 校验、协议版本校验，提供健康检查与日志输出，具备用于生产环境的安全配置选项。
    • 多传输支持：提供 stdio（适用于直接集成的本地客户端，例如 Claude Code）与 http（REST 风格的 JSON-RPC 驶入/ SSE 推送）。
    • 会话与审计：内置审计模式，用于在特定场景下排除 notes，提升对话上下文的可控性。
  • 安装步骤
    • 安装前提：需在具备 Rust 编译环境的系统上构建与运行。
    • 构建与运行（示例）
      • 在项目根目录编译并运行：通过内建的 CLI 启动 MCP 服务器。
      • 运行 STDIO 服务器：将服务器作为一个外部进程接收来自标准输入的 JSON-RPC 请求并通过标准输出返回响应。
      • 运行 HTTP 服务器：启动 Web 服务端，监听指定地址与端口，客户端通过 HTTP(JSON-RPC) 进行交互。
  • 服务器配置（MCP 客户端需要的最小信息） 为了让 MCP 客户端（如 Claude）能连接到服务器，需在客户端配置中指明服务器端信息。以下为 JSON 格式的示例配置，包含 server name、command 与 args，描述注释均为为方便理解的说明： { "server_name": "cqs", "command": "cqs", "args": [ "serve", "--project", "/path/to/project" ] } 注释说明
    • server_name: MCP 客户端识别的服务器名称，这里设为 "cqs"。
    • command: 服务器启动的命令，这里使用可执行二进制名称 "cqs"。
    • args: 启动参数，示例为在本地项目根路径启动服务器，实际场景可改为通过 HTTP 传输，如添加 "--transport http"、"--bind 0.0.0.0"、"--port 3000" 等选项，以及安全相关参数如 "--api-key"。
  • 基本使用方法
    • 启动方式
      • 通过 STDIO (适用于本地集成的 LLM 客户端): cqs serve --project /path/to/project
      • 通过 HTTP (对外暴露): cqs serve --transport http --bind 0.0.0.0 --port 3000 --project /path/to/project
    • 客户端交互要点
      • 初始化服务器、建立能力声明和工具清单。
      • 客户端通过 initialize 请求获取服务器信息、协议版本及可用工具。
      • 使用 tools/list 查看可用工具，使用 tools/call 调用具体工具。
      • 如需获取嵌入、资源、或执行读文件等功能，可结合 store 与工具实现复杂的工作流。
  • 额外要点
    • 服务器实现了健康检查、错误处理、以及对无效请求的错误返回，确保与 MCP 客户端的对接稳定性。
    • 通过配置可开启 API Key 认证、Origin 校验等安全特性，适配在受控网络或本地环境中的使用场景。

服务器信息

访问项目