Docx MCP Server

🚀 DOCX MCP Server

このサーバーは、完全な書式設定をサポートしたMicrosoft Word（.docx）ドキュメントを処理するための包括的なモデルコンテキストプロトコル（MCP）サーバーです。

✨ 主な機能

このMCPサーバーは、強力なmammothライブラリを使用して高度なDOCXドキュメント処理機能を提供します。

• テキスト抽出：単語数を含むプレーンテキストを抽出
• HTML変換：書式を保持したままHTMLに変換
• 構造解析：ドキュメントの構造、見出し、および書式要素を解析
• 画像抽出：埋め込まれた画像を抽出（base64形式またはファイルに保存）
• Markdown変換：Markdown形式に変換
• リッチな書式サポート：太字、斜体、リスト、見出しなどを処理

🛠️ 利用可能なツール

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、altテキスト、base64ステータス）
• 出力ディレクトリ情報
• 処理メッセージ

5. convert_to_markdown

DOCXファイルをMarkdown形式に変換します。

パラメーター:

• file_path (文字列): .docxファイルへのパス

戻り値:

• Markdownコンテンツ
• 単語数
• 処理メッセージ

📦 インストール

npm install
npm run build

💻 使用例

基本的な使用法

サーバーは標準入出力で動作し、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"
}

📋 サポートされる機能

• ✅ テキスト抽出: 単語数付きのプレーンテキスト
• ✅ リッチな書式: 太字、斜体、下線、取り消し線
• ✅ ドキュメント構造: 見出し（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として埋め込むことができます。
• ファイルエクスポート: 画像を指定されたディレクトリに抽出することができます。
• メタデータ: altテキストとコンテンツタイプの保存

ドキュメント解析

以下を含む包括的なドキュメント解析を提供します。

• 文字数と単語数
• 段落数と見出し数
• 書式要素の統計
• ドキュメント構造の階層

🛠️ 開発

依存関係をインストールします。

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

インスペクターは、ブラウザでデバッグツールにアクセスするためのURLを提供します。

📜 バージョン履歴

• v0.2.0: mammothライブラリを使用して完全に書き換え、5つの包括的なツールを追加
• v0.1.0: docx-parserを使用した基本的なテキスト抽出（非推奨）

📄 ライセンス

ISCライセンス