# MCP MySQL数据库服务

这是一个基于FastMCP框架的MySQL数据库查询服务，提供Resources、Prompts、Tools三种服务类型，允许AI助手通过MCP协议执行数据库查询操作。

## 功能特性

### Resources（资源服务）
- `database://tables` - 获取数据库中所有表名
- `database://table/{table_name}/data` - 获取指定表的数据（支持分页）
- `database://table/{table_name}/structure` - 获取指定表的结构信息

### Prompts（提示词服务）
- `sql_query_assistant` - SQL查询助手提示词，根据用户需求生成SQL查询建议

### Tools（工具服务）
- `execute_complex_query` - 执行复杂的多表SQL查询

## 技术栈

- **语言**: Python 3.8+
- **MCP框架**: FastMCP（基于标准MCP协议）
- **数据库驱动**: PyMySQL
- **开发工具**: mcp dev
- **测试工具**: mcp inspector

## 安装和配置

### 1. 安装依赖

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

### 2. 配置数据库

编辑 `.env` 文件，配置MySQL数据库连接信息：

```env
MYSQL_HOST=localhost
MYSQL_PORT=3307
MYSQL_USER=root
MYSQL_PASSWORD=root
MYSQL_DATABASE=mcp
```

### 3. 启动服务

#### 开发模式（stdio）

使用MCP开发模式启动服务，适合开发和调试：

```bash
mcp dev mcp_server.py
```

服务启动后会显示：
```
Starting MCP inspector...
⚙️ Proxy server listening on localhost:6277
🔑 Session token: [token]
🚀 MCP Inspector is up and running at: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=[token]
```

#### 生产模式（SSE）

使用SSE（Server-Sent Events）模式启动HTTP服务，适合生产环境部署：

```bash
python mcp_server.py --mode sse --port 8000
```

服务启动后会显示：
```
🚀 启动MCP SSE服务器...
📡 服务地址: http://localhost:8000
🔗 MCP端点: http://localhost:8000/sse
📊 健康检查: http://localhost:8000/health
📖 API文档: http://localhost:8000/docs
```

#### 命令行参数

```bash
python mcp_server.py [选项]

选项:
  --mode {stdio,sse}    运行模式: stdio (默认) 或 sse
  --host HOST          SSE服务器主机 (默认: localhost)
  --port PORT          SSE服务器端口 (默认: 8000)
  -h, --help           显示帮助信息
```

## 使用方法

### 1. 通过MCP Inspector测试

启动服务后，浏览器会自动打开MCP Inspector界面，你可以：

- **测试Resources**: 查看数据库表列表、表数据、表结构
- **测试Prompts**: 使用SQL查询助手生成查询建议
- **测试Tools**: 执行复杂的SQL查询

### 2. 在Kiro IDE中配置

#### stdio模式配置（开发环境）

在Kiro的MCP配置中添加：

