MariaDB-Guard-RO-MCP

关键词

数据库保护只读查询JSON-RPCPHP 服务生产环境诊断

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，使用 PHP 提供对数据库的只读访问、工具执行以及提示渲染能力，面向将来与 LLM 客户端进行交互，提供安全、可扩展的上下文服务框架。

  • 主要功能点

    • JSON-RPC 服务器：实现 MCP 规范的请求/响应流程，支持 initialize、ping、tools/list、tools/call 等基础方法。
    • 资源与工具管理：定义并暴露工具集合，允许 LLM 客户端调用数据库查询、Explain、以及其他工具。
    • Prompts 与渲染：提供统一的输出结构，包含结构化内容、SQL 格式化输出以及 Explain 结果等。
    • 安全模型与账户检查：包含账号只读性检查、缓存机制、以及对环境变量的基础保护，确保生产环境的安全性。
    • 日志与监控：对 MCP SQL 请求、执行时间、结果行数及执行计划进行日志记录，便于審计与优化。
    • 会话与权限管理：通过 MCP_TOKEN 进行请求鉴权，支持 Inspector（信道/流式 HTTP 等）等传输的扩展能力。
    • 多环境部署支持：提供 Quick Start、Docker、以及 Apache/Nginx 方案等多种部署方式；包含健康检查接口。

  • 安装步骤

      1. 准备运行环境：安装 PHP 及一个 Web 服务器（如 Apache/Nginx+PHP-FPM）。
      1. 获取代码：git clone https://github.com/PmaControl/MariaDB-Guard-RO-MCP.git
      1. 配置环境变量：复制模板并编辑 .env（如 DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASS、MCP_TOKEN、MAX_ROWS_DEFAULT、MAX_ROWS_HARD、MAX_SELECT_TIME_S、WHERE_FULLSCAN_MAX_ROWS、MCP_QUERY_LOG 等）。
      1. 启动服务：可按 README 说明使用 install.sh 进行快速部署，或在 Apache/Nginx 下配置虚拟主机（默认监听 13306 端口，/mcp 路径处理 MCP 请求）。
      1. 健康检查：curl -sS http://127.0.0.1:13306/health，确认服务健康。
      1. MCP 客户端使用：对 MCP 的 /mcp 接口进行 JSON-RPC 调用，例如 initialize、ping、tools/list、tools/call 等。

  • 服务器配置（给 MCP 客户端的启动信息，实际连接端口与参数由客户端配置决定） 备注：以下 JSON 描述用于 MCP 客户端了解如何启动/连接 MCP 服务器。注意这不是代码块，便于直接阅读。

    { "serverName": "MariaDB-Guard-RO-MCP", "endpoint": "http://127.0.0.1:13306/mcp", "startCommand": "docker run --rm -p 13306:13306 -e DB_HOST=127.0.0.1 -e DB_PORT=3306 -e DB_NAME=my_database -e DB_USER=my_user_mcp_ro -e DB_PASS=my_password -e MCP_TOKEN=my_token mariadb-guard-ro-mcp:local", "args": [ "--install-dir", "/srv/www/mcp-mariadb", "--http-port", "13306", "--db-host", "127.0.0.1", "--db-port", "3306", "--db-name", "my_database", "--db-user", "my_user_mcp_ro", "--db-pass", "my_password", "--mcp-token", "my_token" ], "notes": "以上 startCommand/args 仅供参考，实际部署可通过 README 的 Docker 或 Apache 配置方式实现。MCP 客户端只需要知道 endpoint、认证令牌（若配置了 MCP_TOKEN）以及必要的请求参数即可。" }

  • 基本使用方法

      1. 通过 health 接口验证服务是否可用。
      1. 使用 initialize 获取协议信息与能力清单；使用工具（tools/list）获取可用工具；使用 tools/call 调用具体工具（如 db_select、db_explain_table 等）。
      1. 对需要的 SQL 查询，遵循只读策略：配合 SqlGuard 的限制，避免危险查询、长时间查询和全表扫描等风险。
      1. 在生产环境中，建议将 MCP 部署在只读副本或只读账户上，并通过 HTTPS 进行对外访问。

服务器信息

访问项目