.codex/skills/mcp-mysql-and-sql-validation/SKILL.md

---
name: mcp-mysql-and-sql-validation
description: MCP MySQL 使用规范与统计 SQL 验证流程；接口测试后必须查库验证；用户问业务数据时自动查库。在使用 MCP 查库、写统计 SQL 或提交含 SQL 的代码时使用。
---
# MCP MySQL 与 SQL 验证
## 一、Skills 定位说明（必读）
本 Skills 用于**约束 AI 在涉及真实业务数据时的行为**，核心目标：
- 让 AI **必须通过 MCP 查询真实数据库**
- 让接口测试 **必须验证数据库结果**
- 让统计 / 报表 **必须跑真实 SQL**
- 让用户直接问“数据是多少”时，AI **自动查库而不是反问**
> 本 Skills 属于：**执行型 + 验证型 + 数据治理型 Skills**  
> 目标：**杜绝 AI 编数据、假验证、只写 SQL 不执行的问题**
---
## 二、何时必须使用本 Skills（触发规则）
只要满足以下任一条件，**AI 必须使用 MCP 数据库工具**。
### 1️⃣ 接口测试场景（新增 / 编辑 / 删除 / 状态变更）
当 AI 执行或协助以下接口相关操作时：
- 新增数据（Create / Add）
- 编辑数据（Update / Edit）
- 删除数据（Delete / Remove / 作废）
- 状态变更（启用 / 禁用 / 完成 / 关闭）
#### 强制规则
- ✅ 接口执行完成后，**必须使用 MCP 查询数据库**
- ✅ 验证数据是否真实新增 / 修改 / 删除
- ❌ 禁止只根据接口返回值判断成功
- ❌ 禁止假设数据库已发生变化
> ✔ 正确行为：“接口返回成功 → MCP 查询表 → 对比数据变化”
---
### 2️⃣ 统计 / 报表 / 看板 / 聚合接口
包括但不限于：
- 数量统计（会员数、订单数、开单数）
- 金额统计（开单金额、支付金额、退款金额）
- 汇总指标（合计、平均值、最大值）
- 环比 / 同比 / 增长率
#### 强制规则
- ✅ 编写统计 SQL 后，**必须通过 MCP 执行**
- ✅ 用真实数据验证结果合理性
- ❌ 禁止“只写 SQL，不执行”
- ❌ 禁止凭经验推断结果
---
### 3️⃣ 用户直接询问业务数据（自动触发）
当用户提问符合以下特征时，AI **必须自动查库**：
#### 触发特征
- 包含：`多少 / 数量 / 金额 / 总数 / 合计`
- 包含明确时间范围：年（如 2026 年）、月（如本月 / 2026-01）、日（如今天 / 昨天）
- 涉及业务实体：会员 / 订单 / 开单 / 门店 / 员工 / 消耗
#### 示例问题
- 2026 年新增会员数量是多少？
- 2026 年开单金额是多少？
- 本月退款总额有多少？
- 今天新增订单数是多少？
#### 强制规则
- ✅ 自动识别为【数据查询问题】
- ✅ 直接使用 MCP 查询数据库
- ❌ 禁止回复“需要查询数据库”
- ❌ 禁止编造、估算或假设数据
---
## 三、MCP MySQL 使用规范
### 1️⃣ 允许的操作范围
- ✅ **只允许**：`SELECT`
- ❌ **禁止**：`INSERT / UPDATE / DELETE / TRUNCATE`
---
### 2️⃣ 表结构查询规范
如需查看表结构，统一使用以下 SQL（将 `<表名>` 替换为实际表名）：
```sql
SELECT COLUMN_NAME,
       DATA_TYPE,
       IS_NULLABLE,
       COLUMN_KEY,
       COLUMN_DEFAULT,
       EXTRA,
       COLUMN_COMMENT
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_NAME = '<表名>';
```
**注意事项**：
- 查询表结构时**不要加 ORDER BY**
- **每次查询只针对一个表**
- 避免一次性发送多条 SQL
---
## 四、SQL 查询验证规范（统计类）
对统计类型的 SQL（报表、看板、统计接口），在提交代码前**必须先**用 MCP MySQL 工具执行验证。
### 验证要求
- [ ] SQL 语法正确，能执行通过
- [ ] 涉及的表、字段存在且类型匹配
- [ ] JOIN 关系正确
- [ ] 统计逻辑与需求一致
- [ ] 用实际数据跑一遍，结果合理
### 原则
只有验证通过的 SQL 才能提交到代码中。
---
## 五、如何通过 MCP 执行 SQL（配置与调用）
### 1️⃣ 配置文件位置
- **路径**：项目根目录下 `.cursor/mcp.json`
- **数据库 MCP 服务名**：`my-sql-db`
### 2️⃣ 当前数据库 MCP 配置说明
本项目中 MySQL MCP 使用 `@davewind/mysql-mcp-server`，连接库为 `lqerp_dev`。配置示例（仅作参考，以实际 `.cursor/mcp.json` 为准）：
```json
"my-sql-db": {
  "command": "npx",
  "args": ["--yes", "@davewind/mysql-mcp-server", "mysql://用户:密码@主机:3306/lqerp_dev"]
}
```
### 3️⃣ 执行 SQL 的方式
- **工具名称**：MCP 提供的 **query** 工具（在 Cursor 中可能显示为 `query` 或带服务前缀，如与 `my-sql-db` 相关）。
- **参数**：传入 **sql**（string），即要执行的 SQL 语句。
- **限制**：该 MCP 仅支持 **只读**，仅可执行 **SELECT**；所有语句在 READ ONLY 事务中执行，禁止 INSERT/UPDATE/DELETE/DDL。
**调用要点**：
1. 在需要查库、验证接口结果或跑统计 SQL 时，直接调用该 MCP 的 query 工具。
2. 传入的 `sql` 必须是合法的 SELECT 语句，一次一条。
3. 用返回结果做数据验证或统计核对。
### 4️⃣ 简单验证示例
- 验证 MCP 连通、可执行 SQL 的示例（在 `lqerp_dev` 下查表数量）：
```sql
SELECT COUNT(*) AS table_count
FROM information_schema.tables
WHERE table_schema = 'lqerp_dev';
```
- 查询某表结构（将 `<表名>` 换为实际表名）：
```sql
SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_COMMENT
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'lqerp_dev' AND TABLE_NAME = '<表名>';
```
### 5️⃣ 小结
| 项目       | 说明 |
|------------|------|
| 配置       | `.cursor/mcp.json`，服务名 `my-sql-db` |
| 执行方式   | 调用 MCP 的 **query** 工具，参数 **sql** |
| 允许操作   | 仅 SELECT |
| 数据库     | `lqerp_dev` |