MySQL 查询工具插件

插件简介

MySQL 查询工具 (@timmy_hu/mysql-query-tool) 是一个 XpertAI 平台插件，为智能体提供 MySQL 数据库查询能力。支持执行 SQL 查询、查看数据库列表、查看表列表、查看表结构、获取数据库连接信息等操作。

适用场景

• 智能体需要查询 MySQL 数据库获取业务数据
• 智能体需要了解数据库表结构以辅助分析
• 智能体需要检查数据库连接状态和服务器信息
• 数据分析场景中，智能体通过 SQL 查询获取原始数据

目录结构

mysql-query-tool/
├── .xpertai-plugin/
│   └── plugin.json                          # 插件清单
├── index.js                                 # CommonJS 入口（XpertPlugin 导出）
├── package.json                             # 项目依赖与元信息
├── README.md                                # 本文件
├── SKILL.md                                 # 根目录 Skill 兜底入口
├── src/
│   ├── mysql-query-tool.module.ts           # NestJS 模块
│   ├── middlewares/
│   │   └── mysql-query-tool.middleware.ts   # 中间件策略 Provider
│   ├── schemas/
│   │   └── config.schema.ts                # zod 配置 Schema
│   ├── shared/
│   │   ├── mysql-query-tool.executor.ts    # 共享业务执行器
│   │   └── mysql-query-tool.types.ts       # 共享类型定义
│   ├── tools/
│   │   ├── mysql-execute-query.tool.ts     # 工具：执行 SQL
│   │   ├── mysql-list-databases.tool.ts    # 工具：列出数据库
│   │   ├── mysql-list-tables.tool.ts       # 工具：列出表
│   │   ├── mysql-describe-table.tool.ts    # 工具：查看表结构
│   │   └── mysql-connection-info.tool.ts   # 工具：连接信息
│   └── mcp/
│       └── mysql-query.mcp-server.ts       # MCP Server 声明
├── resources/
│   └── skills/
│       └── mysql-query-tool/
│           ├── SKILL.md                     # 平台可发现 Skill 资源
│           └── skill.json                   # Skill 清单
├── scripts/
│   ├── check-plugin.js                      # 自检脚本
│   ├── run-skill.js                         # Skill 兜底运行脚本
│   ├── invoke-tool.js                       # 本地工具调用脚本
│   └── package-zip.js                       # zip 打包脚本
└── examples/
    ├── request.example.json                 # 调用示例
    └── skill-input.example.json             # Skill 输入示例

安装与导入

通过 npm 安装到 XpertAI 平台

curl -X POST http://10.161.48.53:3300/api/plugin \
  -H "Authorization: Bearer <token>" \
  -H "organization-id: <org-id>" \
  -H "Content-Type: application/json" \
  -d '{"pluginName": "@timmy_hu/mysql-query-tool", "version": "1.0.0", "source": "npm"}'

本地开发

npm install
npm run check   # 运行自检脚本

配置项说明

| 配置项 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | mysqlHost | string | ✅ | __REPLACE_WITH_MYSQL_HOST__ | MySQL 主机地址 | | mysqlPort | number | ❌ | 3306 | MySQL 端口号 | | mysqlUser | string | ✅ | __REPLACE_WITH_MYSQL_USER__ | MySQL 用户名 | | mysqlPassword | string | ✅ | __REPLACE_WITH_MYSQL_PASSWORD__ | MySQL 密码（敏感） | | mysqlDatabase | string | ✅ | __REPLACE_WITH_MYSQL_DATABASE__ | 默认数据库名 | | connectionLimit | number | ❌ | 10 | 连接池最大连接数 | | connectTimeout | number | ❌ | 10000 | 连接超时（毫秒） | | allowDangerousSQL | boolean | ❌ | false | 是否允许危险 SQL |

⚠️ 安全提示：敏感配置（密码等）请使用占位符或环境变量，发布前务必替换为真实值。

Agent Middleware 工具列表

