soul-yongping/开发文档/8、部署/MCP-MySQL配置说明.md

MCP MySQL 配置说明

日期: 2026-02-04
目的: 通过 MCP (Model Context Protocol) 在 Cursor 中直接操作 Soul 小程序数据库

---

✅ 已配置的 MCP 服务

1. Soul-MySQL（新增）

用途: Soul 小程序生产数据库操作

配置文件: C:\Users\29195\.cursor\mcp.json

{
  "Soul-MySQL": {
    "command": "npx",
    "args": [
      "-y",
      "@f4ww4z/mcp-mysql-server",
      "--host",
      "56b4c23f6853c.gz.cdb.myqcloud.com",
      "--port",
      "14413",
      "--user",
      "cdb_outerroot",
      "--password",
      "Zhiqun1984",
      "--database",
      "soul_miniprogram"
    ],
    "env": {}
  }
}

数据库信息:

• 主机: 56b4c23f6853c.gz.cdb.myqcloud.com（腾讯云 CDB）
• 端口: 14413
• 用户: cdb_outerroot
• 密码: Zhiqun1984
• 数据库: soul_miniprogram

---

🔧 使用方法

1. 重启 Cursor

配置文件修改后，需要完全重启 Cursor 才能生效：

1. 关闭所有 Cursor 窗口
2. 重新打开 Cursor
3. 等待 MCP 服务启动

2. 验证连接

在 Cursor 中输入：

@Soul-MySQL 列出所有表

或使用工具调用：

// 查询所有表
user-MySQL-list_tables

// 查看表结构
user-MySQL-describe_table
{
  "table": "orders"
}

// 执行查询
user-MySQL-query
{
  "sql": "SELECT * FROM orders LIMIT 10"
}

---

📊 可用的操作

1. 查询数据（只读）

-- 查看最近订单
SELECT * FROM orders 
ORDER BY created_at DESC 
LIMIT 10;

-- 统计订单状态
SELECT status, COUNT(*) as count, SUM(amount) as total
FROM orders 
GROUP BY status;

-- 查看用户购买情况
SELECT 
  u.id, 
  u.nickname, 
  u.has_full_book,
  COUNT(o.id) as order_count,
  SUM(o.amount) as total_spent
FROM users u
LEFT JOIN orders o ON u.id = o.user_id AND o.status = 'paid'
GROUP BY u.id, u.nickname, u.has_full_book
ORDER BY total_spent DESC
LIMIT 20;

2. 修改数据（慎重！）

-- 修复订单表 status 字段（关键修复）
ALTER TABLE orders 
MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') 
DEFAULT 'created';

-- 手动解锁用户章节
UPDATE users 
SET purchased_sections = JSON_ARRAY_APPEND(
  COALESCE(purchased_sections, '[]'), '$', '1-1'
)
WHERE id = 'user_xxx';

-- 手动补记订单
INSERT INTO orders (
  id, order_sn, user_id, open_id,
  product_type, product_id, amount, description,
  status, transaction_id, pay_time, created_at, updated_at
) VALUES (
  'MP20260204123456789012', 'MP20260204123456789012',
  'user_xxx', 'oXXXX...', 'section', '1-1', 9.9,
  '章节1-1购买', 'paid', 'wx_transaction_id',
  NOW(), NOW(), NOW()
);

3. 查看表结构

-- 查看表结构
DESCRIBE orders;
DESCRIBE users;
DESCRIBE referral_bindings;

-- 查看索引
SHOW INDEX FROM orders;

-- 查看表创建语句
SHOW CREATE TABLE orders;

---

⚠️ 重要提醒

1. 生产数据库操作

• ⚠️ 这是生产数据库，所有操作都会直接影响线上服务
• ✅ 查询操作（SELECT）相对安全
• ❌ 修改操作（UPDATE/DELETE/ALTER）必须谨慎
• 💡 建议先在本地数据库测试

2. 数据备份

修改重要数据前，建议先备份：

-- 备份整个表
CREATE TABLE orders_backup AS SELECT * FROM orders;

-- 备份特定数据
CREATE TABLE orders_backup_20260204 AS 
SELECT * FROM orders WHERE DATE(created_at) = '2026-02-04';

3. 事务操作

对于关联性强的修改，使用事务：

START TRANSACTION;

-- 修改操作1
UPDATE users SET has_full_book = TRUE WHERE id = 'user_xxx';

-- 修改操作2
INSERT INTO orders (...) VALUES (...);

-- 确认无误后提交
COMMIT;

-- 或者出错时回滚
-- ROLLBACK;

---

🎯 常见操作场景

场景1: 修复订单表状态字段

-- 1. 先查看当前定义
SHOW CREATE TABLE orders;

-- 2. 修改 ENUM 定义
ALTER TABLE orders 
MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') 
DEFAULT 'created';

-- 3. 验证修改
DESCRIBE orders;

场景2: 查询用户支付问题

-- 查询特定用户的订单记录
SELECT * FROM orders 
WHERE user_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg'
ORDER BY created_at DESC;

-- 查询用户购买记录
SELECT 
  id, nickname, has_full_book, purchased_sections,
  pending_earnings, earnings
FROM users 
WHERE id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg';

