314 lines
14 KiB
Markdown
314 lines
14 KiB
Markdown
# Aspose.Words MCP Server 技术方案分析
|
|
|
|
> 调研时间：2026 年 5 月 | 作者：沙洲工作室
|
|
>
|
|
> 基于源码阅读（v26.4.0），非黑盒测评
|
|
|
|
## 基本信息
|
|
|
|
| 项目 | 信息 |
|
|
|------|------|
|
|
| 仓库 | [aspose-words/Aspose.Words-MCP-Server](https://github.com/aspose-words/Aspose.Words-MCP-Server) |
|
|
| 语言 | Python |
|
|
| 许可证 | MIT（Server 层），Aspose.Words SDK 为商业许可 |
|
|
| 代码量 | ~6,628 行 Python（含测试） |
|
|
| 外部依赖 | 2 个核心包（fastmcp + aspose-words） |
|
|
| 支持格式 | 仅 Word (.docx) |
|
|
| 版本号 | 与 Aspose.Words SDK 版本对齐（26.4.0） |
|
|
|
|
---
|
|
|
|
## 一、整体架构
|
|
|
|
### 分层结构
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ AI Agent（Claude 等） │
|
|
├─────────────────────────────────────────────────┤
|
|
│ FastMCP 传输层 │
|
|
│ stdio / streamable-http / SSE │
|
|
├─────────────────────────────────────────────────┤
|
|
│ mcp_server.py（1,758 行） │
|
|
│ register_tools() — 90 个 @mcp.tool 注册 │
|
|
│ ↓ │
|
|
│ tool_xxx() 辅助函数 — 可脱离 MCP 独立调用 │
|
|
├─────────────────────────────────────────────────┤
|
|
│ core/ 模块（12 个） │
|
|
│ ┌─────────┬─────────┬─────────┬──────────┐ │
|
|
│ │ content │ tables │ layout │ export │ │
|
|
│ │ 595行 │ 413行 │ 128行 │ 196行 │ │
|
|
│ ├─────────┼─────────┼─────────┼──────────┤ │
|
|
│ │ reading │ notes │ io │ styles │ │
|
|
│ │ 178行 │ 254行 │ 102行 │ 42行 │ │
|
|
│ ├─────────┼─────────┼─────────┼──────────┤ │
|
|
│ │comments │watermarks│protection│ links │ │
|
|
│ │ 45行 │ 47行 │ 43行 │ 36行 │ │
|
|
│ ├─────────┴─────────┴─────────┴──────────┤ │
|
|
│ │ store.py（67行）— 文档 ID ↔ 名称映射 │ │
|
|
│ │ utils/docs_util.py — 路径/颜色/段落工具 │ │
|
|
│ │ utils/license.py — 许可证处理 │ │
|
|
│ └────────────────────────────────────────┘ │
|
|
├─────────────────────────────────────────────────┤
|
|
│ Aspose.Words Python SDK │
|
|
│ （商业闭源，需许可证或评估模式） │
|
|
└─────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 模块关系
|
|
|
|
**"薄门面 + 厚核心"架构**，三层调用链清晰分离：
|
|
|
|
1. **MCP 工具层**（`mcp_server.py`）：90 个用 `@mcp.tool` 装饰器注册的函数，负责参数校验和 MCP 接口适配
|
|
2. **tool_xxx() 辅助层**（同一文件）：可脱离 MCP 框架独立调用的函数，方便测试
|
|
3. **core/ 业务层**（12 个模块）：实际调用 Aspose.Words SDK 的业务逻辑
|
|
|
|
这种分离意味着如果要把 MCP 换成 REST API 或 gRPC，只需要替换最外层。
|
|
|
|
### 文档存储模型
|
|
|
|
**DocumentStore**（`store.py`，67 行）是一个线程安全的内存字典：
|
|
- `threading.RLock` 保证并发安全
|
|
- 存储 `doc_id → {name: str}` 的映射
|
|
- 纯内存会话级存储，不持久化
|
|
|
|
文档实体以 UUID 命名的 `.docx` 文件存储在 `DOCS_DATA_DIR`（默认 `./data`）。重启后扫描 data 目录可恢复。
|
|
|
|
### 无状态操作模式
|
|
|
|
每次操作都遵循**加载 → 修改 → 保存**的无状态模式：
|
|
|
|
```
|
|
1. path = ensure_path(doc_id) # 获取 .docx 文件路径
|
|
2. doc = aw.Document(str(path)) # 加载文档到内存
|
|
3. builder = aw.DocumentBuilder(doc) # 创建构建器
|
|
4. [执行操作]
|
|
5. doc.save(str(path)) # 保存回磁盘
|
|
```
|
|
|
|
没有驻留进程，没有内存缓存。每次调用都重新加载文件。简单可靠，但连续大量操作时性能不如 OfficeCLI 的 Resident Mode。
|
|
|
|
---
|
|
|
|
## 二、API 抽象设计
|
|
|
|
### 90 个 MCP 工具分类
|
|
|
|
Aspose MCP Server 注册了 90 个扁平的 MCP 工具，没有 OfficeCLI 那样的三层分级——每个工具是一个独立的操作：
|
|
|
|
#### 文档生命周期管理（~10 个）
|
|
|
|
| 工具 | 功能 |
|
|
|------|------|
|
|
| create_document | 创建新文档 |
|
|
| delete_document | 删除文档 |
|
|
| copy_document | 复制文档 |
|
|
| list_documents | 列出所有文档 |
|
|
| merge_documents | 合并多份文档 |
|
|
| save_as_new | 另存为新文档 |
|
|
| get_info | 获取文档信息 |
|
|
| stats | 文档统计 |
|
|
| get_document_base64 | 获取文档的 Base64 编码 |
|
|
|
|
#### 内容插入（~20 个）
|
|
|
|
这是工具数量最多的类别。采用**三位置插入模式**——同一种内容类型提供三个变体：
|
|
|
|
| 位置 | 示例工具 |
|
|
|------|---------|
|
|
| 文末（end） | `insert_text_end`、`add_page_break_end`、`insert_list_end`、`insert_html_end` |
|
|
| 文首（start） | `insert_text_start`、`add_page_break_start`、`insert_list_start`、`insert_html_start` |
|
|
| 指定段落（at_paragraph） | `insert_text_at_paragraph`、`add_page_break_at_paragraph`、`insert_list_at_paragraph` |
|
|
|
|
此外还有按锚文本定位的变体：`insert_header_near_text`、`insert_line_or_paragraph_near_text`、`insert_numbered_list_near_text`。
|
|
|
|
支持的内容类型：纯文本、标题、段落、分页符、列表（有序/无序）、HTML、Markdown、Base64 图片。
|
|
|
|
#### 内容读取与搜索（~6 个）
|
|
|
|
| 工具 | 功能 |
|
|
|------|------|
|
|
| read_paragraphs | 按索引范围读取段落 |
|
|
| get_text | 获取全文文本 |
|
|
| get_xml | 获取文档 XML |
|
|
| get_outline / get_outline_simple | 获取文档大纲 |
|
|
| find_text | 文本搜索 |
|
|
|
|
#### 文本操作（~3 个）
|
|
|
|
| 工具 | 功能 | 特点 |
|
|
|------|------|------|
|
|
| replace_text | 文本替换 | 支持正则（有安全验证）、大小写、全词匹配、join_runs |
|
|
| delete_paragraph | 删除指定段落 | 按索引 |
|
|
| format_text | 格式化文本范围 | 支持段落内 start_pos/end_pos 字符级定位 |
|
|
|
|
#### 表格操作（~18 个）
|
|
|
|
表格是工具最多的模块之一，操作粒度细到单元格级：
|
|
|
|
| 工具 | 粒度 |
|
|
|------|------|
|
|
| add_table_end / start / at_paragraph | 表格创建（三位置） |
|
|
| format_table | 表格整体格式 |
|
|
| set_table_cell_shading | 单元格着色 |
|
|
| apply_table_alternating_rows | 交替行颜色 |
|
|
| highlight_table_header | 高亮表头 |
|
|
| merge_table_cells / horizontal / vertical | 单元格合并 |
|
|
| set_table_cell_alignment | 单元格对齐 |
|
|
| set_table_column_width / widths | 列宽 |
|
|
| set_table_width | 表格总宽 |
|
|
| auto_fit_table_columns | 自动列宽 |
|
|
| format_table_cell_text | 单元格内文本格式 |
|
|
| set_table_cell_padding | 单元格内边距 |
|
|
|
|
#### 页面布局（~6 个）
|
|
|
|
| 工具 | 功能 |
|
|
|------|------|
|
|
| add_header_text / add_footer_text | 页眉页脚 |
|
|
| add_page_numbering | 页码 |
|
|
| set_different_first_page_header_footer | 首页不同页眉页脚 |
|
|
| set_page_setup | 页面设置（边距/方向/纸张） |
|
|
| insert_section_break | 分节符 |
|
|
|
|
#### 脚注/尾注（~12 个）
|
|
|
|
脚注是功能最丰富的子模块：
|
|
- 添加/删除脚注和尾注
|
|
- 按锚文本定位脚注
|
|
- 验证脚注是否存在
|
|
- 脚注和尾注互转
|
|
- 脚注样式设置
|
|
- 获取所有注释
|
|
|
|
#### 其他模块
|
|
|
|
| 模块 | 工具数 | 功能 |
|
|
|------|--------|------|
|
|
| 评论 | 3 | 获取所有评论、按作者/段落过滤 |
|
|
| 属性 | 2 | 读写文档属性（标题/作者/关键词） |
|
|
| 保护 | 3 | 加密保护、取消保护、限制编辑 |
|
|
| 水印 | 2 | 文字水印、图片水印（Base64） |
|
|
| 链接 | 2 | 书签、超链接 |
|
|
| 样式 | 1 | 创建自定义样式 |
|
|
| 导出 | 3 | 多格式导出、高级导出选项、页面渲染为图片 |
|
|
|
|
### 操作粒度
|
|
|
|
| 粒度 | 说明 | 示例 |
|
|
|------|------|------|
|
|
| 段落级 | **核心寻址单位**，绝大多数操作以 `paragraph_index` 定位 | insert_text_at_paragraph(paragraph_index=3) |
|
|
| Run 级 | format_text 支持段落内字符范围 | format_text(paragraph_index=2, start_pos=5, end_pos=10) |
|
|
| 单元格级 | 表格操作精确到行列 | set_table_cell_shading(table_index=0, row=1, col=2) |
|
|
| 锚文本定位 | 通过文本内容查找位置 | insert_header_near_text(anchor_text="Introduction") |
|
|
|
|
### 设计特点
|
|
|
|
**扁平化工具设计**：不同于 OfficeCLI 的三层架构（语义/DOM/XML），Aspose MCP Server 的 90 个工具是扁平排列的。每个工具做一件明确的事，参数自解释。这降低了 AI Agent 的认知负担——不需要理解"应该用哪一层"，直接找到对应操作即可。
|
|
|
|
**三位置插入模式**：`end/start/at_paragraph` 三个变体虽然增加了工具数量，但让 AI 不需要学习复杂的定位语法。
|
|
|
|
**安全设计**：正则表达式替换有专门的安全验证器——禁止 lookaround、backreference、group 引用、堆叠量词，最大 256 字符，防止 ReDoS 攻击。
|
|
|
|
---
|
|
|
|
## 三、Office 文档引擎
|
|
|
|
### 核心依赖：Aspose.Words SDK
|
|
|
|
Aspose MCP Server 的**全部文档处理能力来自 Aspose.Words 商业 SDK**。Server 层不做任何格式解析——它只是把 MCP 调用翻译成 Aspose.Words API 调用。
|
|
|
|
使用的核心 Aspose.Words API：
|
|
|
|
| API | 用途 |
|
|
|-----|------|
|
|
| `aw.Document(path)` | 加载文档 |
|
|
| `aw.DocumentBuilder(doc)` | 内容构建器（插入文本/图片/表格等） |
|
|
| `doc.range.replace()` / `replace_regex()` | 文本替换 |
|
|
| `doc.get_child_nodes()` | 节点遍历（段落/表格/评论/脚注） |
|
|
| `builder.insert_*()` | 插入各种元素 |
|
|
| `aw.saving.*SaveOptions` | 各格式导出选项 |
|
|
| `doc.watermark` | 水印 API |
|
|
| `doc.protect()` / `unprotect()` | 文档保护 |
|
|
| `aw.JoinRunsOptions` | Run 合并（26.x 新特性） |
|
|
|
|
### 格式转换能力
|
|
|
|
这是 Aspose 相比 OfficeCLI 的**核心优势**——Aspose.Words SDK 内置了完整的文档渲染引擎，可以高保真输出多种格式：
|
|
|
|
**输出格式**：
|
|
- 文档：DOCX、RTF、ODT
|
|
- 排版：PDF（含 PDF/A 合规级别）
|
|
- 网页：HTML、MHTML、HTML Fixed、EPUB、Markdown
|
|
- 图片：PNG、JPEG、TIFF、SVG
|
|
- 其他：Docling (JSON)
|
|
|
|
**输入格式**：通过 `import_from_file` 可导入 Aspose.Words 支持的所有格式。
|
|
|
|
OfficeCLI 不做格式转换和渲染，只在原生 OOXML 格式内操作。当需要"把 docx 转成 PDF"时，Aspose 是更成熟的选择。
|
|
|
|
### 兼容性
|
|
|
|
**优势**：
|
|
- Aspose.Words 是 20 年的商业产品，格式兼容性经过大量企业验证
|
|
- 内置完整的文档渲染引擎，PDF 输出质量高
|
|
- 支持旧格式（.doc）的导入
|
|
- 不依赖 Microsoft Office
|
|
|
|
**限制**：
|
|
- 无许可证时有评估限制（输出文档带水印、页数限制）
|
|
- 仅覆盖 Word 格式——Excel 需要 Aspose.Cells MCP Server（TypeScript 实现），PPT 需要 Aspose.Slides（尚无 MCP Server）
|
|
- SDK 为闭源商业产品，无法审计其内部行为
|
|
|
|
---
|
|
|
|
## 四、技术栈
|
|
|
|
| 组件 | 技术选择 | 说明 |
|
|
|------|---------|------|
|
|
| 语言 | Python 3.11 - 3.13 | |
|
|
| MCP 框架 | FastMCP | 第三方 MCP 协议库，处理传输和序列化 |
|
|
| 文档引擎 | aspose-words ≥ 26.4.0 | 商业 SDK，Python 绑定 |
|
|
| 传输协议 | stdio / streamable-http / SSE | 通过环境变量 MCP_TRANSPORT 配置 |
|
|
| 测试框架 | pytest | 14 个测试文件，分三层 |
|
|
| 代码规范 | Ruff | 格式化 + lint |
|
|
| 构建 | Python build | 标准 pyproject.toml |
|
|
| 安装 | pip install aspose-words-mcp | PyPI 分发 |
|
|
|
|
### 配置方式
|
|
|
|
通过环境变量配置：
|
|
|
|
| 变量 | 默认值 | 说明 |
|
|
|------|-------|------|
|
|
| MCP_TRANSPORT | stdio | 传输协议 |
|
|
| MCP_HOST | 0.0.0.0 | HTTP 模式主机 |
|
|
| MCP_PORT | 8080 | HTTP 模式端口 |
|
|
| MCP_PATH | / | HTTP 路径 |
|
|
| DOCS_DATA_DIR | ./data | 文档存储目录 |
|
|
|
|
### 测试覆盖
|
|
|
|
14 个测试文件，分三层：
|
|
|
|
| 层级 | 文件 | 覆盖 |
|
|
|------|------|------|
|
|
| 单元测试 | test_store.py | DocumentStore |
|
|
| 服务器集成 | test_client_integration.py, test_run_server_config.py | MCP 客户端交互、启动配置 |
|
|
| 功能测试 | 10 个文件 | 文档管理、内容创建、表格、页面设置、页眉页脚、水印链接、HTML/Markdown、保护/批注/脚注等 |
|
|
|
|
有 `AGENTS.md` 规范 AI Agent 的编码行为：禁止 `getattr/hasattr` 动态访问、禁止 broad `try/except`、版本必须与 Aspose.Words 对齐。
|
|
|
|
### Aspose 的 MCP 生态
|
|
|
|
Aspose 在多个产品线复制了相同的 AI 集成模式：
|
|
|
|
| 产品线 | MCP Server | 语言 | 仓库 |
|
|
|--------|-----------|------|------|
|
|
| Words | aspose-words-mcp | Python | [链接](https://github.com/aspose-words/Aspose.Words-MCP-Server) |
|
|
| Cells | aspose-cells-mcp | TypeScript | [链接](https://github.com/aspose-cells/Aspose.Cells-MCP) |
|
|
| Words | agentic-net-examples | C# | AI 验证的示例代码 |
|
|
| Cells | agentic-net-examples | C# | AI 验证的示例代码 |
|
|
|
|
模式一致：MCP Server + Agentic 示例库，逐步覆盖整个 Office 格式家族。
|