金大哥 - huoshui-pdf-converter MCP 详情

article

README

🚀 活水 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 服务器使用时，可使用以下工具：

pdf_to_markdown：将 PDF 文件转换为 Markdown

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

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
}

list_supported_formats：获取支持的格式和引擎
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 生成功能（最后选择）。

引擎选择逻辑

检测到 CJK 字符时 → 使用 ReportLab。
遇到复杂格式时 → 使用 xhtml2pdf。
处理基本文档时 → 使用任何可用的引擎。

开发

设置开发环境

# 克隆仓库
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

故障排除

常见问题

中文字符显示问题：
- 确保安装了 Arial Unicode 或类似字体。
- 转换器会自动检测并使用合适的字体。
导入错误：
- 安装所有依赖项：pip install huoshui-pdf-converter[all]。
MCP 连接问题：
- 检查 Claude Desktop 日志。
- 确保 Python 已添加到系统路径中。

日志记录

启用调试日志：

import logging
logging.basicConfig(level=logging.DEBUG)

贡献

欢迎贡献代码！请按以下步骤操作：

分叉仓库。
创建功能分支（git checkout -b feature/amazing-feature）。
提交更改（git commit -m 'Add amazing feature'）。
推送到分支（git push origin feature/amazing-feature）。
打开拉取请求。

📄 许可证

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

致谢

使用 FastMCP 实现模型上下文协议支持。
使用 PyMuPDF 进行 PDF 解析。
使用 ReportLab 进行 PDF 生成。
受对更好的 PDF 与 Markdown 转换工具需求的启发。

支持

问题反馈：GitHub Issues
讨论交流：GitHub Discussions
邮箱联系：your.email@example.com

huoshui-pdf-converter