Huoshui Pdf Converter

🚀 活水 PDF コンバーター (Huoshui PDF Converter)

このコンバーターは、高品質でクロスプラットフォーム対応の PDF と Markdown の相互変換を行う MCP (Model Context Protocol) サーバーとして実装されています。双方向変換に対応し、全ての Unicode/CJK 文字をサポートしています。

✨ 主な機能

コア機能

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

技術的特徴

• Pure Python：外部システムの依存関係は必要ありません。
• 自動フォント検出：システムの Unicode フォントを自動的に検出して使用します。
• スマートエンジン選択：コンテンツに基づいて自動的にエンジンを切り替えます。
• 包括的なエラーハンドリング：エラー時の適切な対応と詳細なログ記録を行います。
• 非同期アーキテクチャ：非ブロッキング操作により、パフォーマンスが向上します。

📦 インストール

MCP レジストリから (推奨)

このサーバーは Model Context Protocol レジストリで利用可能です。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": {}
    }
  }
}

💻 使用例

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

# PDF を Markdown に変換
huoshui-pdf pdf-to-md input.pdf output.md

# Markdown を PDF に変換
huoshui-pdf md-to-pdf input.md output.pdf

# オプション付き
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 を Markdown に変換
    pdf_converter = PDFToMarkdownConverter()
    result = await pdf_converter.convert(
        pdf_path="input.pdf",
        output_path="output.md",
        extract_images=True,
        preserve_formatting=True
    )

    # Markdown を 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. 基本的なドキュメントの場合 → 利用可能なエンジンを使用

開発

開発環境のセットアップ

# リポジトリをクローン
git clone https://github.com/yourusername/huoshui-pdf-converter.git
cd huoshui-pdf-converter

# 依存関係をインストール
uv pip install -e ".[dev]"

# テストを実行
python test_converter.py

プロジェクト構造

huoshui-pdf-converter/
├── huoshui_pdf_converter/
│   ├── __init__.py
│   ├── server.py           # MCP サーバーの実装
│   ├── pdf_converter.py    # PDF から Markdown へのコンバーター
│   └── markdown_converter.py # Markdown から PDF へのコンバーター
├── 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 ファイルを参照してください。

謝辞

• Model Context Protocol サポートに FastMCP を使用しています。
• PDF 解析に PyMuPDF を使用しています。
• PDF 生成に ReportLab を使用しています。
• より良い PDF ↔ Markdown 変換ツールの必要性に触発されて作成されました。

サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• メール: your.email@example.com