What is Chatexcel Mcp

chatExcel-mcp is an intelligent Excel processing and data analysis server based on the Model Context Protocol (MCP). It is designed for smart parsing of Excel files, data processing, code execution, and interactive chart generation, supporting complex Excel formats and advanced data visualization.

Use cases

Use cases for chatExcel-mcp include automating Excel data processing tasks, generating interactive reports, validating data integrity in datasets, and executing custom data analysis scripts within a secure environment.

How to use

To use chatExcel-mcp, users can interact with the server through its provided MCP tools. Users can upload Excel files, utilize tools for data validation, execute code, and generate visualizations based on the data processed.

Key features

Key features of chatExcel-mcp include intelligent Excel processing, secure code execution in a sandbox environment, interactive visualizations using Plotly, data quality verification, and support for complex formats such as multi-level headers and merged cells.

Where to use

chatExcel-mcp can be used in various fields including data analysis, business intelligence, academic research, and any domain that requires efficient handling and visualization of Excel data.

ChatExcel MCP Server - 企业级增强版 v2.1.1

最新更新 (2025-06-19): pandas导入问题完全修复，项目结构优化完成，企业级功能全面就绪

🚀 企业级Excel智能处理与数据分析MCP服务器 - 基于FastMCP构建的高性能数据处理解决方案

chatExcel-mcp 是一个基于 MCP (Model Context Protocol) 的企业级 Excel 智能处理服务器，提供强大的 Excel 文件分析、数据处理、公式计算和可视化功能。

🚀 核心特性

📊 31个专业MCP工具

• 数据读取与元数据分析 (2个工具): 智能编码检测、结构分析
• 数据处理与执行 (9个工具): 安全代码执行、参数推荐、模板生成
• 数据可视化 (3个工具): 交互式图表生成(Chart.js)
• 数据验证与质量控制 (12个工具): 多级质量检查、智能清洗
• Excel公式处理 (5个工具): 公式解析、编译、执行、验证

🏗️ 双引擎架构

• Python引擎: 基于pandas/openpyxl的传统处理，支持复杂数据分析
• Go引擎: 高性能并发处理，适用于大规模数据处理(可选)

🧮 Excel公式引擎 (新增)

• 公式解析: AST语法分析和安全验证，支持复杂嵌套公式
• 公式编译: 代码生成和依赖分析，优化执行性能
• 公式执行: 安全执行环境和结果验证，支持上下文计算
• 依赖分析: 依赖图生成和循环检测，避免计算死锁
• 公式验证: 语法检查和风险评估，确保公式安全性

🔍 数据质量控制 (增强)

• 多级质量检查: 数据完整性、一致性、准确性全面验证
• 智能数据清洗: 自动化数据清理和格式标准化
• 批量处理: 并行处理多个Excel文件，提升处理效率
• 高级提取: 多条件数据提取和内容分析
• 智能合并: 多表格数据合并和配置化处理
• 字符格式转换: 自动化字符格式转换和规则配置

🛡️ 企业级安全

• 代码安全: AST分析和函数白名单，防止恶意代码执行
• 执行沙箱: 隔离执行环境，保护系统安全
• 权限控制: 细粒度访问控制和操作审计
• 依赖扫描: 智能依赖分析和安全漏洞检测

⚡ 性能优化

• 智能缓存: 多级缓存策略，减少重复计算
• 并发处理: 异步任务执行，提升处理速度
• 内存管理: 大文件分块处理，优化内存使用
• 错误恢复: 自动重试机制和健康监控

📋 项目概述

ChatExcel MCP Server 是一个功能强大的模型上下文协议(MCP)服务器，专门为Excel文件处理、数据分析和可视化而设计。项目集成了Python生态系统的最佳数据处理库，并通过Go excelize库提供高性能Excel操作能力。

🎯 核心特性

• 31个专业MCP工具 - 覆盖数据读取、处理、验证、可视化、公式计算、数据质量控制全流程
• 双引擎架构 - Python pandas + Go excelize 混合处理引擎
• Excel公式引擎 - 基于formulas库的完整Excel公式解析、编译和执行系统
• 数据质量控制 - 7个专业数据质量工具，支持高级数据清洗和验证
• 智能参数推荐 - 自动检测Excel文件结构并推荐最佳读取参数
• 企业级安全 - 多层安全机制，代码沙箱执行环境，公式安全验证
• 性能优化 - 缓存机制、并发处理、内存优化
• 健康监控 - 完整的服务监控、日志记录和错误追踪
• 可视化支持 - 交互式图表生成(Chart.js、Plotly、Matplotlib)

🛠️ MCP工具列表

本项目提供 31个专业MCP工具，覆盖Excel数据处理、分析、验证、公式计算和数据质量控制的完整生命周期。

📊 数据读取与元数据工具 (4个)

🔧 数据处理与执行工具 (6个)

📈 数据可视化工具 (3个)

