xsql MCP 服务端

关键词

AI上下文服务数据库查询SSH代理云端协作多传输协议

使用说明（Markdown 格式）

  • 项目简介

    • xsql 提供一个 MCP 服务器实现，允许 AI 客户端通过统一的协议访问和执行数据库查询、注册并调用外部工具、以及获取并渲染 Prompt/工具规范等上下文信息。服务器以 JSON-RPC 形式收发请求与响应，支持多种传输通道（如标准输入输出和流式 HTTP），并实现会话管理、能力声明以及对资源、工具和提示的标准化提供。

  • 主要功能点

    • 通过 MCP 协议处理客户端请求，统一返回 JSON-RPC 风格的响应，包含 OK/错误、数据和错误详情等字段。
    • 托管与管理资源（Resources），注册与执行工具（Tools），以及定义并渲染 Prompt 模板（Prompts），以便 AI 客户端在对话中灵活获取上下文与能力。
    • 支持多种传输协议：
      • StdIO（stdio）: 直接在进程的标准输入/输出之间进行 JSON-RPC 交互。
      • Streamable HTTP（streamable_http）: 通过 HTTP 轮询/流式传输与客户端通信，便于前端/桌面应用接入。
    • 安全与认证：
      • 对 Streamable HTTP 传输提供基于 Bearer token 的简单认证保护，防止未授权访问。
    • 与现有数据库驱动的整合：
      • 通过配置文件整合 profiles，支持像 xsql query 这样的工具，用于在 MCP 场景中执行 SQL 查询并将结果以结构化格式返回给 AI 客户端。
    • 配置能力：
      • 支持从配置文件加载 profile、SSH 代理、以及 MCP 传输选项，提供命令行与环境变量控制的优先级合并逻辑。

  • 安装与运行步骤

    • 准备工作
      • 需要安装 Go 语言环境。
      • 获取源码后进入仓库根目录。
    • 构建服务器
      • 使用仓库提供的命令构建可执行文件（默认输出为 xsql，可通过 go build ./cmd/xsql 完成编译）。
    • 启动 MCP 服务器
      • 运行命令：xsql mcp server --config /path/to/xsql.yaml
      • 该配置文件应包含所需的 Profiles、SSH Proxies、以及 MCP 相关设置（如传输方式、HTTP 地址等）。
    • 与 MCP 客户端的连接方式
      • 客户端在配置中需要指向该 MCP 服务器，通过命令和参数启动的方式建立连接（下面的配置示例中包含 server name、command、args，供客户端使用）。
    • 常见故障与排错
      • 配置缺失/错误会返回 MCP/客户端约定的错误码，处理时可参考项目的错误码体系来定位问题。

  • 服务器配置（MCP 客户端使用的连接信息） 说明：以下为 MCP 客户端的连接配置示例，用于在Claude Desktop 等客户端上注册并连接到本仓库实现的 MCP 服务器。客户端本身需要仅了解服务器的启动命令和参数，不需要修改服务器端代码。 备注：server 名称应与部署时的识别一致，command 指向本仓库提供的 MCP 服务器可执行文件（在此示例中为 xsql），_args 则为启动 MCP 服务器的具体参数。具体路径请替换为实际部署时的路径。

    { "servers": [ { "name": "xsql", "command": "xsql", "args": ["mcp", "server", "--config", "/path/to/xsql.yaml"] } // 如有其它 MCP 服务器，可在此继续添加 ] }

    参数说明

    • name: MCP 服务器在客户端侧的识别名。
    • command: 启动 MCP 服务器的命令（在本实现中通常为二进制名，如 xsql）。
    • args: 启动命令的参数数组，确保包含子命令和所需的配置路径，例如 "mcp", "server", "--config", "/path/to/xsql.yaml"。
    • 说明：此配置仅用于客户端连接 MCP 服务器，实际的服务器启动与运行由服务器端实现负责，客户端只需要按照该配置启动并连接即可。

  • 基本使用方法

    • 启动后，AI 客户端（如 Claude、Cursor 等）通过 MCP 客户端与服务器建立连接，发送初始化请求并按照需请求工具、资源等能力。
    • 客户端发送请求后，服务器根据 MCP 约定返回 JSON-RPC 风格的响应数据或错误信息，AI 客户端再进行解析与后续交互。
    • 服务器还支持通过配置指定的传输协议，开发者/部署者可以根据自身网络环境选择 stdio 或流式 HTTP。

  • 参考实现要点与要点摘要

    • MCP 相关核心实现点：服务器端处理 MCP 请求、注册工具、处理输入参数、返回标准化的 Envelope（含 ok、schema_version、data、error 等字段）。
    • 安全性：对流式 HTTP 传输提供 Bearer Token 认证，确保只有持 token 的客户端能够访问。
    • 配置与扩展性：通过配置文件管理 profiles、SSH 代理以及 MCP 配置，便于在不同环境下快速切换。

  • 备注

    • 本仓库不仅包含 MCP 服务端实现，还包含对工具、配置、以及对外暴露的 API 的完整实现与测试覆盖。若要在实际环境中部署，请确保 yml/yaml 配置正确，且 MCP 客户端能够通过配置的命令和参数正确连接。

服务器信息

访问项目