Files

T

Your Name aa65f10c52 docs: Phase 2 audit records, project memory, WSL guide

Audit docs:
- docs/reports/audit-phase-2{a-j}-line-walk.md: per-file line walk findings
- docs/reports/audit-phase-2-findings-matrix.md: 63 findings (52 fixed, 3 partial, 7 accepted)
- docs/reports/2026-05-23-full-audit-report.md: full audit consolidation
- docs/reports/audit-full-vs-phase2-reconciliation.md: cross-reference
- docs/reports/audit-phase-2-walk-closure.md: closure sign-off

Project docs:
- docs/project/phase-2-audit-remediation.md: SSOT for all fixes
- docs/project/alert-push-policy.md: dashboard alert design decisions
- docs/project/production-verification-checklist.md: first-deploy checklist
- docs/project/script-execution.md: script platform design
- docs/project/wsl-integration-test.md: WSL code-only verification guide
- docs/project/line-walk-audit-standard.md: audit methodology
- docs/project/mysql-mcp-setup.md: MCP config guide

Changelogs: 18 entries (2026-05-22 to 2026-05-23)
Project memory: CLAUDE.md, AGENTS.md updated to reflect current state
Deploy: nginx_https.conf template updated

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-23 15:27:40 +08:00

4.6 KiB

Raw Blame History

MySQL MCP 配置指南

包：yclenove/mysql-mcp-server (@yclenove/mysql-mcp-server)

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

1. 安装（本机一次）

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

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

验证：

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 后，运行同步脚本：

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. 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 启动：

优先 WSL 用户目录 Node 20（~/.local/node-v20.19.2/）— 可连内网 MySQL
回退 Windows Node 22（C:\nvm4w\nodejs\node.exe）— 仅修复语法错误

在 WSL 安装 Node 20

bash scripts/wsl_install_node20.sh

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

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

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

安装后 Reload Cursor MCP。

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

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 常用命令

cd /mnt/c/Users/uzuma/Desktop/svn/Nexus/.claude/worktrees/suspicious-williams-fe9492

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

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

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

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

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

5. 在 Cursor 中启用

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

验收清单可参考上游 MCP_CURSOR_TEST.md。

6. 安全约定

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

7. 故障排查

现象	处理
连到 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 变更；确认服务运行后再测

4.6 KiB Raw Blame History Unescape Escape