shazhou-wiki/research/aspose-mcp-tech.md

Aspose.Words MCP Server 技术方案分析

调研时间：2026 年 5 月 | 作者：沙洲工作室

基于源码阅读（v26.4.0），非黑盒测评

基本信息

项目	信息
仓库	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	链接
Cells	aspose-cells-mcp	TypeScript	链接
Words	agentic-net-examples	C#	AI 验证的示例代码
Cells	agentic-net-examples	C#	AI 验证的示例代码

模式一致：MCP Server + Agentic 示例库，逐步覆盖整个 Office 格式家族。