Servidor de Consultas MySQL

MySQL 查询服务器

这是一个基于 MCP（Model-Controller-Provider）框架的 MySQL 查询服务器，通过 SSE（Server-Sent Events）提供 MySQL 数据库操作功能。

功能特性

• 使用 FastMCP 框架构建
• 支持通过 SSE（Server-Sent Events）实时传输数据
• 提供 MySQL 数据库查询接口
• 完整的日志记录系统
• 自动事务管理（commit/rollback）
• 支持通过环境变量进行配置
• SQL 安全机制
  • 风险等级控制
  • SQL 注入防护
  • 拦截危险操作
  • 强制检查 WHERE 子句
  • 自动返回受影响的行数
• 敏感信息保护机制
• 自动格式化和增强元数据查询结果

API 功能

系统提供四大类工具：

基本查询工具

• mysql_query：执行任意 SQL 查询，支持参数化查询

元数据查询工具

• mysql_show_tables：获取数据库表列表，支持模式匹配和结果限制
• mysql_show_columns：获取表的列信息
• mysql_describe_table：描述表结构
• mysql_show_create_table：获取创建表的语句

数据库信息查询工具

• mysql_show_databases：获取所有数据库列表，支持筛除系统数据库
• mysql_show_variables：获取 MySQL 服务器变量
• mysql_show_status：获取 MySQL 服务器状态信息

高级表结构查询工具

• mysql_show_indexes：获取表索引信息
• mysql_show_table_status：获取表状态信息
• mysql_show_foreign_keys：获取表外键信息
• mysql_paginate_results：提供结果分页功能

系统要求

• Python 3.6+
• MySQL 服务器
• 依赖项：
  • mysql-connector-python
  • python-dotenv
  • mcp（FastMCP 框架）

安装步骤

1. 将项目克隆到本地：

git clone [URL do projeto]
cd mysql-query-server

2. 安装依赖项：

pip install -r requirements.txt

3. 配置环境变量：
   • 复制 .env.example 文件并将其重命名为 .env
   • 根据需要修改 .env 文件中的配置

环境变量配置

在 .env 文件中配置以下参数：

基本配置

• HOST：服务器监听地址（默认：127.0.0.1）
• PORT：服务器监听端口（默认：3000）
• MYSQL_HOST：MySQL 服务器地址
• MYSQL_PORT：MySQL 服务器端口
• MYSQL_USER：MySQL 用户名
• MYSQL_PASSWORD：MySQL 密码
• MYSQL_DATABASE：MySQL 数据库名称

SQL 安全配置

• ENV_TYPE：环境类型（development/production）
• ALLOWED_RISK_LEVELS：允许的风险等级（LOW/MEDIUM/HIGH/CRITICAL）
• BLOCKED_PATTERNS：被阻止的 SQL 模式（正则表达式，以逗号分隔）
• ENABLE_QUERY_CHECK：启用 SQL 安全检查（true/false）
• ALLOW_SENSITIVE_INFO：允许查询敏感信息（true/false）
• SENSITIVE_INFO_FIELDS：自定义敏感字段模式列表（以逗号分隔）

安全机制详情

风险等级控制

• LOW：查询操作（SELECT）和元数据操作（SHOW、DESCRIBE 等）
• MEDIUM：基本数据修改（INSERT、带 WHERE 的 UPDATE/DELETE）
• HIGH：结构变更（CREATE/ALTER）和不带 WHERE 的 UPDATE
• CRITICAL：危险操作（DROP/TRUNCATE）和不带 WHERE 的 DELETE

环境差异

• 开发环境：
  • 允许风险较高的操作
  • 不会隐藏敏感信息
  • 提供详细的错误消息
• 生产环境：
  • 默认仅允许风险等级为 LOW 的操作
  • 严格限制数据修改
  • 自动隐藏敏感信息
  • 错误消息不会暴露实现细节

敏感信息保护

系统会自动检测并隐藏包含以下关键词的状态变量／值：

