mcp-document-converter

MCP ドキュメントコンバーター

MCP（Model Context Protocol）ドキュメントコンバーター — 複数の形式間でドキュメントを変換し、AI エージェントが簡単にドキュメントを変換できる強力な MCP ツールです。

🌐 言語: 英語 | 中文

特長

• マルチフォーマット対応: Markdown、HTML、DOCX、PDF、テキストの主要な5つのドキュメント形式に対応
• 双方向変換: 任意の形式から任意の形式に変換できます（5×5＝25通りの変換組み合わせ）
• MCP プロトコル: MCP 標準に準拠しており、Trae IDE などの AI アシスタントのツールとして利用できます
• プラグインアーキテクチャ: 新しいパーサーやレンダラーを簡単に追加できます
• 構文ハイライト: HTML および PDF の出力でコードの構文ハイライトに対応
• スタイルのカスタマイズ: CSS スタイルをカスタマイズできます
• メタデータの保持: 変換時にドキュメントのタイトル、作成者、作成日時などのメタデータを保持します

---

📚 ドキュメント

ユーザーガイド · API リファレンス · コントリビューション · 変更履歴 · ライセンス

---

アーキテクチャ

flowchart TB
    subgraph Parsers["Parsers"]
        MD[Markdown]
        DOCX1[DOCX]
        HTML1[HTML]
        PDF1[PDF]
        TXT1[Text]
    end

    subgraph IR["Intermediate Representation (IR)"]
        DT[Document Tree]
        META[Metadata]
        ASSETS[Assets]
    end

    subgraph Renderers["Renderers"]
        HTML2[HTML]
        PDF2[PDF]
        MD2[Markdown]
        DOCX2[DOCX]
        TXT2[Text]
    end

    MD --> IR
    DOCX1 --> IR
    HTML1 --> IR
    PDF1 --> IR
    TXT1 --> IR
    
    IR --> HTML2
    IR --> PDF2
    IR --> MD2
    IR --> DOCX2
    IR --> TXT2

コアコンポーネント

1. DocumentIR（中間表現）: すべてのドキュメントを統一的に抽象化し、ドキュメントツリー、メタデータ、アセットなどを含みます。
2. BaseParser（パーサー基底クラス）: パーサーのインターフェースを定義し、さまざまな形式を DocumentIR に解析します。
3. BaseRenderer（レンダラー基底クラス）: レンダラーのインターフェースを定義し、DocumentIR をさまざまな形式にレンダリングします。
4. ConverterRegistry（レジストリ）: すべてのパーサーとレンダラーを管理し、形式の検索と自動マッチングを提供します。
5. DocumentConverter（変換エンジン）: パーサーとレンダラーを連携させ、ドキュメント変換を実行します。

対応形式

入力形式（パーサー）

形式	拡張子	MIME タイプ	機能
Markdown	.md, .markdown, .mdown, .mkd	text/markdown	YAML Front Matter、GFM 拡張機能
HTML	.html, .htm	text/html	セマンティックタグの解析
DOCX	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	スタイル、表、画像
PDF	.pdf	application/pdf	テキスト抽出と構造認識
テキスト	.txt, .text	text/plain	自動エンコーディング検出と構造認識

出力形式（レンダラー）

形式	拡張子	MIME タイプ	機能
HTML	.html	text/html	美しいスタイル、コードのハイライト、レスポンシブデザイン
Markdown	.md	text/markdown	標準 Markdown 形式、YAML Front Matter
DOCX	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	Word 文書形式、スタイルの保持
PDF	.pdf	application/pdf	WeasyPrint で生成、ページ分割に対応
テキスト	.txt	text/plain	プレーンテキスト、基本的な書式を保持

変換マトリックス

flowchart LR
    subgraph Sources["Source Formats"]
        MD_S[Markdown]
        HTML_S[HTML]
        DOCX_S[DOCX]
        PDF_S[PDF]
        TXT_S[Text]
    end

    subgraph Targets["Target Formats"]
        MD_T[Markdown]
        HTML_T[HTML]
        DOCX_T[DOCX]
        PDF_T[PDF]
        TXT_T[Text]
    end

    MD_S --> Targets
    HTML_S --> Targets
    DOCX_S --> Targets
    PDF_S --> Targets
    TXT_S --> Targets

