Nexus Deploy
811eb97fbf
Rename WSL helpers to Linux-native scripts, expose Redis in docker-compose, prefer .venv tools in pre_deploy_check, and record 2026-06-04 audit waves.
194 lines
5.9 KiB
Markdown
194 lines
5.9 KiB
Markdown
# 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` 绿点
|