内容
# 📊 SmartOffice-MCP
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](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) |
| :---: | :---: |
|  |  |
### 📊 专业财务与业务表格自动构建 (Auto-Generated Tables)
| 业务排版样式 1 | 业务排版样式 2 |
| :---: | :---: |
|  |  |
---
## 🚀 快速开始 (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) 开源协议。
