word-mathtype-mcp

面向学术 Word 文档处理的本地 MCP 工具集，重点解决通用 Word 自动化工具通常缺失的两类能力：

• 真实 MathType OLE 对象处理
• 真实 Word REF / 书签交叉引用处理

当前仓库的主交付物是 paper_mcp_server。仓库中还保留了一个配套的 paper_core 模块，供相关论文工作流联调用；但 word-mathtype-mcp 的核心定位仍然是 Word / MathType / REF 的 MCP 服务。

适用场景

• 论文中含大量 MathType 公式，需要读取、插入、替换、删除或转换
• 需要在 Word 中维护真实的参考文献引用、REF 字段和书签
• 需要对论文做格式整理、段落批处理、表格格式统一和版本化保存
• 需要把这些能力通过 MCP 暴露给 Codex、ChatGPT 或其他 MCP 客户端

核心能力

文档检查

• 检查文档结构、段落、表格、参考文献、交叉引用和嵌入对象
• 列出 Word 原生公式和 MathType 对象
• 检查参考文献区条目、编号和 ref_bib_n 书签
• 检查 REF 交叉引用是否损坏

真实 MathType 对象处理

这里的 MathType 指 Equation.DSMT4 等真实 OLE 对象，不是仅限 Word 原生 OMML。

• 读取已有 MathType 内容
• 写入新的真实 MathType 公式
• 替换已有 MathType 对象内容
• 删除指定 MathType 对象
• MathType 与 Word 原生公式双向转换

真实 Word 交叉引用

这里的交叉引用指 Word 的 REF 字段加书签，不是普通文本替换。

• 插入参考文献条目并自动编号
• 在正文插入真实 [n] 引用字段
• 新增真实 Word REF 交叉引用
• 自动创建书签
• 修复损坏交叉引用
• 刷新交叉引用显示文字

论文格式处理

• 统一标题、正文、表格、参考文献的字体字号与缩进
• 批量整理参考文献格式
• 整理公式段为“公式居中、编号右对齐”
• 按格式配置检查文档
• 按 论文草稿_V数字.docx 规则保存下一版文件

实时编辑桥接

• 列出当前 Word 已打开的文档
• 获取当前活动文档
• 将现有操作直接应用到当前活动文档

能力边界

• 现在支持真实 MathType 对象的识别、读取、新建、删除、转换和重建式替换
• 现在不宣称直接改写任意旧 MathType OLE 对象的内核字节
• latex / mathml 路径下，现有“编辑已有 MathType”本质上是原位置重建真实 MathType 对象
• 现在支持真实 Word REF 引用的新增与修复，而不是纯文本替换

环境要求

基础要求：

• Windows
• Python 3.10+
• Microsoft Word

使用真实 MathType 能力时还需要：

• 已安装 MathType
• 当前用户拥有桌面会话权限

安装

安装完整依赖：

pip install -e .[windows,mathtype]

如果只想先使用不依赖 MathType 的部分：

pip install -e .

启动 MCP 服务

word-mathtype-mcp --transport stdio

也可以直接用 Python 模块方式：

python -m paper_mcp_server --transport stdio

支持的传输方式：

• stdio
• sse
• streamable-http

MCP 客户端配置示例

{
  "mcpServers": {
    "word-mathtype-mcp": {
      "command": "word-mathtype-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

如果不走脚本入口，也可以写成：

{
  "mcpServers": {
    "word-mathtype-mcp": {
      "command": "python",
      "args": ["-m", "paper_mcp_server", "--transport", "stdio"]
    }
  }
}

常用工具

文档检查：

• word_inspect_document
• word_list_paragraphs
• word_inspect_mathtype_objects
• word_inspect_word_equations
• word_inspect_cross_references
• word_inspect_reference_entries

实时编辑：

• word_list_open_documents
• word_get_active_document
• word_apply_operation_to_active_document

MathType：

• word_read_mathtype_content
• word_insert_mathtype_object
• word_write_mathtype_equation
• word_replace_mathtype_object_content
• word_delete_mathtype_object
• word_convert_mathtype_to_word_equation
• word_convert_word_equation_to_mathtype

交叉引用：

• word_insert_reference_entry
• word_insert_reference_citation
• word_add_cross_reference
• word_repair_cross_references

格式处理：

• word_apply_thesis_format
• word_apply_format_profile
• word_audit_format
• word_fix_references
• word_fix_formula_layout
• word_fix_mathtype_equation_layout
• word_format_mathtype_paragraphs
• word_format_paragraph_range
• word_format_all_tables
• word_save_as_next_version

仓库结构

• paper_mcp_server/: MCP 服务与 Word / MathType / REF 实现
• format_profiles/: 论文格式配置
• tests/: 测试
• paper_core/: 当前保留的配套工作流模块，供相关论文场景联调

测试

pytest tests/paper_core/test_word_mcp.py -q