Metadata-Version: 2.4
Name: multimymcp
Version: 1.0.0
Summary: 生产级 MySQL 多数据源 MCP 工具，适配 TRAE CN IDE 环境
Author-email: wanhonglei <wanhonglei@example.com>
License-Expression: MIT
Project-URL: Source, https://gitee.com/wanhonglei/multi-mysql-mcp
Project-URL: Bug Tracker, https://gitee.com/wanhonglei/multi-mysql-mcp/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pymysql>=1.0.0
Requires-Dist: DBUtils>=2.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: cryptography>=3.4.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: json5>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=6.2.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"

# MultiMyMCP - 生产级 MySQL 多数据源 MCP 工具

## 项目概述

MultiMyMCP 是一个完全适配 TRAE SOLO IDE 环境的生产级 MySQL 多数据源管理工具。它提供了增强型连接池、安全配置、性能监控等核心功能，支持标准 MCP 协议，让 AI 能够直接查询多个 MySQL 数据库。

## 核心特性

### 1. 标准 MCP 协议支持
- 完全符合 MCP (Model Context Protocol) 标准
- 支持 JSON-RPC 2.0 通信协议
- 提供 4 个核心工具：query_database、list_datasources、execute_sql、get_schema
- 与 TRAE SOLO IDE 无缝集成

### 2. 增强型连接池
- 支持连接池动态扩容/缩容
- 记录连接使用时长和 SQL 执行耗时
- 连接池状态监控（当前连接数、空闲连接数、等待队列长度）
- 线程安全的连接管理

### 3. 安全与通用规范
- SQL 执行超时控制
- 数据源配置加密存储（AES-256）
- SQL 白名单/黑名单机制
- 危险 SQL 操作拦截

### 4. 多数据源支持
- 支持同时管理多个 MySQL 数据源
- 灵活的数据源切换
- 全局配置文件管理
- 支持主从库配置

## 技术栈

- **Python**: 3.8+
- **核心依赖**: pymysql, DBUtils>=2.0, python-dotenv, cryptography, json5
- **可选依赖**: psutil, pytest

## 项目结构

```
MultiMyMCP/
├── multimymcp/
│   ├── __init__.py              # 模块初始化
│   ├── core.py                  # 核心MCP接口
│   ├── config.py                # 配置管理
│   ├── encryption.py            # 加密工具
│   ├── pool.py                  # 连接池管理
│   ├── executor.py              # SQL执行器
│   ├── monitor.py               # 监控模块
│   ├── exceptions.py            # 异常定义
│   ├── cli.py                   # 命令行接口
│   ├── mcp_server.py            # MCP服务器主程序
│   ├── mcp_protocol.py          # MCP协议处理器
│   ├── mcp_tools.py             # MCP工具实现
│   └── mcp_config_loader.py     # MCP配置加载器
├── tests/                       # 单元测试
├── docs/                        # 文档
├── requirements.txt             # 依赖配置
├── setup.py                     # 打包配置
├── README.md                    # 项目说明
├── CHANGELOG.md                 # 更新日志
└── .env.example                 # 环境变量示例
```

## 安装步骤

### 1. 克隆项目

```bash
git clone git@gitee.com:wanhonglei/multi-mysql-mcp.git
cd multimymcp
```

### 2. 安装依赖

```bash
pip3 install -r requirements.txt
```

### 3. 安装项目（开发模式）

```bash
pip3 install -e .
```

### 4. 验证安装

```bash
python3 -m multimymcp.mcp_server --help
```

应该看到帮助信息输出。

## MCP 服务器使用指南

### 第一步：创建配置文件

#### 1.1 创建配置目录

```bash
mkdir -p ~/.multimymcp
```

#### 1.2 创建配置文件

创建 `~/.multimymcp/mcp_config.json5` 文件：

```bash
cat > ~/.multimymcp/mcp_config.json5 << 'EOF'
{
  "datasources": {
    "master": {
      "host": "localhost",
      "port": 3306,
      "user": "root",
      "password": "your_password",
      "database": "production",
      "pool_min_size": 2,
      "pool_max_size": 10
    },
    "slave": {
      "host": "localhost",
      "port": 3307,
      "user": "readonly",
      "password": "your_password",
      "database": "production",
      "pool_min_size": 5,
      "pool_max_size": 20
    }
  },
  "security": {
    "whitelist_enabled": false,
    "blacklist_enabled": true,
    "blacklist": ["DROP", "TRUNCATE", "ALTER", "CREATE"]
  }
}
EOF
```

**重要提示**：
- 请将 `your_password` 替换为实际的数据库密码
- 根据实际情况修改 host、port、user、database 等参数
- 可以添加更多数据源

