Huoshui Pdf Converter

活水PDF转换器（Huoshui PDF Converter）

   ](https://pypi.org/project/huoshui-pdf-converter/)

一个高质量的跨平台PDF ↔ Markdown转换器，以MCP（模型上下文协议）服务器的形式实现。支持双向转换，全面兼容Unicode/CJK字符。

特点/功能

核心能力

• PDF → Markdown（翻译为中文即：将PDF转换为Markdown）提取文本和图像并保持布局
• Markdown → PDF（Markdown转换为PDF）使用多种渲染引擎生成精美的PDF文件
• Unicode支持全面支持中文、日文、韩文及其他Unicode字符
• 跨平台适用于Windows、macOS和Linux系统
• MCP集成与Claude桌面版或任何MCP兼容的客户端一起使用

技术特性

• 纯Python无需外部系统依赖
• 自动字体检测查找并使用系统Unicode字体
• 智能引擎选择根据内容自动切换引擎
• 全面错误处理优雅降级和详细日志记录
• 异步架构非阻塞操作以提升性能

安装

来自MCP注册表（推荐）

此服务器可在模型上下文协议注册表中找到。请使用您的MCP客户端进行安装。

mcp-name: io.github.huoshuiai42/huoshui-pdf-converter 翻译为中文是：“MCP名称：io.github.huoshuiai42/huoshui-pdf-converter（火水PDF转换器）”。不过，这里的“火水PDF转换器”是根据“huoshui”（可能意为“火水”或为特定项目名）和“PDF转换器”的功能进行的意译，实际翻译时可能需要根据具体项目或公司的命名习惯来调整。如果“huoshuiai42”和“huoshui”是特定的项目名或品牌名，那么直接保留原样也是合理的。因此，一个更通用的翻译可能是：“MCP名称：io.github.huoshuiai42/huoshui-pdf-converter（火水项目PDF转换器）”

作为一个Python包

pip install huoshui-pdf-converter

或者使用 uv （推荐）：

uv pip install huoshui-pdf-converter

作为MCP服务器

在您的Claude桌面配置中添加：

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转换为Markdown将PDF文件转换为Markdown格式

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

1. 将Markdown转换为PDF将Markdown文件转换为PDF

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

1. 列出支持的格式获取支持的格式和引擎

1. 验证文件在转换前验证输入文件

支持的格式

输入格式

• PDF（Portable Document Format，便携式文档格式）所有标准PDF文件（PDF 1.0至1.7版本）
• Markdown（一种轻量级的标记语言，用于格式化文本）CommonMark 和 GitHub 扩展的 Markdown

输出选项

• 页面大小A4、A3、信纸尺寸（Letter）、法律文件尺寸（Legal）
• 边距可定制（例如，“1厘米”，“0.5英寸”）
• 字体大小任意点数大小
• 图片从PDF中提取PNG、JPEG格式

Unicode和字体支持

该转换器能够自动检测并使用适用于不同语言的适当字体：

• macOSArial Unicode、苹方（PingFang SC）、思源黑体（STHeiti）
• Windows微软雅黑，宋体，Arial Unicode MS（一种支持多种语言字符的无衬线字体）
• LinuxNoto Sans CJK，思源黑体（Source Han Sans），文泉驿（WenQuanYi）

建筑学

转换引擎

PDF → Markdown（即：将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或类似字体 - 转换器将自动检测并使用合适的字体

1. 导入错误：

- 安装所有依赖项： pip install huoshui-pdf-converter[all]

1. 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许可协议授权 - 请参阅 许可证 文件中有详细信息。

致谢

• 使用（某种材料/技术/工具）建造 FastMCP 用于模型上下文协议支持
• 用途 PyMuPDF（注：这是一个库或软件的名称，直接翻译可能无法准确传达其含义，但在此处可理解为“Python的MuPDF库”或保持原名以指代特定的Python库） 用于PDF解析
• 用途 ReportLab（注：这是一个用于生成PDF等文档的Python库的名称，直接翻译可能无法准确传达其专业含义，因此在此保留原英文名称） 用于生成PDF文件
• 受改进PDF与Markdown转换工具需求的启发

支持

• 问题:
• 讨论：
• 电子邮件您的邮箱示例：your.email@example.com