Chat Excel MCP

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

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

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

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

](https://python.org)  ](https://golang.org)  ](pyproject.toml)    

🚀 核心特性

📊 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. 小文件 (50MB): 优先使用Go引擎工具，性能更佳
2. 复杂公式: 必须使用公式处理工具链，确保安全性
3. 批量处理: 使用批量工具，提升效率
4. 质量要求高: 使用完整质量控制流程

⚡ 性能优化建议

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

1. 重新安装依赖

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

1. 验证修复

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

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

检查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**: 访问  并附上诊断信息

## 📄 许可证

本项目采用 [MIT License](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](https://www.python.org/dev/peps/pep-0008/) 代码风格
- 添加适当的测试用例
- 更新相关文档
- 确保所有测试通过

### 代码质量检查

代码格式化

black .

代码检查

flake8 .

类型检查

mypy .

安全检查

bandit -r .

## 📞 联系方式

- **项目维护者**: ChatExcel Team
- **问题反馈**: 
- **功能建议**: 
- **技术支持**: lillardw459@gmail.com

## 🙏 致谢

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

- [FastMCP](https://github.com/jlowin/fastmcp) - MCP服务器框架
- [pandas](https://pandas.pydata.org/) - 数据分析库
- [openpyxl](https://openpyxl.readthedocs.io/) - Excel文件处理
- [excelize](https://github.com/qax-os/excelize) - Go Excel库
- [formulas](https://github.com/vinci1it2000/formulas) - Excel公式解析和执行引擎
- [Chart.js](https://www.chartjs.org/) - 图表可视化
- [Plotly](https://plotly.com/) - 交互式图表

---

**⭐ 如果这个项目对您有帮助，请给我们一个星标！**

[⬆ 回到顶部](#chatexcel-mcp-server)