# DataMaster MCP Server

## 项目简介

**DataMaster MCP Server** 是一个功能强大的数据分析管理服务器，基于 **Model Context Protocol (MCP)** 构建。这个项目源于现代数据分析工作中遇到的几个核心痛点：

- **数据源碎片化**：企业数据分散在数据库、API、文件等不同系统中，整合困难
- **分析流程复杂**：从数据获取到分析结果需要多个工具切换，效率低下
- **协作困难**：数据分析师、开发人员、业务人员之间缺乏统一的交互接口
- **重复劳动**：每次分析都要重复编写数据连接、清洗、转换的代码

为了解决这些问题，我们开发了这个 **一站式数据管理和分析平台**，将数据库操作、API集成、数据处理、分析计算等功能整合到一个统一的MCP服务器中。用户只需要通过简单的自然语言指令，就能完成复杂的数据分析任务。

### 核心功能特性

🔍 **多数据源集成**
- 支持SQLite、MySQL、PostgreSQL等主流数据库
- 集成RESTful API数据获取
- 统一的数据源管理界面

📊 **智能数据处理**
- 数据清洗（去重、缺失值处理、类型转换）
- 数据转换（列重命名、标准化、计算新列）
- 数据筛选（条件过滤、采样、列选择）

📈 **高级分析能力**
- 描述性统计分析
- 趋势分析和预测
- 数据可视化预览

💾 **灵活数据导出**
- 支持Excel、CSV、JSON等多种格式
- 自动生成标准化报告
- 一键分享分析结果

## 部署指南

### 环境要求

- **Python**: 3.8 或更高版本
- **操作系统**: Windows 10/11, macOS 10.15+, Ubuntu 18.04+
- **内存**: 最少4GB RAM（推荐8GB以上）
- **存储**: 至少1GB可用空间

#### 2. 安装依赖
```bash
pip install datamaster-mcp
```

#### 3. 配置文件设置

创建配置文件 `config/mcp_config.json`：

```json
{
  "mcpServers": {
    "datamaster-mcp": {
      "command": "uvx",
      "args": [
        "datamaster-mcp"
      ]
    }
  }
}
```

## 使用示例

### 示例1：连接数据库并查询数据

**用户输入：**
```
连接到本地的sales数据库，查询2024年的销售数据
```

**系统响应：**
```
✅ 数据库连接成功！
📊 查询结果：找到15,847条2024年销售记录

数据概览：
├─ 总销售额：¥2,847,392.50
├─ 订单数量：15,847笔
├─ 平均订单金额：¥179.68
└─ 数据时间范围：2024-01-01 至 2024-12-31

数据已保存到表：sales_2024_analysis
```

### 示例2：API数据获取和分析

**用户输入：**
```
从天气API获取北京最近7天的天气数据，分析温度趋势
```

**系统响应：**
```
🌤️ 天气数据获取成功！
📈 温度趋势分析完成

7天温度统计：
├─ 最高温度：28.5°C (10月15日)
├─ 最低温度：12.3°C (10月12日)
├─ 平均温度：20.8°C
└─ 温度变化：整体呈下降趋势 (-3.2°C)

📊 数据可视化已生成：exports/weather_trend_20241015_143022.png
```

### 示例3：数据清洗和导出

**用户输入：**
```
清洗用户数据表，去除重复邮箱，填充缺失的手机号码
```

**系统响应：**
```
🧹 数据清洗完成！

清洗结果统计：
├─ 原始记录：8,432条
├─ 重复邮箱：127条（已删除）
├─ 缺失手机：2,156条（已填充默认值）
├─ 数据类型转换：3列
└─ 清洗后记录：8,305条

📤 清洗结果已导出：exports/cleaned_users_20241015_144512.xlsx
```

### 示例4：复杂SQL查询和可视化

**用户输入：**
```
查询每个产品类别的月度销售额，按销售额降序排列
```

**系统响应：**
```
📊 查询执行成功！

月度销售排行榜：
├─ 电子产品：¥847,392.00 (占比29.7%)
├─ 服装配饰：¥624,193.50 (占比21.9%)
├─ 家居用品：¥518,472.30 (占比18.2%)
├─ 图书文具：¥392,847.20 (占比13.8%)
└─ 运动户外：¥347,392.00 (占比12.2%)

📈 可视化图表已生成：
├─ 柱状图：exports/category_sales_bar_20241015_145533.png
├─ 饼图：exports/category_sales_pie_20241015_145533.png
└─ 数据表：exports/category_monthly_sales.xlsx
```

### 实际使用截图展示

#### 主界面展示
```
┌─────────────────────────────────────────────────────────────┐
│                 DataMaster MCP Server                      │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  🔍 数据源管理    📊 数据分析    ⚙️ 数据处理    🌐 API │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  已连接数据源:                                      │  │
│  │  📊 SQLite数据库: analysis.db (已连接)               │  │
│  │  🌐 天气API: api.weather.com (已配置)               │  │
│  │  📈 股票API: api.stocks.com (已配置)                │  │
│  └─────────────────────────────────────────────────────┘  │
│  [输入指令] > 连接到sales数据库，查询2024年销售数据...     │
└─────────────────────────────────────────────────────────────┘
```

