AI导哈

XFA-PDF表单填充服务

一个用于读取和填充XFA-PDF表单字段的MCP服务器，适用于加拿大移民表格（IRCC IMM系列）以及任何XFA-PDF文件，支持智能值解析和动态行管理。

  • by VisaFlo
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 VisaFlo/xfa-pdf-mcp

使用说明

xfa pdf mcp

用于读取和填写XFA-PDF表单字段的MCP（模型上下文协议）服务器。专为加拿大移民表格（IRCC IMM系列）而设计，但适用于任何XFA-PDF。

经过测试 95+IRCC移民表格 100%往返成功。

快速入门（托管）

无需安装。只需一步即可连接到托管的MCP服务器。

ChatGPT

  1. 首选 设置 > 开发者模式 （必要时启用）
  2. 首选 连接器 > 添加MCP服务器
  3. 输入URL: https://xfa-pdf-mcp.vflo.app/mcp
  4. 将其命名为“XFA PDF Filler”并保存

然后问ChatGPT： “上传imm5257e.pdf并填写FamilyName=KIM，GivenName=YULBIN”

克劳德代码

claude mcp add --transport http xfa-pdf https://xfa-pdf-mcp.vflo.app/mcp

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "xfa-pdf": {
      "type": "streamable-http",
      "url": "https://xfa-pdf-mcp.vflo.app/mcp"
    }
  }
}

OpenAI代理SDK/响应API

# Connect as an MCP tool source
tool = {"type": "mcp", "server_url": "https://xfa-pdf-mcp.vflo.app/mcp"}

自托管设置

选项1:Docker（推荐）

docker run -p 8080:8080 ghcr.io/visaflo/xfa-pdf-mcp

然后连接克劳德：

claude mcp add --transport http xfa-pdf http://localhost:8080/mcp

选项2：本地（stdio）

需要Python 3.11+。

git clone https://github.com/VisaFlo/xfa-pdf-mcp.git
cd xfa-pdf-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

claude mcp add --transport stdio --scope user xfa-pdf-mcp \
  /path/to/xfa-pdf-mcp/.venv/bin/python -- -m xfa_pdf_mcp.server

运作原理

XFA PDF将表单定义和数据作为XML嵌入到PDF容器中。此服务器：

  1. 打开PDF pikepdf
  2. 提取XFA datasets XML（表单数据）和 template XML（字段定义）
  3. 构建所有字段的元数据缓存，包括LOV（值列表）下拉选项
  4. 通过修改数据集XML、自动将标签解析为代码来填充字段
  5. 写回修改后的XML并保存新的PDF

填写时不需要Adobe Acrobat。输出PDF必须在Adobe Reader/AAcrobat中打开才能正确呈现（浏览器不支持XFA）。

工具

工具 说明
upload_pdf 通过URL或base64上传PDF。URL是大文件的首选。
list_fields 列出所有可填写的字段，包括路径、类型、值和下拉选项
get_field_values 获取特定字段路径的当前值
fill_fields 使用标签、复选框和日期的自动解析批量填充字段
download_pdf 以base64格式下载已填写的PDF
close_pdf 关闭和免费资源
list_repeating_sections 列出动态行部分（家属、子女、就业等）
add_row 向重复节添加新行

上传选项： upload_pdf 接受其中之一 pdf_url （指向PDF的HTTP/HTTPS链接）或 pdf_base64 （内联base64）。建议对大文件使用URL，以避免有效负载大小限制。

对于本地stdio模式， upload_pdf/download_pdf 被替换为 open_pdf （文件路径）/ save_pdf （文件路径）。

工作流程

upload_pdf -> list_fields -> fill_fields -> download_pdf -> close_pdf

对于具有动态行的表单：

upload_pdf -> list_repeating_sections -> add_row (repeat) -> download_pdf -> close_pdf

智能价值解决方案

服务器会自动将人类可读的值解析为正确的表单代码。

下拉菜单（选项列表）

传递显示标签而不是代码。引擎从表单的数据集XML中提取LOV（值列表）并自动解析。

"Canada"       -> "511"
"Married"      -> "01"
"Korea, South" -> "258"
"BC"           -> "11"
"Vancouver"    -> "8634"

级联依赖下拉（省取决于国家，市取决于省）是通过合并所有LOV列表来处理的。

复选框（复选按钮）

