# MySQL MCP Server Pro 使用指南和架构说明
## 📚 目录
1. [什么是 MCP](#什么是-mcp)
2. [如何使用](#如何使用)
3. [MySQL 语句生成位置](#mysql-语句生成位置)
4. [工作流程详解](#工作流程详解)
5. [工具说明](#工具说明)
---
## 什么是 MCP
**MCP (Model Context Protocol)** 是一个协议，允许 AI 客户端（如 Claude Desktop、Cursor、通义千问等）通过标准化的方式连接和使用各种服务器提供的工具和资源。
这个 MySQL MCP Server Pro 就是一个实现了 MCP 协议的服务器，它提供了操作 MySQL 数据库的各种工具。
---
## 如何使用
### 1. 架构概览
```
用户 → AI 客户端（Cursor/Claude Desktop等） → MCP 协议 → MySQL MCP Server Pro → MySQL 数据库
```
### 2. 配置步骤
#### 方式一：使用 uvx（推荐，无需下载源码）
在支持 MCP 的客户端配置文件中添加：
```json
{
"mcpServers": {
"mysql": {
"command": "uvx",
"args": [
"--from",
"mysql_mcp_server_pro",
"mysql_mcp_server_pro",
"--mode",
"stdio"
],
"env": {
"MYSQL_HOST": "192.168.x.xxx",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "root",
"MYSQL_DATABASE": "your_database",
"MYSQL_ROLE": "admin"
}
}
}
}
```
#### 方式二：本地开发（Streamable Http 模式）
1. 启动服务器：
```bash
uv run -m mysql_mcp_server_pro.server
```
2. 在客户端配置：
```json
{
"mcpServers": {
"mysql_mcp_server_pro": {
"name": "mysql_mcp_server_pro",
"type": "streamableHttp",
"isActive": true,
"url": "http://localhost:3000/mcp/"
}
}
}
```
### 3. 使用示例
配置完成后，在 AI 客户端中直接与 AI 对话，例如：
**用户输入：**
```
查询用户表中张三的数据
```
**AI 的工作流程：**
1. AI 理解用户需求
2. AI 调用 `get_table_name` 工具，根据"用户表"查找表名
3. AI 调用 `get_table_desc` 工具，获取表结构
4. **AI 生成 SQL 语句**：`SELECT * FROM user_table WHERE name = '张三'`
5. AI 调用 `execute_sql` 工具执行 SQL
6. AI 返回查询结果给用户
---
## MySQL 语句生成位置
### ⚠️ 重要说明
**MySQL 语句（如 `SELECT * FROM table WHERE ...`）不是在服务器代码中生成的，而是由调用 MCP 的 AI 客户端（模型）生成的！**
### 详细说明
#### 1. 服务器端（MySQL MCP Server Pro）
服务器只负责：
- ✅ 提供工具接口（Tools）
- ✅ 执行 SQL 语句（通过 `execute_sql` 工具）
- ✅ 提供数据库元信息查询工具（如 `get_table_name`、`get_table_desc`）
- ✅ 权限控制和安全检查
- ❌ **不负责生成 SQL 语句**
#### 2. 客户端端（AI 模型）
AI 客户端负责：
- ✅ 理解用户的自然语言需求
- ✅ 选择合适的工具并调用
- ✅ **生成 SQL 语句**（这是关键！）
- ✅ 根据工具返回结果进行后续处理
### SQL 生成过程示例
#### 示例 1：直接执行 SQL
**用户输入：**
```
执行这个 SQL：SELECT * FROM users WHERE age > 18
```
**流程：**
1. AI 理解：用户想执行一个 SQL
2. AI 直接调用 `execute_sql` 工具，传入用户提供的 SQL
3. 服务器执行 SQL 并返回结果
**在这个例子中，SQL 是用户提供的，不是 AI 生成的。**
#### 示例 2：自然语言转 SQL
**用户输入：**
```
查询年龄大于18岁的用户
```
**流程：**
1. AI 理解：用户想查询用户数据
2. AI 可能需要先调用 `get_table_desc` 获取表结构
3. **AI 生成 SQL**：`SELECT * FROM users WHERE age > 18`（AI 在这里生成！）
4. AI 调用 `execute_sql` 工具执行生成的 SQL
5. 返回结果
**在这个例子中，SQL 是 AI 根据用户意图生成的！**
#### 示例 3：根据表描述查询
**用户输入：**
```
查询用户信息表中张三的数据
```
**流程：**
1. AI 理解用户需求
2. AI 调用 `get_table_name` 工具，查询"用户信息表"对应的实际表名
- 工具内部执行：`SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_COMMENT LIKE '%用户信息%'`
- **这个 SQL 是工具内部硬编码的**，用于查询元数据
3. 获得表名后，AI 调用 `get_table_desc` 获取表结构
- 工具内部执行：`SELECT COLUMN_NAME FROM information_schema.COLUMNS WHERE TABLE_NAME = 'user_info'`
- **这个 SQL 也是工具内部硬编码的**
4. **AI 根据表结构生成查询 SQL**：`SELECT * FROM user_info WHERE name = '张三'`
- **这个 SQL 是 AI 生成的！**
5. AI 调用 `execute_sql` 执行生成的 SQL
6. 返回结果
---
## 工作流程详解
### 工具注册机制
```python
# 工具类继承 BaseHandler 会自动注册
class ExecuteSQL(BaseHandler):
name = "execute_sql"
description = "在MySQL数据库上执行SQL"
def get_tool_description(self) -> Tool:
# 返回工具描述，AI 会根据这个描述决定如何使用
return Tool(...)
async def run_tool(self, arguments: Dict[str, Any]):
# 执行工具逻辑
pass
```
### 工具调用流程
```
1. 服务器启动时，所有继承 BaseHandler 的类自动注册到 ToolRegistry
2. AI 客户端通过 MCP 协议调用 list_tools() 获取所有可用工具
3. AI 客户端根据工具描述和用户需求，选择并调用合适的工具
4. 服务器执行工具并返回结果
5. AI 客户端根据结果继续处理或生成下一步操作
```
### 提示词模板（Prompts）
除了工具，服务器还提供了提示词模板：
1. **analyzing-mysql-prompt**：分析 MySQL 问题的提示词
2. **query-table-data-prompt**：查询表数据的提示词（引导 AI 按照特定流程调用工具）
这些提示词可以引导 AI 按照特定的工作流程来处理用户请求。
---
## 工具说明
### 核心工具
| 工具名称 | 功能 | SQL 生成位置 |
|---------|------|-------------|
| `execute_sql` | 执行 SQL 语句 | **AI 客户端生成**或用户提供 |
| `get_table_name` | 根据表注释查询表名 | 工具内部硬编码（查询 information_schema） |
| `get_table_desc` | 获取表结构 | 工具内部硬编码（查询 information_schema） |
| `get_table_index` | 获取表索引 | 工具内部硬编码（查询 information_schema） |
| `optimize_sql` | SQL 优化建议 | **AI 客户端生成**（基于分析结果生成优化建议） |
### 特殊工具
#### `use_prompt_queryTableData`
这个工具比较特殊，它返回一个提示词给 AI，引导 AI 按照特定流程调用工具：
```python
# 该工具返回一个 prompt，告诉 AI 如何工作
prompt = """
- Workflow:
1. 调用工具"get_table_name"
2. 调用工具"get_table_desc"
3. 调用工具"execute_sql"
"""
```
**注意：** 这个工具默认没有继承 `BaseHandler`，需要在代码中修改才能启用。
---
## 总结
### 关键点
1. **SQL 语句主要由 AI 客户端生成**，而不是服务器
2. **服务器只提供工具接口**，不负责理解自然语言或生成 SQL
3. **工具内部查询元数据的 SQL 是硬编码的**（如查询 information_schema）
4. **用户执行的业务 SQL 是 AI 根据工具返回的信息生成的**
### 代码位置
- **工具定义**：`src/mysql_mcp_server_pro/handles/`
- **工具注册**：`src/mysql_mcp_server_pro/handles/base.py`
- **SQL 执行**：`src/mysql_mcp_server_pro/utils/execute_sql_util.py`
- **提示词模板**：`src/mysql_mcp_server_pro/prompts/`
- **服务器主程序**：`src/mysql_mcp_server_pro/server.py`
### 如何扩展
1. **添加新工具**：在 `handles/` 目录下创建新文件，继承 `BaseHandler`
2. **修改工具行为**：直接修改对应的工具类
3. **添加提示词模板**：在 `prompts/` 目录下创建新文件，继承 `BasePrompt`
---
希望这份指南能帮助你理解 MySQL MCP Server Pro 的工作原理！
