MariaDB-Guard-RO-MCP

关键词

数据库网关安全审计只读查询JSON-RPC数据库代理

使用说明：

  • 项目简介

    • 该仓库实现了一个 MCP 服务器，核心职责是以标准化的 JSON-RPC 方式向 LLM 客户端暴露上下文信息和功能，包括对数据库资源的只读访问、工具（如 db_select、db_explain、db_explain_table 等）的注册与执行，以及对查询的解释与日志记录。服务器通过 HTTP 提供服务端点，包含初始化、心跳、工具调用等能力，并集成安全控制和会话管理。代码结构清晰，具备完整的服务器端实现与必要的单元测试。

  • 主要功能点

    • MCP 协议实现与 JSON-RPC 通信：实现 initialize、ping、tools/list、tools/call 等 MCP 协议方法，接收请求并返回标准化的 JSON-RPC 响应。
    • 只读访问与查询保护：对 SQL 查询实行严格的只读策略，阻止危险模式（如 FOR UPDATE、递归 CTE 等），并对 WHERE 全表扫描、JOIN 使用、列数等做出保护。
    • 工具集合与数据能力：提供 db_select、db_tables、db_schema、db_indexes、db_explain、db_explain_table、db_processlist、db_variables 等工具，覆盖数据读取、元数据查询、执行计划获取等需求。
    • 安全与审计：内置账户安全检查（read-only 权限、服务器只读模式、缓存机制等），并对查询活动进行日志记录与异常处理。
    • 日志与监控：对 SQL 请求、执行计划、耗时、返回行数等进行日志记录，便于后续审计和性能分析。
    • 服务器部署与扩展性：提供 Docker 运行方案、快速安装脚本，以及通过 Apache/Nginx 等反向代理的部署指南。

  • 安装步骤（简要）

    • 环境准备：确保服务器上有 PHP（含 PDO_MYSQL 及相关扩展）、Web 服务器（如 Apache/Nginx）及 MariaDB/MySQL 服务。仓库 README 提供了快速安装示例。
    • 安装与配置：克隆仓库后，按 README 指引复制环境配置模板 .env，配置数据库连接参数、MCP_TOKEN、日志路径、查询策略等。
    • 启动与运行：可以通过提供的 install.sh 脚本在服务器上搭建并启动，默认通过 HTTP 端口 13306 提供 MCP 服务。也提供 Docker 构建与运行示例，便于快速部署。
    • 健康检查：通过 health 端点（GET /health）检查服务状态；通过 POST /mcp 进行 MCP 请求通信。

  • 服务器配置（面向 MCP 客户端的连接信息，JSON 格式描述，非代码块展示）

    • serverName: "MariaDB-Guard-RO-MCP"
    • command: "docker"（若使用 Docker 部署）
    • args: [ "run", "--rm", "-p", "13306:13306", "-e", "DB_HOST=127.0.0.1", "-e", "DB_PORT=3306", "-e", "DB_NAME=your_database", "-e", "DB_USER=your_mcp_ro_user", "-e", "DB_PASS=your_password", "-e", "MCP_TOKEN=your_token", "mariadb-guard-ro-mcp:latest" ] 注释：以上示例展示了在容器化部署场景下的配置方式，包含数据库连接信息和 MCP 访问鉴权参数。若采用其他部署方式（如直接在服务器上使用 Apache/Nginx），请将 command/args 替换为相应的启动命令组合。

  • 基本使用方法（简明、易操作）

    • 启动与配置
      • 根据 README 指引配置 .env，将 DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASS、MCP_TOKEN 等参数设置正确。
      • 使用 Apache/Nginx 作为反向代理，将入口流量转发到 MCP HTTP 服务，默认暴露在端口 13306。
    • 与 LLM 客户端交互
      • 使用 MCP 客户端（如 LLM 代理或自定义脚本）通过 JSON-RPC 2.0 方式对 /mcp 路径发起请求，执行 initialize、ping、tools/list、tools/call等方法。
      • 使用工具调用时，针对需要执行的 SQL，通过 db_select、db_explain、db_explain_table 等工具完成安全、受控的数据访问与分析。
    • 安全与监控
      • 确保 MCP_TOKEN 设置为强认证令牌；若未设置，系统按无鉴权策略运行（详见 README）。
      • 日志文件路径在 .env 配置中指定，便于审计与排错。
    • 常见操作
      • 健康检查：访问 /health 端点，确认服务状态为 healthy。
      • MCP 流程：发送 initialize、ping、工具列表、具体工具调用等请求，LLM 客户端按 MCP 协议进行会话管理。

  • 说明与注意

    • 该实现包含完整的服务端代码、路由、工具实现、账户安全检查与日志记录，非仅示例或客户端代码。代码结构清晰、功能明确，符合 MCP 服务器实现的核心要素。
    • 部署时请结合实际数据库版本与网络环境配置安全策略，确保仅允许信任来源访问 MCP 端点。

服务器信息

访问项目