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 許可證