DOCX TOC MCP Server

基于 TypeScript 开发的 MCP (Model Context Protocol) 服务器，为 AI 助手提供强大的文档处理能力。通过标准 MCP 协议，AI 助手可以智能地读取、分析和操作 DOCX 文档、Excel 文件，并支持 Mermaid 图表渲染和 JSON 数据校验。

🌟 核心能力

• 📊 智能目录提取：从 DOCX 文件中精确提取多级标题结构
• 📝 内容智能分析：获取指定章节下的完整文本内容
• 🎯 动态内容注入：在指定位置插入文本、图片、表格或新标题
• 📋 Excel 数据处理：读取 Excel 文件并转换为 CSV 格式
• 🎨 Mermaid 图表渲染：将 Mermaid 代码渲染为图片
• 🔄 模板驱动生成：基于 JSON 数据和模板生成 DOCX 文档
• ✅ JSON Schema 校验：校验 JSON 文件的数据有效性
• 🤖 AI 原生集成：通过 MCP 协议无缝集成到 AI 工作流

🚀 快速开始

作为 MCP 服务器使用

方式一：NPM 包（推荐）

# 全局安装
npm install -g doc-process-mcp

# 或者使用 npx
npx -y doc-process-mcp

方式二：本地开发

git clone <repository-url>
cd docx-mcp
npm install
npm run build

Claude Desktop 配置

发布版本配置

{
  "mcpServers": {
    "doc-process": {
      "command": "npx",
      "args": ["-y", "doc-process-mcp"]
    }
  }
}

开发版本配置

{
  "mcpServers": {
    "doc-process": {
      "command": "node",
      "args": ["D:\\workspace\\ipaas-ai\\docx-mcp\\dist\\index.js"]
    }
  }
}

配置文件路径

• Windows: %APPDATA%/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

📋 开发指南

环境准备

# 克隆项目
git clone <repository-url>
cd docx-mcp

# 安装依赖
npm install

# 开发模式（热重载）
npm run dev

# 构建生产版本
npm run build

# 运行测试
npm start

项目结构

docx-mcp/
├── src/
│   ├── index.ts                 # MCP 服务器入口
│   ├── doc-process-utils.ts     # DOCX 解析核心逻辑
│   ├── docx-template-utils.ts   # 模板处理工具
│   ├── excel-utils.ts           # Excel 文件处理
│   └── types/                   # TypeScript 类型定义
│       └── module.types.ts      # 模块相关类型
├── example/
│   ├── create-test-doc.js       # 测试文档生成器
│   └── test-functions.js        # 功能测试脚本
├── dist/                        # 构建输出
├── package.json                 # 项目配置
└── README.md                    # 项目文档

🛠️ 提供的工具

1. get_docx_toc - 提取目录结构

获取 DOCX 文件的完整目录层级结构。

参数:

• docxPath (string): DOCX 文件的绝对路径

返回值:

• 目录项数组，包含：
  • title: 标题文本
  • level: 标题层级 (1-9)
  • paragraphIndex: 文档中的段落索引
  • headingIndex: 目录中的索引位置

使用示例:

[
  {
    "title": "第一章 引言",
    "level": 1,
    "paragraphIndex": 0,
    "headingIndex": 0
  },
  {
    "title": "1.1 研究背景",
    "level": 2,
    "paragraphIndex": 5,
    "headingIndex": 1
  }
]

2. get_text_under_heading - 提取章节内容

获取指定标题下的所有文本内容，自动识别章节边界。

参数:

• docxPath (string): DOCX 文件路径
• headingIndex (number): 目录索引位置
• title (string, 可选): 标题验证
• level (number, 可选): 层级验证

3. add_text_after_heading - 插入文本占位符

在指定章节后插入文本占位符，支持批量内容生成。

参数:

• docxPath (string): 原始文件路径
• headingIndex (number): 目标章节索引
• placeholder (string, 可选): 占位符文本，默认"{{text}}"
• outputPath (string, 可选): 输出文件路径

4. add_image_after_heading - 插入图片

在指定章节后插入本地图片，自动调整尺寸适应页面。

参数:

• docxPath (string): 原始文件路径
• headingIndex (number): 目标章节索引
• imagePath (string): 图片文件路径
• outputPath (string, 可选): 输出文件路径

5. add_table_after_heading - 插入表格

在指定章节后插入表格，支持自定义表头和表格数据。

参数:

• docxPath (string): 原始文件路径
• headingIndex (number): 目标章节索引
• table (object): 表格数据对象，包含 head 和 body
  • head: 表头行，包含 cells 数组
  • body: 表格主体，包含 rows 数组
• outputPath (string, 可选): 输出文件路径

6. insert_heading - 插入新标题

在文档中指定标题的同级位置插入新标题。

参数:

• docxPath (string): 文档文件路径
• text (string): 新标题文本
• headingIndex (number): 参考标题的索引
• insertPosition (string, 可选): 插入位置 "before" 或 "after"，默认 "after"

7. read_excel_as_csv - 读取 Excel 文件

读取 Excel 文件的第一个 sheet 并转换为 CSV 字符串。

参数:

• excelPath (string): Excel 文件的绝对路径

返回值:

• CSV 格式的字符串

