Huoshui Pdf Converter

🚀 活水 PDF 轉換器 (Huoshui PDF Converter)

活水 PDF 轉換器是一款高質量、跨平臺的 PDF 與 Markdown 雙向轉換器，以 MCP（模型上下文協議）服務器形式實現，全面支持 Unicode/CJK 字符。

🚀 快速開始

活水 PDF 轉換器是一個強大的工具，可實現 PDF 與 Markdown 之間的雙向轉換。你可以通過以下幾種方式安裝和使用它。

✨ 主要特性

核心功能

• PDF 轉 Markdown：提取文本和圖像並保留佈局。
• Markdown 轉 PDF：使用多種渲染引擎生成精美的 PDF。
• Unicode 支持：全面支持中文、日文、韓文和其他 Unicode 字符。
• 跨平臺：可在 Windows、macOS 和 Linux 上運行。
• MCP 集成：可與 Claude Desktop 或任何 MCP 兼容的客戶端配合使用。

技術特性

• 純 Python 實現：無需外部系統依賴。
• 自動字體檢測：查找並使用系統 Unicode 字體。
• 智能引擎選擇：根據內容自動切換引擎。
• 全面的錯誤處理：優雅降級並提供詳細日誌。
• 異步架構：非阻塞操作，性能更佳。

📦 安裝指南

從 MCP 註冊表安裝（推薦）

此服務器可在模型上下文協議註冊表中獲取。使用你的 MCP 客戶端進行安裝。 mcp 名稱：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 已添加到系統路徑中。

日誌記錄

啟用調試日誌：

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 文件。

致謝

• 使用 FastMCP 實現模型上下文協議支持。
• 使用 PyMuPDF 進行 PDF 解析。
• 使用 ReportLab 進行 PDF 生成。
• 受對更好的 PDF 與 Markdown 轉換工具需求的啟發。

支持

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions
• 郵箱聯繫：your.email@example.com