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`（Linux 原生：`scripts/linux_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` 不足则 `bash scripts/install_node20.sh` 或 `nvm install 20`。

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

### 本地常用命令

```bash
cd "${NEXUS_ROOT:-~/Nexus}"

python3 scripts/check_mysql.py
python3 scripts/bootstrap_database.py   # 空库建表
python3 scripts/sync_mysql_mcp_env.py --writable
bash scripts/start-dev.sh
bash scripts/local_verify.sh
```

---

## 5. （已废弃）WSL / Windows 主机

开发机已迁移 **Ubuntu 原生**；勿再使用 `wsl` MCP 或 `scripts/wsl_*`。历史说明见 `docs/changelog/2026-06-04-cursor-plugins-linux-mcp.md`。

---

## 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'` | Node 18 过旧；`bash scripts/install_node20.sh` 后 Reload MCP |
| MCP `test_connection` 失败 | 确认 Docker MySQL 已启动：`bash scripts/start-dev.sh` |
| `npx` / `npm ERR! ECONNRESET` | 配置 SOCKS5 代理，见 **§9** |

---

## 9. npm/npx 代理（SOCKS5）

国内或受限网络下，`npx -y @yclenove/mysql-mcp-server` 可能因无法访问 `registry.npmjs.org` 失败。

### 本机代理（当前）

| 项 | 值 |
|----|-----|
| 类型 | SOCKS5 |
| 地址 | `192.168.124.93:10808` |
| URL | `socks5://192.168.124.93:10808` |

### 方式 A — 环境变量（终端 + MCP 脚本自动 source）

写入 [`scripts/npm-proxy.env`](scripts/npm-proxy.env)（已 gitignore，从 `npm-proxy.env.example` 复制）：

```bash
export ALL_PROXY=socks5://192.168.124.93:10808
export HTTP_PROXY=socks5://192.168.124.93:10808
export HTTPS_PROXY=socks5://192.168.124.93:10808
export NO_PROXY=localhost,127.0.0.1,::1
```

[`scripts/linux_mcp_mysql.sh`](scripts/linux_mcp_mysql.sh) 启动时会自动 `source` 该文件。

**注意**：npm/npx **不能**直接识别 `socks5://` 环境变量（会报 `this.connect is not a function`）。  
- **已本地安装** `node_modules/.bin/mysql-mcp-server` 时：无需 npx，MCP 正常启动。  
- **需要 npx 拉包时**：脚本会自动走 `proxychains4`（需 `/etc/proxychains4.conf` 含 `socks5 192.168.124.93 10808`）。

### 方式 B — npm 原生 HTTP 代理

npm 的 `proxy` / `https-proxy` **仅支持 HTTP**。若网关同时提供 HTTP 端口（如 Clash `7890`）：

```bash
npm config set proxy http://192.168.124.93:<HTTP端口>
npm config set https-proxy http://192.168.124.93:<HTTP端口>
```

查看：`npm config get proxy`

### 方式 C — proxychains（SOCKS 最可靠）

```bash
sudo apt install -y proxychains4
# 编辑 /etc/proxychains4.conf：注释掉默认 socks4，添加：
#   socks5 192.168.124.93 10808
proxychains4 -q npx -y @yclenove/mysql-mcp-server
```

### 方式 D — 本地安装，跳过 npx 联网

```bash
cd ~/Nexus
source scripts/npm-proxy.env   # 首次 install 仍需代理
npm install --no-save @yclenove/mysql-mcp-server@latest
```

[`scripts/linux_mcp_mysql.sh`](scripts/linux_mcp_mysql.sh) 应优先执行 `./node_modules/.bin/mysql-mcp-server`，再回退 `npx`。

### 验证清单

- [ ] `npm ping` 返回 pong（非 ECONNRESET）
- [ ] `timeout 3 npx -y @yclenove/mysql-mcp-server` 出现 `[MySQL MCP] Starting...`
- [ ] Cursor Settings → MCP → `mysql-mcp` 绿点