本插件通过 MysqlQueryToolMiddleware 中间件策略注册，createMiddleware() 返回以下工具：

| 工具编码 | 工具名称 | 说明 | |----------|----------|------| | mysql_execute_query | 执行 SQL 查询 | 执行 SQL 语句并返回结果，支持参数化查询 | | mysql_list_databases | 列出数据库 | 列出 MySQL 服务器上所有数据库 | | mysql_list_tables | 列出表 | 列出指定数据库的所有表 | | mysql_describe_table | 查看表结构 | 查看表的字段结构信息 | | mysql_connection_info | 连接信息 | 获取 MySQL 连接和服务器状态 |

Skill 兜底运行说明

当平台无法直接调用 Agent Middleware Tool 时，可通过 Skill 间接运行：

# 使用示例输入
node scripts/run-skill.js examples/skill-input.example.json

# 通过命令行传入 JSON
node scripts/run-skill.js '{"tool":"mysql_list_databases","input":{}}'

# 调用指定工具
node scripts/invoke-tool.js mysql_execute_query '{"sql":"SELECT 1+1 AS result"}'

scripts 目录说明

| 脚本 | 用途 | 命令示例 | |------|------|----------| | check-plugin.js | 自检插件结构和导出 | npm run check | | run-skill.js | Skill 兜底运行 | npm run skill:run | | invoke-tool.js | 本地工具调用 | npm run tool:invoke mysql_list_databases '{}' | | package-zip.js | zip 打包 | npm run package:zip |

入参说明

mysql_execute_query

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sql | string | ✅ | SQL 语句 | | params | string[] | ❌ | 参数化查询占位符参数 |

mysql_list_tables

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | database | string | ❌ | 数据库名，不填则使用默认数据库 |

mysql_describe_table

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | table | string | ✅ | 表名称 | | database | string | ❌ | 数据库名，不填则使用默认数据库 |

返回值说明

所有工具返回 JSON 字符串，结构如下：

成功响应

{
  "success": true,
  "rowCount": 10,
  "columns": ["id", "name", "email"],
  "rows": [{ "id": 1, "name": "Alice", "email": "[email protected]" }],
  "message": "查询执行成功"
}

失败响应

{
  "success": false,
  "error": "错误描述",
  "code": "ER_NO_SUCH_TABLE"
}

调用示例

参见 examples/request.example.json 和 examples/skill-input.example.json。

常见错误和处理方式

| 错误码 | 说明 | 处理方式 | |--------|------|----------| | ECONNREFUSED | 无法连接到 MySQL 服务器 | 检查主机地址和端口是否正确 | | ER_ACCESS_DENIED_ERROR | 用户名或密码错误 | 检查配置中的用户名和密码 | | ER_BAD_DB_ERROR | 数据库不存在 | 检查数据库名是否正确 | | ER_NO_SUCH_TABLE | 表不存在 | 检查表名是否正确 | | SQL 安全拦截 | 危险 SQL 被拦截 | 如需执行，设置 allowDangerousSQL: true |

安全注意事项

1. SQL 注入防护：默认禁止多语句执行，建议使用参数化查询
2. 危险操作拦截：默认拦截 DROP DATABASE、TRUNCATE TABLE 等危险操作
3. 敏感配置：密码等敏感信息请使用占位符或环境变量，不要硬编码
4. 连接池限制：默认连接池大小为 10，可根据需要调整
5. 结果集限制：查询结果默认只返回前 100 行，避免内存溢出

使用方式

1. 在 XpertAI 平台安装本插件
2. 配置 MySQL 连接参数（主机、端口、用户名、密码、数据库名）
3. 在智能体编排中添加 "MySQL 查询工具中间件"
4. 智能体即可通过工具调用查询 MySQL 数据库

下一步

安装完成后，前往 http://10.161.48.53:3300 平台：

1. 在「插件管理」中确认插件已安装
2. 在「智能体编排」中添加中间件「MySQL 查询工具中间件」
3. 配置 MySQL 连接参数
4. 开始使用智能体查询数据库