# mysqlDbMcp

生产级 **MySQL MCP** 服务：多数据源 YAML 配置，同时支持 **MCP CLI（stdio）** 与 **MCP HTTP（Streamable HTTP）**，默认全局只读，兼容 MySQL 5.7 / 8.0。

仓库：https://github.com/ErrSilent/mysqlDbMcp

## 能力一览

| 类别 | 内容 |
| --- | --- |
| 元数据 | 库 / 表 / 字段 / 索引 / 主键 / 外键 |
| 查询 | 只读 SQL、`EXPLAIN`（可选 JSON） |
| 安全 | 默认只读、危险 SQL 拦截、行数与超时、库表白名单、审计日志、参数化查询；写入需显式开关 |
| 连接 | 每数据源独立连接池、请求会话隔离、运行时按 `datasource` 切换 |
| 协议 | Tools + Resources + Prompts；stdio / HTTP |
| 可选模块 | 慢 SQL、健康巡检、测试数据生成、向量检索（YAML 开关，默认关闭） |

## 快速开始（Linux / macOS）

```bash
./scripts/install.sh
cp config/config.example.yaml config/config.yaml
# 编辑 config/config.yaml 中的 datasources / security
./scripts/start-stdio.sh          # MCP CLI
# 或
./scripts/start-http.sh           # MCP HTTP → http://127.0.0.1:3100/mcp
```

## 快速开始（Windows）

```bat
scripts\install.bat
copy config\config.example.yaml config\config.yaml
scripts\start-stdio.bat
scripts\start-http.bat
```

手动启动：

```bash
npm ci && npm run build
node dist/index.js --mode stdio --config ./config/config.yaml
node dist/index.js --mode http  --config ./config/config.yaml
```

## 配置说明

所有业务参数来自外部 YAML，**禁止依赖代码内硬编码**。模板见 [`config/config.example.yaml`](config/config.example.yaml)。

要点：

- `datasources[]`：多 MySQL 源；第一项为默认源。
- `security.readonly: true`（默认）+ `allow_write: false`：彻底关闭写能力；`run_write` 不会注册。
- 打开写入必须同时满足：`readonly: false`、`allow_write: true`、目标源 `force_readonly: false`。即使用写打开，`DROP/ALTER/TRUNCATE/CREATE/...` 仍被拦截。
- `max_rows` / `query_timeout_ms`：结果截断与超时（5.7 用应用层超时；8.0 额外尝试 `max_execution_time`）。
- `whitelist.databases` / `tables`：库表白名单（`*` 表示不限制名称，但仍受账号权限约束）。
- `security.audit`：JSONL 全量操作审计。
- `modules.*.enabled`：可选模块开关。

## MCP Tools

| Tool | 说明 |
| --- | --- |
| `list_datasources` | 列出数据源 |
| `list_databases` | 库列表（白名单过滤） |
| `list_tables` | 表列表 |
| `describe_table` | 字段 |
| `list_indexes` | 索引 |
| `list_primary_keys` | 主键 |
| `list_foreign_keys` | 外键 |
| `run_query` | 只读 SQL（支持 `params`） |
| `explain_query` | 执行计划 |
| `run_write` | 仅当写入开关打开时注册 |

Resources：`mysql://datasources`、`mysql://{ds}/databases`、`mysql://{ds}/{db}/tables`、`mysql://{ds}/{db}/{table}/schema`  

Prompts：`analyze_schema`、`optimize_query`、`draft_readonly_sql`

## 调用示例

- Stdio / 客户端配置：[`examples/mcp-cli-call.md`](examples/mcp-cli-call.md)
- HTTP / curl：[`examples/mcp-http-call.md`](examples/mcp-http-call.md)

## 生产安全清单

1. 生产账号只授予 `SELECT`（及必要的 `SHOW VIEW` / `PROCESS` 等），不要用高权限账号。
2. 保持 `readonly: true`、`allow_write: false`、各源 `force_readonly: true`。
3. 收紧 `whitelist`，避免 `*`。
4. 设置合理的 `max_rows` 与 `query_timeout_ms`。
5. 开启审计并轮转 `logs/audit.jsonl`。
6. HTTP 模式务必配置 `server.http.auth_token`，并在反向代理终止 TLS。
7. 客户端优先使用 `params` 参数化，避免拼接 SQL。
8. 错误以结构化 JSON 返回：`{ "code", "message", "details?" }`。

## 开发与验证

```bash
npm run typecheck
npm run seed          # 需要本地 MySQL（默认 mcp/mcp @ mcp_demo）
npm run e2e           # stdio 端到端（含危险 SQL 拒绝）
```

Cursor Cloud Agent 环境见 [`.cursor/`](.cursor/)（MySQL 8 + Node 22，启动时初始化演示库）。

## 许可证

以仓库声明为准。