🔍 数据验证与质量工具 (3个)

🤖 智能辅助工具 (3个)

🧮 Excel公式处理工具 (5个)

🔍 数据质量控制工具 (7个) - 新增

📋 Workflow使用手册 - 31个MCP工具全流程指南

本章节按照用户实际使用场景和数据处理全流程，将31个MCP工具进行分类关联，提供完整的workflow使用指南。

🎯 数据处理全流程概览

flowchart TD
    A[📁 数据源] --> B[🔍 数据探索阶段]
    B --> C[📊 数据读取阶段]
    C --> D[🔧 数据处理阶段]
    D --> E[✅ 数据验证阶段]
    E --> F[📈 数据可视化阶段]
    F --> G[🧮 公式计算阶段]
    G --> H[🔍 质量控制阶段]
    H --> I[📤 数据输出阶段]
    
    B --> B1[文件结构检测]
    B --> B2[元数据分析]
    B --> B3[参数推荐]
    
    C --> C1[智能读取]
    C --> C2[编码检测]
    C --> C3[模板生成]
    
    D --> D1[代码执行]
    D --> D2[数据转换]
    D --> D3[批量处理]
    
    E --> E1[完整性验证]
    E --> E2[质量检查]
    E --> E3[数据比对]
    
    F --> F1[图表生成]
    F --> F2[交互可视化]
    F --> F3[报告输出]
    
    G --> G1[公式解析]
    G --> G2[公式执行]
    G --> G3[依赖分析]
    
    H --> H1[数据清洗]
    H --> H2[格式转换]
    H --> H3[多表合并]
    
    I --> I1[Excel写入]
    I --> I2[图表嵌入]
    I --> I3[性能对比]

🚀 阶段一：数据探索与准备 (7个工具)

📋 使用场景

当您拿到一个新的Excel文件时，首先需要了解文件结构、数据特征和最佳读取方式。

🛠️ 核心工具组合

💡 Workflow示例

📊 阶段二：数据读取与加载 (4个工具)

📋 使用场景

基于探索阶段的分析结果，执行高效、准确的数据读取操作。

🛠️ 核心工具组合

💡 Workflow示例

🔧 阶段三：数据处理与转换 (6个工具)

📋 使用场景

对读取的数据进行清洗、转换、计算和处理操作。

🛠️ 核心工具组合

💡 Workflow示例

✅ 阶段四：数据验证与质量控制 (10个工具)

📋 使用场景

确保数据质量、完整性和准确性，是数据处理流程中的关键环节。

🛠️ 核心工具组合

🔍 基础验证工具 (3个)

🧹 高级质量控制工具 (7个)

💡 Workflow示例

📈 阶段五：数据可视化与报告 (3个工具)

📋 使用场景

将处理后的数据转换为直观的图表和交互式可视化报告。

🛠️ 核心工具组合

💡 Workflow示例

🧮 阶段六：Excel公式处理与计算 (5个工具)

📋 使用场景

处理复杂的Excel公式、进行高级计算和依赖关系分析。

🛠️ 核心工具组合

💡 Workflow示例

🎯 完整Workflow集成示例

📋 端到端数据处理流程

📚 最佳实践建议

🎯 工具选择策略

1. 小文件 (<10MB): 使用Python引擎工具，响应快速
2. 大文件 (>50MB): 优先使用Go引擎工具，性能更佳
3. 复杂公式: 必须使用公式处理工具链，确保安全性
4. 批量处理: 使用批量工具，提升效率
5. 质量要求高: 使用完整质量控制流程

⚡ 性能优化建议

1. 缓存策略: 重复操作启用缓存机制
2. 并发处理: 批量任务使用并发工具
3. 内存管理: 大文件使用分块处理
4. 引擎选择: 根据性能测试结果选择最佳引擎

🔒 安全使用原则

1. 代码执行: 始终在沙箱环境中执行
2. 公式处理: 必须进行安全验证
3. 文件访问: 验证文件路径和权限
4. 资源限制: 设置合理的超时和内存限制

🧮 Excel公式处理功能详解

功能概述

基于 formulas==1.2.10 库构建的完整Excel公式处理系统，提供从解析到执行的全流程支持。

核心工具详解

1. parse_formula - 公式解析器

# 解析Excel公式并获取AST结构
result = parse_formula("=SUM(A1:A10)*2", validate_security=True)
# 返回: 语法树、函数列表、引用单元格、安全状态

2. compile_workbook - 工作簿编译器

# 将Excel文件编译为Python代码或JSON结构
result = compile_workbook("/path/to/file.xlsx", output_format="python")
# 支持格式: 'python', 'json'

3. execute_formula - 公式执行引擎

# 在指定上下文中执行Excel公式
context = '{"A1": 10, "A2": 20}'
result = execute_formula("=A1+A2", context)
# 返回: 计算结果、执行状态、性能指标

4. analyze_dependencies - 依赖分析器