-- 查询用户推荐关系
SELECT * FROM referral_bindings
WHERE referee_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg'
   OR referrer_id = 'ogpTW5a9exdEmEwqZsYywvgSpSQg';

场景3: 统计数据分析

-- 今日订单统计
SELECT 
  COUNT(*) as total_orders,
  SUM(CASE WHEN status = 'paid' THEN 1 ELSE 0 END) as paid_orders,
  SUM(CASE WHEN status = 'paid' THEN amount ELSE 0 END) as total_revenue
FROM orders 
WHERE DATE(created_at) = CURDATE();

-- 用户活跃度统计
SELECT 
  DATE(created_at) as date,
  COUNT(DISTINCT user_id) as active_users,
  COUNT(*) as total_orders,
  SUM(amount) as revenue
FROM orders 
WHERE status = 'paid'
  AND created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(created_at)
ORDER BY date DESC;

-- 推广效果统计
SELECT 
  u.nickname as referrer,
  COUNT(rb.id) as total_referrals,
  SUM(CASE WHEN rb.status = 'converted' THEN 1 ELSE 0 END) as conversions,
  SUM(rb.commission_amount) as total_commission
FROM users u
LEFT JOIN referral_bindings rb ON u.id = rb.referrer_id
WHERE rb.id IS NOT NULL
GROUP BY u.id, u.nickname
ORDER BY total_commission DESC
LIMIT 20;

场景4: 紧急数据修复

-- 手动解锁用户权限（用户支付但未解锁）
START TRANSACTION;

-- 1. 补记订单
INSERT INTO orders (
  id, order_sn, user_id, open_id,
  product_type, product_id, amount, description,
  status, transaction_id, pay_time, created_at, updated_at
) VALUES (
  'MANUAL_20260204_001', 'MANUAL_20260204_001',
  'user_xxx', 'oXXXX...', 'section', '1-1', 9.9,
  '手动补记-章节1-1购买', 'paid', 'manual_fix',
  NOW(), NOW(), NOW()
);

-- 2. 解锁章节
UPDATE users 
SET purchased_sections = JSON_ARRAY_APPEND(
  COALESCE(purchased_sections, '[]'), '$', '1-1'
)
WHERE id = 'user_xxx'
  AND NOT JSON_CONTAINS(COALESCE(purchased_sections, '[]'), '"1-1"');

-- 3. 如果有推荐人，分配佣金
UPDATE users 
SET pending_earnings = pending_earnings + (9.9 * 0.9)
WHERE id = (SELECT referred_by FROM users WHERE id = 'user_xxx');

-- 4. 更新推荐关系状态
UPDATE referral_bindings 
SET status = 'converted', 
    conversion_date = NOW(),
    commission_amount = 8.91,
    order_id = 'MANUAL_20260204_001'
WHERE referee_id = 'user_xxx' 
  AND status = 'active';

COMMIT;

---

🔗 其他 MCP 服务

MySQL（本地）

• 用途: 本地 sass 数据库
• 主机: localhost:3306
• 数据库: sass

MongoDB

• 用途: 测试 MongoDB 连接
• 连接: mongodb://admin:admin123@192.168.1.201:27017/admin

Ollama

• 用途: 本地 AI 模型调用
• 脚本: C:\Users\29195\mcp_ollama_server.py

---

📝 MCP 工具列表

使用 @Soul-MySQL 可以调用以下工具：

工具名	功能	示例
user-MySQL-connect_db	连接数据库	自动连接
user-MySQL-query	执行 SELECT 查询	{"sql": "SELECT * FROM orders LIMIT 10"}
user-MySQL-execute	执行 INSERT/UPDATE/DELETE	{"sql": "UPDATE users SET ..."}
user-MySQL-list_tables	列出所有表	无参数
user-MySQL-describe_table	查看表结构	{"table": "orders"}

---

🚀 快速开始

1. 检查订单表状态

@Soul-MySQL 执行查询：DESCRIBE orders;

2. 查看最近订单

@Soul-MySQL 查询最近10条订单记录

3. 修复订单表（如需要）

@Soul-MySQL 执行以下SQL：
ALTER TABLE orders 
MODIFY COLUMN status ENUM('created', 'pending', 'paid', 'cancelled', 'refunded', 'expired') 
DEFAULT 'created';

---

⚡ 故障排查

问题1: MCP 服务未启动

症状: 输入 @Soul-MySQL 没有提示

解决:

1. 完全关闭 Cursor
2. 检查 mcp.json 文件格式是否正确
3. 重新打开 Cursor
4. 查看 Cursor 输出日志

问题2: 连接超时

症状: 执行查询时提示连接超时

解决:

1. 检查网络连接
2. 确认数据库服务器是否在线
3. 检查防火墙/安全组配置
4. 验证数据库账号密码

问题3: 权限不足

症状: 提示没有权限执行某些操作

解决:

1. 检查数据库用户权限
2. 某些操作需要超级管理员权限
3. 联系 DBA 授权

---

📚 相关文档

• 支付订单完整修复方案
• 订单表状态字段修复说明
• 支付订单未创建问题分析
• 数据库设计

---

现在你可以在 Cursor 中直接使用 @Soul-MySQL 来操作生产数据库了！ 🎉

记得重启 Cursor 使配置生效！