# MCP数据库查询服务

一个基于Model Context Protocol (MCP)的SQLite数据库查询服务，为AI应用提供标准化的数据库访问能力。

## 🚀 功能特性

### 核心功能
- **数据库连接管理**: 安全的SQLite数据库连接和查询
- **SQL查询执行**: 支持SELECT查询，内置安全防护
- **表结构查询**: 获取数据库表的详细结构信息
- **样本数据获取**: 快速预览表中的示例数据
- **架构导出**: 完整的数据库架构信息

### MCP协议支持
- **工具(Tools)**: 提供5个核心数据库操作工具
- **资源(Resources)**: 支持数据库元数据资源访问
- **提示(Prompts)**: 内置SQL查询和分析提示模板
- **安全机制**: SQL注入防护、查询限制、访问控制

### 技术架构
- **通信协议**: JSON-RPC over stdio
- **数据库**: SQLite 3.x
- **编程语言**: Python 3.8+
- **依赖管理**: pip/requirements.txt

## 📦 安装指南

### 1. 环境要求
- Python 3.8 或更高版本
- pip 包管理器

### 2. 克隆项目
```bash
git clone <repository-url>
cd mcp_learn
```

### 3. 安装依赖
```bash
pip install -r requirements.txt
```

### 4. 创建示例数据库
```bash
python create_sample_database.py
```

## 🎯 快速开始

### 方式一：使用启动脚本
```bash
python start_server.py
```

### 方式二：直接启动服务器
```bash
python mcp_database_server.py
```

## 📋 项目结构

```
mcp_learn/
├── README.md                    # 项目说明文档
├── requirements.txt             # Python依赖列表
├── config.py                    # 服务器配置文件
├── database_manager.py          # 数据库管理模块
├── mcp_database_server.py       # MCP服务器主程序
├── create_sample_database.py    # 示例数据库创建脚本
├── start_server.py             # 服务器启动脚本
└── sample_data.db              # 示例SQLite数据库(运行后生成)
```

## 🛠️ 可用工具

### 1. query_database
执行SQL查询操作
```json
{
  "name": "query_database",
  "arguments": {
    "query": "SELECT * FROM users WHERE age > 25 LIMIT 10"
  }
}
```

### 2. get_table_info
获取表结构信息
```json
{
  "name": "get_table_info",
  "arguments": {
    "table_name": "users"
  }
}
```

### 3. list_tables
列出所有数据库表
```json
{
  "name": "list_tables",
  "arguments": {}
}
```

### 4. get_table_sample
获取表样本数据
```json
{
  "name": "get_table_sample",
  "arguments": {
    "table_name": "products",
    "limit": 5
  }
}
```

### 5. get_database_schema
获取完整数据库架构
```json
{
  "name": "get_database_schema",
  "arguments": {}
}
```

## 📚 可用资源

### 1. 数据库表列表
- **URI**: `database://tables`
- **描述**: 获取所有数据库表的列表

### 2. 数据库架构
- **URI**: `database://schema`
- **描述**: 获取完整的数据库架构信息

### 3. 特定表信息
- **URI**: `database://table/{table_name}`
- **描述**: 获取指定表的详细信息

## 💡 提示模板

### 1. SQL查询助手
- **名称**: `sql_query_helper`
- **用途**: 帮助构建和优化SQL查询

### 2. 数据分析助手
- **名称**: `data_analysis_helper`
- **用途**: 协助进行数据分析和洞察

### 3. 表结构分析
- **名称**: `schema_analysis_helper`
- **用途**: 分析数据库表结构和关系

## 🔧 配置说明

### config.py 配置项

```python
class DatabaseConfig:
    database_path: str = "sample_data.db"  # 数据库文件路径
    connection_timeout: int = 30           # 连接超时时间
    query_timeout: int = 60               # 查询超时时间
    max_query_results: int = 1000         # 最大查询结果数

class SecurityConfig:
    allowed_operations: List[str] = ["SELECT"]  # 允许的SQL操作
    forbidden_tables: List[str] = []           # 禁止访问的表
    enable_sql_injection_protection: bool = True  # SQL注入防护

class MCPConfig:
    server_name: str = "database-query-server"  # 服务器名称
    server_version: str = "1.0.0"              # 服务器版本

class LoggingConfig:
    log_file: str = "mcp_server.log"  # 日志文件路径
    log_rotation: str = "1 day"       # 日志轮转周期
    log_level: str = "INFO"           # 日志级别
```

## 🔒 安全特性

### SQL注入防护
- 参数化查询
- SQL语句验证
- 危险关键词过滤

### 访问控制
- 操作类型限制（仅允许SELECT）
- 表访问控制
- 查询结果数量限制

### 错误处理
- 详细的错误信息
- 安全的错误响应
- 日志记录

## 🔌 客户端集成

### Claude Desktop
在Claude Desktop配置文件中添加：
```json
{
  "mcpServers": {
    "database-query": {
      "command": "python",
      "args": ["/path/to/mcp_database_server.py"],
      "cwd": "/path/to/mcp_learn"
    }
  }
}
```

### Cursor IDE
1. 打开Cursor设置
2. 添加MCP服务器配置
3. 指定服务器路径和参数

### 其他MCP客户端
任何支持MCP协议的客户端都可以连接此服务器。

## 📊 示例数据库

示例数据库包含以下表：

### users (用户表)
- id, username, email, full_name, age, city, registration_date, is_active

### products (产品表)
- id, name, category, price, stock_quantity, description, created_date

### orders (订单表)
- id, user_id, order_date, total_amount, status, shipping_address

### order_items (订单详情表)
- id, order_id, product_id, quantity, unit_price

### activity_logs (活动日志表)
- id, user_id, action, description, ip_address, timestamp

## 🐛 故障排除

### 常见问题

1. **依赖安装失败**
   ```bash
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

2. **数据库文件不存在**
   ```bash
   python create_sample_database.py
   ```

3. **权限错误**
   确保对项目目录有读写权限

4. **端口占用**
   MCP使用stdio通信，不涉及端口问题

### 调试模式
修改config.py中的日志级别：
```python
log_level: str = "DEBUG"
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

## 📄 许可证

MIT License - 详见LICENSE文件

## 📞 支持

如有问题或建议，请：
1. 查看文档和FAQ
2. 提交Issue
3. 联系维护者

---

**注意**: 这是一个示例项目，用于演示MCP协议的数据库查询功能。在生产环境中使用前，请确保进行充分的安全评估和测试。