• password、auth、credential、key、secret、private
• ssl、tls、cipher、certificate
• host、path、directory 及其他系统路径信息

事务管理

• 对修改操作（INSERT/UPDATE/DELETE）自动提交事务
• 出错时自动回滚事务
• 返回操作影响的行数

启动服务

运行以下命令以启动服务：

python src/server.py

服务将在配置的地址和端口上启动，默认为 http://127.0.0.1:3000/sse

项目结构

.
├── src/                     # Diretório de código-fonte
│   ├── server.py           # Arquivo principal do servidor
│   ├── db/                 # Código relacionado ao banco de dados
│   │   └── mysql_operations.py # Implementação de operações MySQL
│   ├── security/           # Código relacionado à segurança SQL
│   │   ├── interceptor.py   # Interceptor SQL
│   │   ├── query_limiter.py # Verificador de segurança SQL
│   │   └── sql_analyzer.py  # Analisador SQL
│   └── tools/              # Código de ferramentas
│       ├── mysql_tool.py           # Ferramentas de consulta básica
│       ├── mysql_metadata_tool.py  # Ferramentas de consulta de metadados
│       ├── mysql_info_tool.py      # Ferramentas de consulta de informações do banco de dados
│       ├── mysql_schema_tool.py    # Ferramentas de consulta avançada de estrutura de tabela
│       └── metadata_base_tool.py   # Classe base para ferramentas de metadados
├── tests/                  # Diretório de código de testes
├── .env.example            # Arquivo de exemplo de variáveis de ambiente
└── requirements.txt        # Arquivo de dependências do projeto

常见问题排查

DELETE 操作未能成功执行

• 检查 DELETE 操作是否包含 WHERE 子句
• 不包含 WHERE 的 DELETE 操作会被标记为 CRITICAL 风险等级
• 确保 ALLOWED_RISK_LEVELS 中包含 CRITICAL（如需执行该操作）
• 检查返回的受影响行数，以确认操作是否确实影响了数据库

环境变量未生效

• 确保 server.py 中的 load_dotenv() 调用发生在导入其他模块之前
• 重启应用，以确保正确加载环境变量
• 检查日志输出“已从环境变量读取风险等级设置”

操作被安全机制拒绝

• 检查操作的风险等级是否在允许范围内
• 如需执行高风险操作，请相应调整 ALLOWED_RISK_LEVELS
• 对于不包含 WHERE 的 UPDATE 或 DELETE，请添加条件（即使是 WHERE 1=1），以降低风险等级

无法查看敏感信息

• 在开发环境中，设置 ALLOW_SENSITIVE_INFO=true
• 在生产环境中，敏感信息默认会被隐藏，这是安全特性

日志系统

服务包含完整的日志记录系统，你可以在控制台和日志文件中查看运行状态和错误消息。日志级别可在 server.py 中配置。

错误处理

服务包含完整的错误处理机制：

• 检查 MySQL 连接器是否导入成功
• 验证数据库配置
• 检查 SQL 安全性
• 捕获并记录运行时错误
• 自动回滚事务

测试客户端

项目包含一个测试客户端（test_client.py），演示如何连接到服务并执行 MySQL 查询。近期改进包括：

• 改进 SSE 会话处理：

  • 双重检查会话 ping
  • 等待服务完全初始化
  • 提供更稳健的错误处理
  • 改进 SSE 事件日志记录

• 改进查询发送：

  • 在查询之间留出适当间隔
  • 发送查询前检查会话状态
  • 提供更稳健的 SSE 响应处理
  • 调整超时时间，以接收所有响应

贡献指南

欢迎提交 Issues 和 Pull Requests，以改进项目。

Licença

MIT License

Copyright (c) 2024 MCP MySQL Query Server

特此免费授予任何获得本软件副本和相关文档文件（"软件"）的人不受限制地处理本软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本，以及允许本软件的使用者这样做，但须符合以下条件： 上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。

本软件按"原样"提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，产生于、源于或与本软件有关，或与本软件的使用或其他交易有关。