MySQL查询插件

插件简介

MySQL查询插件是 XpertAI 平台的数据源类插件，通过 MCP Tool 形式暴露 MySQL 数据库查询能力，支持执行 SQL 查询、列出数据库表、查看表结构等常用操作。

适用场景

• 智能体需要查询 MySQL 数据库中的数据
• 数据分析场景中快速获取数据库表结构信息
• 自动化报表生成，从 MySQL 提取数据
• 数据库运维辅助，快速查看表结构和数据概况

目录结构

mysql-query/
├── .xpertai-plugin/
│   └── plugin.json              # 插件清单
├── index.js                     # 插件入口（CommonJS）
├── package.json                 # 项目依赖与元信息
├── README.md                    # 使用说明
├── src/
│   ├── mysql-query.module.ts    # NestJS 插件模块
│   ├── mysql-query.service.ts   # MySQL 查询服务
│   ├── schemas/
│   │   └── config.schema.ts     # zod 配置 Schema
│   └── mcp/
│       ├── mysql-query.mcp-server.ts  # MCP Server 定义
│       └── tools/
│           ├── execute-query.tool.ts  # 执行SQL查询工具
│           ├── list-tables.tool.ts    # 列出表工具
│           └── describe-table.tool.ts # 查看表结构工具
└── examples/
    └── request.example.json     # 调用示例

安装方式

通过 npm 安装到 XpertAI 平台

npm install @xpert-ai-timmy_hu/mysql-query

在 XpertAI 平台导入

在 XpertAI 平台（http://10.161.48.53:3300）的插件管理页面，通过 npm 源安装：

• 包名：@xpert-ai-timmy_hu/mysql-query
• 版本：1.0.0
• 来源：npm

配置项说明

| 配置项 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | host | string | 是 | - | MySQL 主机地址 | | port | number | 否 | 3306 | MySQL 端口号 | | user | string | 是 | - | MySQL 用户名 | | password | string | 是 | - | MySQL 密码 | | database | string | 是 | - | MySQL 数据库名称 | | connectTimeout | number | 否 | 10000 | 连接超时时间（毫秒） | | connectionLimit | number | 否 | 5 | 连接池大小 | | ssl | boolean | 否 | false | 是否启用 SSL 连接 | | queryTimeout | number | 否 | 30000 | 查询超时时间（毫秒） | | allowDangerousSql | boolean | 否 | false | 是否允许执行危险 SQL |

MCP Tool 列表

1. 执行SQL查询 (execute-sql-query)

执行 SQL 查询语句并返回结果集。

入参：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sql | string | 是 | SQL 查询语句 | | params | any[] | 否 | 参数化查询参数 |

出参：

| 字段 | 类型 | 说明 | |------|------|------| | success | boolean | 查询是否成功 | | rows | any[] | 查询结果行 | | rowCount | number | 返回/受影响行数 | | fields | object[] | 字段信息 | | error | string | 错误信息（失败时） |

2. 列出数据库表 (list-tables)

列出当前数据库中的所有表名。

入参： 无

出参：

| 字段 | 类型 | 说明 | |------|------|------| | success | boolean | 操作是否成功 | | tables | string[] | 表名列表 | | count | number | 表的总数 | | error | string | 错误信息（失败时） |

3. 查看表结构 (describe-table)

查看指定表的字段结构信息。

入参：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | tableName | string | 是 | 表名 |

出参：

| 字段 | 类型 | 说明 | |------|------|------| | success | boolean | 操作是否成功 | | tableName | string | 表名 | | columns | object[] | 列信息（Field, Type, Null, Key, Default, Extra） | | error | string | 错误信息（失败时） |

调用示例

{
  "tool": "execute-sql-query",
  "input": {
    "sql": "SELECT * FROM users WHERE status = ? LIMIT 10",
    "params": ["active"]
  }
}

常见错误和处理方式

| 错误 | 原因 | 处理方式 | |------|------|----------| | 连接超时 | 主机地址或端口不正确 | 检查 host 和 port 配置 | | 认证失败 | 用户名或密码错误 | 检查 user 和 password 配置 | | 数据库不存在 | database 名称错误 | 检查 database 配置 | | 危险 SQL 被拒绝 | 执行了 DROP/TRUNCATE 等操作 | 设置 allowDangerousSql 为 true（谨慎使用） | | 查询超时 | SQL 执行时间过长 | 增加 queryTimeout 或优化 SQL |

安全注意事项

1. 密码安全：请勿在代码中硬编码数据库密码，使用平台配置管理功能
2. SQL 注入：始终使用参数化查询（params），避免拼接 SQL
3. 权限控制：建议使用只读账号连接数据库
4. 危险操作：默认禁止 DROP、TRUNCATE 等危险 SQL，如需执行请显式开启 allowDangerousSql
5. 网络隔离：确保 MySQL 服务器仅对 XpertAI 平台开放访问