8. render_mermaid_to_image - 渲染 Mermaid 图表

将 Mermaid 代码渲染为 PNG 图片并保存到指定路径。

参数:

• mermaidCode (string): Mermaid 图表代码字符串
• outputPath (string): 输出 PNG 图片的绝对路径

支持类型:

• flowchart (流程图)
• sequence (时序图)
• class (类图)
• state (状态图)
• er (实体关系图)
• gantt (甘特图)
• 等 Mermaid 所有图表类型

9. validate_json_file_with_schema - JSON Schema 校验

使用 JSON Schema 校验 JSON 文件的有效性。

参数:

• jsonFilePath (string): JSON 文件的绝对路径
• schemaFilePath (string): JSON Schema 文件的绝对路径

返回值:

• valid (boolean): 是否校验通过
• errors (string): 校验错误信息（如果校验失败）

10. generate_docx_from_template_with_json - 基于 JSON 数据生成文档

从 JSON 文件读取数据，基于 DOCX 模板生成新文档。

参数:

• templatePath (string): DOCX 模板文件的绝对路径
• jsonFilePath (string): JSON 数据文件的绝对路径
• outputPath (string): 输出 DOCX 文件的绝对路径

功能:

• 支持 docx-templates 的所有功能
• 支持条件语句、循环、图片插入等高级特性

🎯 实际应用场景

📖 学术论文分析

AI: 请分析这篇论文的第二章研究方法
MCP: 使用 get_docx_toc 提取目录 → 定位第二章 → 使用 get_text_under_heading 提取内容

📊 报告图表插入

AI: 在"数据分析"章节后插入 Mermaid 流程图
MCP: 使用 render_mermaid_to_image 渲染图表 → 使用 add_image_after_heading 插入图表

🔄 文档批量处理

AI: 批量处理100份合同，在每份合同的"条款说明"后添加标准注释
MCP: 循环调用 add_text_after_heading 批量处理

📋 Excel 数据导入

AI: 从 Excel 文件读取数据并生成报告表格
MCP: 使用 read_excel_as_csv 读取数据 → 使用 add_table_after_heading 插入表格

📄 模板批量生成

AI: 基于 JSON 数据批量生成合同文档
MCP: 使用 generate_docx_from_template_with_json 批量生成文档

🔧 开发示例

创建测试文档

cd example
node create-test-doc.js  # 生成测试文档
node test-functions.js   # 运行功能测试

集成到 AI 工作流

示例对话场景：

用户: "帮我分析这份市场调研报告的结构"

AI + MCP:

1. 调用 get_docx_toc 提取完整目录
2. 识别关键章节：执行摘要、方法论、数据分析、结论建议
3. 调用 get_text_under_heading 逐章提取内容
4. 生成结构化的分析报告

用户: "在'竞争对手分析'这章后面加个 Mermaid 流程图"

AI + MCP:

1. 根据目录找到"竞争对手分析"的 headingIndex
2. 调用 render_mermaid_to_image 渲染流程图
3. 调用 add_image_after_heading 插入图表
4. 返回更新后的文档路径

用户: "基于这个 JSON 数据生成报告"

AI + MCP:

1. 调用 validate_json_file_with_schema 校验数据有效性
2. 调用 generate_docx_from_template_with_json 生成文档
3. 返回生成的文档路径

⚠️ 注意事项

• 文件路径: 必须使用绝对路径，支持 Windows 和 Unix 格式
• 标题样式: 确保文档使用标准 Word 标题样式（Heading 1-9）
• 图片格式: 支持 PNG、JPG、JPEG、GIF、SVG 等常见格式
• 性能优化: 大文档处理可能需要数秒，建议在后台异步执行
• 格式保留: 所有操作都会保留原始文档的格式和样式

📊 技术架构

核心组件

• DOCX 解析器: 基于 OpenXML 标准，精确解析文档结构
• 样式识别引擎: 智能识别标题层级和内容边界
• 内容注入系统: 无损插入文本、图片、表格和标题，保持格式一致性
• 模板渲染引擎: 支持复杂数据绑定和动态内容生成
• 图表渲染引擎: 基于 Mermaid 和 Puppeteer 的图表生成和渲染
• Excel 数据处理器: 读取和转换 Excel 文件数据
• JSON Schema 校验器: 基于 AJV 的数据校验引擎

依赖库

• @modelcontextprotocol/sdk: MCP 协议实现
• adm-zip: DOCX 文件解压和压缩
• xml-js: XML 解析和生成
• docx-templates: 高级模板渲染
• image-size: 图片尺寸自动计算
• mermaid: Mermaid 图表渲染引擎
• puppeteer: 无头浏览器，用于图表渲染
• xlsx: Excel 文件读取和解析
• ajv: JSON Schema 校验库

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发规范

1. 使用 TypeScript 进行开发
2. 遵循 ESLint 代码规范
3. 为新增功能编写测试用例
4. 更新相关文档

测试流程

npm run build    # 构建项目
npm start        # 启动服务器
# 在 Claude Desktop 中测试功能

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• Model Context Protocol - 标准化的 AI 工具协议
• OpenXML SDK - DOCX 格式规范
• docx-templates - 模板渲染引擎