#### 数据库连接配置
```
┌─────────────────────────────────────────┐
│         数据库连接配置                  │
├─────────────────────────────────────────┤
│  数据库类型: SQLite                     │
│  数据库路径: ./data/sales.db           │
│  连接状态: ✅ 已连接                    │
│  表数量: 12张                           │
│  总记录数: 125,847条                   │
├─────────────────────────────────────────┤
│  可用表:                                │
│  • customers (8,432条)                 │
│  • orders (15,847条)                   │
│  • products (342条)                    │
│  • sales_records (45,293条)            │
└─────────────────────────────────────────┘
```

#### 数据查询结果
```
┌─────────────────────────────────────────────┐
│            SQL查询结果                     │
├─────────────────────────────────────────────┤
│  查询: SELECT * FROM sales WHERE year=2024 │
│  执行时间: 0.23秒                          │
│  返回记录: 15,847条                        │
├─────────────────────────────────────────────┤
│  数据概览:                                  │
│  ├─ 总销售额: ¥2,847,392.50               │
│  ├─ 平均订单: ¥179.68                     │
│  ├─ 最高单笔: ¥12,450.00                   │
│  └─ 数据范围: 2024-01-01 ~ 2024-12-31     │
└─────────────────────────────────────────────┘
```

#### API数据获取
```
┌─────────────────────────────────────────────┐
│            API数据获取                      │
├─────────────────────────────────────────────┤
│  API名称: 天气数据API                       │
│  请求URL: api.weather.com/v1/forecast      │
│  响应状态: ✅ 200 OK                       │
│  数据大小: 45.2 KB                        │
├─────────────────────────────────────────────┤
│  数据预览:                                  │
│  日期        温度    湿度    天气           │
│  2024-10-15  28.5°C  65%    晴             │
│  2024-10-14  26.2°C  70%    多云           │
│  2024-10-13  24.8°C  72%    阴             │
└─────────────────────────────────────────────┘
```

#### 数据清洗工具
```
┌─────────────────────────────────────────────┐
│            数据清洗结果                     │
├─────────────────────────────────────────────┤
│  清洗前记录: 8,432条                      │
│  清洗后记录: 8,305条                      │
│  删除重复: 127条                          │
│  填充缺失: 2,156条                        │
├─────────────────────────────────────────────┤
│  清洗操作:                                  │
│  ✓ 去除重复邮箱地址                        │
│  ✓ 填充缺失手机号码                        │
│  ✓ 标准化日期格式                          │
│  ✓ 验证邮箱格式                            │
└─────────────────────────────────────────────┘
```

#### 分析结果导出
```
┌─────────────────────────────────────────────┐
│            导出结果                         │
├─────────────────────────────────────────────┤
│  导出格式: Excel (.xlsx)                   │
│  文件路径: exports/sales_analysis.xlsx    │
│  文件大小: 2.34 MB                        │
│  包含工作表: 3个                           │
├─────────────────────────────────────────────┤
│  工作表内容:                                │
│  • 销售概览                                │
│  • 月度趋势                                │
│  • 产品分析                                │
└─────────────────────────────────────────────┘
```

### 高级使用技巧

#### 批量处理
```bash
# 批量处理多个数据表
python -m datamaster_mcp.main --batch-process tables.txt --config batch_config.json
```

#### 定时任务
```bash
# 设置定时数据更新
python -m datamaster_mcp.main --schedule "0 9 * * *" --task daily_report
```

#### 自定义分析模板
```json
{
  "template_name": "monthly_sales_analysis",
  "steps": [
    {"action": "query", "sql": "SELECT * FROM sales WHERE date >= ?"},
    {"action": "clean", "config": {"remove_duplicates": true}},
    {"action": "analyze", "type": "trend"},
    {"action": "export", "format": "excel"}
  ]
}
```

## 故障排除

### 常见问题

**Q: 连接数据库失败**
A: 检查数据库配置和网络连接，确保数据库服务正在运行

**Q: API请求超时**
A: 增加API超时时间设置，检查网络连接稳定性

**Q: 内存不足错误**
A: 减少单次处理的数据量，或增加系统内存

### 日志查看
```bash
# 查看实时日志
tail -f logs/datamaster.log

# 查看错误日志
grep ERROR logs/datamaster.log
```

## 技术支持

- **GitHub Issues**: [提交问题](https://github.com/your-username/DataMaster-MCP/issues)
- **文档**: [完整文档](https://datamaster-mcp.readthedocs.io)
- **社区**: [讨论论坛](https://github.com/your-username/DataMaster-MCP/discussions)

---

**DataMaster MCP Server** - 让数据分析变得简单而强大！