インストール

pip を使用する（推奨）

pip install mcp-document-converter

ソースからインストールする

git clone https://github.com/xt765/mcp-document-converter.git
cd mcp-document-converter
pip install -e .

MCP ツール

このサーバーでは、以下のツールを提供しています。

convert_document

文書を別の形式に変換します。

引数：

• source_path（string、必須）：ソース文書のパス。
• target_format（string、必須）：変換先の形式（html、pdf、markdown、docx、text）。
• output_path（string、任意）：出力ファイルのパス。
• source_format（string、任意）：ソースファイルの形式（指定がない場合は自動検出されます）。
• options（object、任意）：template、css、preserve_metadata などの追加オプション。

設定

Trae IDE / Claude Desktop での使用

以下を MCP 設定ファイルに追加します。

オプション 1：PyPI を使用する（推奨）

{
  "mcpServers": {
    "mcp-document-converter": {
      "command": "uvx",
      "args": [
        "mcp-document-converter"
      ]
    }
  }
}

オプション 2：GitHub リポジトリを使用する

{
  "mcpServers": {
    "mcp-document-converter": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/xt765/mcp-document-converter",
        "mcp-document-converter"
      ]
    }
  }
}

オプション 3：Gitee リポジトリを使用する（中国国内からのアクセスが高速）

{
  "mcpServers": {
    "mcp-document-converter": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://gitee.com/xt765/mcp-document-converter",
        "mcp-document-converter"
      ]
    }
  }
}

オプション 4：pip を使用する（手動インストール）

まず、パッケージをインストールします。

pip install mcp-document-converter

次に、設定に追加します。

{
  "mcpServers": {
    "mcp-document-converter": {
      "command": "mcp-document-converter",
      "args": []
    }
  }
}

Cherry Studio での使用

Cherry Studio は、MCP プロトコルを介してさまざまなツールを統合できる、強力なオープンソースのデスクトップ AI クライアントアシスタントです。

設定例：

使用例：

使用方法

MCP ツールとして使用する

設定後、AI アシスタントは以下のツールを直接呼び出せます。

1. convert_document（推奨）

統一されたインターフェースを使用して、サポートされている任意の文書形式を変換します。

# Markdown to HTML
convert_document(
    source_path="document.md",
    target_format="html"
)

# HTML to PDF
convert_document(
    source_path="document.html",
    target_format="pdf"
)

# DOCX to Markdown
convert_document(
    source_path="document.docx",
    target_format="markdown"
)

# Conversion with options
convert_document(
    source_path="document.md",
    target_format="html",
    output_path="output.html",
    options={
        "css": "custom.css",
        "preserve_metadata": True
    }
)

2. list_supported_formats

サポートされているすべての文書形式を一覧表示します。

list_supported_formats()

3. get_conversion_matrix

形式変換マトリックス全体を取得します。

get_conversion_matrix()

4. can_convert

ソース形式から変換先形式への変換がサポートされているかを確認します。

can_convert(source_format="markdown", target_format="pdf")

5. get_format_info

特定の形式に関する詳細情報を取得します。

get_format_info(format="markdown")

Python ライブラリとして使用する

from mcp_document_converter import DocumentConverter
from mcp_document_converter.registry import get_registry
from mcp_document_converter.parsers import MarkdownParser, HTMLParser
from mcp_document_converter.renderers import HTMLRenderer, PDFRenderer

# Register parsers and renderers
registry = get_registry()
registry.register_parser(MarkdownParser())
registry.register_parser(HTMLParser())
registry.register_renderer(HTMLRenderer())
registry.register_renderer(PDFRenderer())

# Create converter
converter = DocumentConverter(registry)

# Convert document
result = converter.convert(
    source="input.md",
    target_format="html",
    output_path="output.html"
)

if result.success:
    print(f"✅ Conversion successful: {result.output_path}")
else:
    print(f"❌ Conversion failed: {result.error_message}")

ツールインターフェースの詳細

convert_document

ドキュメントをある形式から別の形式に変換します。

パラメーター：

パラメーター	型	必須	説明
source_path	string	✅	入力ファイルのパス。絶対パスまたは相対パスを指定できます
target_format	string	✅	出力形式：html、pdf、markdown、docx、text
output_path	string	❌	出力ファイルのパス（任意。デフォルトでは入力ファイル名を使用します）
source_format	string	❌	入力形式（任意。ファイル拡張子から自動検出します）
options	object	❌	変換オプション

