xfa pdf mcp
用于读取和填写XFA-PDF表单字段的MCP（模型上下文协议）服务器。专为加拿大移民表格（IRCC IMM系列）而设计，但适用于任何XFA-PDF。
经过测试 95+IRCC移民表格 100%往返成功。
快速入门（托管）
无需安装。只需一步即可连接到托管的MCP服务器。
ChatGPT
- 首选 设置 > 开发者模式 （必要时启用）
- 首选 连接器 > 添加MCP服务器
- 输入URL:
https://xfa-pdf-mcp.vflo.app/mcp - 将其命名为“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容器中。此服务器：
- 打开PDF
pikepdf - 提取XFA
datasetsXML（表单数据）和templateXML（字段定义） - 构建所有字段的元数据缓存，包括LOV（值列表）下拉选项
- 通过修改数据集XML、自动将标签解析为代码来填充字段
- 写回修改后的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）
许可证
麻省理工学院