PDF Form Proof

pdf-form-proof

填写可填写的 PDF 表单，然后验证每个值确实显示在页面上。

mcp-name: io.github.EssenceAlignment/pdf-form-proof

PDF 可以在数据中保存某个值，但人们查看、打印或上传的页面上却什么也不显示，或者显示不全。大多数表单工具做到“字段已设置”就停止了。这个工具会继续验证：它会渲染页面，再通过 OCR（光学字符识别，即从图像中读取文字的软件）读取页面，并将识别结果与文件中存储的文本进行比较。每个值都会得到 VISIBLE、INVISIBLE、RENDER-ONLY 或 MISSING 判定。

它可作为 MCP 服务（MCP，即 Model Context Protocol，是一种让 Claude 等 AI 应用调用外部工具的插件标准）、Claude 插件、Gemini CLI 扩展，也可作为普通命令行工具使用。

功能

工具	功能	会修改文件吗？
pdf_form_inspect	列出所有可填写字段：确切名称、类型、当前值、必填标记，以及用于勾选每个复选框或单选按钮的值	否
pdf_form_fill	按确切名称填写字段并写入新的 PDF。如果有任何名称不在表单中，就会拒绝整个填写操作。绝不会修改源文件，也不会覆盖现有文件。返回新文件的 SHA-256，并读取所有文本值以进行核验	写入一个新文件
pdf_form_verify	渲染页面、对其运行 OCR，并为每个值给出判定。可以将检查范围限制在页面的某个区域，避免页面其他位置出现的相同值导致验证通过	否
pdf_sha256	生成文件的 SHA-256 指纹，精确记录所生成的文件	否

所有工具都带有 MCP 注解：四个工具均设置了 readOnlyHint 和 destructiveHint。

适用对象

适用于需要反复填写同一类官方 PDF 的任何人：小型非营利组织和社区组织（例如供应商表格，包括 IRS W-9、拨款和资助方表格、项目登记及同意书）、运营人员，以及希望 AI 助手填写表格时不会掩盖填写不完整或不可见问题的开发者。

安装

你需要 Python 3.10 或更高版本，以及 uv（https://docs.astral.sh/uv/）。验证工具还需要安装两个免费程序：

• macOS：brew install poppler tesseract
• Debian 或 Ubuntu：sudo apt install poppler-utils tesseract-ocr

Claude Desktop（MCP 服务）

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "pdf-form-proof": {
      "command": "uvx",
      "args": ["pdf-form-proof"]
    }
  }
}

或者安装最新 GitHub 版本中的 .mcpb 文件：双击该文件，或前往 Settings > Extensions > Advanced settings > Install Extension。

Claude Code（插件）

claude plugin marketplace add EssenceAlignment/pdf-form-proof
claude plugin install pdf-form-proof@pdf-form-proof

Gemini CLI（扩展）

gemini extensions install https://github.com/EssenceAlignment/pdf-form-proof

命令行

uvx --from pdf-form-proof pdf-form-inspect form.pdf
uvx --from pdf-form-proof pdf-form-fill form.pdf filled.pdf values.json
uvx --from pdf-form-proof pdf-form-verify filled.pdf --require "Sample Community Food Bank"

values.json 将确切字段名称（来自 pdf-form-inspect）映射到对应的值：

{
  "topmostSubform[0].Page1[0].f1_01[0]": "Sample Community Food Bank",
  "topmostSubform[0].Page1[0].Boxes3a-b_ReadOrder[0].c1_1[0]": "/1"
}

文本字段接受字符串。复选框或单选按钮接受其某个开启状态值（由 inspect 显示，例如 "/1" 或 "/Yes"），也可以接受空字符串以清除选择。

退出代码：0 表示成功；1 表示发现问题（verify 发现某个值不可见，或填入的值无法读回）；2 表示拒绝操作（字段名称未知、文件缺失、输出文件已存在，或 tesseract 等工具出错）。

示例

$ pdf-form-verify filled.pdf --require "Sample Community Food Bank" --require "Sample Pantry Program"
PDF FORM PROOF - legibility check  verdict: PASS
  file: filled.pdf  page 1 at 300 dpi  scope: whole page
  VALUE                       SOURCE    TEXT  RENDER  VERDICT
  Sample Community Food Bank  required  yes   yes     VISIBLE
  Sample Pantry Program       required  yes   yes     VISIBLE
  limit: legibility only; says nothing about whether values are correct

限制（请仔细阅读）

• 仅支持 AcroForm 表单。检测到仅含 XFA 的表单（Adobe LiveCycle 动态表单）时会拒绝填写。
• finalize 会移除 XFA 数据包和 NeedAppearances 标记，使查看器根据各自的外观流绘制这些值。它不会扁平化表单；字段仍可编辑。
• 验证证明的是可读性，而非正确性。它无法判断某个值是否为表单要求的正确答案。
• OCR 可能会误读较小、风格化或手写风格的字体。REFUSE 判定意味着“查看页面”，而不是“文件已损坏”。工具故障（缺少 poppler 或 tesseract、渲染错误）会报告为工具故障，绝不会作为文档问题报告。
• 不会创建签名。inspect 会列出签名字段，但不会对其进行处理。
• 此工具用于填写表单，不提供法律、税务、福利或其他专业建议，也不会决定任何字段应填写什么内容。

隐私政策

pdf-form-proof 完全在你的计算机上运行。

• 数据收集：无。它只读取你指定的 PDF 文件，并且只写入你指定的输出路径。
• 使用和存储：每张渲染后的页面图像都会写入 ~/.cache/pdf-form-proof 下的临时文件夹，并在 OCR 步骤完成后立即删除，包括步骤失败的情况。除非你使用 --keep-render 要求保留副本，否则不会有任何内容留在磁盘上。（0.1.0 版本会保留最后一张图像，直到下次运行；0.1.1 会在首次运行时删除任何此类遗留文件。）
• 与第三方共享：无。它不会发起网络请求，也不会发送遥测数据。
• 保留期限：除你创建的文件外，不会保留任何内容。
• 联系方式：请在 https://github.com/EssenceAlignment/pdf-form-proof/issues 提交问题

起源

填充引擎和页面可见性检查是为生产文档工作流而开发的。当时，一份已填表单通过了所有基于文本的检查，却仍被退回，因为页面上看不到某个值。由此总结出两条规则：绝不隐藏未完成的填充；检查人们实际看到的页面，而不只检查文件中的数据。

作者

由 Eric Brakebill-Jones 构建，MSW 系统架构师 | 临床工作流与资助数据沿袭。 GitHub：https://github.com/EssenceAlignment

更改

• 0.1.1：OCR 完成后立即删除渲染后的页面图像（在 0.1.0 中，该图像会保留到下次运行）。新增作者信息。
• 0.1.0：首次发布。

许可证

MIT。请参阅 LICENSE。