📊 SmartOffice-MCP

SmartOffice-MCP 是一个强大的、本地优先的 Model Context Protocol (MCP) 服务端与可视化智能体客户端，专为赋能 AI Agent 直接操作、分析、排版和生成 Microsoft Office 文档（Excel、Word、PPT、PDF）而设计。

---

🎯 解决什么痛点？(Pain Points & Core Value)

在日常办公中，你是否也经常遇到以下烦恼？

• ❌ Office 工具门槛高：想做专业的数据透视表、高级公式、高颜值主题排版，却记不住 Excel 繁琐的菜单步骤和复杂的 Python 脚本。
• ❌ 网络模板套路多：网上好看的表格或报告模版往往需要付费下载，甚至强迫充值会员。
• ❌ 效率低、重复劳动：接到竞品分析、周报汇总、销售分析任务，手动复制粘贴、调整对齐和配色，动辄耗费半小时甚至数小时的宝贵时间。

💡 有了 AutoOffice-MCP，这一切迎刃而解：

• 🗣️ 大白话直接操控：你不需要是 Office 专家，直接用 自然语言（大白话） 提问（如：“帮我生成一份带有总和计算、使用高级蓝色调排版的销售周报”），AI 自动帮你写好数据并美化格式！
• 📸 截图一键复刻：看到别人家精美的表格设计？直接截图发给 AI，系统能够智能复刻出 1:1 格式对齐、配色精美且自带公式的原生 Excel 模板，省去摸索时间与模板费用。
• ⚡ 效率指数级暴增：将原来需要半个小时、甚至数小时的繁琐排版与数据整理工作，缩短至几分钟内全自动搞定！

---

💡 官方推荐模型 (Recommended Models)

为了获得最佳的自动化工具调用（Tool Calling）精度与排版稳定性，本项目强烈推荐使用以下两款模型：

• 🥇 Google Gemini 3.5 Flash （官方首推，推理极速，支持复杂多步骤工具调用）
• 🥇 OpenAI GPT-4o （逻辑极强，排版与脚本编写稳定性极高）

⚠️ 提示：其他轻量或早期版本模型（如部分 Flash-Lite、Mini 等）在复杂 Office 自动化指令下可能存在函数调用参数丢失或格式不兼容的情况，不推荐用于生产环境。

---

✨ 核心特性 (Key Features)

• 📈 Excel 智能处理与数据可视化：
  • 自动插入 SUM/AVERAGE 公式、网格边框对齐与专业配色主题。
  • 数据透视表构建、图表生成与 Pandas 深度数据剖析。
  • 支持直接运行高级 Python 排版与计算脚本。
• 📝 Word 与 PDF 模版化处理：
  • 基于 Jinja2 语法的 Word 模板动态填充与批量生成交付件。
  • PDF 表单域分析、自动填表与文本坐标布局探测。
• ⚡ 异步多线程引擎 (Async & Multi-threaded)：
  • 采用 FastAPI 与 Starlette 后台线程池（run_in_threadpool），工具执行完全非阻塞，支持多网页并发请求。
• 🎨 现代化可视化智能体客户端 (Web Client)：
  • 提供美观的对话时间线（Timeline），0ms 即时连接反馈，杜绝卡顿等待空白。
  • SSE 实时流式响应，内置自动化工具调用状态展示与折叠式详细调试参数（JSON Inspector）。
• 🔒 安全沙盒防护：
  • 严格的工作目录隔离与路径校验，彻底杜绝目录穿越漏洞。

---

📸 自动化效果展示 (Showcase)

SmartOffice-MCP 拥有极高的表格理解与样式重构能力。以下为 AI Agent 自动生成与复刻 Excel 表格的实际渲染效果：

🎯 复杂表格 1:1 智能复刻 (Table Replication)

原图样本 (Original)	AI 自动化复刻结果 (Replicated by AI)

📊 专业财务与业务表格自动构建 (Auto-Generated Tables)

业务排版样式 1	业务排版样式 2

---

🚀 快速开始 (Quick Start)

1. 环境安装

确保你已安装 Python 3.10 或更高版本。在项目根目录下运行：

# 创建虚拟环境（可选但推荐）
python -m venv .venv
# Windows 激活环境
.\.venv\Scripts\activate
# Mac/Linux 激活环境
source .venv/bin/activate

# 安装项目及依赖
pip install .

2. 启动可视化 Web 客户端

运行以下命令即可启动可视化 AI 助手页面：

smartoffice-client

启动后，打开浏览器访问 http://127.0.0.1:8000。在右上角系统设置中填入 API Key，选择推荐的 Gemini 3.5 Flash 或 GPT-4o 即可开始办公自动化！

3. 作为标准 MCP Server 接入客户端

如果你使用的是 Claude Desktop、Cursor 或其他 MCP 兼容客户端，可在其配置文件（如 claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "smartoffice-mcp": {
      "command": "python",
      "args": ["-m", "smartoffice_mcp.gateway"]
    }
  }
}

---

📂 项目结构

smartoffice-mcp/
├── src/smartoffice_mcp/
│   ├── gateway.py          # MCP 标准网关与工具路由定义
│   ├── client_web/         # FastAPI 可视化客户端后台及静态页面
│   ├── engines/            # Excel / Word / PDF 核心自动化处理引擎
│   └── utils/              # 沙盒路径校验与公共工具
├── pyproject.toml          # 项目配置与依赖包清单
├── LICENSE                 # MIT 开源协议
└── README.md               # 项目说明文档

---

📄 开源协议

本项目采用 MIT License 开源协议。