huoshui-pdf-converter

活水 PDF コンバーター（Huoshui PDF Converter）

MCP（Model Context Protocol）サーバーとして実装された、高品質でクロスプラットフォーム対応の PDF ↔ Markdown コンバーターです。Unicode/CJK 文字を完全にサポートし、双方向変換が可能です。

特長

主な機能

• PDF → Markdown：レイアウトを保持しながらテキストと画像を抽出します
• Markdown → PDF：複数のレンダリングエンジンを使用して、美しい PDF を生成します
• Unicode サポート：中国語、日本語、韓国語などの Unicode 文字を完全にサポートします
• クロスプラットフォーム：Windows、macOS、Linux で動作します
• MCP 統合：Claude Desktop または MCP 互換クライアントで使用できます

技術的な特長

• Pure Python：外部のシステム依存関係は不要です
• フォントの自動検出：システムの Unicode フォントを検出して使用します
• スマートなエンジン選択：コンテンツに応じてエンジンを自動で切り替えます
• 包括的なエラー処理：適切な縮退動作と詳細なログ記録を提供します
• 非同期アーキテクチャ：パフォーマンス向上のため、ブロッキングしない処理を実現します

インストール

MCP Registry から（推奨）

このサーバーは Model Context Protocol Registry で利用できます。お使いの MCP クライアントを使用してインストールしてください。

mcp-name: io.github.huoshuiai42/huoshui-pdf-converter

Python パッケージとして

pip install huoshui-pdf-converter

または、uv を使用します（推奨）。

uv pip install huoshui-pdf-converter

MCP サーバーとして

Claude Desktop の設定に追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "huoshui-pdf-converter": {
      "command": "uvx",
      "args": ["huoshui-pdf-converter"],
      "env": {}
    }
  }
}

特定の Python 環境を使用する場合は、次のように設定します。

{
  "mcpServers": {
    "huoshui-pdf-converter": {
      "command": "python",
      "args": ["-m", "huoshui_pdf_converter.server"],
      "env": {}
    }
  }
}

使用方法

コマンドラインインターフェース

# Convert PDF to Markdown
huoshui-pdf pdf-to-md input.pdf output.md

# Convert Markdown to PDF
huoshui-pdf md-to-pdf input.md output.pdf

# With options
huoshui-pdf md-to-pdf input.md output.pdf --page-size A4 --margin 2cm --font-size 12

Python ライブラリとして

import asyncio
from huoshui_pdf_converter import PDFToMarkdownConverter, MarkdownToPDFConverter

async def main():
    # PDF to Markdown
    pdf_converter = PDFToMarkdownConverter()
    result = await pdf_converter.convert(
        pdf_path="input.pdf",
        output_path="output.md",
        extract_images=True,
        preserve_formatting=True
    )

    # Markdown to PDF
    md_converter = MarkdownToPDFConverter()
    result = await md_converter.convert(
        markdown_path="input.md",
        output_path="output.pdf",
        page_size="A4",
        margin="2cm",
        font_size=12
    )

asyncio.run(main())

MCP ツール

MCP サーバーとして使用する場合、次のツールを利用できます。

1. pdf_to_markdown：PDF ファイルを Markdown に変換します

   {
     "pdf_path": "path/to/input.pdf",
     "output_path": "path/to/output.md",
     "extract_images": true,
     "preserve_formatting": true
   }
   

2. markdown_to_pdf：Markdown ファイルを PDF に変換します

   {
     "markdown_path": "path/to/input.md",
     "output_path": "path/to/output.pdf",
     "page_size": "A4",
     "margin": "2cm",
     "font_size": 12
   }
   

3. list_supported_formats：対応形式とエンジンを取得します

4. validate_file：変換前に入力ファイルを検証します

対応形式

入力形式

• PDF：すべての標準的な PDF ファイル（PDF 1.0～1.7）
• Markdown：CommonMark および GitHub Flavored Markdown

出力オプション

• ページサイズ：A4、A3、Letter、Legal
• 余白：カスタマイズ可能（例：「1cm」、「0.5in」）
• フォントサイズ：ポイント単位で任意のサイズを指定できます
• 画像：PDF から PNG、JPEG を抽出します

Unicode とフォントのサポート

このコンバーターは、言語に応じた適切なフォントを自動で検出して使用します。

• macOS：Arial Unicode、PingFang SC、STHeiti
• Windows：Microsoft YaHei、SimSun、Arial Unicode MS
• Linux：Noto Sans CJK、Source Han Sans、WenQuanYi

アーキテクチャ

変換エンジン

PDF → Markdown

• PyMuPDF (MuPDF)：高品質なテキストと画像の抽出

Markdown → PDF

• ReportLab：Unicode の優れたサポートとクロスプラットフォーム互換性
• xhtml2pdf：優れた HTML/CSS レンダリング（フォールバック）
• fpdf2：基本的な PDF 生成（最終手段）

エンジン選択ロジック

1. CJK 文字を検出した場合 → ReportLab を使用します
2. 複雑な書式の場合 → xhtml2pdf を使用します
3. 基本的なドキュメントの場合 → 利用可能な任意のエンジンを使用します

開発

開発環境のセットアップ

# Clone the repository
git clone https://github.com/yourusername/huoshui-pdf-converter.git
cd huoshui-pdf-converter

# Install dependencies
uv pip install -e ".[dev]"

# Run tests
python test_converter.py

プロジェクト構成

huoshui-pdf-converter/
├── huoshui_pdf_converter/
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   ├── pdf_converter.py    # PDF to Markdown converter
│   └── markdown_converter.py # Markdown to PDF converter
├── pyproject.toml
├── README.md
├── LICENSE
└── test_converter.py

トラブルシューティング

よくある問題

1. 漢字が表示されない：

   • Arial Unicode または同様のフォントがインストールされていることを確認してください
   • コンバーターは適切なフォントを自動的に検出して使用します

2. インポートエラー：

   • すべての依存関係をインストールしてください：pip install huoshui-pdf-converter[all]

3. MCP 接続の問題：

   • Claude Desktop のログを確認してください
   • Python が PATH に含まれていることを確認してください

ログ記録

デバッグログを有効にします：

import logging
logging.basicConfig(level=logging.DEBUG)

コントリビューション

コントリビューションを歓迎します。次の手順に従ってください：

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

謝辞

• Model Context Protocol のサポートに FastMCP を使用しています
• PDF の解析に PyMuPDF を使用しています
• PDF の生成に ReportLab を使用しています
• より優れた PDF ↔ Markdown 変換ツールの必要性に着想を得ています

サポート

• 課題：GitHub Issues
• ディスカッション：GitHub Discussions
• メール：[email protected]