SuperDataAnalysis - DataMaster_MCP

# 🛠️ DataMaster MCP 开发者文档 > **开发者和AI使用的技术文档** - 工具设计、修复记录和AI使用指南 --- ## 📋 目录 1. [项目架构](#项目架构) 2. [工具设计理念](#工具设计理念) 3. [AI工具使用指南](#ai工具使用指南) 4. [修复记录](#修复记录) 5. [开发规范](#开发规范) 6. [测试验证](#测试验证) --- ## 🏗️ 项目架构 ### 核心模块 ``` DataMaster_MCP/ ├── main.py # MCP服务器主入口 ├── config/ # 配置管理模块 │ ├── config_manager.py # 配置管理器 │ ├── database_manager.py # 数据库管理器 │ ├── api_connector.py # API连接器 │ ├── api_data_storage.py # API数据存储 │ └── data_transformer.py # 数据转换器 ├── requirements.txt # 依赖包 └── docs/ # 文档目录 ``` ### 设计原则 1. **模块化设计** - 每个功能独立模块 2. **配置驱动** - 通过配置文件管理连接 3. **错误容错** - 完善的错误处理机制 4. **AI友好** - 详细的工具描述和参数说明 --- ## 💡 工具设计理念 ### 核心理念 **工具专注数据获取和计算，AI专注智能分析和洞察** ### 设计特性 #### 1. 两步连接法 **设计目的**: 分离连接测试和实际使用，提高稳定性 ```python # 第一步：创建配置（测试连接） connect_data_source( source_type="mysql", config={"host": "localhost", "user": "root", ...} ) # 返回：temp_mysql_20250724_173102 # 第二步：使用配置（实际连接） connect_data_source( source_type="database_config", config={"database_name": "temp_mysql_20250724_173102"} ) ``` **优势**: - 连接参数验证和实际使用分离 - 临时配置自动管理 - 支持配置复用 #### 2. 参数兼容性 支持多种参数名称变体： - `user` / `username` - `password` / `passwd` - `database` / `db` #### 3. 查询工具分工 - `execute_sql`: 本地SQLite和指定数据源 - `query_external_database`: 专门查询外部数据库 --- ## 🤖 AI工具使用指南 ### 工具速查表 | 工具名称 | 主要功能 | 核心参数 | 使用场景 | |---------|---------|---------|----------| | `connect_data_source` | 连接数据源 | source_type, config | 数据库连接、文件导入 | | `execute_sql` | 查询本地数据 | query, params | SQLite查询 | | `query_external_database` | 查询外部数据库 | database_name, query | MySQL/PostgreSQL/MongoDB | | `get_data_info` | 获取数据信息 | info_type, table_name | 数据探索 | | `analyze_data` | 数据分析 | analysis_type, table_name | 统计分析 | | `process_data` | 数据处理 | operation_type, config | 数据清洗、转换 | | `export_data` | 数据导出 | export_type, data_source | 结果导出 | ### AI使用最佳实践 #### 1. 数据库连接流程 ```python # ✅ 正确的连接流程 # 步骤1：创建配置 result1 = connect_data_source( source_type="mysql", config={"host": "localhost", "user": "root", "password": "pass", "database": "test"} ) # 获取临时配置名：temp_mysql_xxx # 步骤2：使用配置连接 result2 = connect_data_source( source_type="database_config", config={"database_name": "temp_mysql_xxx"} ) # 步骤3：查询数据 query_external_database( database_name="temp_mysql_xxx", query="SELECT * FROM users LIMIT 10" ) ``` #### 2. 数据分析工作流 ```python # 完整的数据分析流程 # 1. 导入数据 connect_data_source( source_type="excel", config={"file_path": "data.xlsx"}, target_table="raw_data" ) # 2. 探索数据结构 get_data_info(info_type="schema", table_name="raw_data") get_data_info(info_type="stats", table_name="raw_data") # 3. 数据质量检查 analyze_data(analysis_type="missing_values", table_name="raw_data") analyze_data(analysis_type="duplicates", table_name="raw_data") # 4. 数据清洗 process_data( operation_type="clean", data_source="raw_data", config={"remove_duplicates": True}, target_table="clean_data" ) # 5. 统计分析 analyze_data(analysis_type="basic_stats", table_name="clean_data") analyze_data(analysis_type="correlation", table_name="clean_data") # 6. 导出结果 export_data(export_type="excel", data_source="clean_data") ``` #### 3. 错误处理指南 **常见错误及解决方案**: 1. **"缺少必需的配置字段: username"** - 解决：使用 `user` 或 `username` 参数 2. **"数据库配置不存在"** - 解决：使用 `list_data_sources()` 查看可用配置 3. **"连接超时"** - 解决：检查网络连接和数据库服务状态 #### 4. 参数格式参考 **数据库连接参数**: ```json { "host": "数据库地址", "port": 端口号(数字), "user": "用户名", // 或 "username" "database": "数据库名", "password": "密码" } ``` **分析类型选项**: - `"basic_stats"` - 基础统计 - `"correlation"` - 相关性分析 - `"outliers"` - 异常值检测 - `"missing_values"` - 缺失值分析 - `"duplicates"` - 重复值检测 **处理操作类型**: - `"clean"` - 数据清洗 - `"transform"` - 数据转换 - `"filter"` - 数据筛选 - `"aggregate"` - 数据聚合 - `"merge"` - 数据合并 - `"reshape"` - 数据重塑 --- ## 🔧 修复记录 ### v1.0.0 重大修复 (2025-01-24) #### 修复内容 1. **✅ 数据库连接参数兼容性修复** - **问题**: MySQL和PostgreSQL连接时参数名不匹配 - **修复**: 统一支持 `user` 和 `username` 参数 - **文件**: `config/database_manager.py` 2. **✅ 临时配置生命周期管理修复** - **问题**: 临时配置创建后立即删除，导致后续查询失败 - **修复**: 临时配置持久化保存，增加管理功能 - **文件**: `main.py`, `config/config_manager.py` 3. **✅ MongoDB查询语法解析改进** - **问题**: 聚合管道JSON解析失败 - **修复**: 支持多种查询语法格式 - **文件**: `config/database_manager.py` 4. **✅ 工具功能增强** - **新增**: `list_temp` 和 `cleanup_temp` 操作 - **改进**: 错误信息和操作反馈 #### 测试验证 ```bash # 运行修复验证测试 python test_fixes.py # 测试结果 ✅ MySQL用户名兼容性: 通过 ✅ PostgreSQL用户名兼容性: 通过 ✅ 临时配置管理: 通过 ✅ MongoDB管道解析: 通过 总计: 4/4 个测试通过 ``` #### 重要发现 **用户验证案例 (2025-01-24)**: 经过实际测试验证，发现之前的"连接失败"问题实际上是使用方法理解偏差： ❌ **错误理解**: - 以为工具有bug，连接总是失败 - 直接使用 `source_type: "mysql"` 等方式连接 - 没有意识到后台自动创建的临时配置 ✅ **正确理解**: - 工具完全正常工作！ - 系统自动创建临时配置（如 `temp_mysql_20250724_173102`） - 必须使用 `source_type: "database_config"` + 配置名称连接 - 使用 `query_external_database` 查询外部数据库 **关键领悟**: 问题不在工具，而在使用方法！两步连接法是设计特性，不是bug！ --- --- ## 🔄 开发流程指南 ### 开发流程概述 **推荐方式：本地持续开发 + 版本发布** 你**不需要**每次都下载包来更新！正确的开发流程是： 1. 在本地项目持续开发和测试 2. 版本稳定后统一发布到 PyPI 3. 用户通过 `pip install -U` 更新 ### 完整开发工作流 #### 阶段1：本地开发环境 ```bash # 1. 克隆或保持本地项目 git clone https://github.com/szqshan/DataMaster.git cd DataMaster # 2. 创建开发环境 python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 3. 安装开发依赖 pip install -r requirements.txt pip install build twine # 发布工具 # 4. 以开发模式安装（重要！） pip install -e . # 可编辑安装，代码修改立即生效 ``` #### 阶段2：日常开发循环 ```bash # 1. 创建功能分支 git checkout -b feature/new-feature # 2. 开发代码 # 编辑 datamaster_mcp/ 下的文件 # 3. 本地测试 python test_mcp_server.py # 运行测试 python start_mcp_server.py # 启动服务器测试 # 4. 提交更改 git add . git commit -m "feat: 添加新功能" # 5. 合并到主分支 git checkout master git merge feature/new-feature ``` #### 阶段3：版本发布流程 ##### 版本号管理 ```bash # 更新版本号（三个地方） # 1. setup.py 中的 version # 2. pyproject.toml 中的 version # 3. datamaster_mcp/__init__.py 中的 __version__ # 版本号规则： # 主版本.次版本.修订版本 # 1.0.1 -> 1.0.2 (bug修复) # 1.0.1 -> 1.1.0 (新功能) # 1.0.1 -> 2.0.0 (重大更改) ``` ##### 发布前检查 ```bash # 1. 运行完整测试 python test_mcp_server.py # 2. 检查包结构 python -c "import datamaster_mcp; print(datamaster_mcp.__version__)" # 3. 构建包 python -m build # 4. 检查构建结果 twine check dist/* ``` ##### 发布到 PyPI ```bash # 1. 测试发布（可选） twine upload --repository testpypi dist/* # 2. 正式发布 twine upload dist/* # 3. 清理构建文件 rm -rf dist/ build/ *.egg-info/ ``` ##### Git 标签和发布 ```bash # 1. 创建版本标签 git tag v1.0.2 git push origin v1.0.2 # 2. 推送代码 git push origin master # 3. 在 GitHub 创建 Release（可选） ``` ### 版本管理策略 #### 版本号含义 - **1.0.x**: 稳定版本，bug 修复 - **1.x.0**: 新功能版本 - **x.0.0**: 重大更新，可能不兼容 #### 发布频率建议 - **热修复**: 发现严重 bug 立即发布 - **功能更新**: 1-2周发布一次 - **大版本**: 1-3个月发布一次 #### 分支策略 ``` master (主分支，稳定版本) ├── develop (开发分支) ├── feature/xxx (功能分支) ├── hotfix/xxx (热修复分支) └── release/x.x.x (发布分支) ``` --- ## 🧪 本地测试指南 ### 测试目标 在本地环境中测试 DataMaster MCP 的完整功能，包括： - MCP 服务器启动和运行 - 与 MCP 客户端（如 Claude Desktop）的连接 - 数据分析功能验证 - 配置文件和环境变量测试 ### 方法一：直接运行测试（推荐） ```bash # 运行完整的自动化测试 python test_mcp_server.py # 如果所有测试通过，直接启动服务器 python start_mcp_server.py ``` ### 方法二：开发模式安装 ```bash # 在项目根目录执行 pip install -e . # 验证安装 datamaster-mcp --help # 或者直接启动 datamaster-mcp ``` ### 配置 MCP 客户端 #### Claude Desktop 配置 在 `claude_desktop_config.json` 中添加： ```json { "mcpServers": { "datamaster-mcp": { "command": "python", "args": [ "d:\\MCP\\SuperDataAnalysis_MCP\\datamaster_mcp\\main.py" ], "env": { "PYTHONPATH": "d:\\MCP\\SuperDataAnalysis_MCP" } } } } ``` **注意：** 请将路径替换为你的实际项目路径。 --- ## 📁 项目结构说明 ### 目录结构 ``` DataMaster_MCP/ ├── 📄 README.md # 项目概览和快速开始 ├── 📚 用户使用手册.md # 完整的功能使用指南 ├── 🛠️ 开发者文档.md # 技术文档和AI使用指南 ├── 📋 CHANGELOG.md # 版本更新记录 ├── ⚙️ main.py # MCP服务器主入口 ├── 📦 requirements.txt # 项目依赖包 ├── 🔧 .env.example # 环境变量模板 ├── 📝 .gitignore # Git忽略文件 ├── 📁 config/ # 配置管理模块 │ ├── 🔗 database_manager.py # 数据库管理器 │ ├── ⚙️ config_manager.py # 配置管理器 │ ├── 🌐 api_connector.py # API连接器 │ ├── 💾 api_data_storage.py # API数据存储 │ ├── 🔄 data_transformer.py # 数据转换器 │ ├── 📊 api_config_manager.py # API配置管理 │ ├── 🗃️ database_config.json # 数据库配置文件 │ ├── 🔌 api_config.json # API配置文件 │ └── 📋 __init__.py # 模块初始化 └── 📄 项目结构说明.md # 本文件 ``` ### 文档说明 #### 🚀 新用户入门 1. **README.md** - 项目概览，快速了解功能和基本使用 2. **用户使用手册.md** - 详细的功能使用指南，包含所有操作示例 #### 🛠️ 开发者和AI 1. **开发者文档.md** - 技术架构、AI使用指南、修复记录 2. **CHANGELOG.md** - 版本更新历史 ### 核心文件说明 #### 主程序 - **main.py** - MCP服务器主入口，包含所有工具函数定义 #### 配置管理 - **config/database_manager.py** - 数据库连接和查询管理 - **config/config_manager.py** - 配置文件管理和验证 - **config/api_connector.py** - API连接和数据获取 - **config/api_data_storage.py** - API数据持久化存储 - **config/data_transformer.py** - 数据格式转换 #### 配置文件 - **config/database_config.json** - 数据库连接配置 - **config/api_config.json** - API端点配置 - **.env.example** - 环境变量模板（复制为.env使用） --- ## 📝 开发规范 ### 代码规范 1. **函数命名**: 使用下划线命名法 2. **错误处理**: 统一返回JSON格式 3. **日志记录**: 关键操作记录日志 4. **参数验证**: 严格验证输入参数 ### 工具开发规范 1. **Docstring要求**: - 详细的功能说明 - 参数类型和说明 - 使用示例 - AI使用建议 2. **返回格式统一**: ```json { "status": "success|error|info", "message": "操作描述", "data": {}, "metadata": { "timestamp": "2024-01-01T12:00:00" } } ``` 3. **错误处理**: - 捕获所有异常 - 提供详细错误信息 - 给出解决建议 ### 配置管理规范 1. **敏感信息**: 使用环境变量 2. **配置文件**: JSON格式，支持注释 3. **默认值**: 提供合理的默认配置 4. **验证机制**: 配置加载时验证 --- ## 🧪 测试验证 ### 测试框架 使用自定义测试框架，包含： - 单元测试 - 集成测试 - 功能验证测试 ### 测试用例 1. **数据库连接测试** - 参数兼容性测试 - 连接超时测试 - 错误处理测试 2. **数据处理测试** - 文件导入测试 - SQL查询测试 - 数据分析测试 3. **API功能测试** - API连接测试 - 数据转换测试 - 存储功能测试 ### 测试命令 ```bash # 运行所有测试 python -m pytest tests/ # 运行特定测试 python test_fixes.py # 运行性能测试 python test_performance.py ``` --- ## 🚀 未来规划 ### 短期目标 (v1.1.0) - [ ] 数据可视化功能 - [ ] 机器学习集成 - [ ] 实时数据流处理 - [ ] Web界面支持 ### 长期目标 (v2.0.0) - [ ] 分布式数据处理 - [ ] 云服务集成 - [ ] 高级分析算法 - [ ] 企业级安全功能 --- ## 📞 开发支持 ### 贡献指南 1. Fork 项目仓库 2. 创建功能分支 3. 编写测试用例 4. 提交Pull Request ### 问题反馈 - **Bug报告**: 提供详细的错误信息和复现步骤 - **功能建议**: 描述需求和使用场景 - **文档改进**: 指出不清晰或错误的地方 --- **版本**: v1.0.0 **维护者**: Shan (学习AI1000天) **更新日期**: 2025年1月24日