小糯 (Xiaonuo) b92c343830 docs: 拆分技术方案分析为两篇独立报告（OfficeCLI / Aspose MCP）[小糯]

2026-05-05 22:15:15 +08:00

14 KiB

Raw Blame History

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                 │
│         （商业闭源，需许可证或评估模式）             │
└─────────────────────────────────────────────────┘

模块关系

"薄门面 + 厚核心"架构，三层调用链清晰分离：

MCP 工具层（mcp_server.py）：90 个用 @mcp.tool 装饰器注册的函数，负责参数校验和 MCP 接口适配
tool_xxx() 辅助层（同一文件）：可脱离 MCP 框架独立调用的函数，方便测试
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 格式家族。

14 KiB Raw Blame History