### 第二步：测试 MCP 服务器

#### 2.1 测试初始化请求

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python3 -m multimymcp.mcp_server
```

**预期输出**：

```json
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": {"name": "multimymcp", "version": "1.0.0"}}}
```

#### 2.2 测试工具列表

```bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python3 -m multimymcp.mcp_server
```

**预期输出**：

```json
{"jsonrpc": "2.0", "id": 2, "result": {"tools": [...]}}
```

### 第三步：在 TRAE SOLO IDE 中配置

#### 3.1 打开 MCP 设置

在 TRAE SOLO IDE 中：

**方式一：通过菜单**
1. 点击菜单栏的 `Preferences`（偏好设置）
2. 选择 `MCP Servers`（MCP 服务器）
3. 点击 `Edit MCP Settings`（编辑 MCP 设置）

**方式二：通过命令面板**
1. 按 `Cmd + Shift + P`（macOS）打开命令面板
2. 输入 `MCP`
3. 选择 `MCP: Edit MCP Settings`

#### 3.2 添加 MCP 服务器配置

在打开的配置文件中，添加以下内容：

```json
{
  "mcpServers": {
    "multimymcp": {
      "command": "python3",
      "args": ["-m", "multimymcp.mcp_server"],
      "env": {}
    }
  }
}
```

**完整配置示例**：

如果文件中已有其他 MCP 服务器，请添加到 `mcpServers` 对象中：

```json
{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": [...]
    },
    "multimymcp": {
      "command": "python3",
      "args": ["-m", "multimymcp.mcp_server"],
      "env": {}
    }
  }
}
```

#### 3.3 保存并重启

1. 保存配置文件（`Cmd + S`）
2. 重启 MCP 服务器或重启 TRAE SOLO IDE

### 第四步：验证配置成功

#### 4.1 检查 MCP 服务器状态

在 TRAE SOLO IDE 中：

1. 打开命令面板（`Cmd + Shift + P`）
2. 输入 `MCP: Show Status`
3. 查看 `multimymcp` 是否显示为 `connected`（已连接）

#### 4.2 测试 AI 调用

在 TRAE SOLO IDE 的 AI 对话框中，尝试以下对话：

```
请列出所有可用的 MySQL 数据源
```

AI 应该会调用 `list_datasources` 工具并返回结果。

```
请查询 master 数据源中的 users 表，返回前 10 条记录
```

AI 应该会调用 `query_database` 工具执行查询。

## 可用的 MCP 工具

### 1. query_database

**描述**：在指定的 MySQL 数据源上执行查询 SQL

**参数**：
- `datasource`: 数据源名称（必需）
- `sql`: 完整的 SELECT 查询语句（必需）

**示例**：

```
请从 master 数据源查询 users 表的前 10 条记录
```

### 2. list_datasources

**描述**：列出所有可用的 MySQL 数据源

**参数**：无

**示例**：

```
请列出所有可用的 MySQL 数据源
```

### 3. execute_sql

**描述**：执行 SQL 语句（INSERT/UPDATE/DELETE 等）

**参数**：
- `datasource`: 数据源名称（必需）
- `sql`: 完整的 SQL 语句（必需）

**示例**：

```
请在 master 数据源中执行以下 SQL：
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')
```

### 4. get_schema

**描述**：获取指定数据源的表结构信息

**参数**：
- `datasource`: 数据源名称（必需）
- `table`: 表名（可选，不指定则返回所有表）

**示例**：

```
请获取 master 数据源中 users 表的结构信息
```

## Python API 使用

### 基本使用

```python
from multimymcp import MultiMyMCP

# 初始化 MCP
mcp = MultiMyMCP()

# 连接数据源
mcp.connect('default')

# 执行 SQL
result = mcp.execute('SELECT * FROM users LIMIT 10')
print(result)

# 断开连接
mcp.disconnect()
```

### 多数据源配置

```python
from multimymcp import MultiMyMCP, DataSourceConfig

mcp = MultiMyMCP()

# 添加主库
master_config = DataSourceConfig(
    name="master",
    host="master_db",
    port=3306,
    user="root",
    password="master_password",
    database="production"
)
mcp.add_data_source(master_config)

# 添加从库
slave_config = DataSourceConfig(
    name="slave",
    host="slave_db",
    port=3306,
    user="readonly",
    password="slave_password",
    database="production"
)
mcp.add_data_source(slave_config)

# 使用不同数据源
mcp.connect('master')
mcp.execute('INSERT INTO users (name) VALUES ("test")')

