pdfnative-mcp

用于 PDF 生成、PDF/A 归档、带长期验证的 PAdES 签名、AcroForms、合并/拆分、加密与布局预览的 MCP 服务器 — 基于 pdfnative 引擎（零依赖、符合 ISO 32000/1）的 28 个工具，适用于 Claude Desktop、Cursor、ChatGPT 以及任何 Model Context Protocol 客户端。

[](https://www.npmjs.com/package/pdfnative-mcp]

✨ 功能

pdfnative-mcp 向任何 MCP 主机提供 28 个生产级工具：

v1.6.0 新功能：

• 1 完整引擎覆盖 — 13 种块类型 — `generate_basic_pdf` 接受 pdfnative 提供的每个 `DocumentBlock`：新增的 `table`、`image`、`link`、`toc`、`barcode`、`svg` 和 `formField` 块与专用工具（`add_table`、`embed_image`、`add_barcode`、`add_form`）在正文结构上共用，因此独立产物于内联块验证与渲染完全一致。规则：`link` 只接受 `http:` / `https:` / `mailto:`（拒绝控制字符）；`image` 块有大小限制（每个 12 M 个 base64 字符，每次调用解码后 24 MiB；PNG 必须是 8 位、非隔行扫描、不带 alpha 通道或调色板——否则会被拒绝并附上补救说明）；`svg` 涵盖路径、基本形状和 <text>（不支持 `transform`、<g> 渐变或 CSS，选项会被静默忽略；绝不获取外部内容）；`toc` 要与 `outline: 'auto'` 搭配使用；在声明 PDF/A 时 `formField` 会报 `PDFA_UNEMBEDDED_FORM_FONT`；`barcode` 没有 `alt`（引擎限制）。**

• 📐 九个文档工具上的布局选项 — `pageSize`（默认 `A4`，另有 `Letter`、`Legal`、`A3`、`Tabloid`）、`margins`（上下左右共四个边距，0–200 pt）、`headderTemplate` / `footerTemplate`，支持 `{page}` `{pages}` `{title}` `{date}`（指定 `footerTemplate` 会替换默认页脚，因此随后的 `footerText` 会被忽略；`{date}` 是构建当天的墙上时间，不是 `creationDate`）、`compress`（FlateDecode 流——文件更小，但字节不同；PDF/A 下 XMP 仍为明文）和 `debug`（辅助参考矩形、未标记内容——不可用于 PDF/UA）。默认不附带这些选项，因此默认输出保持字节级完全一致。

• 🔐 构建时加密 — 在七个文档工具（`generate_basic_pdf`、`add_table`、`add_form`、`add_international_text`、`embed_image`、`add_barcode`、`add_char）上提供 \encrypt`：标准安全处理器（Standard Security Handler），默认 AES-128 / AES-256，保留 AcroForm（与 `encrypt_pdf` 不同，后者会重建页面树）。与 `pdfA` 互斥（`VALIDATION_EXPLOR`），绝不缓存；在 `prepare_signature_placeholder`（必须保持可签名）或 `add_attachment`（PDF/A-3）上不提供此选项。

• 📏 `inspect_layout` — 第 28 个工具：对相同的 `blocks` 和 `layout` 输入做只读分页预览，在不渲染 PDF 的情况下报告 `totalPages` 以及每 block 的 page / x / top / width / height。已知引擎缺口：`toc` 块被量计为 0 pt，因此含打印目录的文档实际分页可能比预览晚 1 页。

• 🔎 `inspect_pdf annotations: true` — 列出每个页面标注（子类型 subtype、0 基页、rect、截断到 200 字符的 contents、title、colour、quadPoints、link URL），以及 `annotationCount`；新增 `check: 'annotations'`。

• 🖼️ 图片水印 — `generate_basic_pdf` 和 `add_table` 支持 `watermark.image`（JPEG/PNG，默认 opaque 0.10，自带 8 MiB 上限），颜色可单独使用或与 `text`（默认 opacity 0.15）组合；两者都支持 `position: 'background' | 'foreground'`。在 `pdfa1b` 下，任何不透明度低于 1.0 都会被拒绝。

• \ `PDFNATIVE_MCP_MAX_INFLATE_BYTES` — 操作者覆盖引擎每流 100 MiB 解压上限操作符（整数 ≥ 1024；无效会拒绝启动）。若附件流被限压上限卡住，`extract_attaactions includeData: true` 会以 `PDF_SE_FAIED` 失败；`extract_text` 会降级为空白页文本（引擎吞掉每页解码失败）。

• 📝 表单 — `add_form` 和 `formField` 块新增 `textbox` 和 `placeholder`；`fieldType: 'textarea'` 现在以 `multilineText` 传到引擎（之前未映射直接透传并渲染为单行单字段——这是 bug 修复，会改变该输入的字节）。`embed_image` 新增 `align` 和 `alt`。

• 🔵 PAdES 长期验证阶梯 — `sign_pdf` 新增 `profile: 'pades'`（ETSI EN 319 142-1 baseline、ESS signing-certificate-v2、`ETSI.CAdES.detached`）、`timestamp: true`（B-T，RFC 3161）、RSA-HA384/512、`certChainDerBase64`、`fieldName` / `allowMultiple` 用于正常加密签名；新的 `add_ltv` 嵌入 /DSS\（B-LT；`mode: 'online'` 通过操作者提供方，或 `mode: 'offline'` 使用调用方提供的 DER 材料）；新的 `timestamp_pdf` 追加 /DocTimeStamp\（B-LTA）。`verify_pdf` 的 `ltv: true` 会报告 profile、timestamp、吊销状态以及 `ltvLevel`。另见 `docs/guides/LTV.md`。

• 🌐 网络规约 — 默认无出站请求。服务器可能发起的唯一出站流量只会前往操作者配置的 RFC 3161 / OCSP / CRL 端点（`PDFNATIVE_MCP_TSA_URL`、`PDFNATIVE_MCP_REVOCATION`、`PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS`），且在 SSRF 防护之后；工具参数永远不能提供 URL。

• 🖨️ 印刷生产 — 每个文档工具都接受 `print`（TrimBox / BleedBox / ArtBox / CropBox，或 `bleed` 简写；裁剪和套准 `marks`；/UserUnit）、`metadata`（`/Author`、`/Subject`、`/Keywords`、`/Trapped`）和 `outputIntent`（用于 PDF/A 的嵌入式 RGB ICC）；`viewerPreferences` 新增 `duplex`、`pickTrayByPDFSize`、`printPageRange`、`numCopies`。`inspect_pdf` 的 `pages: true` 会报告这些 box；merge / split / extract 会保留它们。见 `docs/guides/PRINT.md`。

• ✍️ `update_metadata` — 以增量更新的方式重写现有 PDF 的 /Info\ 和 XMP；之前的修订和签名会原样保留。

• 📊 图表 v2 — `stackedBar` / `stackedBarH` / `area` / `scatter`，辅助右侧轴（`axis2`）、`axis.scale: 'log'`、`xAxis.type: 'linear' | 'time'`、`dataLabels`、`labelStride` / `labelRotation`；重叠的分类标签会偏移自动稀疏。

• 📜 诚实的 PDF/A — `embedFonts: true` 会嵌入 Noto Sans Latin（base-14 Helvetica 不嵌入，因此对纯文本 Latin 文本做 PDF/A 声明会被 veraPDF 拒绝）；`strict: true` 选择失败而不是产生不合规文件；`includeDiagnostics: true` 会回传引擎诊断信息。本地运行 veraPDF 验证脚本（`npm run validate:pdfa`）测试 26 个文件的语料库（其中 24 个通过验证，3 个为负面 canaries，跳过 2 个 pages-tree 输出），并支持 fail-closed 的 `VERAPDF_REQUIRED=1` 模式；CI work 使用 SHA-256 固定安装包，且在 1.6.0 中保持非 blocking 状态。已知引擎缺口：`add_form` 即使启用 `embedFonts`，其输出仍不通过 PDF/A-2b（存在未嵌入的 /DR /Helv）；`prepare_signature_placeholder` 的输出只有在签名后才合规。

• 🧰 `inspect_pdf` — `signatures: true` 时可枚举签名；`dss` / `docTimeStampCount` / `trapped`（存在性 gating）新增了 `check` 值 `dss`、`docTimeS`、`trapped`；`checks` 只列出你指定的键，且 `signed` 是结构性的（只要存在签名字段字段，有效与否交由 `verify_pdf` 负责）。

• 🔁 可复现输出 — 所有九个文档工具都可以选设 `creationDate` 固定 /CreationDate\、XMP 日期和 trailer /ID\；`signingTime`（`prepare_signature_placeholder` 和 `sign_pdf` 现在传递给时区偏移）可固定 /Sig /M\。在同一台主机的同主机时区下，字节完全相同。由 `reproducible_output` 提示词提供支持。

• ͡️ 加固边界 — 严格的输入 schema（未知或拼错的键 → VALIDATION_EXPLOR\ 而不是静默覆盖）；容忍 `data:…;base64,` 前缀，但拒绝 PEM 默认置于 DER、双倍编码的载荷，并附上解决建议；在页面树工具中错误页索引触发 VALIDATION_ERROR 且附带 0-based 提示；未知工具名是 JSON-RPC 协议级错误（`-32602`，[UNKNOWN_TOOL]`）。

• HTTP Bearer token — 通过选用 `PDFNATIVE_MCP_HTTP_TOKEN` 保护 Streamable HTTP 端点（否则返回 401\ 和 WWW-Authenticate\）。若不设置，loopback 端点没有任何验证文件——参见 `SECURITY.md`。

• \ 目录 — `tools/list` 约 245 kB（1.4.0 约 108 kB），因为现在每个块 kind、layout option 和 `encrypt` fragment 都会内联声明——按策略不使用 `$ref` / `$defs`，因此将 inputSchema\ 转发给 function-calling API 的 host 永远不会遇到引用问题；服务器说明约 6.7 kB（从 12.9 kB 降）。这种结构由 `scripts/tool-shape.mjs` + `tests/catalog-parity.test.ts` 守护，而 `tests/catalogue-superset.test.ts` 证明在线目录是已发布 1.5.0 目录的 superset；每个工具最多只带两个可执行 _meta.examples\，其余例子放到 ``examples/` 下面。新增四个 recipe 提示词：` pades_ladder`、`print_ready`、`reproducible_output`、`pdfa_valid`。

• 🐛 修复 — 在 pdfnative < 1.7 中，签名者 /SignerName / reason / location / contactInfo 未写入 /Sig 字典；现在会在此方体过程在占位阶段提前嵌入。`verify_pdf` 不再对 B-LTA 文档报告 `allValid: false`（此前一个 `/DocTimeStamp 被误当作 CMS 签名）。

• 🔌 MCP 2026-07-28 — 基于 MCP TypeScript SDK v2（`@modear）的 MCP 2026-07-28，自动回退到 2025 时代的 \initialize` 握手——现有主机无需改动即可继续使用。参见 [MCP 协议 compliance](#- m-wrapper).

• 引擎升级 — pdfnative v1.7.0 (LTV、print生产、charts v2、digest 声 4？——译：...).

v1.5.0 新功能：

• 📊 原生矢量图表 — `add_chart` 将条形 / 水平条形 / 线形 / 饼图 / 环形图渲染为纯 PDF 路径算子（不是栅格，PDF/A-safe，自动 alt 属性）。`generate_asic_pdf` 现在也接受 `pretty` block 与文字和表格一起布局。

• 📝 Fill & flatten 表单 — `read_form_fields` 列表现有 AcroForm 的字段；`fill_form` 以非破坏性、增量的更新进行填充和/或展平（与 `add_form` 对应）。

• 🔐 加密往返 — `encrypt_pdf` 重新保护 AES-128 / AES-256（绝不输出 RC4）；`decrypt_pdf` 恢复明文副本；`password` 输入打开加密的源文件；`merge_pdfs` / `split_pdf` / `extract_pages` 新增 `password` + `encrypt`。

• 🔤 文本提取真正的 — `extract_text` 现在能解析每个字体的 /ToUnicode CMap（不再输出字形索引），并可返回带位置的 `runs`。

• 🔗 原生 MCP 资源 — 沙箱中生成的 PDF 变成 pdfnative://output/… 资源（resources/list + resources/read），并在 file 模式结果中带有 resource_link，可在跨调用时重新引用。

• ** tool annotations** — 每个工具公布 readOnlyHint / destructiveHint / idempotentHint / openWorldHint。

• ⬆ 引擎升级 — pdfnative v1.6.0 (解密/加密、extractText、填表 / 展开、charts；color-emoji subsets 221 → 1167 glyph)。

v1.4.0 新功能：

• 🤝 AI 治理 + 人在环回 — draft_governance_issue 让代理在本地起草完全合规的 GitHub issue（草稿 .md + 机器可读的合规报告）。代理是起草者，绝不自主提交：人类是唯一门槛，服务器零 GitHub 写入（且自 v1.6.0 起，除操作者配置的 TSA / OCSP / CRL 端点外不发任何出站请求）。由governance_contract 与 draft_issue_workflow MCP prompts 支持。

• ✏️ 标注等 — annotate_pdf 增量式地在现有 PDF 上叠加高亮、便签、下文线、删除 & 上的强调、正方形、圆圈、直线和自由文本标注。它只是一个视觉审阅层，而非 redaction，原字节依然存在。

• 🔢 inspect_pdf 中的页标签 — 只读3 inspect_pdf now provides /PageLabels ranges（main / decimal / prefixed）。

• ∑ 数学 / 科学文本 — add_international_text 拥有 lang: 'math'（显式，像 emoji 一样）按需嵌入 Noto Sans Math。

• 🔌 MCP prompts — server now advertises prompts capability with governance_contract and draft_issue_workflow。

• ⬆ 引擎升级 — pdfnative v1.5.0。

v1.3.0 新功能：

• ** 三个页面树工具** — merge_pdfs、split_pdf、extract_pages（基于 pdfnative v1.4.0 的页面树 API 构建；加密的源文件在 v1.5.0 添加 password 之前会被拒绝）。

• 🔖 书签、页面标签和嵌套列表 — generate_basic_pdf 新增 outline（'auto' 或显式树）、pageLabels、多级 list 项和 viewerPreferences。

• ${cell border... Here we must not translate code names. Let's translate carefully. We'll present after.

Let's craft final full text.* 三个页面树工具** — merge_pdfs、split_pdf、extract_pages（基于 pdfnative v1.4.0 构建；加密源文件在 v1.5.0 加入 password 之前会被拒绝）。

• 🔖 书签、标签与嵌套列表 — generate_basic_pdf 新增 outline（'auto' 或显式树）、pageLabels、多层 list 项和 viewerPreferences。

• 📐 表格单元格边框与对齐 — add_table 新增 cellBorders、cellVAlign 和 viewerrences；add_international_text 新增 viewerPreferences。

• 🔐 Constant-time signing — sign_pdf 签名 RSA 和 EC-DER 密钥，通过 node:crypto 提供者，并支持透明纯 JS 回退（原始 P-256 标量保持纯 JS，签名验证也纯 JS）；签名保持互操作。

• 引擎升级 — pdfnative v1.5.0。

• 新增工具 extract_attachments — 从 PDF 中读回嵌入文件（完成 Factur-X / ZUGFeR 的往返），支持逐字节的载荷、filename 过滤，以及 includeData: false 的仅元数据探测。

• 💧 水印 — generate_basic_pdf 和 add_table 可接受可选的 watermark（文本、不透明度、角度、颜色、位置；自 v1.6.0 起支持 image）并在每页上渲染。

• 🌐 Unicode normalize 规范化 — generate_basic_pdf 和 add_international_text 可选启用 NFC/NFD/NFKC/NFKD。

• 节省 token 的读取 — 只读工具（inspect_pdf、verify_pdf、validate_pdf、extract_text、extract_attachments；自 v1.5.0 起 read_form_fields）可接受可选的 verbosity: 'summary' 和 fields: [...] 参数，从而使大型结果集响应体积约减少 90%，同时不丢智能体所依赖的字段。默认设置不变。

• no base64 duplication — 生成的 PDF（base64 模式）只返回一次作为嵌入的 resource 内容块，而不再同时复制到 structuredContent。

• 🔧 MCP registry publish fix — mcpName 现在使用规范的 GitHub 登录名大小写形式（io.github.Nizoka/pdfnative-mcp），以使注册表的区分大小写校验接受该 npm 包。

• 依赖 — 升级到 zod 4。

v1.1.0 中的新增功能：

• 工具 validate_pdf — 只读的 PDF/U (ISO 14289-P) 结构正确性检查。

• 六种新文字 — 泰卢固、僧伽罗、藏文、高棉文、阿姆哈拉、吉巽亚文（共 24 个 scripts）。

• COLRv1 彩色 emoji — 原生彩色 emoji，并支持无彩色回退。

• 工具 newline sanitizer — ... 中的 \ input with paragraph 内嵌 \n 自动拆分为独立段落（PDF/A 安全）。

• Automatic NFC normalize 为 add_international_text。

• 引擎升级 — pdfnative v1.4.0 : 欧元符号 / CP-125符号现在可以正确提取，表单元格换行时获得唯一的逐-ine MCIDs（符合 PDF/A 规范）。

v1.0.0 中的新增功能：

• 三个新工具：verify_pdf、add_attachment（Factur-X / ZUGFeR）、extract_text。

• 智能表格字段：wrap、repeatHeader、zebra、caption、minRowHeight、cellPadding。

• inspect_pdf 现在报告 hasSignaturePlaceholder 以及 per-astachment summary；新的 check 值有 'placeholder' 和 'attachments'。

• 签名体验改进：sign_pdf 接受 ECDSA SEC1 / PKBS#8 DER 密钥，并在缺少时自动注入 /Sig 占位（一键签署任意 PPDF）。

• 可选缓存（PDFINATIVE_MCP_CACHE_DIR）：以 SHA-256 为键，过期时间 1小时，LRU 256 MiB。

• _meta.apiVersion 和每个工具 _meta.examples 用于 AI 代理发现 — 见 docs/API_STABILITY.md。

• AI 代理指南：docs/AI_GUIDE.md — 决策树及常见错误。另见根目录 AGENTS.md 操作手册。

• PDF/A 编写指南永久：docs/guides/PDFA.md。

• 环境变量重新名称：PDFNATIVE_MCP_UTPUT_DIR（先前为 PDFNATIVE_MPC_OUTUT_DIR；旧名称仍可用，只显示一次弃用警告）。

• ✅ 当前： merge_pdfs, split_pdf, extract_pages（v1.4.0 工具）、annotate_pdf（v1.4.0 工具），以及 v1.5.0 工具（sign_pdf 等）。** 为您提供。

All tools support two output modes:

• base64 (默认) — 生成的 PDF 一次返回为嵌入的 resource 内容（以 data:application/pdf;base64,… 形式）；structuredContent 仅包含 { mode, sizeBytes }（如果 includeDiagnostics: true 还包括 diagnostics[]，以及 add_ltv 的 summary）。

• file — PDF 写到由 PDFNATIVE_MCP_OUT_DIR 配置的沙箱目录。除非设置该变量，否则禁用；拒绝绝对路径、路径传递、非 .pdftail 且不接受 NUL 字节。

从 v1.1.0 升级：唯一的行为变更是不再将 base64 字节输出到 structuredContent.base64。请从嵌入式 content 块读取：

- const base64 = response.structuredContent.base64;   // v1.1.0
+ const block = response.content.find((c) => c.type === 'resource');
+ const base64 = block.resource.blob;                  // v1.2.0

Token 节省读取（v1.0）——七个只读工具（inspect_pdf, verify_pdf, validate_pdf, extract_text, extract_attachments, read_pdf_fields, inspect_layout) 支持两个可选输入：

• verbosity: 'summary' — 返回精简标量结只（由您调用），例如 verify_pdf → { signatureCount, allValid, invalid, summary }（如 ltv: true 则还包含 ltvLevel）； inspect_pdf 保留存在的 hasDocumentTimestamp, trapped, checksPassed。

• fields: ['a', 'b.c'] — 投影到以点分隔的字段；后于 verbosity 应用。未匹配字段省略并记录在 _meta.unmatchedFields 中（附带 _meta.availableFields)。

最小 “pdf 已签名且有效” 探测：{ "pdfBase64": "…", "verbosity": "summary", "fields": ["allValid"] } 。

为什么选择 pdfnative？

pdfnative-mcp 继承底层引擎的全部保证：

• 引擎零运行时依赖 — 纯 JavaScript，不过程绑定（本服务器只增加 MCP SDK 和 zod：共三个运行时依赖）。

• 输出符合 ISO 32000-1（PDF 1.7）。

• 支持 PDF/A-1b/2b/3b/2u/3b、AI-128/256 加密、AcroForm、数字签名。

• 支持 24 种文字（25 个 lang 代码，含 emoji 和 math），具备 BiDi 重排、阿拉伯语定位文本、泰语/天城文/孟加拉/泰米尔语 OpenType 特性。

• 可安全树structure ESM。

Related MCP server: rendoc

Installation

# Run directly with npx (recommended for MCP clients)
npx -y pdfnative-mcp

# Or install globally
npm install -g pdfnative-mcp
pdfnative-mcp

条件：Node >= 22。

Configuration

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs"
      }
    }
  }
}

Cursor / Continue / Zed / Windsurf / Cline / Red Code

任何以 stdio 方式运行的 MCP 兼容客户端均可使用。使用同样的 command + args + env 三点。以 Curser（~/.curser/mcp.json）为例：

{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": { "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs" }
    }
  }
}

• • 本级开发环境兼容性：见上方 # 节。

🌐 支持的 AI 生态环境与客户端

pdfnative-mcp 面向 MCP 原生环境设计，兼容以 stdio/HTTP 的 MCP 客户端。社区确认的兼容联系人包括：。

• Ontheia — 一个自托管、开源安全优先的 AI 代理平台。已在 issue #41 中记录。

MCP 协议 external 11: 支持

自 v1.6.0 起，服务器基于 MCP TS-SDK v2（@modelscontext），并实现 MCP 2026-2026：

• 无状态服务 — server/discover 取代 initialize；所有响应包含 resultType 及 _meta.serverInfo。

• 缓存提示 — tools/list, prompts/list 标注为 public 并设 ttlMs 24 h； server/discover 为 public； resources/list 列为 private, ttlMs: 0。

• 资源错误 — 未知 URI 返回 JSON-RP -32602。

• ** legacy fallback** — initialize 请求来自 2025-11-25 等旧客户端时，则通过 SDK 的兼容路径继续服务。

• 协议错误 — tools/call 未知工具名返回 -32602；不返回 isError。

• 输出模式 — structuredContent 接受 option schema（2025-06-18 规定），且不设置 $schema。

MCP protocol behavior after app reads as follows.

Server配置

环境变量包含：PDFNATIVE_MCP_CACHE_DIR, PDFNATIVE_MCP_OUTPUT_DIR, PDFNATIVE_MCP_HTTP_TOKEN。

工具参考

[generate_basic_pdf

{
  "title": "Q1 2026 Report",
  "blocks": [
    { "type": "heading", "text": "Executive summary", "level": 1 },
    { "type": "paragraph", "text": "Revenue grew 24% year over year." },
    { "type": "list", "style": "bullet", "items": ["Strong APAC", "Stable EU", "Soft NA"] },
    { "type": "pageBreak" },
    { "type": "heading", "text": "Details", "level": 2 }
  ],
  "footerText": "Confidential — Internal use only",
  "outputMode": "base64"
}

13 种 block 种类：headin、paragraph、list、table、image、ling、toc、barcode、svg、formField、chart、pageBreak、spacer。一份复合报告：

{
  "title": "Quarterly report",
  "blocks": [
    { "type": "toc" },
    { "type": "heading", "text": "Sales", "level": 1 },
    { "type": "table", "headers": ["Region", "Revenue"], "rows": [["EMEA", "1.2 M"], ["APAC", "0.9 M"]], "zebra": true },
    { "type": "image", "imageBase64": "<base64 JPEG>", "mimeType": "image/jpeg", "width": 300, "alt": "Revenue chart" },
    { "type": "svg", "data": "M10 10 H 90 V 90 H 10 Z", "viewBox": [0, 0, 100, 100], "fill": "#0a7e8c" },
    { "type": "barcode", "format": "qr", "data": "https://example.com/q1", "align": "center" },
    { "type": "link", "text": "Full dataset", "url": "https://example.com/data" },
    { "type": "formField", "fieldType": "text", "name": "reviewer", "label": "Reviewed by" }
  ],
  "outline": "auto",
  "pageSize": "Letter",
  "headerTemplate": { "right": "{title} — page {page}/{pages}" },
  "embedFonts": true
}

块规则：table、barcode、formField 和 chart 与 add_table /add_barcode / add_form / add_chart 采用相同的正文；link URL 必须是 http:、https: 或 mailto:；image 块每块上限 12M base64 字符、每块解码后 24 MiB（PNG：8bit 灰度/RGB、非交错、无 alpha 通道、无调色板 — 否则返回 VALIDATION_ERROR 并附带可修复方案）；svg 支持 <path>、<rect>、<circle>、<ellipse>、<line>、<plyline>、<plygon>、<text>/<tspan>，并静默忽略 transform、<g>、<use>、<image>、渐变、不透明度与 CSS（不获取任何外部引用）；toc 由 heading 块构建，并与 outline: 'auto' 搭配；在 pdfA 下 formField 会报告 PDFA_UNEMBEDDED_FORM_FONT（strict: true 时失败）；barcode 不提供 alt。在渲染前可用相同输入先调用 inspect_layout 预览分页结果。

add_barcode

{
  "format": "qr",
  "data": "https://pdfnative.dev",
  "caption": "Scan to learn more",
  "ecLevel": "H",
  "outputMode": "file",
  "outputPath": "tickets/event-42.pdf"
}

支持的格式： qic、jasafe, code128, ean13, datamatrix, pdf417。

add_interrnational_text

{
  "title": "مرحبا بالعالم",
  "lang": "ar",
  "paragraphs": [
    "هذا اختبار للنص العربي مع تشكيل OpenType ومحارف ثنائية الاتجاه.",
    "Mixed content: العربية + English ✓"
  ]
}

支持的 lang 代码（25 个）：ar, he, th, ja, zh, ko, el, hi, bn, ta, ru, ka, hy, tr, pl, vi, latin, te, si, bo, km, my, am, emojii, math。字体始终嵌入（没有 embedFonts 这个输入）；想获得逐字节相同的输出请固定 creationDate。

多脚本文档 — 传入一个数组或逗号分隔列表：

{
  "title": "Mixed Script",
  "lang": ["ar", "emoji"],
  "paragraphs": ["العربية مع رموز 🎉🚀"],
  "pdfA": "pdfa2u"
}

sign_pdf

自 v1.0.0 起，sign_pdf 会缺失时自动注入 /Sig 占位符 — 一次调用即可签署任意 PDF：

{
  "pdfBase64": "<any base64 PDF>",
  "algorithm": "rsa-sha256",
  "certDerBase64": "<base64 X.509 cert in DER>",
  "rsaKeyPkcs1DerBase64": "<base64 PKCS#1 RSAPrivateKey DER>",
  "signerName": "Alice",
  "reason": "Approval",
  "location": "Paris, FR",
  "signingTime": "2026-01-15T10:30:00Z"
}

ECDSA P‑256：使用 algorithm: "ecdsa-sha256"，并配合 ecPrivateKeyDerBase64（SEC1 或 PKS#8 DER）或 ecPrivateScalarHex（64 个十六进制字符）。

PEM → DER 转换：

openssl x509 -in cert.pem -outform DER | base64 -w0                 # cert
openssl rsa  -in key.pem  -outform DER -traditional | base64 -w0    # RSA PKCS#1
openssl pkey -in key.pem  -outform DER | base64 -w0                 # ECDSA

只有当需要自定义占位符时才使用 prepare_placeholder的占位符（例如：大于 4096 位的 RSA 密钥传更大的placeholderBytes、subFilter: 'ETSI.CAdES.detached、reserveTimestamp: true）。否则直接调用 sign_pdf` 即可。

PAdES 阶梯（v1.6.0）。sign_pdf 以 profile: "pades" 得到 B-B 签名；加上 timestamp: true 得到 B-T（需 PDFNATIVE_MCP_TSA_URL），再加 add_ltv（B‑LT）与 timestamp_pdf（B‑LTA）：

// 1. sign_pdf  { ..., "profile": "pades", "timestamp": true, "certChainDerBase64": ["<intermediate DER>"] }
// 2. add_ltv   { "pdfBase64": "<signed>", "mode": "online" }            // or "offline" + certificatesDerBase64 / ocspResponsesDerBase64 / crlsDerBase64
// 3. timestamp_pdf { "pdfBase64": "<ltv>" }                              // re-run before the TSA certificate expires
// 4. verify_pdf { "pdfBase64": "<final>", "ltv": true }                  // -> ltvLevel: "B-LTA"

签署者元数据（signerName、reason、location、contactInfo）会烘入占位符；fieldName 选择多枚未签名占位符之一（否则 PLACEHOLDER_AMBIG_UOUS），而 allowMultiple: true 会添加更多签名。见 docs/guides/LTV.md。

add_table

{
  "title": "Monthly Sales",
  "headers": ["Region", "Units", "Revenue"],
  "rows": [
    ["APAC", "1200", "$240,000"],
    ["EMEA", "800", "$160,000"]
  ],
  "infoItems": [{ "label": "Period", "value": "January 2025" }],
  "footerText": "Internal use only",
  "outputMode": "base64"
}

add_form

{
  "title": "Employee Onboarding",
  "fields": [
    { "fieldType": "text", "name": "fullName", "label": "Full Name", "required": true },
    { "fieldType": "dropdown", "name": "dept", "label": "Department", "options": ["Engineering", "Sales", "HR"] },
    { "fieldType": "checkbox", "name": "agree", "label": "I agree to the terms", "checked": false },
    { "fieldType": "listbox", "name": "skills", "label": "Skills", "options": ["TypeScript", "PDF", "MCP"] },
    { "fieldType": "textarea", "name": "notes", "label": "Notes", "placeholder": "Anything we should know?" }
  ],
  "outputMode": "base64"
}

Field 类型：text、textarea（多行，/FFf 4096）、checkbox、radio、dropdown、listbox；placeholder 表示在字段空时显示提示文本。添加 encrypt 可生成仍保留其 AcroForm 的密码保护表单。在 PDF/A 声明下，控件外观字体不会被嵌入（PDFA_UNEMBEDDED_FORM_FONT）。

embed_image

{
  "title": "Product Photo",
  "imageBase64": "<base64-encoded JPEG bytes>",
  "mimeType": "image/jpeg",
  "caption": "Front view of Model X",
  "width": 400,
  "align": "center",
  "alt": "Front view of the Model X chassis",
  "outputMode": "base64"
}

注意： 引擎的 PNG 解码器只接受 8 位、非交错的灰度/RGB 图像。Alpha 通道（色彩类型 4/6）、调色板（类型3）、16 位与交错 PNG 会在边界被拒绝，返回 VALIDATION_ERROR 并以可按提示修复（压平或重新导出）— 对 image 块与图像水印也适用同样规则。embed_image.imageBase64 保持其在 1.5.0 的约定，不设长度上限；12 M 字符上限只适用于内联 image 块和水印图图像的 water。

prepare_signature_placeholder

{
  "title": "Service Agreement",
  "signerName": "Alice Dupont",
  "reason": "Approved",
  "location": "Paris, FR",
  "blocks": [
    { "type": "paragraph", "text": "By signing below, I accept the terms and conditions." }
  ],
  "outputMode": "base64"
}

将返回的 PDF 字节交给 sign_pdf 即可完成签署工作流。

inspect_pdf

只读的结构与安全检测 — 适合下游验证、CI 断言以及那些需要对 PDF 探究清楚后再行动的 AI 代理。

{
  "pdfBase64": "<base64 PDF>",
  "pages": true,
  "check": ["pdfa", "signed", "attachments"]
}

返回内容：

{
  "version": "1.7",
  "pageCount": 3,
  "encryption": "none",          // 'none' | 'aes-128' | 'aes-256' | 'rc4' | 'unknown'
  "pdfA": "3B",                  // null when no PDF/A claim is present
  "signatureCount": 1,
  "hasSignaturePlaceholder": false,
  "attachments": [{ "filename": "factur-x.xml", "mimeType": "application/xml", "sizeBytes": 1234, "relationship": "Source" }],
  "info": { "Producer": "pdfnative", "Title": "Invoice INV-2025-001" },
  "perPage": [{ "index": 0, "width": 595, "height": 842 }],
  "checks": { "pdfa": true, "signed": true, "attachments": true },
  "checksPassed": true
}

check[] 可接受任何 'pdfa'、'ndsign'、'encrypted'、'placeholder'、'parent'、placeholder'、'streams'、signature （括号内的为 v1.6.0 起的 doTimetamp、trapped、annotation）。checksPassed 是所有请求检的全部为真时的逻辑与。signatures: true 会增加每字段清单（subFilter、isDocTimetamp、isPlaceholder、byteRange、vriKey）；annotation: true 会增加 annotations[]（每个 /Annots 条目：0 起 page、subtype、rect，以及存在时 专人… contents（超过 200 字符会截断）、title、color、quadPoints、链接 url）和 annotationCount；dss、docTimetampCount和trapped仅在存在时出现；在pages: true时每个perPage项还有trimBox/bleedBox/artBox/cropBox/userUnit`（如已经设置）。

inspect_layout

只读型的翻页 pre-非 — blocks 与 generate_basic_pdf 相同，再加上所有会移动块位置的输入（title、footerText、pdfA、normalize、embedFonts、pageSize、margins、headerTemplate、footerTemplate）。不产出任何 PDF；只要给入与将输出 generate_basic_pdf 完全相同的输入值，totalPages 就会相同。

{ "title": "Memo", "blocks": [{ "type": "paragraph", "text": "Short note." }], "pageSize": "Letter", "verbosity": "summary", "fields": ["totalPages"] }

完整结果包含 pageW{idth、pageHeight、margins、totalPages 与 页面的 pages[].blocks[] （type、page、x、top节，width、height，单位 pt，保留两位小数）。已知引擎缺口：toc` 块在这里会被量化为 0 pt，所以含本期目录打印的文档实际可能比预览多一页。

validate_pdf

只读的 PDF/UA（ISO 14289‑1） 结构符合性检查，用于 Tagged PDF。用任意工具在 pdfA 与 pdfA: 'pdfa2u' 下生成无障碍文档，再做校验。

{ "pdfBase64": "<tagged-pdf-base64>" }

返回内容：

{
  "standard": "pdf-ua-1",
  "valid": true,
  "errors": [],          // blocking structural violations (empty when valid)
  "warnings": [],        // non-blocking best-practice recommendations
  "summary": "PDF/UA structural prerequisites hold."
}

它检查 PDF 中的 /MarkInfo /Marked true、/StructTreeRoot（+ /ParentTree）、/Media（XMP）、/Size，以及每页 MCID 的唯一性。这是一个快速开发阶段的门禁——并非用于替代完整的参考验证器（veraPDF），后者还会额外检查字体、颜色和渲染。

annotate_pdf

通过增量更新在现有 PDF 上叠加标记批注。这是一个视觉审阅层，不是 redaction（涂黑/删除）——底层内容不会被改动。

{
  "pdfBase64": "<base64 PDF>",
  "annotations": [
    { "type": "highlight", "page": 0, "rect": [72, 700, 520, 715], "color": [1, 1, 0], "contents": "Check this figure" },
    { "type": "text", "page": 0, "rect": [540, 700, 560, 720], "contents": "Reviewer note" }
  ]
}

类型包括：text、highlight、underline、strikeout、squiggly、square、circle、line、freetext。页面索引从 0 开始。加密的源文件会被拒绝（ENCRYPTED_SOURCE）——请先运行 decrypt_pdf（该操作会移除签名和 AcroForm），再标注，之后重新运行 en crypt_pdf 即可。

draft_governance_issue

在本地生成符合治理规范的 GitHub issue，供人工审查后提交。服务器绝不会联 GitHub（它唯一可能的网络出口，就是运维人员配置的 TSA / OCSP / CRL 端点——见网络与出口）；它返回的是草稿 Markdown 加一份机器可读的合规报告。

{
  "title": "add_table drops the caption on the second page",
  "issueType": "bug",
  "summary": "The table caption is only rendered on page 1 when repeatHeader is true.",
  "reproduction": { "command": "add_table with caption + repeatHeader over 2 pages (examples/bordered-table.json, then inspect_pdf)", "result": "Page 2 has no caption row." },
  "expectedBehavior": "The caption repeats with the header on every page.",
  "duplicateSearchPerformed": true
}

如果草稿建议了一个运行时依赖、缺少复步，或将 duplicateSearchPerformed 设为 false，就会被拒并返回 GOVERNANCE_VIOLATION。完整的人机协同（human-in-the-loop）契约见 docs/guides/AI_GOVERNANCE.md。

verify_pdf、add_attachment、extract_text

各工具的专门章节请参见 docs/AI_GUIDE.md，参考见 docs/KNOWLEDGE_BASE.md。可以直接运行的示例位于 examples/ 中。

🔐 安全模型

pdfnative-mcp 运行宿主进程内，并暴露 stdio MCP 服务器（或仅本机回环的 HTTP 端点）。它不会在配置的沙盒之外执行任何 I/O。

• 文件写入由 PDFNATIVE_MCP_OUTPUT_DIR 控制。若该变量未设置，file 输出模式会被拒绝并抛出 SecurityError。

• 路径解析：拒绝绝对路径、穿越路径序列（..）、NUL 字节，以及除 .pdf 之外的任何扩展名。

• 输出大小：每次调用被限制在 50 MB 以内。

• 输入：每个工具入参都在边界处通过严格的 JSON Schema + Zod 运行时检查做校验；未知或拼写错误的键（无论顶层还是嵌套）都会得到 VALIDATION_ERROR；并且任何解析执行之前，base64 / DER 载荷都会被做合理性检查（允许 data: 前缀；PEM 或双重编码的输入会被拒绝，并给出对应的整改提示）。

• HTTP 传输（PDFNATIVE_MCP_PORT）：仅绑定回环地址；除非设置 PDFNATIVE_MCP_HTTP_TOKEN，否则没有身份验证（若缺少该 token，则拒绝 401）。

网络与出站

服务器默认不做任何出站网络请求。它可能产生的唯一出站流量，只会前往运维人员在环境中为 PAdES 长期验证而配置的 RFC 3161 / OCSP / CRL 端点（即 PDFNATIVE_MCP_TSA_URL、PDFNATIVE_MCP_REVOCATION、PDFNATIVE_MCP_NETWORK_ALLOWED_HEEDS）——绝不会去访问任何由工具参数提供的 URL，绝不去 GitHub，绝不用于另一类遥测。当这些配置不存在时，sign_pdf timestamp: true、timestamp_pdf 和 add_ltv mode: 'onLine' 都会在触到文档之前快速失败，返回 TSA_NOT_CONFIGURED / REVOCATION_NOT_CONFIGURED；而 add_ltv mode: 'offline' 会把调用者提供的材料 embedding 进文档，且完全不使用网络。

OCSP / CRL 的 URL 来自 PDF 内不可信证书的 ALA / CRL 分发点扩展，因此每次拉取都会经过一个 SSRF 防护：

• 目标主机必须匹配运维允许列表（host、host:port 或 *.suffix；裸通配符会被拒绝）。列表中的条目是主机名，而不是 URL：host:port 条目只匹配 URL 中带显式端口的请求（URL 解析器会省略默认的 :80 / :443——请为这些请求列出裸主机名）；通配符条目不能带端口；IDN 主机名必须采用 punycode 形式（xn--…）；IPv6 字面量需要带方括号（[2001:db8::1]）；

• 只支持 http: 和 https:，不允许内嵌认证信息，重定向请求不跟随；

• 回环、link-local、私有、unique-local、CGNAT、未指定以及组播地址的字面量（包括十进制/八进制/十六进制写法，以及 IPv4 映射的 IPv6）都会被拒绝，除非该字面量已被明确加入白。该防护只检查字面量——因此，已允许的主机名若解析成内网地址（DNS rebinding 攻击）就无法被检测到，因为不增加解析依赖就不会有 resolver；请只允许名单中那台主机确实在你自己的控制下；

• 每次请求的超时（PDFNATIVE_MCP_NETWORK_TIMEOUT_MS）和响应大小值（Tsa 为 256 KiB、OCSP 1 MiB、CRL 16 MiB）在流式读取期间都强制执行，因此在响应主体还没有完全取得之前就会将其切断，而不是整个缓冲区读取；

• OCSP 响应及 CRL 在嵌入 add_ltv 之前，会先对响应方返回的内容做解析校验；

• TSA 的 URL 是运维信任的（仅检查 scheme 与凭据）；PDFNATIVE_MCP_TSA_AUTH 的 secret 永远不会出现在日志或错误信息中。

• 提供方（provider）按每次调用构建，并通过 pdfnative 的 per-call 选项传入——进程范围内通用的 PROVIDER 设置器永远不会被使用，因此并发请求之间不共享任何状态。server/discover 指令会输出当前的出口策略（只包含端点类型，从不输出机密信息）。

查看SECURITY.md 以了解负责制史的披露流程，docs/guides/LTV.md 则介绍了运维配置。

🔪 本地开发

git clone https://github.com/Nizoka/pdfnative-mcp.git
cd pdfnative-mcp
npm install
npm run typecheck
npm run lint
npm test
npm run build
npm run validate:pdfa     # advisory: veraPDF over the 26-file PDF/A corpus (24 validated; skips when veraPDF is absent; VERAPDF_REQUIRED=1 fails closed)
node scripts/tool-shape.mjs --write   # only after a deliberate tools/list schema change (catalogue parity fixture)

基于 stdio 对服务器进行冒烟测试：

node dist/cli.js
# In another terminal, send a JSON-RPC initialize request via stdin (e.g. with mcp-inspector).

**Contributors：**完整、本地验证工作流请见[Dev，guides/LOCAL_TESTING.md — 包括质量门禁、以示例当测试、验证生成的 PDF 结构是否合法（assertValidPdf、inspect_pdf、validate_pdf、verify_pdf）、在查看器中打开输出、用 veraPDF 做外部 PDF/A 校验，以及使用 MCP Inspector。

📣 发布流程

pdfnative-mcp 与 pdfnative 遵循相同的发布方式：

• 在 Goss-notes/vX.Y.Z.md 每个 tag 对应一份发布说明；

• CHANGELOG.md 跟随镜像每个发布里设置；

• GitHub Release 的正文从 Goss-notes/vX.Y.Z.md 专辑复制；

• 在 GitHub Actions 的 Trusted Publishing（OID）+ OIDC 机制下完成 npm 发布，无需 NPM_TOKEN。

关于规范结构与发布清单，请见 release-notes/TEMPLATE.md。

灯***

📚 项目结构

src/
├── cli.ts                      # entrypoint: stdio (default) or Streamable HTTP (PDFNATIVE_MCP_PORT)
├── http.ts                     # Node http <-> Web Request/Response bridge + Host/Origin loopback guard
├── auth.ts                     # opt-in HTTP bearer token (PDFNATIVE_MCP_HTTP_TOKEN)
├── base64.ts                   # base64 / DER boundary decoding with agent-facing diagnostics
├── index.ts                    # public library exports
├── server.ts                   # Server factory, tool registry, cache hints, SERVER_INSTRUCTIONS
├── network.ts                  # operator-configured TSA / OCSP / CRL egress + SSRF guard
├── print.ts                    # print-production schema (boxes, bleed, marks, userUnit, outputIntent, metadata, creationDate)
├── diagnostics.ts              # PDF/A diagnostics sink, strict / includeDiagnostics / embedFonts
├── chart.ts                    # charts v2 schema + ChartBlock mapper
├── blocks.ts                   # the 7 extended document blocks (table, image, link, toc, barcode, svg, formField)
├── layout.ts                   # pageSize / margins / header & footer templates / compress / debug / encrypt (PdfLayoutOptions)
├── table.ts, barcode.ts, form.ts, image.ts   # bodies shared by a dedicated tool and its inline block
├── watermark.ts                # text and/or image watermark + position, PDF/A-1b transparency guard
├── encryption.ts               # password + encrypt schema (Standard Security Handler), decrypt error mapping
├── inflate-cap.ts              # PDFNATIVE_MCP_MAX_INFLATE_BYTES (engine decompression cap) + PDF_PARSE_FAILED mapping
├── output.ts                   # sandboxed file writer / base64 emitter (single + multi)
├── text.ts                     # newline sanitizer (Safe PDF/A)
├── doc-features.ts             # nested lists, outline, page labels, viewer prefs (+ print-dialog defaults)
├── pagetree.ts                 # page-tree error mapping (merge/split/extract)
├── crypto-provider.ts          # node:crypto signing provider for DER keys (SHA-256/384/512); verification stays pure JS
├── projection.ts               # verbosity / fields projection for the seven read tools
├── errors.ts                   # ToolError, SecurityError, GovernanceError
└── tools/
    ├── generate-basic-pdf.ts
    ├── inspect-layout.ts
    ├── add-barcode.ts
    ├── sign-pdf.ts
    ├── add-ltv.ts
    ├── timestamp-pdf.ts
    ├── update-metadata.ts
    ├── add-international-text.ts
    ├── add-table.ts
    ├── add-form.ts
    ├── read-form-fields.ts
    ├── fill-form.ts
    ├── add-chart.ts
    ├── embed-image.ts
    ├── inspect-pdf.ts
    ├── verify-pdf.ts
    ├── validate-pdf.ts
    ├── add-attachment.ts
    ├── extract-attachments.ts
    ├── extract-text.ts
    ├── merge-pdfs.ts
    ├── split-pdf.ts
    ├── extract-pages.ts
    ├── annotate-pdf.ts
    ├── encrypt-pdf.ts
    ├── decrypt-pdf.ts
    ├── draft-governance-issue.ts
    └── prepare-signature-placeholder.ts
scripts/
├── verify-issue.mjs            # governance draft checker (npm run verify:issue)
├── validate-pdfa.mjs           # veraPDF run (npm run validate:pdfa; PASS/FAIL/XFAIL/XPASS/INFRA/SKIP)
├── generate-pdfa-corpus.mjs    # builds the 26-file PDF/A corpus (24 validated incl. 3 negative canaries, 2 page-tree outputs)
└── tool-shape.mjs              # structural tools/list fingerprint (--write refreshes tests/_fixtures/tool-shape.json)
.github/workflows/ci.yml        # Linux (Node 22 / 24) + Windows quality gate
.github/workflows/verapdf.yml   # non-blocking veraPDF CI job (SHA-256-pinned installer, VERAPDF_REQUIRED=1)
tests/                          # vitest suites (one per tool / module; document-blocks, layout-options, inspect-layout,
                                #   watermark, inflate-cap, catalogue-parity + catalogue-superset vs the 1.5.0 fixture)

🗺 路线图

v1.6.0 已发布（完整引擎升级——支持 13 种班类型、布局选项、inspect_layout，并具备 PAdES 长期验证、打印生产、charts v2、update_metadata、MCP 2026-07-28）。完整计划等——已发布里程碑、进行中工作、未来方向——可在 ROUTE.md中查看。

暂缓事项：

• redact_pdf —— pdfnative 没有内容不可删除的 API；若仅做“覆盖式 redaction”，可能造成错误的安全体验。

• 原生 ECDSA验证 —— router 未提供导出 ecdsVerifyHash；所以 verify_pdf 对 P-256 保留它的纯 JS 路径。

• HTTP 页面流 —— MCP 2026-07-28 仍不支持部分 structuredContent，所以大结果只能一次性返回。

有功能建议吗？欢迎提交 issue 或 PR。

⭐ 给项目加个星星

如果 pdfnative-mcp 对你有用，也请把“start”这个仓库——也请顺手对最底层引擎 Nizoka/pdfnative 竖标 star。星标既帮助其他开发者发现您的项目、也激励我持续开发。

🤝 贡献

贡献非常欢迎。请先阅读 CONTRIBUTING.md，查阅本仓库的[open issues](https://github.com/Nizoka/pdfnative issues)，并遵守 行为准则。

📄 许可证

[MIT License] © 2026 Nizoka

pdfnative-mcp 是构建于 pdfnative 与 Model Context Protocol TypeScript SDK 之上。