DOCX TOC MCP Server

基于 TypeScript 开发的 MCP (Model Context Protocol) 服务器，为 AI 助手提供强大的 DOCX 文档处理能力。通过标准 MCP 协议，AI 助手可以智能地读取、分析和操作 Word 文档的结构化内容。

🌟 核心能力

• 📊 智能目录提取：从 DOCX 文件中精确提取多级标题结构
• 📝 内容智能分析：获取指定章节下的完整文本内容
• 🎯 动态内容注入：在指定位置插入占位符或图片
• 🔄 模板驱动生成：基于模板和数据生成新的 DOCX 文档
• 🤖 AI 原生集成：通过 MCP 协议无缝集成到 AI 工作流

🚀 快速开始

作为 MCP 服务器使用

方式一：NPM 包（推荐）

# 全局安装
npm install -g docx-toc-mcp

# 或者使用 npx
npx -y docx-toc-mcp

方式二：本地开发

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

Claude Desktop 配置

发布版本配置

{
  "mcpServers": {
    "docx-toc": {
      "command": "npx",
      "args": ["-y", "docx-toc-mcp"]
    }
  }
}

开发版本配置

{
  "mcpServers": {
    "docx-toc": {
      "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 服务器入口
│   ├── docx-toc-utils.ts     # DOCX 解析核心逻辑
│   └── docx-template-utils.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. generate_docx_from_template - 模板生成

基于模板和数据生成新的 DOCX 文档，支持动态图片插入。

参数:

• templatePath (string): 模板文件路径
• outputPath (string): 输出文件路径
• data (object): 模板数据对象

🎯 实际应用场景

📖 学术论文分析

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

📝 报告自动生成

AI: 基于模板生成月度报告，在"数据分析"章节后插入图表
MCP: 使用 add_image_after_heading 插入图表 → 使用 generate_docx_from_template 填充数据

🔄 文档批量处理

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

🔧 开发示例

创建测试文档

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. 生成结构化的分析报告

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

AI + MCP:

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

⚠️ 注意事项

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

📊 技术架构

核心组件

• DOCX 解析器: 基于 OpenXML 标准，精确解析文档结构
• 样式识别引擎: 智能识别标题层级和内容边界
• 内容注入系统: 无损插入文本和图片，保持格式一致性
• 模板渲染引擎: 支持复杂数据绑定和动态内容生成

依赖库

• @modelcontextprotocol/sdk: MCP 协议实现
• adm-zip: DOCX 文件解压和压缩
• xml-js: XML 解析和生成
• docx-templates: 高级模板渲染
• image-size: 图片尺寸自动计算

🤝 贡献指南

欢迎提交 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 - 模板渲染引擎