# 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 格式家族。