```json
{
  "mcpServers": {
    "mysql-database": {
      "command": "python",
      "args": ["path/to/mcp_server.py"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

#### SSE模式配置（生产环境）

在Kiro的MCP配置中添加：

```json
{
  "mcpServers": {
    "mysql-database-sse": {
      "command": "python",
      "args": ["path/to/mcp_server.py", "--mode", "sse", "--port", "8000"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 3. 通过HTTP API访问（SSE模式）

当服务以SSE模式运行时，可以通过HTTP接口访问：

- **健康检查**: `GET http://localhost:8000/health`
- **MCP SSE端点**: `GET http://localhost:8000/sse`
- **API文档**: `GET http://localhost:8000/docs`

## API参考

### Resources

#### 获取表列表
- **URI**: `database://tables`
- **返回**: 数据库中所有表名的JSON列表

```json
{
  "tables": ["users", "orders", "products"],
  "count": 3,
  "database": "mcp"
}
```

#### 获取表数据
- **URI**: `database://table/{table_name}/data`
- **参数**: `table_name` - 表名
- **返回**: 表数据和分页信息

```json
{
  "table_name": "users",
  "data": [...],
  "pagination": {
    "limit": 1000,
    "offset": 0,
    "returned": 10,
    "total": 100
  }
}
```

#### 获取表结构
- **URI**: `database://table/{table_name}/structure`
- **参数**: `table_name` - 表名
- **返回**: 表结构信息

```json
{
  "table_name": "users",
  "columns": [
    {
      "Field": "id",
      "Type": "int(11)",
      "Null": "NO",
      "Key": "PRI"
    }
  ],
  "create_statement": "CREATE TABLE ..."
}
```

### Prompts

#### SQL查询助手
- **名称**: `sql_query_assistant`
- **参数**:
  - `query_description` (必需) - 查询需求描述
  - `table_name` (可选) - 目标表名
- **返回**: SQL查询建议和说明

### Tools

#### 执行复杂查询
- **名称**: `execute_complex_query`
- **参数**:
  - `sql_query` (必需) - SQL查询语句
  - `limit` (可选，默认1000) - 结果行数限制
- **返回**: 查询结果

```json
{
  "sql": "SELECT * FROM users LIMIT 1000",
  "results": [...],
  "count": 10,
  "limit": 1000,
  "success": true
}
```

## 使用示例

### 1. 获取所有表名

在MCP Inspector中选择Resource `database://tables`，点击执行。

### 2. 查看用户表数据

选择Resource `database://table/users/data`，查看用户表的前1000条记录。

### 3. 获取SQL查询建议

使用Prompt `sql_query_assistant`：
```json
{
  "query_description": "查询最近一周注册的用户",
  "table_name": "users"
}
```

### 4. 执行复杂查询

使用Tool `execute_complex_query`：
```json
{
  "sql_query": "SELECT u.name, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id",
  "limit": 500
}
```

## 特性说明

### 安全特性
- 只读操作：仅支持SELECT查询
- 结果限制：默认最多返回1000行数据
- 错误处理：完善的异常处理和错误日志

### 性能特性
- 连接管理：自动管理数据库连接
- 查询超时：30秒查询超时保护
- 分页支持：支持大数据集的分页查询

### 开发特性
- 热重载：使用`mcp dev`支持代码热重载
- 调试友好：通过MCP Inspector可视化调试
- 标准协议：完全兼容MCP标准协议

## 故障排除

### 1. 数据库连接失败
- 检查`.env`文件中的数据库配置
- 确认MySQL服务正在运行
- 验证数据库用户权限

### 2. MCP服务启动失败
- 确认已安装所有依赖：`pip install -r requirements.txt`
- 检查Python版本（需要3.8+）
- 查看错误日志信息

### 3. Inspector无法连接
- 确认服务正常启动
- 检查端口是否被占用（6274, 6277）
- 使用正确的认证令牌

## 开发说明

### 项目结构
```
mcp-service/
├── mcp_server.py      # 主服务文件
├── requirements.txt   # 依赖配置
├── .env              # 数据库配置
├── README.md         # 使用说明
└── MCP需求.md        # 需求文档
```

### 扩展开发
如需添加新功能，可以：
1. 添加新的Resource、Prompt或Tool
2. 使用`@mcp.resource()`、`@mcp.prompt()`、`@mcp.tool()`装饰器
3. 通过`mcp dev`测试新功能

## 许可证

本项目仅用于学习和实践MCP协议开发。

## 部署说明

### 生产环境部署（SSE模式）

1. **使用systemd服务**（Linux）：

创建服务文件 `/etc/systemd/system/mcp-mysql.service`：

```ini
[Unit]
Description=MCP MySQL Database Service
After=network.target mysql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/mcp-service
Environment=PATH=/path/to/venv/bin
ExecStart=/path/to/venv/bin/python mcp_server.py --mode sse --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启动服务：
```bash
sudo systemctl enable mcp-mysql
sudo systemctl start mcp-mysql
sudo systemctl status mcp-mysql
```

2. **使用Docker部署**：

创建 `Dockerfile`：
```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["python", "mcp_server.py", "--mode", "sse", "--host", "0.0.0.0", "--port", "8000"]
```

构建和运行：
```bash
docker build -t mcp-mysql-service .
docker run -d -p 8000:8000 --env-file .env mcp-mysql-service
```

3. **使用nginx反向代理**：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE特殊配置
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
    }
}
```

## 更新日志

### v1.1.0 (2025-01-08)
- ✅ 新增SSE（Server-Sent Events）模式支持
- ✅ 支持HTTP API访问
- ✅ 添加命令行参数配置
- ✅ 完善生产环境部署说明
- ✅ 支持健康检查和API文档端点

### v1.0.0 (2025-01-08)
- ✅ 完成基础MCP服务实现
- ✅ 支持3个Resources服务
- ✅ 支持1个Prompts服务
- ✅ 支持1个Tools服务
- ✅ 通过MCP Inspector测试验证
- ✅ 支持mcp dev启动方式

![img.png](doc/img.png)