# 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 包（推荐）

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

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

#### 方式二：本地开发

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

### Claude Desktop 配置

#### 发布版本配置
```json
{
  "mcpServers": {
    "doc-process": {
      "command": "npx",
      "args": ["-y", "doc-process-mcp"]
    }
  }
}
```

#### 开发版本配置
```json
{
  "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`

## 📋 开发指南

### 环境准备

```bash
# 克隆项目
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`: 目录中的索引位置

**使用示例:**
```json
[
  {
    "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 批量生成文档
```

## 🔧 开发示例

### 创建测试文档
```bash
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. 更新相关文档

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

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- [Model Context Protocol](https://modelcontextprotocol.io/) - 标准化的 AI 工具协议
- [OpenXML SDK](https://github.com/OfficeDev/Open-XML-SDK) - DOCX 格式规范
- [docx-templates](https://github.com/guigrpa/docx-templates) - 模板渲染引擎

---

<div align="center">
  <p><strong>让 AI 真正理解你的文档 📄✨</strong></p>
  <p>通过 DOCX TOC MCP，AI 助手不再只是"看"文档，而是真正"理解"文档结构</p>
</div>