# 📊 SmartOffice-MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Protocol](https://img.shields.io/badge/MCP-1.1.2+-purple.svg)](https://modelcontextprotocol.io/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)

**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) |
| :---: | :---: |
| ![原图样本](assets/demo-original.png) | ![AI复刻结果](assets/demo-replicated.png) |

### 📊 专业财务与业务表格自动构建 (Auto-Generated Tables)
| 业务排版样式 1 | 业务排版样式 2 |
| :---: | :---: |
| ![自动构建表格1](assets/demo-table-1.png) | ![自动构建表格2](assets/demo-table-2.png) |

---

## 🚀 快速开始 (Quick Start)

### 1. 环境安装

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

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

# 安装项目及依赖
pip install .
```

### 2. 启动可视化 Web 客户端

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

```bash
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`）中添加：

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

---

## 📂 项目结构

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

---

## 📄 开源协议

本项目采用 [MIT License](LICENSE) 开源协议。