# 分析Excel文件中的公式依赖关系
result = analyze_dependencies("/path/to/file.xlsx")
# 返回: 依赖图、循环检测、影响分析

5. validate_formula - 公式验证器

# 验证公式的安全性和有效性
result = validate_formula("=SUM(A1:A10)")
# 返回: 安全评估、语法检查、风险等级

安全特性

• AST安全分析: 检测潜在的恶意代码模式
• 函数白名单: 仅允许安全的Excel函数
• 引用验证: 验证单元格引用的合法性
• 执行沙箱: 隔离的公式执行环境

性能优化

• 缓存机制: 解析结果智能缓存
• 并发支持: 多公式并行处理
• 内存管理: 大文件分块处理
• 错误恢复: 优雅的异常处理

📋 版本更新日志

v2.1.1 (2025-06-19) - pandas导入修复版

🔧 关键修复

• ✅ pandas导入问题完全修复: 彻底解决MCP服务器中pandas导入失败的问题
  • 增强了fallback_enhanced_run_excel_code函数的执行环境
  • 添加了多种pandas和numpy引用方式支持 (pd, pandas, np, numpy)
  • 完善了内置函数和常用模块的导入
  • 改进了错误处理和返回格式
• ✅ 项目结构优化: 完成项目文件整理和结构优化
  • 移动文档文件到record/目录统一管理
  • 清理冗余文件，优化目录结构
  • 完善配置文件和依赖管理

🆕 新增模块

• enhanced_globals_config.py - 增强的全局配置模块
• pandas_fix_patch.py - pandas导入修复补丁
• mcp_pandas_integration.py - MCP服务器集成修复模块
• 完整的测试验证套件

v2.1.0 (2025-06-18) - 企业级增强版

🎉 重大更新

• ✅ tabulate库完全集成: 彻底解决tabulate ImportError问题，支持pandas.to_markdown()功能
• ✅ Excel公式引擎增强: 基于formulas==1.2.10的完整公式处理系统
• ✅ 31个MCP工具: 新增7个数据质量控制工具，覆盖完整数据处理生命周期
• ✅ 安全机制优化: 增强代码执行沙箱，完善安全验证机制
• ✅ 性能提升: Go excelize集成，缓存机制，并发处理优化
• ✅ 健康监控: 完整的服务监控、日志记录和错误追踪系统
• ✅ 环境兼容性: 完善的虚拟环境支持和依赖检查

v2.0.0 (2025-06-18) - 重大更新

🎉 重大更新

• ✅ MCP工具扩展: 从24个扩展到31个专业工具
• ✅ 双引擎架构: Python + Go高性能处理
• ✅ 数据验证增强: 多级验证和质量控制
• ✅ 可视化升级: Chart.js交互式图表
• ✅ 安全加固: 代码执行沙箱和权限控制
• ✅ 解除tabulate库限制: 完全移除对tabulate库的安全限制，支持表格格式化功能
• ✅ 安全配置优化: 更新security.json配置，将tabulate添加到安全模块列表
• ✅ 代码执行增强: 优化secure_code_executor.py，提升代码执行安全性
• ✅ 测试覆盖完善: 新增tabulate库独立测试和MCP集成测试
• ✅ 文档更新: 完善README和requirements.txt版本信息

🚀 快速开始

📋 环境要求

📦 依赖管理

核心依赖

• MCP协议: mcp>=1.9.4, fastmcp>=2.8.0
• 数据处理: pandas>=1.5.3, numpy>=1.26.4, pandasai>=2.3.0
• Excel处理: openpyxl>=3.1.5, xlsxwriter>=3.2.5
• 机器学习: torch>=2.1.0, transformers>=4.39.2, scikit-learn>=1.2.2
• 可视化: matplotlib>=3.10.1, seaborn>=0.13.2, plotly>=6.0.1
• Web服务: fastapi>=0.115.12, uvicorn>=0.30.6, gradio>=5.23.3

📦 依赖兼容性说明

本项目已解决以下依赖冲突问题：

• ✅ pandas导入修复: 完全解决MCP环境中pandas导入失败问题 (v2.1.1)
• ✅ 执行环境增强: 支持多种pandas/numpy引用方式 (pd, pandas, np, numpy)
• ✅ Torch版本: 降级至 torch==2.1.0 以兼容 torchvision==0.16.0
• ✅ PandasAI兼容: 升级至 pandasai==2.3.0 并保持 pandas==1.5.3
• ✅ Pydantic版本: 升级至 pydantic==2.11.7 以支持MCP和其他现代依赖
• ✅ SSL证书问题: 提供 --trusted-host 参数解决方案
• ✅ 项目结构优化: 文档整理到record/目录，清理冗余文件

故障排除

如果遇到依赖冲突，请按以下步骤操作：

1. 检查依赖状态

pip check
python scripts/health_check.py

2. 重新安装依赖

