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