Docx MCP Server

🚀 DOCX MCP 服务器

这是一个全面的模型上下文协议（MCP）服务器，用于处理 Microsoft Word（.docx）文档，支持完整的文档格式。

🚀 快速开始

该服务器通过标准输入输出（stdio）运行，并通过 JSON-RPC 2.0 协议进行通信。

使用 MCP 客户端的示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analyze_structure",
    "arguments": {
      "file_path": "/path/to/document.docx"
    }
  }
}

使用 Roo 的示例

{
  "file_path": "/path/to/document.docx"
}

✨ 主要特性

此 MCP 服务器借助强大的 mammoth 库，提供了先进的 DOCX 文档处理能力：

• 文本提取：提取纯文本并统计字数
• HTML 转换：转换为 HTML 格式并保留文档格式
• 结构分析：分析文档结构、标题和格式元素
• 图像提取：提取嵌入的图像（以 base64 格式或保存到文件）
• Markdown 转换：转换为 Markdown 格式
• 丰富格式支持：处理粗体、斜体、列表、标题等

📦 安装指南

npm install
npm run build

💻 使用示例

基础用法

以下是使用 MCP 客户端调用 analyze_structure 工具的示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analyze_structure",
    "arguments": {
      "file_path": "/path/to/document.docx"
    }
  }
}

高级用法

以下是使用 Roo 调用工具的示例：

{
  "file_path": "/path/to/document.docx"
}

📚 详细文档

可用工具

1. extract_text

从 DOCX 文件中提取纯文本内容。 参数：

• file_path（字符串）：.docx 文件的路径 返回值：
• 纯文本内容
• 处理消息
• 字数统计

2. convert_to_html

将 DOCX 文件转换为 HTML 格式并保留格式。 参数：

• file_path（字符串）：.docx 文件的路径
• include_styles（布尔值，可选）：是否包含内联样式（默认：true） 返回值：
• 带格式的 HTML 内容
• 处理消息
• 警告和错误信息

3. analyze_structure

分析文档结构、标题和格式元素。 参数：

• file_path（字符串）：.docx 文件的路径 返回值：
• 文档统计信息（字符数、字数、段落数、标题数）
• 结构分析（带级别信息的标题）
• 格式分析（粗体、斜体、列表数量）
• 处理消息

4. extract_images

从 DOCX 文件中提取并列出图像。 参数：

• file_path（字符串）：.docx 文件的路径
• output_dir（字符串，可选）：保存提取图像的目录 返回值：
• 图像总数
• 图像详细信息（src、替代文本、base64 状态）
• 输出目录信息
• 处理消息

5. convert_to_markdown

将 DOCX 文件转换为 Markdown 格式。 参数：

• file_path（字符串）：.docx 文件的路径 返回值：
• Markdown 内容
• 字数统计
• 处理消息

支持的功能

• ✅ 文本提取：提取纯文本并统计字数
• ✅ 丰富格式：支持粗体、斜体、下划线、删除线
• ✅ 文档结构：支持标题（H1 - H6）、段落
• ✅ 列表：支持有序和无序列表
• ✅ 图像：支持以 base64 格式提取或导出为文件
• ✅ 表格：支持基本表格结构（通过 HTML 转换）
• ✅ 链接：保留超链接
• ✅ 样式：支持自定义样式映射
• ✅ 错误处理：提供全面的错误报告
• ✅ 多格式输出：支持 HTML、Markdown、纯文本输出

高级功能

自定义样式映射

convert_to_html 工具支持自定义样式映射，以生成更好的语义化 HTML 输出：

// 示例样式映射
"p[style-name='Heading 1'] => h1:fresh"
"r[style-name='Strong'] => strong"
"r[style-name='Emphasis'] => em"

图像处理

• Base64 嵌入：图像可以以 base64 数据 URL 形式嵌入
• 文件导出：图像可以提取到指定目录
• 元数据：保留替代文本和内容类型信息

文档分析

提供全面的文档分析，包括：

• 字符和字数统计
• 段落和标题数量统计
• 格式元素统计
• 文档结构层次分析

开发

安装依赖：

npm install

构建服务器：

npm run build

开发时自动重建：

npm run watch

为 Claude Desktop 安装

要在 Claude Desktop 中使用该服务器，需添加服务器配置： 在 MacOS 上：~/Library/Application Support/Claude/claude_desktop_config.json 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docx-format-server": {
      "command": "/path/to/docx-format-server/build/index.js"
    }
  }
}

依赖项

• @modelcontextprotocol/sdk：MCP 协议实现
• mammoth：高级 DOCX 处理库
• zod：模式验证
• typescript：TypeScript 支持

错误处理

所有工具都包含全面的错误处理，针对以下情况提供详细的错误消息：

• 文件未找到错误
• 无效文件格式
• 处理错误
• 权限问题

调试

由于 MCP 服务器通过标准输入输出进行通信，调试可能具有挑战性。建议使用 MCP Inspector，可通过以下命令运行：

npm run inspector

Inspector 将提供一个 URL，可在浏览器中访问调试工具。

版本历史

• v0.2.0：使用 mammoth 库完全重写，新增 5 个全面的工具
• v0.1.0：使用 docx-parser 进行基本文本提取（已弃用）

📄 许可证

ISC 许可证