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 的客户端搭配使用

技术特性

• 纯 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. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 使用 FastMCP 构建，以支持 Model Context Protocol
• 使用 PyMuPDF 解析 PDF
• 使用 ReportLab 生成 PDF
• 灵感源于对更完善的 PDF ↔ Markdown 转换工具的需求

支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• 电子邮件：[email protected]