传递类似布尔值的值。发动机从模板中读取正确的开/关值。

"true"  -> "Y" (or "N", "1", etc. depending on the field)
"false" -> "" (or "0", etc.)

接受的输入： true/false, yes/no, checked/unchecked, on/off, 1/0

日期（日期时间编辑/图片）

以任何通用格式传递日期。发动机正常化为 YYYY-MM-DD.

"01/15/2025"         -> "2025-01-15"
"20250115"           -> "2025-01-15"
"January 15, 2025"   -> "2025-01-15"
"2025/01/15"         -> "2025-01-15"

动态行

某些表单有重复的部分（家属、子女、就业历史等），可以动态添加行：

# List available repeating sections
sections = list_repeating_sections(doc_id)
# -> [{"path": "IMM_5707/page1/SectionB/Child", "max": -1, "current_count": 4, ...}]

# Add a new row
add_row(doc_id, "IMM_5707/page1/SectionB/Child", {
    "FamilyName": "SIMPSON",
    "GivenName": "BART",
    "Relationship": "Son",
    "DOBYear": "2005",
})

示例

“在~/Downloads/imm5257e.pdf打开IMM5257表格，列出个人详细信息字段，填写：姓氏=KIM，给予者姓名=YULBIN，性别=男性，地点出生国=韩国，公民身份=韩国，出生年份=1990，出生月份=01，出生日期=15。保存到~/Desktop/inm5257_filed.pdf“

字段类型

类型 描述
textEdit 自由文本输入
choiceList 带有LOV选项的下拉菜单（自动解析）
checkButton 复选框（自动从true/false解析）
dateTimeEdit 日期选择器（自动标准化为YYYY-MM-DD）
numericEdit 数字输入
picture 屏蔽输入（日期、邮政编码）
barcode 自动生成条形码（只读）
signature 签名字段

测试

# All tests (42 total)
.venv/bin/pytest tests/ -v

# Unit tests only
.venv/bin/pytest tests/test_engine.py tests/test_engine_bytes.py -v

# Integration tests (require IMM PDFs in ~/Downloads/)
.venv/bin/pytest tests/test_integration.py -v

测试表格

已通过95+IRCC移民表格验证，包括：

表格 说明
IMM 0008 加拿大通用申请表
IMM 1283 财务评估
IMM 1294 学习许可申请
IMM 1295 工作许可申请
IMM 1344 担保申请
IMM 5257 临时居民签证申请
IMM 5406 其他家庭信息
IMM 5409 普通法同居法定声明
IMM 5476 代理人的使用
IMM 5490 赞助协议和承诺
IMM 5532 关系信息
IMM 5562 补充信息-您的旅行
IMM 5645 家庭信息
IMM 5707 家庭信息（IMM 5707）
IMM 5708 访客许可申请
IMM 5709 学习许可申请（加拿大）
IMM 5710 工作许可申请（加拿大）
IMM 5768 超级签证的财务评估

建筑

                     +------------------+
                     |   XfaPdfEngine   |
                     |  (pikepdf+lxml)  |
                     +--------+---------+
                              |
              +---------------+---------------+
              |                               |
    +---------v----------+        +-----------v-----------+
    |  Local MCP Server  |        |  Remote MCP Server    |
    |  (stdio)           |        |  (streamable-http)    |
    |  server.py         |        |  server_remote.py     |
    +--------------------+        +-----------------------+
              |                               |
    Claude Code/Desktop           ChatGPT, Claude Desktop,
    (local install)               Claude Code, OpenAI Agents
                                  (hosted — no install)

部署

谷歌云运行

gcloud run deploy xfa-pdf-mcp --source . --region us-central1 --allow-unauthenticated

码头工人

docker build -t xfa-pdf-mcp .
docker run -p 8080:8080 xfa-pdf-mcp

局限性

  • 输出PDF必须在中打开 Adobe Reader/Acrobat （不是Chrome、预览版或Firefox）
  • 字段与 bind="none" 模板中的内容不能通过数据集填写
  • 嵌入式JavaScript验证仅在Adobe Reader中运行
  • 保存时删除数字签名（需要避免“认证无效”警告）
  • 少数表格（例如IMM 5444）没有LOV数据；下拉菜单需要原始代码值
  • 不支持非XFA PDF（仅限AcroForm）

许可证

麻省理工学院

相关 MCP