PDF Developer Helper

这是一个本地 MCP server，用来协助 PDF 开发者调试、渲染、解析和做页面回归检查。它通过 stdio 暴露工具，适合接入 Codex、Claude Desktop 或其他支持 MCP 的客户端。

功能

• 检查 PDF 基本信息、metadata、页尺寸、旋转、注释数量。
• 提取指定页面文本。
• 搜索 PDF 文本并返回上下文。
• 渲染单页 PDF 为 PNG/JPEG。
• 可选：使用基于 PDFium 的原生命令行程序渲染页面，支持选择 PDFium 渲染后端和常用渲染参数。
• 分析页面布局，返回文本块、图片块、链接、字体和绘图对象概要。
• 对比两个 PDF 页面渲染后的像素差异，可输出 diff 图。
• 用 pypdf 和 PyMuPDF 做基础打开校验，帮助定位损坏文件或渲染问题。
• 可选：通过浏览器自动化调用 PDFCrowd Inspect PDF 页面，查看更详细的 Info、Images、Fonts、Objects。

安装

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

如果要使用 PDFCrowd Inspect PDF 页面解析工具，还需要安装可选浏览器依赖：

pip install -e ".[web]"
python -m playwright install chromium

如果要使用 PDFium 原生渲染 CLI，需要下载 PDFium SDK 并构建：

.\scripts\setup-pdfium.ps1 -V8
cmake -S native\pdfium-renderer -B build\pdfium-renderer -DPDFIUM_ROOT="$PWD\.deps\pdfium-v8-win-x64"
cmake --build build\pdfium-renderer --config Release

如果已经有本机 PDFium，例如：

C:\Users\ikun\Downloads\pdfium-v8-win-x64

可以直接构建：

cmake -S native\pdfium-renderer -B build\pdfium-renderer -DPDFIUM_ROOT="C:\Users\ikun\Downloads\pdfium-v8-win-x64"
cmake --build build\pdfium-renderer --config Release

本地运行

python -m pdf_developer_helper.server

或者安装后直接运行：

pdf-developer-helper

MCP 客户端配置示例

如果你使用当前目录下的虚拟环境，可以把 MCP server 配成：

{
  "mcpServers": {
    "pdf-developer-helper": {
      "command": "C:\\PDF-Developer-Hepler\\.venv\\Scripts\\python.exe",
      "args": ["-m", "pdf_developer_helper.server"],
      "cwd": "C:\\PDF-Developer-Hepler"
    }
  }
}

工具列表

• inspect_pdf: 读取文件大小、哈希、页数、metadata 和页面概要。
• validate_pdf: 使用多个 PDF 库检查文件是否能正常打开。
• extract_text: 提取指定页面文本，支持 1,3-5,last 这样的页面选择。
• search_text: 在文本层里搜索关键词并返回上下文。
• render_page: 把单页渲染为图片，默认输出到 .pdf-helper-output/rendered。
• render_page_with_pdfium: 调用 native/pdfium-renderer 构建出的 PDFium CLI 渲染单页，输出 BMP。
• analyze_page_layout: 查看单页文本块、图片块、链接、字体和绘图对象概要。
• compare_pages: 渲染两个 PDF 页面并计算像素差异，适合排查回归。
• inspect_pdf_with_pdfcrowd: 打开 https://pdfcrowd.com/inspect-pdf/，把本地 PDF 传给页面的文件输入框，并抓取 Info、Images、Fonts、Objects 文本。

页面编号使用 1-based 编号，也就是第一页传 1。

inspect_pdf_with_pdfcrowd 是外部网页自动化工具，不会影响其它本地工具。若需要走代理，可以传：

{
  "pdf_path": "C:\\path\\to\\file.pdf",
  "proxy_server": "http://127.0.0.1:7897"
}

render_page_with_pdfium 支持的关键参数：

{
  "pdf_path": "C:\\path\\to\\file.pdf",
  "page_number": 1,
  "backend": "default",
  "dpi": 144,
  "rotation": 0,
  "background": "#FFFFFF",
  "render_annotations": true
}

backend 可以是 default、agg、skia。skia 是否可用取决于下载的 PDFium build 是否包含 Skia。

测试

pytest