# 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
- 当前用户拥有桌面会话权限

## 安装

安装完整依赖：

```bash
pip install -e .[windows,mathtype]
```

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

```bash
pip install -e .
```

## 启动 MCP 服务

```bash
word-mathtype-mcp --transport stdio
```

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

```bash
python -m paper_mcp_server --transport stdio
```

支持的传输方式：

- `stdio`
- `sse`
- `streamable-http`

## MCP 客户端配置示例

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

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

```json
{
  "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/`: 当前保留的配套工作流模块，供相关论文场景联调

## 测试

```bash
pytest tests/paper_core/test_word_mcp.py -q
```