mcp.connect('slave')
result = mcp.execute('SELECT * FROM users')
```

### 事务处理

```python
from multimymcp import MultiMyMCP

mcp = MultiMyMCP()
mcp.connect('default')

# 使用事务
try:
    mcp._executors['default'].begin_transaction()
    
    mcp.execute('INSERT INTO orders (user_id, amount) VALUES (1, 100)')
    mcp.execute('UPDATE users SET balance = balance - 100 WHERE id = 1')
    
    mcp._executors['default'].commit_transaction()
except Exception as e:
    mcp._executors['default'].rollback_transaction()
    raise
```

## 监控与调试

### 1. 连接池状态

```python
status = mcp.get_pool_status()
print(f"当前连接数: {status['current_size']}")
print(f"活跃连接数: {status['active_size']}")
print(f"空闲连接数: {status['idle_size']}")
```

### 2. 性能报告

```python
report = mcp.get_performance_report()
print(f"总执行次数: {report['summary']['total_sql_executions']}")
print(f"成功率: {report['summary']['success_rate']:.2f}%")
print(f"平均执行时间: {report['summary']['avg_execution_time']:.3f}s")
```

### 3. 健康检查

```python
health = mcp.get_health_status()
if health['healthy']:
    print("系统健康状态良好")
else:
    print("系统存在问题:")
    for issue in health['issues']:
        print(f"- {issue}")
```

## 命令行工具

```bash
# 查看帮助
multimymcp --help

# 连接数据源
multimymcp connect default

# 执行 SQL
multimymcp execute "SELECT * FROM users"

# 查看状态
multimymcp status

# 健康检查
multimymcp health

# 性能报告
multimymcp performance

# 列出数据源
multimymcp list

# 调整连接池大小
multimymcp resize 5 20
```

## 常见问题排查

### 问题 1：MCP 服务器无法启动

**症状**：状态显示为 `disconnected` 或 `error`

**解决方法**：

1. 检查 Python 路径是否正确：
   ```bash
   which python3
   ```
   
2. 在配置中使用完整路径：
   ```json
   {
     "mcpServers": {
       "multimymcp": {
         "command": "/usr/bin/python3",
         "args": ["-m", "multimymcp.mcp_server"],
         "env": {}
       }
     }
   }
   ```

### 问题 2：找不到模块

**症状**：错误信息显示 `ModuleNotFoundError`

**解决方法**：

1. 确认项目已安装：
   ```bash
   pip3 install -e /path/to/MultiMyMCP
   ```

2. 在配置中添加 PYTHONPATH：
   ```json
   {
     "mcpServers": {
       "multimymcp": {
         "command": "python3",
         "args": ["-m", "multimymcp.mcp_server"],
         "env": {
           "PYTHONPATH": "/path/to/MultiMyMCP"
         }
       }
     }
   }
   ```

### 问题 3：数据库连接失败

**症状**：AI 调用工具时返回连接错误

**解决方法**：

1. 检查配置文件中的数据库连接信息
2. 确认数据库服务正在运行
3. 测试数据库连接：
   ```bash
   mysql -h localhost -P 3306 -u root -p
   ```

## 安全配置

### 生产环境配置

```json5
{
  "security": {
    "whitelist_enabled": true,
    "blacklist_enabled": true,
    "whitelist": ["SELECT", "INSERT", "UPDATE", "DELETE"],
    "blacklist": ["DROP", "TRUNCATE", "ALTER", "CREATE", "GRANT", "REVOKE"]
  }
}
```

## 性能优化建议

### 1. 连接池优化

```python
# 推荐配置
config = DataSourceConfig(
    # 其他配置...
    pool_min_size=5,      # 基础并发数
    pool_max_size=15,     # 最大并发数
    pool_timeout=30,      # 连接池超时(秒)
    sql_timeout=60        # SQL执行超时(秒)
)
```

### 2. SQL 优化

- 使用参数化查询
- 批量执行操作
- 使用事务减少网络开销
- 限制结果集大小

## 测试

运行单元测试：

```bash
pytest tests/ -v --cov=multimymcp
```

## 版本信息

- **版本**: 1.0.0
- **发布日期**: 2026-03-12
- **Python 版本**: 3.8+

## 许可证

MIT License

## 更新日志

### v1.0.0 (2026-03-12)
- 初始版本发布
- 实现标准 MCP 协议支持
- 实现 4 个核心 MCP 工具
- 实现核心连接池管理
- 实现加密存储功能
- 实现 SQL 执行器和监控功能
- 完整的单元测试覆盖
- 详细的文档和使用指南

## 技术支持

如有任何问题，请参考文档或提交 Issue。
