Nexus/docs/project/mysql-mcp-setup.md

# MySQL MCP 配置指南

> 包：[yclenove/mysql-mcp-server](https://github.com/yclenove/mysql-mcp-server) (`@yclenove/mysql-mcp-server`)

供 Cursor Agent 通过 MCP 安全查询 Nexus MySQL（schema、EXPLAIN、只读 SELECT）。

---

## 1. 安装（本机一次）

```bash
npm install -g @yclenove/mysql-mcp-server@latest
```

或使用项目已配置的 `npx`（无需全局安装，见 `.cursor/mcp.json`）。

验证：

```bash
npx -y @yclenove/mysql-mcp-server
# 应看到 [MySQL MCP] Starting...（Ctrl+C 退出）
```

---

## 2. 项目 MCP 配置

已提交：`.cursor/mcp.json`（经 WSL 调用 `scripts/wsl_mcp_mysql.sh`）

**不要在 `mcp.json` 的 `env` 里写密码**；连接信息写在项目根 `.env`。

---

## 3. 数据库连接（`.env`）

### 方式 A：安装向导 / 已有 `.env`

复制示例并填写 `NEXUS_DATABASE_URL` 后，运行同步脚本：

```bash
copy .env.example .env
# 编辑 NEXUS_DATABASE_URL 为真实连接
python scripts/sync_mysql_mcp_env.py
```

脚本会根据 `NEXUS_DATABASE_URL` 写入：

| 变量 | 说明 |
|------|------|
| `MYSQL_HOST` / `MYSQL_PORT` | 从 URL 解析 |
| `MYSQL_USER` / `MYSQL_PASSWORD` | 从 URL 解析 |
| `MYSQL_DATABASE` | 库名（通常为 `nexus`） |
| `MYSQL_READONLY` | 生产 `true`；本地开发 `false`（`--writable`） |
| `MYSQL_DATABASE_ALLOWLIST` | 仅允许该库 |

### 方式 B：手动

在 `.env` 末尾添加与 `NEXUS_DATABASE_URL` 一致的 `MYSQL_*` 变量（见 `.env.example` 注释块）。

---

## 4. Linux 原生开发（Ubuntu / ~/Nexus）

```bash
cd ~/Nexus
python3 scripts/sync_mysql_mcp_env.py --writable
chmod +x scripts/linux_mcp_mysql.sh
```

`.cursor/mcp.json` 应使用 `bash` + `scripts/linux_mcp_mysql.sh`（**不要**再用 `wsl` + Windows 路径）。

需要 **Node.js 20+**：`node -v` 不足则 `nvm install 20` 或 `fnm use 20`。

Reload Cursor MCP 后让 Agent 调用 `test_connection`。

---

## 5. WSL 开发环境（Windows 主机 + WSL）

MySQL 在 `172.31.x` 内网时，**从 WSL 可连、从 Windows 可能不可达**。项目已按 WSL 配置：

### `.cursor/mcp.json`（经 WSL 启动，需 Node 20+）

`mysql-mcp-server` 使用 `import ... with { type: 'json' }`，**WSL 自带 Node 18 会报 `SyntaxError: Unexpected token 'with'`**。

当前通过 `scripts/wsl_mcp_mysql.sh` 启动：
1. 优先 WSL 用户目录 Node 20（`~/.local/node-v20.19.2/`）— 可连内网 MySQL
2. 回退 Windows Node 22（`C:\nvm4w\nodejs\node.exe`）— 仅修复语法错误

**在 WSL 安装 Node 20**

```bash
bash scripts/wsl_install_node20.sh
```

若 WSL 报 `Could not resolve host: export` 或 DNS 失败：

```powershell
# Windows PowerShell（项目根）
pwsh scripts/cache-node20-windows.ps1
```

```bash
# 再从 WSL 解压安装
bash scripts/wsl_install_node20.sh
```

安装后 Reload Cursor MCP。

### 本地开发：MCP 可写 + MySQL 最大权限

```bash
python3 scripts/sync_mysql_mcp_env.py --writable   # MYSQL_READONLY=false
mysql -h 172.31.170.47 -u root -p < scripts/grant_nexus_local.sql
```

仅用于本地库；生产环境保持 `MYSQL_READONLY=true`。

### WSL 常用命令

```bash
cd "${NEXUS_ROOT:-$HOME/Nexus}"   # 或你的 WSL 挂载路径

# 检查连接与表
python3 scripts/wsl_check_mysql.py

# 库存在但无表时初始化（16 张表）
python3 scripts/bootstrap_database.py

# 同步 MCP 变量（本地可写）
python3 scripts/sync_mysql_mcp_env.py --writable
```

WSL 内安装 MCP（可选，加速启动）：

```bash
npm install -g @yclenove/mysql-mcp-server@latest
```

---

## 6. 在 Cursor 中启用

1. 用 **本仓库根目录** 作为工作区打开（使 MCP 进程 `cwd` 能加载 `.env`）
2. **Settings → MCP** → 启用 `mysql-mcp`（绿点）
3. 若无显示：**Developer: Reload Window**
4. 测试：让 Agent 调用 `test_connection` 或 `list_tables`

验收清单可参考上游 [MCP_CURSOR_TEST.md](https://github.com/yclenove/mysql-mcp-server/blob/main/MCP_CURSOR_TEST.md)。

---

## 7. 安全约定

- 生产库：**必须** `MYSQL_READONLY=true`
- 使用 `MYSQL_DATABASE_ALLOWLIST` 限制库名
- `.env` 已在 `.gitignore`，勿提交
- Agent 查库优先 `query` / `describe_table` / `explain_query`，禁止破坏性 DDL

---

## 8. 故障排查

| 现象 | 处理 |
|------|------|
| 连到 127.0.0.1 但库不对 | 运行 `python scripts/sync_mysql_mcp_env.py` 与 `NEXUS_DATABASE_URL` 对齐 |
| MCP 未出现 | Reload Window；确认 Node/npx 在 PATH |
| `.env` 不存在 | 先 `copy .env.example .env` 或完成 install.html |
| v1.4.2+ 环境被覆盖 | 项目根 `.env` 中 `MYSQL_*` 优先于系统环境变量 |
| `SyntaxError: Unexpected token 'with'` | WSL Node 18 过旧；执行 `bash scripts/wsl_install_node20.sh` 后 Reload MCP |
| MCP 能启动但 `test_connection` 失败 | 当前走 Windows Node 回退，连不上 `172.31.x`；必须在 WSL 装好 Node 20 |
| `curl: Could not resolve host: export` | WSL 代理变量损坏；脚本已 `unset` + `--noproxy`；或用 `cache-node20-windows.ps1` |
| `ECONNREFUSED 172.31.170.47:3306` | MySQL 未启动或 IP 变更；确认服务运行后再测 |