pip uninstall -y torch torchvision pandasai pandas pydantic
pip install torch==2.1.0 torchvision==0.16.0 --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org
pip install pandasai==2.3.0 --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org
pip install "pydantic>=2.7.2" --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org

3. 验证修复

pip check
python scripts/health_check.py
### ⚡ 一键部署 (推荐)

```bash
# 1. 克隆项目
git clone https://github.com/chatexcel/chatExcel-mcp.git
cd chatExcel-mcp

# 2. 一键部署（自动安装依赖、配置环境、启动服务）
./start.sh

# 3. 验证部署状态
python scripts/health_check.py

🔧 手动部署

# 1. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或 venv\Scripts\activate  # Windows

# 2. 安装依赖
pip install -r requirements.txt --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org

# 3. 启动GO服务 (可选，用于高性能Excel处理)
cd excel-service
go run main.go &
cd ..

# 4. 启动MCP服务器
python server.py

📊 服务状态验证

# 检查服务健康状态
curl http://localhost:8080/api/v1/health  # GO服务
python scripts/health_check.py            # 完整系统检查

🔧 手动安装

步骤1: 环境准备

# 克隆项目
git clone https://github.com/chatexcel/chatExcel-mcp.git
cd chatExcel-mcp

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

步骤2: 安装依赖

# 升级pip
pip install --upgrade pip

# 如果遇到SSL证书问题，使用以下命令
pip install -r requirements.txt --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org

# 或者正常安装
pip install -r requirements.txt

# 验证安装
python3 check_dependencies.py

# 运行健康检查脚本
python scripts/health_check.py

# 检查依赖冲突
pip check

步骤3: 配置服务

# 生成MCP配置文件
python3 generate_mcp_config.py

# 检查环境配置
python3 check_env.py

步骤4: 启动服务

# 启动标准服务器
python3 server.py

# 或启动增强版服务器（推荐）
python3 enhanced_server.py

# 后台运行
nohup python3 server.py > chatexcel.log 2>&1 &

🐳 Docker部署

使用预构建镜像

# 拉取镜像
docker pull chatexcel/mcp-server:latest

# 运行容器
docker run -d \
  --name chatexcel-mcp \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  chatexcel/mcp-server:latest

本地构建

# 构建镜像
docker build -t chatexcel-mcp .

# 运行容器
docker run -d \
  --name chatexcel-mcp \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  chatexcel-mcp

🔍 安装验证

# 运行健康检查
python3 scripts/health_check.py

# 运行功能测试
python3 test/quick_test.py

# 验证MCP工具
python3 comprehensive_mcp_test.py

# 检查服务状态
curl http://localhost:8080/health

🔧 开发指南

项目结构

chatExcel-mcp/
├── chatexcel_mcp/          # 主要源代码
│   ├── __init__.py
│   ├── server.py           # MCP服务器主文件
│   ├── tools/              # 工具模块
│   │   ├── excel_tools.py  # Excel操作工具
│   │   ├── chart_tools.py  # 图表生成工具
│   │   └── ai_tools.py     # AI分析工具
│   └── utils/              # 工具函数
├── tests/                  # 测试文件（已创建）
├── docs/                   # 文档
├── examples/               # 示例文件
├── scripts/                # 脚本文件
│   └── health_check.py     # 健康检查脚本
├── requirements.txt        # 依赖列表（已更新）
├── pyproject.toml         # 项目配置（已更新）
└── README.md              # 项目说明

环境健康检查

项目包含完整的健康检查机制：

# 运行完整健康检查
python scripts/health_check.py

健康检查包括：

• ✅ Python版本验证
• ✅ 虚拟环境检测
• ✅ 依赖包版本验证
• ✅ 项目文件结构完整性
• ✅ 服务器模块导入测试

版本兼容性

当前环境已验证兼容：

• Python: 3.8+
• Torch: 2.1.0 (兼容 torchvision 0.16.0)
• PandasAI: 2.3.0 (兼容 pandas 1.5.3)
• Pydantic: 2.11.7 (支持MCP 1.9.4)
• 所有依赖: 无冲突状态

🔧 MCP配置与集成

MCP客户端配置

Claude Desktop配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "chatexcel": {
      "command": "python3",
      "args": [
        "/path/to/chatExcel-mcp2.0/server.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/chatExcel-mcp2.0"
      }
    }
  }
}

自动配置生成

# 生成MCP配置文件
python3 generate_mcp_config.py

# 查看生成的配置
cat mcp_config_absolute.json

环境变量配置

创建 .env 文件：

# 服务配置
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8080
MCP_LOG_LEVEL=INFO

# Excel处理配置
EXCEL_MAX_FILE_SIZE=100MB
EXCEL_CACHE_ENABLED=true
EXCEL_GO_SERVICE_URL=http://localhost:8081

# 安全配置
CODE_EXECUTION_TIMEOUT=30
MAX_MEMORY_USAGE=1GB
SECURE_MODE=true

📖 使用示例

🔍 基础Excel读取

# 使用MCP工具读取Excel文件
result = await mcp_client.call_tool(
    "read_excel_metadata",
    {"file_path": "/path/to/your/file.xlsx"}
)

print(f"工作表数量: {result['sheets_count']}")
print(f"数据行数: {result['total_rows']}")
print(f"编码格式: {result['encoding']}")

🤖 智能参数推荐

# 获取最佳读取参数
params = await mcp_client.call_tool(
    "suggest_excel_read_parameters_tool",
    {"file_path": "/path/to/complex.xlsx"}
)

# 使用推荐参数读取
data = await mcp_client.call_tool(
    "excel_read_enhanced",
    {
        "file_path": "/path/to/complex.xlsx",
        **params["recommended_params"]
    }
)

print(f"读取成功，数据形状: {data['shape']}")

📊 数据处理与分析

# 执行数据分析代码
analysis = await mcp_client.call_tool(
    "run_excel_code",
    {
        "file_path": "/path/to/data.xlsx",
        "code": """
        # 数据清洗和分析
        df_clean = df.dropna()
        summary = df_clean.describe()
        correlation = df_clean.corr()
        
        # 数据质量检查
        missing_data = df.isnull().sum()
        duplicate_rows = df.duplicated().sum()
        
        print("=== 数据摘要 ===")
        print(summary)
        print(f"\n缺失数据: {missing_data.sum()}")
        print(f"重复行数: {duplicate_rows}")
        """
    }
)

📈 可视化图表生成

# 生成交互式柱状图
chart = await mcp_client.call_tool(
    "bar_chart_to_html",
    {
        "labels": ["Q1", "Q2", "Q3", "Q4"],
        "datasets": [
            {
                "label": "销售额(万元)",
                "data": [120, 150, 180, 200],
                "backgroundColor": "rgba(54, 162, 235, 0.6)"
            }
        ],
        "title": "2024年季度销售报告",
        "options": {
            "responsive": True,
            "plugins": {
                "legend": {"display": True}
            }
        }
    }
)

print(f"图表已生成: {chart['filepath']}")

🧮 Excel公式处理

# 解析Excel公式
formula_result = await mcp_client.call_tool(
    "parse_formula",
    {
        "formula": "=SUM(A1:A10)*0.1+AVERAGE(B1:B10)",
        "validate_security": True
    }
)

print(f"公式解析成功: {formula_result['is_valid']}")
print(f"引用单元格: {formula_result['references']}")

# 执行公式
execute_result = await mcp_client.call_tool(
    "execute_formula",
    {
        "formula": "=A1+B1",
        "context": '{"A1": 10, "B1": 20}'
    }
)

print(f"计算结果: {execute_result['result']}")

🔍 数据质量控制

# 增强数据质量检查
quality_check = await mcp_client.call_tool(
    "enhanced_data_quality_check",
    {
        "file_path": "/path/to/data.xlsx",
        "check_types": ["completeness", "consistency", "accuracy"],
        "generate_report": True
    }
)

print(f"数据质量评分: {quality_check['quality_score']}")
print(f"发现问题: {len(quality_check['issues'])}")

# 批量数据验证
batch_verification = await mcp_client.call_tool(
    "batch_data_verification_tool",
    {
        "file_paths": [
            "/path/to/file1.xlsx",
            "/path/to/file2.xlsx"
        ],
        "verification_rules": {
            "check_duplicates": True,
            "validate_formats": True,
            "check_completeness": True
        }
    }
)

print(f"批量验证完成，处理文件数: {batch_verification['processed_count']}")

🏗️ 项目架构

系统架构图

graph TB
    A[MCP Client] --> B[FastMCP Server]
    B --> C[Tool Router]
    C --> D[Excel Engine]
    C --> E[Data Engine]
    C --> F[Chart Engine]
    
    D --> G[Python pandas]
    D --> H[Go excelize]
    D --> I[openpyxl]
    
    E --> J[Data Validator]
    E --> K[Code Executor]
    E --> L[Cache Manager]
    
    F --> M[Chart.js]
    F --> N[Plotly]
    F --> O[Matplotlib]
    
    P[Security Layer] --> C
    Q[Monitoring] --> B
    R[Logging] --> B

核心模块

📁 主要文件结构

chatExcel-mcp/
├── server.py                 # 主服务器文件（19个MCP工具）
├── enhanced_server.py        # 增强版服务器
├── config.py                 # 配置管理
├── excel_enhanced_tools.py   # Excel增强工具
├── excel_smart_tools.py      # Excel智能工具
├── data_verification.py      # 数据验证引擎
├── comprehensive_data_verification.py  # 综合数据验证
├── excel-service/           # Go excelize服务
│   ├── main.go
│   ├── go.mod
│   └── go.sum
├── templates/               # 图表模板
│   ├── barchart_template.html
│   ├── linechart_template.html
│   └── piechart_template.html
├── scripts/                 # 运维脚本
│   ├── deploy.py
│   ├── health_check.py
│   └── maintenance.sh
├── config/                  # 配置文件
│   ├── runtime.yaml
│   ├── security.json
│   └── system.json
└── tests/                   # 测试套件
    ├── unit/
    ├── integration/
    └── performance/

🔧 引擎类设计

• ExcelEnhancedProcessor: 高性能Excel处理引擎
• DataVerificationEngine: 数据验证和质量检查引擎
• ComprehensiveDataVerifier: 综合数据验证器
• SecureCodeExecutor: 安全代码执行器

数据流架构

Excel处理流程

sequenceDiagram
    participant C as Client
    participant S as Server
    participant E as Excel Engine
    participant G as Go Service
    participant P as Python Engine
    
    C->>S: 调用excel_read_enhanced
    S->>E: 路由到Excel引擎
    E->>G: 尝试Go excelize
    alt Go服务可用
        G-->>E: 返回高性能结果
    else Go服务不可用
        E->>P: 降级到pandas
        P-->>E: 返回标准结果
    end
    E-->>S: 返回处理结果
    S-->>C: 返回最终结果

数据验证流程

sequenceDiagram
    participant C as Client
    participant S as Server
    participant V as Validator
    participant R as Reporter
    
    C->>S: 调用verify_data_integrity
    S->>V: 启动验证引擎
    V->>V: 结构验证
    V->>V: 数据类型检查
    V->>V: 完整性验证
    V->>V: 统计分析
    V->>R: 生成验证报告
    R-->>S: 返回详细报告
    S-->>C: 返回验证结果

代码执行流程

sequenceDiagram
    participant C as Client
    participant S as Server
    participant SE as Security Engine
    participant EX as Executor
    participant M as Monitor
    
    C->>S: 调用run_excel_code
    S->>SE: 安全检查
    SE->>SE: 黑名单过滤
    SE->>SE: 语法验证
    SE-->>S: 安全通过
    S->>EX: 沙箱执行
    EX->>M: 监控执行
    M->>M: 资源监控
    M->>M: 超时检查
    EX-->>S: 返回执行结果
    S-->>C: 返回最终结果

性能优化架构

缓存机制

graph LR
    A[请求] --> B{缓存检查}
    B -->|命中| C[返回缓存]
    B -->|未命中| D[处理请求]
    D --> E[更新缓存]
    E --> F[返回结果]
    
    G[缓存策略]
    G --> H[LRU淘汰]
    G --> I[TTL过期]
    G --> J[内存限制]

并发处理

# 并发处理示例
class ConcurrentProcessor:
    def __init__(self, max_workers=4):
        self.executor = ThreadPoolExecutor(max_workers=max_workers)
        self.semaphore = asyncio.Semaphore(max_workers)
    
    async def process_batch(self, tasks):
        async with self.semaphore:
            futures = [self.executor.submit(task) for task in tasks]
            results = await asyncio.gather(*futures)
            return results

安全架构设计

多层安全防护

graph TB
    A[用户请求] --> B[输入验证层]
    B --> C[权限检查层]
    C --> D[代码安全层]
    D --> E[执行沙箱层]
    E --> F[输出过滤层]
    F --> G[审计日志层]
    
    H[安全策略]
    H --> I[黑名单过滤]
    H --> J[白名单验证]
    H --> K[资源限制]
    H --> L[超时控制]

错误处理机制

graph LR
    A[异常发生] --> B{异常类型}
    B -->|安全异常| C[安全日志]
    B -->|业务异常| D[业务日志]
    B -->|系统异常| E[系统日志]
    
    C --> F[告警通知]
    D --> G[用户反馈]
    E --> H[运维通知]
    
    F --> I[安全响应]
    G --> J[错误恢复]
    H --> K[系统修复]

扩展性设计

插件架构

# 插件接口定义
class MCPToolPlugin:
    def __init__(self, name: str, version: str):
        self.name = name
        self.version = version
    
    def register_tools(self, mcp_server):
        """注册MCP工具"""
        raise NotImplementedError
    
    def initialize(self, config: dict):
        """初始化插件"""
        pass
    
    def cleanup(self):
        """清理资源"""
        pass

# 插件管理器
class PluginManager:
    def __init__(self):
        self.plugins = {}
    
    def load_plugin(self, plugin_class, config=None):
        plugin = plugin_class()
        plugin.initialize(config or {})
        self.plugins[plugin.name] = plugin
        return plugin

配置管理

# 动态配置示例
class ConfigManager:
    def __init__(self, config_path="config/"):
        self.config_path = Path(config_path)
        self.configs = {}
        self.watchers = {}
    
    def load_config(self, name: str) -> dict:
        config_file = self.config_path / f"{name}.yaml"
        with open(config_file, 'r') as f:
            config = yaml.safe_load(f)
        self.configs[name] = config
        return config
    
    def watch_config(self, name: str, callback):
        """监控配置文件变化"""
        self.watchers[name] = callback

监控与运维架构

健康检查

# 健康检查示例
class HealthChecker:
    def __init__(self):
        self.checks = {
            "database": self.check_database,
            "cache": self.check_cache,
            "disk_space": self.check_disk_space,
            "memory": self.check_memory
        }
    
    async def run_health_check(self) -> dict:
        results = {}
        for name, check_func in self.checks.items():
            try:
                results[name] = await check_func()
            except Exception as e:
                results[name] = {"status": "error", "error": str(e)}
        
        overall_status = "healthy" if all(
            r.get("status") == "healthy" for r in results.values()
        ) else "unhealthy"
        
        return {
            "status": overall_status,
            "checks": results,
            "timestamp": datetime.utcnow().isoformat()
        }

日志与监控

graph TB
    A[应用日志] --> B[日志收集器]
    C[性能指标] --> D[指标收集器]
    E[错误追踪] --> F[错误收集器]
    
    B --> G[日志存储]
    D --> H[指标存储]
    F --> I[错误存储]
    
    G --> J[日志分析]
    H --> K[监控告警]
    I --> L[错误分析]
    
    J --> M[运维仪表板]
    K --> M
    L --> M

🧪 测试与验证

运行测试套件

# 运行所有测试
python3 -m pytest tests/ -v

# 运行特定测试
python3 comprehensive_mcp_test.py
python3 final_verification.py

# 性能测试
python3 test/performance/benchmark.py

健康检查

# 服务健康检查
curl http://localhost:8080/health

# 详细诊断
python3 diagnose_mcp_setup.py

# Excel功能验证
python3 demo_excel_features.py

核心依赖验证

# NumPy和Pandas功能验证
python3 -c "import numpy as np; import pandas as pd; print('✅ 核心依赖正常')"

# Excel智能处理功能测试
python3 test_excel_smart_features.py

# Go服务连接测试
python3 excel_go_client.py --test

🔒 安全考虑

代码执行安全

• 黑名单过滤: 禁止危险操作（os, sys, subprocess等）
• 沙箱环境: 隔离代码执行环境
• 资源限制: 内存、CPU、执行时间限制
• 输入验证: 严格的参数验证和类型检查

文件访问安全

• 路径验证: 防止目录遍历攻击
• 文件大小限制: 防止大文件攻击
• 格式验证: 确保文件格式正确性
• 权限检查: 文件读写权限验证

网络安全

• HTTPS支持: 加密传输
• 认证机制: API密钥验证
• 速率限制: 防止DDoS攻击
• 审计日志: 完整的操作记录

🛠️ 运维工具

自动化脚本

# 部署脚本
./scripts/deploy.py --env production

# 健康检查
./scripts/health_check.py --detailed

# 维护脚本
./scripts/maintenance.sh --clean-cache

# 依赖更新
./scripts/update_dependencies.sh

缓存管理

# 清理缓存
python3 cache_manager.py --clean

# 缓存统计
python3 cache_manager.py --stats

# 缓存配置
vim cache_config.json

日志管理

# 查看实时日志
tail -f logs/chatExcel.log

# 日志分析
python3 scripts/log_analyzer.py --date today

# 日志轮转
logrotate config/logrotate.conf

⚡ 性能优化

内存优化

• 分块读取: 大文件分块处理
• 内存池: 对象重用机制
• 垃圾回收: 主动内存清理
• 缓存策略: LRU缓存淘汰

并发优化

• 异步处理: asyncio并发模型
• 线程池: CPU密集型任务并行
• 连接池: 数据库连接复用
• 队列机制: 任务队列管理

I/O优化

• 批量操作: 减少I/O次数
• 压缩传输: 数据压缩传输
• 预读取: 智能数据预加载
• 缓存命中: 提高缓存命中率

🐛 故障排除

📋 快速诊断

# 运行全面诊断工具
python3 diagnose_mcp_setup.py

# 检查系统健康状态
python3 scripts/health_check.py --detailed

# 验证所有依赖
python3 check_dependencies.py

🔧 常见问题解决方案

1. 🚫 服务启动失败

问题症状: 服务无法启动或立即退出

# 检查端口占用
lsof -i :8080
# 如果端口被占用，杀死进程或更换端口
kill -9 <PID>

# 检查Python环境
which python3
python3 --version

# 检查依赖完整性
pip check
pip list | grep -E "fastmcp|pandas|openpyxl"

# 查看详细错误日志
python3 server.py --debug
# 或查看日志文件
tail -f chatExcel.log

解决方案:

# 重新安装依赖
pip install --upgrade --force-reinstall -r requirements.txt

# 清理缓存
pip cache purge
python3 -c "import shutil; shutil.rmtree('.encoding_cache', ignore_errors=True)"

# 使用不同端口启动
MCP_SERVER_PORT=8081 python3 server.py

2. 📊 Excel读取失败

问题症状: 无法读取Excel文件或读取结果异常

# 检查文件权限和格式
ls -la /path/to/file.xlsx
file /path/to/file.xlsx

# 验证文件完整性
python3 -c "import openpyxl; wb=openpyxl.load_workbook('/path/to/file.xlsx'); print('文件正常')"

# 测试基础读取功能
python3 test/simple_test.py /path/to/file.xlsx

解决方案:

# 修复文件权限
chmod 644 /path/to/file.xlsx

# 使用不同的读取引擎
python3 -c "
import pandas as pd
# 尝试不同引擎
for engine in ['openpyxl', 'xlrd']:
    try:
        df = pd.read_excel('/path/to/file.xlsx', engine=engine)
        print(f'{engine} 引擎成功')
        break
    except Exception as e:
        print(f'{engine} 引擎失败: {e}')
"

# 检查编码问题
python3 utils/encoding_detector.py /path/to/file.xlsx

3. 🔗 Go服务连接失败

问题症状: Go excelize服务无法连接或响应超时

# 检查Go服务状态
ps aux | grep excel-service
lsof -i :8081

# 测试Go服务连接
curl -v http://localhost:8081/health
telnet localhost 8081

解决方案:

# 重新编译Go服务
cd excel-service
go mod tidy
go build -o excel-service main.go

# 启动Go服务
./excel-service &

# 如果Go不可用，禁用Go服务
export EXCEL_GO_SERVICE_ENABLED=false
python3 server.py

4. 🔒 权限和安全问题

问题症状: 代码执行被阻止或安全检查失败

# 检查安全配置
cat config/security.json

# 测试安全模式
python3 -c "
from security.secure_code_executor import SecureCodeExecutor
executor = SecureCodeExecutor()
result = executor.execute('print(\"Hello World\")')
print(result)
"

解决方案:

# 调整安全配置（谨慎操作）
vim config/security.json

# 临时禁用严格模式（仅用于调试）
export SECURE_MODE=false
python3 server.py

# 检查黑名单配置
python3 -c "from config import SECURITY_CONFIG; print(SECURITY_CONFIG['blacklisted_modules'])"

5. 💾 内存和性能问题

问题症状: 处理大文件时内存不足或响应缓慢

# 监控内存使用
top -p $(pgrep -f server.py)

# 检查缓存状态
python3 cache_manager.py --stats

# 清理缓存
python3 cache_manager.py --clean

解决方案:

# 调整内存限制
export MAX_MEMORY_USAGE=2GB
export EXCEL_MAX_FILE_SIZE=50MB

# 启用分块处理
export CHUNK_SIZE=10000
python3 server.py

# 优化缓存配置
vim cache_config.json

🔍 调试工具

基础调试

# 简单功能测试
python3 test/simple_debug.py

# MCP工具测试
python3 comprehensive_mcp_test.py

# 快速验证
python3 test/quick_test.py

高级调试

# 性能分析
python3 -m cProfile -o profile.stats server.py
python3 -c "import pstats; p=pstats.Stats('profile.stats'); p.sort_stats('cumulative').print_stats(10)"

# 内存分析
python3 -m memory_profiler server.py

# 网络调试
netstat -tulpn | grep :8080
ss -tulpn | grep :8080

日志分析

# 实时日志监控
tail -f chatExcel.log | grep -E "ERROR|WARNING"

# 日志统计分析
python3 scripts/log_analyzer.py --date today --level ERROR

# 清理旧日志
find . -name "*.log" -mtime +7 -delete

📞 获取帮助

如果以上解决方案无法解决问题，请：

1. 收集诊断信息:

   python3 diagnose_mcp_setup.py > diagnosis.txt
   python3 --version >> diagnosis.txt
   pip list >> diagnosis.txt
   

2. 创建最小复现示例:

   python3 test/create_minimal_test.py
   

3. 提交Issue: 访问 GitHub Issues 并附上诊断信息

📄 许可证

本项目采用 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

开发规范

• 遵循 PEP 8 代码风格
• 添加适当的测试用例
• 更新相关文档
• 确保所有测试通过

代码质量检查

# 代码格式化
black .

# 代码检查
flake8 .

# 类型检查
mypy .

# 安全检查
bandit -r .

📞 联系方式

• 项目维护者: ChatExcel Team
• 问题反馈: GitHub Issues
• 功能建议: GitHub Discussions
• 技术支持: [email protected]

🙏 致谢

感谢以下开源项目的支持：

• FastMCP - MCP服务器框架
• pandas - 数据分析库
• openpyxl - Excel文件处理
• excelize - Go Excel库
• formulas - Excel公式解析和执行引擎
• Chart.js - 图表可视化
• Plotly - 交互式图表