オプション：

オプション	型	デフォルト	説明
template	string	-	テンプレート名
css	string	-	カスタム CSS スタイル
preserve_metadata	boolean	true	メタデータを保持するかどうか
extract_images	boolean	true	画像を抽出するかどうか

例：

{
  "source_path": "/path/to/document.md",
  "target_format": "html",
  "output_path": "/path/to/output.html",
  "options": {
    "css": "body { font-family: Arial; }",
    "preserve_metadata": true
  }
}

拡張機能の開発

新しいパーサーの追加

from typing import List, Union
from pathlib import Path
from mcp_document_converter.core.parser import BaseParser
from mcp_document_converter.core.ir import DocumentIR, Node, NodeType

class MyParser(BaseParser):
    @property
    def supported_extensions(self) -> List[str]:
        return [".myext"]
    
    @property
    def format_name(self) -> str:
        return "myformat"
    
    @property
    def mime_types(self) -> List[str]:
        return ["application/x-myformat"]
    
    def parse(self, source: Union[str, Path, bytes], **options) -> DocumentIR:
        # Read source file
        content = self._read_source(source)
        
        # Parse into DocumentIR
        document = DocumentIR()
        document.title = "My Document"
        
        # Add content nodes
        document.add_node(Node(
            type=NodeType.PARAGRAPH,
            content=[Node(type=NodeType.TEXT, content="Hello World")]
        ))
        
        return document

新しいレンダラーの追加

from typing import Any
from mcp_document_converter.core.renderer import BaseRenderer
from mcp_document_converter.core.ir import DocumentIR

class MyRenderer(BaseRenderer):
    @property
    def output_extension(self) -> str:
        return ".myext"
    
    @property
    def format_name(self) -> str:
        return "myformat"
    
    @property
    def mime_type(self) -> str:
        return "application/x-myformat"
    
    def render(self, document: DocumentIR, **options: Any) -> str:
        # Render DocumentIR to target format
        parts = []
        
        if document.title:
            parts.append(f"# {document.title}")
        
        for node in document.content:
            # Render each node
            pass
        
        return "\n".join(parts)

拡張機能の登録

from mcp_document_converter.registry import get_registry

# Register new parser and renderer
registry = get_registry()
registry.register_parser(MyParser())
registry.register_renderer(MyRenderer())

テスト

# Run all tests
python tests/test_conversion.py

# Run specific test
python tests/test_conversion.py::test_markdown_to_html

環境変数

変数	説明	デフォルト
MCP_CONVERTER_LOG_LEVEL	ログレベル	INFO
MCP_CONVERTER_TEMP_DIR	一時ファイルのディレクトリ	システムの一時ディレクトリ

依存関係

コア依存関係

• mcp >= 1.26.0 - MCP プロトコルの実装
• pydantic >= 2.12.5 - データ検証

パーサーの依存関係

• markdown >= 3.5.0 - Markdown の解析
• beautifulsoup4 >= 4.12.0 - HTML の解析
• python-docx >= 1.1.0 - DOCX の解析
• pypdf >= 6.7.4 - PDF の解析
• chardet >= 5.0.0 - 文字エンコーディングの検出
• pyyaml >= 6.0.0 - YAML の解析

レンダラーの依存関係

• weasyprint >= 60.0 - PDF のレンダリング
• pygments >= 2.17.0 - コードのハイライト表示
• jinja2 >= 3.1.6 - テンプレートエンジン
• reportlab >= 4.0.0 - PDF の生成

開発用依存関係

• pytest >= 7.0.0 - テストフレームワーク
• pytest-asyncio >= 0.21.0 - 非同期テストのサポート
• pytest-cov >= 4.0.0 - カバレッジレポート
• basedpyright >= 1.0.0 - 型チェック
• ruff >= 0.1.0 - リントとフォーマット

ライセンス

MIT ライセンス

コントリビューション

Issue と Pull Request を歓迎します！

関連プロジェクト

• MCP Document Reader - 複数のドキュメント形式に対応した MCP ドキュメントリーダー
• Model Context Protocol - Model Context Protocol の公式ドキュメント