chatExcel - Excel智能处理与数据分析MCP服务器

📋 项目概述

chatExcel 是一个基于 Model Context Protocol (MCP) 的智能 Excel 处理与数据分析服务器，专为复杂 Excel 文件的智能解析、数据处理和可视化设计。提供 14 个专业 MCP 工具，支持智能读取、数据验证、代码执行和交互式图表生成。

🎉 最新更新 (2025-06-10):

• ✅ 增强多级列头检测系统
• ✅ 优化参数推荐算法
• ✅ 完善数据验证功能
• ✅ 提升缓存性能
• ✅ 增强安全特性

✨ 核心特性

• 智能Excel处理: 自动检测编码、多级表头识别、参数推荐
• 安全代码执行: 沙箱环境支持 pandas/numpy 代码
• 交互式可视化: 基于 Plotly 的柱状图、饼图、折线图
• 数据质量验证: 完整性检查、质量评估、批量处理
• 缓存优化: 智能编码检测缓存，提升性能
• 复杂格式支持: 处理多级标题、合并单元格、不规则格式

🛠️ MCP工具列表 (14个)

工具名称	功能描述	支持格式
read_metadata	CSV 元数据读取与分析	CSV
read_excel_metadata	Excel 元数据读取与编码检测	Excel
suggest_excel_read_parameters_tool	智能推荐 Excel 读取参数	Excel
detect_excel_file_structure_tool	Excel 文件结构检测	Excel
create_excel_read_template_tool	生成 Excel 读取代码模板	Excel
run_excel_code	Excel 代码执行引擎	Excel
run_code	CSV 代码执行引擎	CSV
bar_chart_to_html	交互式柱状图生成	数据数组
pie_chart_to_html	交互式饼图生成	数据数组
line_chart_to_html	交互式折线图生成	数据数组
verify_data_integrity	数据完整性验证	Excel, CSV
validate_data_quality	数据质量验证与建议	Excel, CSV
comprehensive_data_verification_tool	综合数据验证	Excel, CSV
batch_data_verification_tool	批量数据验证	Excel, CSV

🚀 编码缓存优化

核心功能

• 智能缓存: 缓存文件编码检测结果
• 自动清理: 定期清除过期缓存
• 大小监控: 实时监控缓存大小
• 自动备份: 定期备份缓存数据
• 配置驱动: JSON 配置灵活控制参数

配置文件 (cache_config.json)

{
  "cache_settings": {
    "max_cache_size_mb": 10,
    "cache_expiry_days": 7,
    "auto_cleanup_interval": 10,
    "enable_auto_backup": true
  },
  "monitoring": {
    "enable_size_monitoring": true,
    "size_warning_threshold_mb": 8,
    "enable_performance_logging": false,
    "log_level": "INFO"
  },
  "maintenance": {
    "auto_reduce_cache_percentage": 50,
    "enable_startup_cleanup": true,
    "enable_periodic_optimization": true,
    "optimization_frequency": "weekly"
  },
  "paths": {
    "cache_directory": ".encoding_cache",
    "backup_directory": ".encoding_cache",
    "log_file": "cache_maintenance.log"
  }
}

使用方法

命令行工具

# 查看缓存统计
python cache_manager.py stats
# 清理过期缓存
python cache_manager.py cleanup
# 监控缓存大小
python cache_manager.py monitor
# 创建备份
python cache_manager.py backup
# 从备份恢复
python cache_manager.py restore

程序集成

from enhanced_excel_helper import EncodingCache
cache = EncodingCache(config_file="cache_config.json")
encoding = cache.get("/path/to/file.xlsx")
if not encoding:
    detected_encoding = detect_file_encoding("/path/to/file.xlsx")
    cache.set("/path/to/file.xlsx", detected_encoding)

📊 系统要求

• Python: 3.11+
• 操作系统: macOS, Linux, Windows
• 内存: 建议 4GB+
• 存储: 至少 500MB

🛠️ 安装部署

快速安装

git clone <repository-url>
cd chatExcel-mcp
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python scripts/health_check.py
python server.py

验证安装

python -c "import pandas as pd; print(f'Pandas {pd.__version__}')"
python -c "import numpy as np; print(f'NumPy {np.__version__}')"
python -c "import plotly; print(f'Plotly {plotly.__version__}')"
python test_complete_functionality.py

🔧 MCP配置

推荐配置 (mcp_config_flexible.json)

{
  "mcpServers": {
    "chatExcel": {
      "command": "python3",
      "args": ["server.py"],
      "cwd": "/path/to/chatExcel-mcp",
      "env": {
        "PATH": "/path/to/venv/bin:/usr/local/bin:/usr/bin:/bin",
        "VIRTUAL_ENV": "/path/to/venv",
        "PYTHONPATH": "/path/to/chatExcel-mcp"
      }
    }
  }
}

测试配置

cd /path/to/chatExcel-mcp
source venv/bin/activate
python server.py
python -c "import mcp; print('MCP包正常')"

📚 API功能

数据元数据读取

• read_metadata: CSV 元数据读取
• read_excel_metadata: Excel 元数据读取，支持复杂参数

代码执行

• run_code: CSV 数据处理代码执行
• run_excel_code: Excel 数据处理代码执行

图表生成

• bar_chart_to_html: 交互式柱状图
• pie_chart_to_html: 交互式饼图
• line_chart_to_html: 交互式折线图

数据质量验证

• validate_data_quality: 数据质量分析与建议
• comprehensive_data_verification_tool: 综合数据验证
• batch_data_verification_tool: 批量数据验证

🧪 测试验证

python test_complete_functionality.py
python test_enhanced_excel.py
python demo_excel_features.py
pytest tests/

🛡️ 安全特性

• 代码沙箱: 阻止危险操作
• 资源限制: 100MB 文件大小，30秒执行超时，1GB 内存限制
• 输入验证: 严格参数检查

🔧 故障排除

常见问题

• 模块导入失败: 激活虚拟环境，重新安装依赖
• 文件编码问题: 清理缓存或手动指定编码
• MCP服务器启动失败: 检查路径、权限、Python版本

诊断工具

python scripts/health_check.py
python -c "import sys, pandas, numpy, plotly; print(f'Python: {sys.version}, Pandas: {pandas.__version__}, NumPy: {numpy.__version__}, Plotly: {plotly.__version__}')"

📄 许可证

MIT 许可证，详见 LICENSE。

🤝 贡献指南

1. Fork 仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📞 联系方式

• 项目主页: GitHub Repository
• 问题反馈: Issues
• 文档: Wiki

chatExcel - 智能高效的 Excel 数据处理！ 🚀