Pdfnative

pdfnative-mcp

用于 PDF 生成、PDF/A 归档、PDF/X-4 印刷交换、精细排版、支持长期验证的 PAdES 签名、AcroForms、合并／拆分、加密和布局预览的 MCP 服务 —— 基于 pdfnative 引擎（零依赖，符合 ISO 32000-1），提供 28 个工具和 7 个提示词，可用于 Claude Desktop、Cursor、ChatGPT 及任何 Model Context Protocol 客户端。

---

✨ 功能

pdfnative-mcp 向任何 MCP 宿主提供 28 个可用于生产环境的工具：

工具	用途
generate_basic_pdf	使用 13 种块类型生成多页文档：heading、paragraph、list、table、image（JPEG/PNG）、link、toc（打印目录）、barcode、svg、formField、chart、pageBreak、spacer——涵盖引擎提供的所有 DocumentBlock。嵌入的换行符会自动拆分为多个段落。可选项包括 pdfA、pdfx（v1.7.0 新增）、print、metadata、embedFonts、watermark、outline、布局选项（pageSize、margins、headerTemplate / footerTemplate、compress、debug、encrypt）、typography（v1.7.0 新增）和 CMYK 颜色（v1.7.0 新增）。
inspect_layout (v1.6.0 新增)	对相同的 blocks（以及 title、footerText、pdfA、normalize、embedFonts、pageSize、margins、headerTemplate、footerTemplate、typography）进行只读的分页试运行：返回页数和每个块的所在位置，不生成 PDF。
add_barcode	QR Code、Code 128、EAN-13、Data Matrix、PDF417——嵌入单页 PDF。
add_international_text	支持 27 种 Unicode 文字系统——老挝文、Tai Tham、New Tai Lue、Tai Le 和 Cham（v1.7.0 新增）——以及拉丁文字、数学符号和 COLRv1 彩色表情符号（旗帜 / ZWJ 序列、肤色修饰符），支持 BiDi 和 OpenType 字形塑形；单个文档可使用多种语言。
add_table	用于表格报告的智能字段（换行、repeatHeader、zebra、caption、minRowHeight、cellPadding）。
add_form	创建包含文本字段、文本区域、复选框、单选按钮、下拉列表、列表框（以及 placeholder 提示文本）的新交互式 AcroForm PDF。
read_form_fields	只读枚举现有 AcroForm 的字段树（名称、类型、值、控件）。
fill_form	填写和/或扁平化现有 AcroForm（非破坏性增量更新）。
add_chart	原生矢量图表 v2——bar / barH / stackedBar / stackedBarH / line / area / scatter / pie / donut，支持次坐标轴、对数和时间刻度、数据标签（纯 PDF 路径运算符，符合 PDF/A）。
embed_image	将 JPEG 或 PNG 图像（base64）嵌入带标题的 PDF 文档（align、用于带标签输出的 alt 文本）。
prepare_signature_placeholder	签名工作流的可选第 1 步——创建含有 /Sig 占位符的 PDF（内置签署者元数据、subFilter、reserveTimestamp）。
sign_pdf	PAdES B-B / B-T CMS 签名（RSA-SHA256/384/512、ECDSA-SHA256 P-256；profile: 'pades'、timestamp、certChainDerBase64、多重签名、可固定的 signingTime）。需要时自动注入占位符。
add_ltv (v1.6.0 新增)	PAdES B-LT——嵌入包含证书和 OCSP/CRL 材料的 /DSS（由操作方配置的提供方，或调用方提供的离线材料）。
timestamp_pdf (v1.6.0 新增)	PAdES B-LTA——从操作方配置的 TSA 追加 RFC 3161 /DocTimeStamp；重新运行即可扩展归档链。
verify_pdf	验证每个 PAdES 签名和文档时间戳（完整性 + 签名值 + 可选的证书链信任；/DocTimeStamp 与任何签名一样计入 allValid）；ltv: true 会报告 B-B…B-LTA 级别。
validate_pdf	验证带标签的 PDF 是否符合 PDF/UA（ISO 14289-1）结构要求；或者使用 standard: 'pdf-x-4'（v1.7.0 新增）验证 PDF/X-4（ISO 15930-7）的结构性前提条件——只读，不是经过认证的预检。
add_attachment	生成包含嵌入文件的 PDF/A-3 文档（Factur-X / ZUGFeRD 发票）。
extract_attachments	只读提取嵌入文件（Factur-X / ZUGFeRD XML 往返），保留逐字节一致的有效载荷。
extract_text	提取 Unicode 文本（解析 /ToUnicode），可选返回带位置信息的文本段；通过 password 打开加密 PDF。
inspect_pdf	只读检查：PDF 版本、页数、加密状态（以及精确的 encryptionInfo）、PDF/A 声明、PDF/X 声明（pdfX，v1.7.0 新增）、签名（以及清单、/DSS、文档时间戳）、页面框、/Trapped、附件、占位符状态，以及通过 annotations: true 获取现有页面注释清单。
update_metadata (v1.6.0 新增)	将现有 PDF 的 /Info 标题 / 作者 / 主题 / 关键词（以及 XMP，包含日期）重写为增量更新；固定 modDate 以生成可复现的字节内容。
encrypt_pdf	使用 AES-128 / AES-256 重新保护 PDF（所有者/用户密码、权限、密码轮换）。
decrypt_pdf	输出 RC4 / AES-128 / AES-256 文档的未加密副本。
merge_pdfs	通过 pdfnative 的页面树 API 将 2–50 个 PDF 合并为一个（保留页面框）。
split_pdf	将一个 PDF 按页面范围拆分为多个文档（多输出）。
extract_pages	提取任意页面子集并生成单个 PDF。
annotate_pdf	添加标记注释（高亮、备注、正方形/圆形、直线、自由文本）作为视觉叠加层——不是涂黑。
draft_governance_issue	在本地起草符合治理要求的 GitHub issue，供人工审查；不会提交，也不会联网。
New in v1.7.0:

• 🔤 精细排版 — 九个文档工具和 inspect_layout 均新增可选的 typography 对象：splitParagraphs，含 orphans / widows；keepHeadingsWithNext；unitBinding；bindShortWords；punctuationSpacing（'fr'、'fr-CA' 或显式规则）；opticalMargins；metrics: 'exact'；fontFeatures（11 个 OpenType 标签）；kerning；hyphenationLanguage。段落块新增 align（left / right / center / justify）、keepWithNext 和 splittable。标题块新增 keepWithNext。如实说明限制：kerning、fontFeatures 和 'fr' 窄不换行空格需要 embedFonts: true（基础 14 字体 Helvetica 会将 'fr' 降级为 'fr-CA'）；捆绑的 Noto Sans 上，tnum / lnum 不会产生任何变化（诊断码 TYPOGRAPHY_FEATURE_INEFFECTIVE）；未安装连字词典，因此 hyphenationLanguage 在此处无效——软连字符（U+00AD）仍会生效。请参阅 docs/guides/TYPOGRAPHY.md。

• 🎨 所有接受颜色的地方均支持 CMYK — 除现有的十六进制 / RGB 格式外，还支持 'c m y k' 操作数字符串（0–1）和 [c, m, y, k] 百分比元组（0–100）：水印、页眉 / 页脚模板、表格单元格边框、大纲条目、图表、link 和 svg 块、annotate_pdf。所有 1.6.0 颜色格式仍会通过验证。

• 🖨️ PDF/X-4 — 六个生成工具（generate_basic_pdf、add_table、add_chart、add_barcode、embed_image、add_international_text）支持 pdfx: 'pdfx4'；除 RGB 外，还支持 CMYK 或 Gray outputIntent 配置文件；支持 print.marks.colourBars；可使用 validate_pdf { standard: 'pdf-x-4' } 检查结果；inspect_pdf 会报告该声明（pdfX，检查项 'pdfx'）。此功能需要打印机的 ICC 配置文件（设备类别 prtr——未捆绑任何配置文件）；要生成符合规范的文件，必须设置 embedFonts: true（否则会出现 PDFX_NO_FONT_ENTRIES；设置 strict: true 时则会拒绝）。它不能与 pdfA 和 encrypt 同时使用。此验证仅检查结构——并非经过认证的预检；结果会在自身的 caveats[] 中说明这一点。请参阅 docs/guides/PRINT.md。

• 🌏 27 种 Unicode 文字 — add_international_text 支持 lo（老挝文）、nod（兰纳文）、khb（新傣仂文）、tdd（傣仂文）和 cjm（占文）；ha、yo、ig、sw 是 latin 的别名（声调符号会附着）；支持渲染表情符号肤色修饰符。PDF/A 中的兰纳文必须使用 pdfa2b，而非 pdfa2u（上游有一个字形缺少 ToUnicode 条目）。

• 🔁 在任何主机上均可复现 — 所有日期均以 UTC 写入，页眉或页脚中的 {date} 会遵循固定的时间点，操作人员可通过 PDFNATIVE_MCP_CREATION_DATE 或 SOURCE_DATE_EPOCH 固定整个进程（请参阅环境变量）。按设计不在此范围内：signingTime、modDate、RFC 3161 令牌和吊销数据、加密、ECDSA 签名。请参阅 docs/guides/REPRODUCIBLE.md。

• 🚦 strict 按诊断码升级处理 — PDFA_* → PDF_A_COMPLIANCE_VIOLATION，PDFX_* → PDF_X_COMPLIANCE_VIOLATION（新增），其他所有情况 → DIAGNOSTIC_ESCALATED（新增）。这两个新增代码仅会由设置了 strict: true 的调用返回。

• 🧩 第七个 MCP 提示词 typography — 并重写 print_ready、reproducible_output、pdfa_valid，纳入 CMYK、PDF/X-4、色条以及 UTC / 操作人员固定时间点。

• 🐛 修复 — 0–1 RGB 三元组（watermark.color、annotate_pdf 的颜色）现在会渲染其指定的颜色（以前 [1, 0, 0] 会渲染成几乎全黑）；任何接受 PDF 输入的工具发生意外故障时，现在会归类为 PDF_PARSE_FAILED，而不再以无代码形式呈现。

• ✅ 上游问题已解决 — 使用 embedFonts: true 构建的 PDF/A 表单现在可通过 veraPDF 验证（AcroForm 字体已嵌入），且 inspect_layout 对 toc 块的测量结果与构建时的布局完全一致。

• 🧪 单一门禁、强化 CI、已验证文档 — npm run gate 是判定通过的唯一标准（通过 stdio 驱动构建后的服务，且 stdout 必须仅包含 JSON-RPC 帧）；veraPDF 会对 41 个文件的合规性语料执行阻断式检查；96 个样本的字节基线会检查输出；npm run verify:docs 会确保文档中引用的所有计数、版本、工具、错误代码和操作人员变量均与 docs/assets/ecosystem.json 及源代码树一致。

• 🧾 目录 — tools/list 增长至约 306 kB（排版片段和扩展后的颜色架构会内联到每个包含这些内容的工具中；npx tsx scripts/tool-shape.ts --check 会确保其小于 320 KiB，说明小于 8 KiB）；_meta.apiVersion 为 1.7.0。

• ⬆ 引擎升级 — pdfnative v1.8.0。工具 API 没有破坏性更改；发生变化的字节（嵌入的 TrueType 子集、print.marks、带有标记定位的成形文本、UTC 日期）已列于 release-notes/v1.7.0.md 的 升级 部分。 New in v1.6.0:

• 🧱 完整引擎覆盖——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）、headerTemplate / footerTemplate（支持 {page} {pages} {title} {date}；footerTemplate 会替换默认页脚，因此此时会忽略 footerText；1.6.0 中的 {date} 使用构建当天的挂钟时间——从 v1.7.0 起改为使用固定的时间点）、compress（FlateDecode 流——文件更小，但字节不同；PDF/A 下的 XMP 保持未压缩）和 debug（辅助矩形、未标记内容——不适用于 PDF/UA）。默认不启用，因此默认输出的字节保持不变。

• 🔐 构建时加密 — 七种文档工具支持 encrypt（generate_basic_pdf、add_table、add_form、add_international_text、embed_image、add_barcode、add_chart）：标准安全处理器，默认使用 AES-128，也支持 AES-256；保留 AcroForm（与会重建页面树的 encrypt_pdf 不同）。不能与 pdfA 同时使用（会返回 VALIDATION_ERROR），结果永不缓存；prepare_signature_placeholder 不提供此功能（必须保持可签名），add_attachment 也不提供（PDF/A-3）。

• 📏 inspect_layout — 第 28 种工具：只读的分页试运行，使用相同的 blocks 和布局输入，不渲染 PDF，并报告 totalPages 以及每个块所在的页面、x 坐标、顶部位置、宽度和高度。1.6.0 中已知的引擎缺陷（已在 v1.7.0 修复）：toc 块被测量为 0 pt，因此包含打印目录的文档实际分页可能比预览多一页。

• 🔎 inspect_pdf annotations: true — 列出每个页面注释（子类型、从 0 开始的页码、rect、最多截取 200 个字符的内容、标题、颜色、quadPoints、链接 URL），并提供 annotationCount；新增 check: 'annotations'。

• 🖼️ 图像水印 — generate_basic_pdf 和 add_table 支持 watermark.image（JPEG/PNG，默认不透明度为 0.10，单独限制为 8 MiB），可单独使用，也可与 text 组合（默认不透明度为 0.15）；两者均支持 position: 'background' | 'foreground'。在 pdfa1b 下，任一不透明度低于 1.0 都会被拒绝。

• 🧯 PDFNATIVE_MCP_MAX_INFLATE_BYTES — 可由运维人员覆盖引擎每个流 100 MiB 的解压缩上限（整数 ≥ 1024；无效值会导致启动被拒）。超出上限的附件流会使 extract_attachments includeData: true 返回 PDF_PARSE_FAILED；extract_text 则会退化为空页面文本（引擎会吞掉逐页解码失败）。

• 📝 表单 — add_form 和 formField 块新增 listbox 和 placeholder；fieldType: 'textarea' 现在会以 multilineText 传给引擎（此前未映射，直接传递后渲染为单行字段——此修复会改变该输入的字节）。embed_image 新增 align 和 alt。

• 🔏 PAdES 长期验证阶梯 — sign_pdf 新增 profile: 'pades'（ETSI EN 319 142-1 基线、ESS signing-certificate-v2、ETSI.CAdES.detached）、timestamp: true（B-T、RFC 3161）、RSA-SHA384/512、certChainDerBase64，以及用于多个签名的 fieldName / allowMultiple；新增 add_ltv，可嵌入 /DSS（B-LT，mode: 'online' 通过运维人员配置的提供方，或 mode: 'offline' 并由调用方提供 DER 材料）；新增 timestamp_pdf，可追加 /DocTimeStamp（B-LTA）。verify_pdf ltv: true 会报告配置文件、时间戳、吊销状态和 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 会报告页面框；合并 / 拆分 / 提取时会保留这些设置。参见 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 不会嵌入，因此纯拉丁文本上的 PDF/A 声明会被 veraPDF 拒绝）；strict: true 会报错，而不是生成不合规文件；includeDiagnostics: true 会回显引擎诊断信息。针对包含 26 个文件的语料库运行本地 veraPDF 脚本（npm run validate:pdfa；24 个通过验证，其中 3 个为负向哨兵文件；跳过 2 个页面树输出），并支持失败即关闭模式 VERAPDF_REQUIRED=1；CI 工作流通过 SHA-256 固定安装程序，且在 1.6.0 中不会阻断构建（从 v1.7.0 起会阻断构建，并在门禁中以 --require-all 取代 VERAPDF_REQUIRED=1）。1.6.0 中已知的引擎缺陷：即使使用 embedFonts，add_form 输出仍不符合 PDF/A-2b（未嵌入 /DR /Helv——已在 v1.7.0 修复）；prepare_signature_placeholder 输出只有在完成签名后才符合要求。

• 🧰 inspect_pdf — 支持 signatures: true 清点签名，以及 dss / docTimestampCount / trapped（需存在相应内容）；新增 check 值 dss、docTimestamp、trapped；checks 只列出你请求的键，signed 表示结构上存在已签名字段（签名是否有效由 verify_pdf 检查）。

• 🔁 可复现输出 — 九种文档工具均可选择性设置 creationDate，以固定 /CreationDate、XMP 日期和 trailer /ID；prepare_signature_placeholder 和 sign_pdf 支持 signingTime（现也支持时区偏移），以固定 /Sig /M。1.6.0 中，在同一主机时区下生成的字节相同（从 v1.7.0 起，在所有主机上均相同：日期均以 UTC 写入）。由 reproducible_output 提示词支持。

• 🛡️ 加固边界 — 严格输入架构（未知或拼写错误的键会返回 VALIDATION_ERROR，而不会被静默忽略）；可接受 data:…;base64, 前缀，遇到 DER 应为 PEM 格式的内容以及双重编码的载荷时会拒绝，并给出确切的修正方法；页面树工具中的页码索引错误会返回 VALIDATION_ERROR 并提示使用从 0 开始的索引；未知工具名称会作为 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.5.0 约为 108 kB），因为现在会在内联内容中公布每种块类型、布局选项和 encrypt 片段——根据策略不使用 $ref / $defs，因此会将 inputSchema 转发给函数调用 API 的主机不会遇到引用；服务说明约为 6.7 kB（此前为 12.9 kB）。结构由 scripts/tool-shape.mjs（从 v1.7.0 起为 scripts/tool-shape.ts）和 tests/catalogue-parity.test.ts 共同检查，tests/catalogue-superset.test.ts 则证明实时工具目录包含已发布的 1.5.0 目录中的所有内容；每种工具最多有两个可执行的 _meta.examples，其余示例位于 examples/。新增四种配方提示词：pades_ladder、print_ready、reproducible_output、pdfa_valid。

• 🐛 修复 — 在 pdfnative < 1.7 中，签名者元数据（signerName / reason / location / contactInfo）从未写入 /Sig 字典；现在会在占位符创建时写入。对于 B-LTA 文档，verify_pdf 不再报告 allValid: false（此前 /DocTimeStamp 会被解析为 CMS 签名）。

• 🔌 MCP 2026-07-28 基于 MCP TypeScript SDK v2（@modelcontextprotocol/server），并自动回退到 2025 时代的 initialize 握手——现有主机无需更改即可继续工作。参见 MCP 协议合规性。

• ⬆ 引擎升级 — pdfnative v1.7.0（LTV、印刷制作、图表 v2、摘要算法敏捷性、旗帜 / ZWJ 表情符号序列、UAX #9 修复）。 v1.5.0 新增功能：

• 📊 原生矢量图表 — add_chart 通过纯 PDF 路径运算符绘制柱状图／横向柱状图／折线图／饼图／圆环图（零栅格化，符合 PDF/A 标准并自动生成替代文本）。generate_basic_pdf 也接受 chart 块，可与文本和表格组合。

• 📝 填写并扁平化表单 — 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）；文件模式的结果中包含 resource_link，便于在后续调用中重新引用。

• 🏷️ 工具注释 — 每个工具都会公布 readOnlyHint／destructiveHint／idempotentHint／openWorldHint。

• ⬆ 引擎升级 — pdfnative v1.6.0（解密／重新加密、extractText、填写／扁平化、图表；彩色表情子集字形数从 221 增至 1167）。

v1.4.0 新增功能：

• 🤝 AI 治理 + 人机协同 — draft_governance_issue 让 Agent 在本地起草完全合规的 GitHub issue（草稿 .md + 机器可读的合规报告）。Agent 是起草者，绝不自主提交：只有人工审核这一道关卡，且服务不会向 GitHub 写入任何内容（自 v1.6.0 起，除调用运营者配置的 TSA／OCSP／CRL 端点外，不会发出任何外部请求）。由 governance_contract 和 draft_issue_workflow MCP 提示词提供支持。
• ✏️ 标记注释 — annotate_pdf 通过增量更新，在现有 PDF 上叠加高亮、便笺、下划线、删除线、波浪线、方形、圆形、直线和自由文本注释。这是视觉审阅层，而非涂黑处理——底层字节保持不变。
• 🔢 inspect_pdf 中的页面标签 — 只读展示 /PageLabels 范围（罗马数字、十进制、带前缀）。
• ∑ 数学／科学脚本 — add_international_text 接受 lang: 'math'（与 emoji 一样需显式指定），以便按需嵌入 Noto Sans Math 字体。
• 🧩 MCP 提示词 — 服务现在公布 prompts 能力，包含 governance_contract 和 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。
• 📐 表格单元格边框和对齐 — add_table 新增 cellBorders、cellVAlign 和 viewerPreferences；add_international_text 新增 viewerPreferences。
• 🔐 恒定时间签名 — sign_pdf 通过 node:crypto 提供程序对 RSA 和 EC-DER 密钥签名，并透明回退到纯 JS 实现（原始 P-256 标量仍使用纯 JS，验证也使用纯 JS）；签名保持互操作性。
• ⬆ 引擎升级 — pdfnative v1.4.0。
• 🆕 工具 extract_attachments——从 PDF 中读取嵌入文件（补全 Factur-X / ZUGFeRD 往返流程），保留逐字节一致的载荷，支持 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；read_form_fields 自 v1.5.0 起支持）接受可选的 verbosity: 'summary' 和 fields: […] 输入，可让大型结果的响应缩小约 90%，同时保留 Agent 用于分支判断的字段。默认值不变。
• 🪙 不重复 base64——生成的 PDF（base64 模式）仅作为嵌入式 resource 内容块返回一次，不再同时复制到 structuredContent 中。
• 🔧 MCP 注册表发布修复——mcpName 现在采用规范的 GitHub 登录名大小写（io.github.Nizoka/pdfnative-mcp），以便注册表的区分大小写验证能够接受 npm 包。
• ⬆ 依赖项——已升级到 zod 4。

v1.1.0 新增内容：

• 🆕 新工具 validate_pdf——只读 PDF/UA（ISO 14289-1）结构符合性检查。
• 🆕 新增六种文字脚本——泰卢固文、僧伽罗文、藏文、高棉文、缅甸文、埃塞俄比亚文（总计 24 种脚本）。
• 🆕 COLRv1 彩色表情符号——原生彩色表情符号，支持单色回退。
• 🆕 换行符清理器——段落中的嵌入式 \n 会自动拆分为多个独立段落（安全 PDF/A）。
• 🆕 add_international_text 自动进行 NFC 规范化。
• 🛠 引擎升级——pdfnative v1.3.0：欧元符号 / CP-1252 符号现在可以正确提取，表格中自动换行的单元格会为每一行分配唯一的 MCID（符合 PDF/UA 安全要求）。

v1.0.0 新增内容：

• 🆕 新增三个工具：verify_pdf、add_attachment（Factur-X / ZUGFeRD）、extract_text。
• 🆕 智能表格字段：wrap、repeatHeader、zebra、caption、minRowHeight、cellPadding。
• 🆕 inspect_pdf 现在会报告 hasSignaturePlaceholder 和每个附件的摘要；新增 check 值 'placeholder' 和 'attachments'。
• 🆕 签名易用性改进：sign_pdf 接受 ECDSA SEC1 / PKCS#8 DER 密钥，并会在缺少 /Sig 占位符时自动注入（只需一次调用即可为任意 PDF 签名）。
• 🆕 可选缓存（PDFNATIVE_MCP_CACHE_DIR）：基于 SHA-256 键，TTL 为 1 小时，采用 256 MiB LRU。
• 🆕 _meta.apiVersion 和每个工具的 _meta.examples，便于 AI Agent 发现工具——参见 docs/API_STABILITY.md。
• 🆕 AI Agent 指南：docs/AI_GUIDE.md——决策树和常见问题。另请参阅 Agent 合约 docs/AGENT_CONTRACT.md（目录、决策树、操作指南、错误表）；贡献者和编码 Agent 请从 AGENTS.md 开始。
• 🆕 PDF/A 编写指南：docs/guides/PDFA.md。
• 🛠 环境变量重命名：PDFNATIVE_MCP_OUTPUT_DIR（原为 PDFNATIVE_MPC_OUTPUT_DIR；旧名称仍可使用，并会显示一次性弃用警告）。
• ✅ 现已提供：merge_pdfs、split_pdf、extract_pages（v1.3.0）、annotate_pdf（v1.4.0）、add_chart / read_form_fields / fill_form / encrypt_pdf / decrypt_pdf 工具，以及加密往返流程和原生 MCP 资源（v1.5.0），还有 add_ltv / timestamp_pdf / update_metadata，以及印刷生产和图表 v2（v1.6.0）。redact_pdf 仍暂缓提供——pdfnative 可以叠加内容或扁平化页面，但无法移除页面内容；仅靠叠加实现的“涂黑”会造成虚假的安全感，因此我们有意不提供此功能（已记录为上游内容移除需求）。

所有工具均支持两种输出模式：

• base64 （默认） — 生成的 PDF 仅作为嵌入式 resource 内容块（data:application/pdf;base64,… URI）返回一次；structuredContent 仅包含 { mode, sizeBytes }（当 includeDiagnostics: true 时还包含 diagnostics[]，对于 add_ltv 还包含 summary）。
• file — 将 PDF 写入通过 PDFNATIVE_MCP_OUTPUT_DIR 配置的沙盒目录。除非设置此变量，否则会禁用文件输出；绝对路径、路径遍历、非 .pdf 扩展名和 NUL 字节均会被拒绝。

**从 v1.1.0 升级：**唯一的行为变更是，base64 模式下的字节不再重复写入 structuredContent.base64。请改为从嵌入式 resource 块中读取：

- 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

**节省令牌的读取（v1.2.0）。**七个只读工具（inspect_pdf、verify_pdf、validate_pdf、extract_text、extract_attachments、read_form_fields、inspect_layout）接受两个可选输入：

• verbosity: 'summary' — 返回精简的纯标量判定结果（省略大型数组／完整文本）。例如，verify_pdf → { signatureCount, allValid, invalid, summary }（ltv: true 时还包含 ltvLevel）；inspect_pdf 在存在时保留 docTimestampCount / 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/2u/3b、AES-128/256 加密、AcroForm、数字签名。
• 27 种 Unicode 文字系统（34 个 lang 代码，包括 latin、emoji、math 和四个 latin 别名），内置 BiDi 重排、阿拉伯语位置字形塑形，以及泰语／天城文／孟加拉语／泰米尔语 OpenType 字形塑形。
• PDF/X-4 印刷交换、DeviceCMYK 颜色和精细排版（孤行／寡行控制、两端对齐、法语标点间距、OpenType 功能）。
• 支持 Tree-shaking 的 ESM 构建。

---

🚀 安装

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

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

要求：Node.js ≥ 22。

---

⚙️ 配置

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 / Roo Code

任何支持 stdio 服务的 MCP 兼容客户端均可使用。使用相同的 command + args + env 三元组。Cursor 示例（~/.cursor/mcp.json）：

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

Windsurf / Cline / Roo Code 在各自的 MCP 配置文件中使用相同的结构。

🌐 支持的 AI 生态系统和客户端

pdfnative-mcp 专为 MCP 原生环境设计，可与支持通过 stdio 或 Streamable HTTP 使用 MCP 的客户端配合使用。

社区已验证的兼容性包括：

• Ontheia — 可自托管的开源 AI Agent 平台（注重隐私）。据 issue #41 报告，可开箱即用，并列于 Ontheia 的兼容 MCP 服务页面。

🔌 MCP 协议兼容性

自 v1.6.0 起，服务基于 MCP TypeScript SDK v2（@modelcontextprotocol/server）构建，并支持 MCP 2026-07-28：

• 无状态服务——server/discover 取代会话握手；每个结果都包含 resultType 和 _meta serverInfo 信封。通过 HTTP 通信时，2026-07-28 客户端会在每个 POST /mcp 请求中发送 Mcp-Method / Mcp-Name 标头。
• 缓存提示——tools/list 和 prompts/list 的缓存级别为 public，ttlMs 为 24 小时；server/discover 的缓存级别为 public，有效期为 1 小时；resources/list / resources/templates/list / resources/read 的缓存级别为 private，ttlMs: 0（生成的 PDF 属于特定主机的用户数据）。
• 资源错误——未知资源 URI 会被报告为 JSON-RPC -32602（Invalid params），这是 2026-07-28 规范的要求。
• 自动兼容旧版协议——客户端使用 initialize（2025-11-25、2025-06-18 或 2025-03-26）建立连接时，会通过 SDK 的旧版路径提供服务，stdio 和 HTTP 均如此。现有主机不会有任何变化。
• HTTP——GET / DELETE /mcp 返回 405（不支持 SSE 恢复；服务无状态）。环回绑定以及 Host / Origin 防护保持不变；Origin 端口现在必须与服务端口相同（SDK 自身的检查不区分端口）；PDFNATIVE_MCP_HTTP_TOKEN 可选择启用 bearer 令牌验证（未提供令牌时返回 401 + WWW-Authenticate）。HTTP 接受 JSON-RPC 批量数组（2025-03-26）。保持活动状态的连接不再累积套接字监听器。
• stdio——与迄今所有 SDK 版本一样，在 initialize 之前发送的请求会被丢弃且不作回复；stdio 不接受 JSON-RPC 批量数组（与 1.5.0 相同；没有主要主机使用批量请求）。
• 协议错误——使用未知工具名称调用 tools/call 时，会返回 JSON-RPC 错误（-32602，[UNKNOWN_TOOL] Unknown tool: …），而不是 isError 结果，因为规范将其归类为错误；isError: true 仅用于执行失败。
• 输出架构——每个 structuredContent 都符合工具的 outputSchema（2026-07-28 的强制要求），包括 verbosity: 'summary' 和 fields 投影：七个读取工具都声明了可投影的架构（所有属性均为可选，并保留 additionalProperties: false）。根据策略，输入架构不带 $schema 关键字（MCP ≥ 2025-11-25 默认使用 JSON Schema 2020-12；某些主机会将 inputSchema 转发给拒绝未知关键字的函数调用 API）。serverInfo 包含 websiteUrl；资源模板为 pdfnative://output/{+path}。

tools/call 负载（content、structuredContent、isError）在 2026-07-28 路径和旧版路径中完全相同；tests/http-modern.test.ts 对此进行断言，tests/schema-conformance.test.ts 使用 SDK 的 JSON Schema 2020-12 验证器校验 structuredContent。

客户端	传输方式	协商的协议
Claude Desktop、Cursor、Continue、Zed、Windsurf、Cline	stdio	旧版 initialize（2025-xx）——保持不变
ChatGPT 和其他 Streamable HTTP 主机	HTTP POST /mcp	旧版无状态 Streamable HTTP——保持不变
MCP 2026-07-28 客户端（SDK v2 Client、当前 MCP Inspector）	stdio / HTTP	server/discover、缓存提示、_meta 信封
Ontheia	stdio	旧版 initialize（社区验证，#41）

环境变量

变量	用途
PDFNATIVE_MCP_OUTPUT_DIR	沙盒目录的绝对路径。启用 outputMode: 'file' 所必需。
PDFNATIVE_MCP_CACHE_DIR	启用持久化 SHA-256 键控结果缓存的绝对路径（TTL 为 1 h，LRU 为 256 MiB；键按工具 API、软件包版本和固定的创建时刻进行命名空间隔离）。未设置时，缓存将被禁用。不会缓存 encrypt_pdf / decrypt_pdf / sign_pdf / add_ltv / timestamp_pdf / update_metadata 或文件模式调用；命中缓存时会附带 _meta.cached: true，并返回先前调用的字节内容。
PDFNATIVE_MCP_PORT	若设置为有效端口（1–65535），则在 http://127.0.0.1:<port>/mcp 启动 HTTP 服务，而非使用 stdio。仅绑定到环回地址，并启用 DNS 重绑定保护（外部 Host / Origin → 403）。除非设置了 PDFNATIVE_MCP_HTTP_TOKEN，否则不进行身份验证——其他本地进程可以访问此端点。
PDFNATIVE_MCP_HTTP_TOKEN	（v1.6.0，机密） HTTP 传输的可选 Bearer 令牌（≥ 16 个字符，不含空格——值强度不足时将中止启动）。设置后，每个 /mcp 请求都必须携带 Authorization: Bearer <token>；否则返回 401 和 WWW-Authenticate: Bearer realm="pdfnative-mcp"（仅在已发送凭据时包含 error="invalid_token"——RFC 6750 §3.1）。使用恒定时间比较，绝不记录日志。
PDFNATIVE_MCP_MAX_INFLATE_BYTES	（v1.6.0） 覆盖引擎对每个数据流设置的 100 MiB 解压上限（防止 zip 炸弹）：正整数，单位为字节，且 ≥ 1024；启动时读取一次——值无效时将拒绝启动。在共享主机上可调低此值；对于可信的大型扫描文档存档可调高此值。附件数据流达到上限时，extract_attachments includeData: true 会失败并返回 PDF_PARSE_FAILED；内容数据流达到上限时，extract_text 会将页面文本降级为空（引擎行为，不会显示错误）。
PDFNATIVE_MCP_TSA_URL	（v1.6.0） RFC 3161 时间戳颁发机构的绝对 http(s) URL，供 sign_pdf timestamp: true 和 timestamp_pdf 使用。未设置时返回 TSA_NOT_CONFIGURED，且不会发出请求。
PDFNATIVE_MCP_TSA_AUTH	（v1.6.0，机密） 发送给 TSA 的可选 Authorization 标头值。绝不记录日志或回显。
PDFNATIVE_MCP_REVOCATION	（v1.6.0） ocsp、crl 或 ocsp,crl——为 add_ltv mode: 'online' 启用在线吊销信息收集。未设置时返回 REVOCATION_NOT_CONFIGURED。
PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS	（v1.6.0） 以逗号分隔的允许列表（host、host:port、*.suffix），用于 OCSP / CRL 响应方。设置 PDFNATIVE_MCP_REVOCATION 时必填——响应方 URL 来自不可信证书。
PDFNATIVE_MCP_NETWORK_TIMEOUT_MS	（v1.6.0） TSA / OCSP / CRL 调用的单次请求超时时间，范围为 1000–120000 ms（默认值为 10000）。
PDFNATIVE_MCP_CREATION_DATE	（v1.7.0） 带时区的 ISO 8601 时刻（例如 2026-01-01T00:00:00Z），用于固定进程所创建的每个文档的创建时刻：/CreationDate、XMP 日期、trailer /ID 以及 {date} 页眉 / 页脚占位符。启动时读取一次——值无效时将拒绝启动；固定时刻的来源会记录到 stderr。
SOURCE_DATE_EPOCH	（v1.7.0） reproducible-builds.org 约定：自 Unix 纪元起的整数秒数，在未设置 PDFNATIVE_MCP_CREATION_DATE 时使用。值无效时将拒绝启动。许多构建环境已导出此变量：从此版本起，它会固定每个文档的创建日期——如果不需要此行为，请在服务器进程中取消设置。
创建日期的优先级（从高到低）：单次调用的 creationDate → PDFNATIVE_MCP_CREATION_DATE → SOURCE_DATE_EPOCH → 系统时钟。日期始终以 UTC 写入，因此固定输出在任何主机和任何时区中都具有相同的字节。按设计，固定日期不涵盖：signingTime（sign_pdf、prepare_signature_placeholder）、modDate（update_metadata）、增量写入器重新生成的第二个 /ID（annotate_pdf、fill_form）、RFC 3161 时间戳令牌和在线撤销数据、加密（新的文件密钥、盐值和 IV）以及 ECDSA 签名（按设计为随机生成）。参见 docs/guides/REPRODUCIBLE.md。

---

🛠 工具参考

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 种块类型：heading、paragraph、list、table、image、link、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 块最多包含 12 M 个 base64 字符，每次调用解码后最多 24 MiB（PNG：8 位灰度/RGB、非隔行扫描、无 alpha、无调色板——否则会返回 VALIDATION_ERROR 并提供解决方法）；svg 支持 <path>、<rect>、<circle>、<ellipse>、<line>、<polyline>、<polygon>、<text>/<tspan>，并会静默忽略 transform、<g>、<use>、<image>、渐变、不透明度和 CSS（绝不会获取外部引用）；toc 根据标题块生成，并与 outline: 'auto' 配合使用；pdfA 中的 formField 需要 embedFonts: true，以嵌入字段字体（否则会出现 PDFA_UNEMBEDDED_FORM_FONT；此时 strict: true 会导致失败）；barcode 没有 alt。渲染前，请使用相同的输入调用 inspect_layout 预览分页。

排版（v1.7.0）。 typography 是一个可选对象（共 12 个键，默认全部关闭——省略时字节保持不变），可用于九种文档工具和 inspect_layout：

{
  "title": "Annual report",
  "embedFonts": true,
  "typography": {
    "splitParagraphs": true, "orphans": 3, "widows": 3,
    "keepHeadingsWithNext": { "minLines": 3 },
    "opticalMargins": true, "kerning": true, "fontFeatures": ["onum", "smcp"],
    "unitBinding": true, "bindShortWords": true, "punctuationSpacing": "fr"
  },
  "blocks": [
    { "type": "heading", "text": "Outlook", "level": 2, "keepWithNext": true },
    { "type": "paragraph", "text": "A long justified paragraph…", "align": "justify" },
    { "type": "paragraph", "text": "Figures by region:", "keepWithNext": true, "splittable": false }
  ]
}

• 键：splitParagraphs、orphans / widows（1–10，默认值为 2，需启用 splitParagraphs）、keepHeadingsWithNext（true 或 { minLines }）、unitBinding（true 或 { units }）、bindShortWords（true 或 { maxLength, words }）、punctuationSpacing（'fr'、'fr-CA' 或由 { char, side, space } 规则组成的数组）、opticalMargins、metrics（默认值为 'approximate' / 'exact'）、fontFeatures（tnum、pnum、lnum、onum、zero、ordn、sups、subs、smcp、c2sc、case）、kerning、hyphenationLanguage。
• 块输入：paragraph 接受 align（默认值为 left，也可设为 right / center / justify）、keepWithNext 和 splittable（会覆盖该块的 typography.splitParagraphs）；heading 接受 keepWithNext（会覆盖该块的 typography.keepHeadingsWithNext）。
• 限制：kerning、fontFeatures 和 'fr' 窄不换行空格需要嵌入字体（embedFonts: true；使用 base-14 Helvetica 时，'fr' 会降级为 'fr-CA'）；metrics: 'exact' 仅作用于 base-14 文本；对随附的 Noto Sans 而言，tnum / lnum 不会产生任何变化（诊断信息为 TYPOGRAPHY_FEATURE_INEFFECTIVE）；未安装任何连字符词典，因此 hyphenationLanguage 在此服务上不起作用——文本中的软连字符（U+00AD）会得到处理。参见 docs/guides/TYPOGRAPHY.md 和 typography 提示词。 CMYK 颜色（v1.7.0）。 每种颜色输入都保留其一直以来支持的形式（图表、模板、link 和 svg 块使用十六进制值；水印和 annotate_pdf 使用 0–1 的 RGB 三元组；轮廓条目和表格单元格边框使用自由字符串），并新增 DeviceCMYK 支持：操作数字符串 'c m y k'，各分量为 0–1（"1 0.6 0 0.1"）；以及百分比元组 [c, m, y, k]，各分量为 0–100（[100, 60, 0, 10]）。如果根据默认 sRGB 意图声明 PDF/A，CMYK 颜色会报告 PDFA_DEVICE_CMYK_CONTENT——此处请使用 RGB 颜色，或提供 CMYK outputIntent。

PDF/X-4（v1.7.0）。 在 generate_basic_pdf、add_table、add_chart、add_barcode、embed_image 和 add_international_text 中设置 pdfx: 'pdfx4'，即可生成 PDF/X-4（ISO 15930-7）文件：%PDF-1.6 文件头、PDF/X-4 XMP 标识、/GTS_PDFX 输出意图、每页均有 TrimBox，以及 /Trapped。

{
  "title": "Spring catalogue",
  "pdfx": "pdfx4",
  "embedFonts": true,
  "outputIntent": { "iccProfileBase64": "<the printer's CMYK ICC profile, base64>", "outputConditionIdentifier": "FOGRA39" },
  "metadata": { "trapped": "False" },
  "print": { "bleed": 14.17, "marks": { "colourBars": true } },
  "blocks": [{ "type": "paragraph", "text": "Four-colour job exchanged as PDF/X-4." }]
}

• 必须提供打印条件对应的 ICC 配置文件作为 outputIntent（设备类别 prtr，CMYK 或 Gray——不随附印刷机配置文件；请咨询印刷厂）；要生成符合规范的文件，需设置 embedFonts: true（否则会报告 PDFX_NO_FONT_ENTRIES；设置 strict: true 时会拒绝请求）；不能与 pdfA 和 encrypt 同时使用；metadata.trapped 必须为 'True' 或 'False'；每页只能带有 TrimBox 或 ArtBox，不能两者都有。对不一致的请求会在开始任何工作前以 VALIDATION_ERROR 拒绝。链接和表单字段会生成报告（PDFX_ANNOTATIONS）；设置 strict: true 时，PDFX_* 诊断会使调用失败，并返回 PDF_X_COMPLIANCE_VIOLATION。
• outputIntent 接受 RGB、CMYK 和 Gray 配置文件（大小 ≤ 8 MiB，在 pdfA 或 pdfx 下均适用）。配置文件必须是有效的 ICC 文件（带有 acsp 签名，大小字段一致）——手工制作的存根文件会被拒绝。
• print.marks 接受 true 或对象；marks.colourBars（true 或 { tints, size }，size 为 4–72 pt，默认值为 12）会在出血区域添加 C、M、Y、K 实色块及其 50 % 色调。默认关闭；需要约 5 mm（14.17 pt）的出血，若色条无法放入，则会跳过。
• 使用 validate_pdf { standard: 'pdf-x-4' } 检查结果——这只是结构检查，并非经认证的印前检查。请参阅 docs/guides/PRINT.md 和 print_ready 提示词。

add_barcode

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

支持的格式：qr、code128、ean13、datamatrix、pdf417。

add_international_text

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

支持的 lang 代码：27 种 Unicode 脚本——ar、he、th、ja、zh、ko、el、hi、bn、ta、ru、ka、hy、tr、pl、vi、te、si、bo、km、my、am，以及自 v1.7.0 起支持的 lo（老挝文）、nod（泰谭文）、khb（新傣仂文）、tdd（傣仂文）、cjm（占文）；另有实用字体 latin、emoji 和 math。自 v1.7.0 起，ha（豪萨语）、yo（约鲁巴语）、ig（伊博语）和 sw（斯瓦希里语）均为 latin 的别名：内置的 Noto Sans 会处理其声调符号，不会嵌入额外字体。字体始终会嵌入（不接受 embedFonts 输入）；设置固定的 creationDate 可确保输出字节一致。该工具还接受 typography 和 pdfx（参见 generate_basic_pdf）。

PDF/A 下的泰谭文： 使用 pdfA: 'pdfa2b' 搭配 lang: 'nod'，不要使用 pdfa2u——引擎中有一个字形缺少 ToUnicode 条目，veraPDF 会因此拒绝 PDF/A-2u（问题已在上游跟踪）。

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

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

sign_pdf

从 v1.0.0 起，如果缺少 /Sig 占位符，sign_pdf 会自动注入一个——只需一次调用即可签署任意 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 或 PKCS#8 DER）或 ecPrivateScalarHex（64 个十六进制字符）。

PEM → DER 转换：

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

只有在需要自定义占位符时才使用 prepare_signature_placeholder（例如，为 >4096 位 RSA 密钥设置更大的 placeholderBytes、设置 subFilter: 'ETSI.CAdES.detached' 或 reserveTimestamp: true）。其他情况下直接调用 sign_pdf。

PAdES 阶梯（v1.6.0）。 使用 profile: "pades" 调用 sign_pdf 会生成 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_AMBIGUOUS），而 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"
}

字段类型：text、textarea（多行，/Ff 4096）、checkbox、radio、dropdown、listbox；字段为空时，placeholder 会显示提示文本。添加 encrypt 可生成受密码保护且保留其 AcroForm 的表单。在声明为 PDF/A 时，传入 embedFonts: true，以便同时嵌入字段字体（从 v1.7.0 起，此类表单可通过 veraPDF 验证）；否则调用会报告 PDFA_UNEMBEDDED_FORM_FONT（此时 strict: true 会导致失败）。

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 块和水印图像。

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 Agent。

{
  "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'、'signed'、'encrypted'、'placeholder'、'attachments'、'dss'、'docTimestamp'、'trapped'、'annotations'（后四项从 v1.6.0 起支持）以及 'pdfx'（从 v1.7.0 起支持：XMP 声明该 PDF 为 PDF/X——这里只检查声明，不验证其有效性；有效性检查请使用 validate_pdf standard: 'pdf-x-4'）。只有当 XMP 声明该 PDF 为 PDF/X 时，结果中才会出现 pdfX（verbosity: 'summary' 也会保留该字段）。checksPassed 是所有请求检查结果的 AND。signatures: true 会添加逐字段清单（subFilter、isDocTimestamp、isPlaceholder、byteRange、vriKey）；annotations: true 会添加 annotations[]（每个 /Annots 条目：从 0 开始的 page、subtype、rect，以及在存在时截断至 200 个字符的 contents、title、color、quadPoints、链接 url）和 annotationCount；只有存在时才会出现 dss、docTimestampCount 和 trapped；设置 pages: true 时，如果对应值已设置，每个 perPage 条目还会包含 trimBox／bleedBox／artBox／cropBox／userUnit。

inspect_layout

只读分页试运行——包含与 generate_basic_pdf 相同的 blocks，以及所有会移动块的输入（title、footerText、pdfA、normalize、embedFonts、pageSize、margins、headerTemplate、footerTemplate，以及自 v1.7.0 起的 typography）。不会生成 PDF；请传入与调用 generate_basic_pdf 时完全相同的内容，以确保 totalPages 一致。

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

完整结果包含 pageWidth、pageHeight、margins、totalPages 和 pages[].blocks[]（type、page、x、top、width、height，单位为点，四舍五入到小数点后两位）。自 v1.7.0 起，试运行和构建共用同一个分页规划器，因此会按照实际排版方式精确测量每种块类型，包括 toc（在 1.6.0 中，toc 块的测量值为 0 pt）。

validate_pdf

只读结构符合性检查。standard 用于选择规则集：'pdf-ua-1'（默认值——适用于带标签 PDF 的 PDF/UA，ISO 14289-1），或自 v1.7.0 起支持的 'pdf-x-4'（PDF/X-4，ISO 15930-7）。使用任何工具通过 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."
}

它会验证目录中的 /MarkInfo /Marked true、/StructTreeRoot（以及 /ParentTree）、/Metadata（XMP）、/Lang，以及每页 MCID 的唯一性。这是一个快速的开发阶段检查门槛——不能替代完整的参考验证器（veraPDF），后者还会检查字体、颜色和渲染。

PDF/X-4（v1.7.0）。{ "pdfBase64": "<pdf>", "standard": "pdf-x-4" } 会检查 ISO 15930-7 的结构先决条件：PDF 1.6 标头、无加密、trailer /ID、PDF/X-4 XMP 标识、带嵌入式 prtr ICC 配置文件的 /GTS_PDFX 输出意图、每页都有嵌套在 BleedBox 和 MediaBox 中的 TrimBox 或 ArtBox、所有字体均已嵌入、打印区域内无注释、无 JavaScript、无嵌入文件，以及设备颜色与输出意图一致。结果的结构相同，另含 caveats[]，其中说明 valid: true 的判定并不代表什么：这不是经过认证的印前检查，而且 veraPDF 不涵盖 PDF/X——请使用 callas pdfToolbox 或 Acrobat Preflight 确认印刷作业。默认的 pdf-ua-1 响应保持不变，不包含 caveats。

annotate_pdf

通过增量更新在现有 PDF 上叠加标记注释。这是一个视觉审阅层，并非涂黑隐去——底层内容不会更改。

{
  "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 开始。color / interiorColor 可接受十六进制字符串或操作数字符串（包括 CMYK 操作数字符串）、0–1 RGB 三元组（[1, 1, 0]），或自 v1.7.0 起支持的 CMYK 百分比元组（[0, 0, 100, 0]）；v1.7.0 还修复了 0–1 三元组的问题，之前它渲染出来几乎是黑色。加密的源文件会被拒绝（ENCRYPTED_SOURCE）——请先运行 decrypt_pdf（会移除签名 / AcroForm），再添加注释，最后重新运行 encrypt_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。完整的人机协同约定请参见 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 Schemas 和 Zod 运行时检查进行验证——未知或拼写错误的键（顶层或嵌套）会被拒绝，并返回 VALIDATION_ERROR；在运行任何解析器之前，还会对 base64 / DER 负载进行合理性检查（容忍 data: 前缀；拒绝 PEM 或双重编码的输入，并提供解决方法）。
• HTTP 传输（PDFNATIVE_MCP_PORT）仅绑定到回环地址；除非设置了 PDFNATIVE_MCP_HTTP_TOKEN，否则不进行身份验证（没有有效的 bearer token 时返回 401）。

网络与出站流量

默认情况下，服务不会发起任何出站网络调用。它可能产生的唯一出站流量，是发往操作者为 PAdES 长期验证在环境中配置的 RFC 3161 / OCSP / CRL 端点（PDFNATIVE_MCP_TSA_URL、PDFNATIVE_MCP_REVOCATION、PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS）——绝不会发往工具参数提供的 URL、绝不会发往 GitHub，也绝不用于遥测。未进行此类配置时，sign_pdf timestamp: true、timestamp_pdf 和 add_ltv mode: 'online' 会在触碰文档之前立即失败，并返回 TSA_NOT_CONFIGURED / REVOCATION_NOT_CONFIGURED；add_ltv mode: 'offline' 会嵌入调用方提供的材料，完全不访问网络。

OCSP / CRL URL 来自 PDF 中不受信任证书的 AIA / CRL 分发点扩展，因此每次获取都会经过 SSRF 防护：

• 主机必须匹配操作者的允许列表（host、host:port 或 *.suffix；拒绝裸通配符）。条目必须是主机名，而非 URL：host:port 条目仅匹配带有显式端口的 URL（URL 解析器会移除默认的 :80 / :443——这类情况请列出不带端口的主机）；通配符条目不能带端口；IDN 主机名必须以 punycode（xn--…）列出；IPv6 字面地址须带方括号（[2001:db8::1]）；
• 仅允许 http: / https:，不得包含内嵌凭据，且绝不跟随重定向；
• 除非逐字列入允许列表，否则会拒绝回环、链路本地、私有、唯一本地、CGNAT、未指定和多播地址字面值（包括十进制 / 八进制 / 十六进制写法以及 IPv4 映射的 IPv6）。防护仅检查字面值——列入允许列表但解析到内部地址的主机名（DNS 重绑定）无法被检测，因为不添加依赖就无法进行解析；允许列表中仅添加你控制的主机；
• 在流式传输过程中强制执行每次请求的超时（PDFNATIVE_MCP_NETWORK_TIMEOUT_MS）和响应上限（TSA 为 256 KiB、OCSP 为 1 MiB、CRL 为 16 MiB），因此超大响应会被截断，而不是缓冲；
• 响应方返回的 OCSP 响应和 CRL 在由 add_ltv 嵌入之前会经过解析验证；
• TSA URL 受操作者信任（仅检查方案和凭据）；绝不会在日志或错误消息中记录或回显 PDFNATIVE_MCP_TSA_AUTH 密钥。

每次调用都会构建 Provider，并通过 pdfnative 的每次调用选项传入——绝不使用进程级 Provider 设置器，因此并发请求之间不会共享任何内容。server/discover 说明会报告当前的出站策略（仅端点类型，绝不包含密钥）。

请参阅 SECURITY.md 了解负责任披露流程，并参阅 docs/guides/LTV.md 了解操作者配置方法。

---

🧪 本地开发

git clone https://github.com/Nizoka/pdfnative-mcp.git
cd pdfnative-mcp
npm ci                    # .npmrc sets ignore-scripts=true: nothing builds on install
npm run gate:fast         # before every commit: typecheck:all, lint, test, server-json, verify:docs
npm run gate              # the CI profile: build, dist checks, stdio smoke test, tool shape, samples, coverage, docs, corpus, validate:pdfx
npx tsx scripts/gate.ts --publish --require-all   # release branches: everything incl. validate:pdfa (veraPDF); a skipped step fails

npm run gate（scripts/gate.ts）是通过标准的唯一判定依据——1631 项测试、vitest.config.ts 的覆盖率阈值，以及通过标准输入输出运行的构建后服务，其中标准输出只能包含 JSON-RPC 帧。该脚本每个步骤打印一行，并将日志写入 test-output/.gate/<step>.log；--only <step> 只运行一个步骤，--json 输出机器可读内容（如需传递标志，请直接调用脚本：npx tsx scripts/gate.ts --fast）。各个步骤都是常规的 npm 脚本：

npm run build && npm run test:generate   # drive the built server under TZ=UTC, operator variables scrubbed -> test-output/samples/
npm run verify:samples    # hold the 96 samples to tests/_fixtures/samples.sha256.json (93 by bytes, 3 by a semantic projection)
npm run corpus:pdfa       # write the 41-file conformance corpus (33 claim PDF/A, 6 claim PDF/X-4, 2 page-tree outputs claim nothing)
npm run validate:pdfx     # in-process structural PDF/X-4 check of the corpus; never skips
npm run validate:pdfa     # veraPDF over the PDF/A files (VERAPDF_HOME, JAVACMD); exit 0 ok / 1 conformance / 2 infrastructure
npm run verify:docs       # every count, version, tool, error code, operator variable, link and anchor in the docs vs docs/assets/ecosystem.json and src/
npx tsx scripts/tool-shape.ts --write   # only after a deliberate tools/list schema change (npm run verify:tool-shape checks the fixture)

有意更改输出时，应使用 npx tsx scripts/verify-samples.ts --update 重新生成基准，并在发布说明中声明——绝不能为了掩盖意外情况而这样做。使用 veraPDF 1.30.2 时，语料库中有 27 项通过、6 项符合预期的失败（必须继续被拒绝的负向哨兵用例）。所有脚本及其标志和退出代码都列在 scripts/README.md 中。

通过标准输入输出对服务进行冒烟测试：

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

贡献者： 请从 AGENTS.md 开始（其中包含所有编码 Agent 和贡献者都应遵守的仓库规则），并参阅 docs/guides/LOCAL_TESTING.md，了解完整的本地验证工作流——质量门禁、将示例用作测试、验证生成的 PDF 在结构上是否正确（assertValidPdf、inspect_pdf、validate_pdf、verify_pdf）、在查看器中打开输出、使用 veraPDF 进行外部 PDF/A 检查，以及使用 MCP Inspector。

📣 发布流程

pdfnative-mcp 遵循与 pdfnative 相同的发布规范：

• 每个标签对应一个发布说明文件，路径为 release-notes/vX.Y.Z.md
• CHANGELOG.md 与每次发布的条目列表保持一致
• GitHub Release 正文从 release-notes/vX.Y.Z.md 复制
• npx tsx scripts/release-prepare.ts --version X.Y.Z 执行版本升级中的机械性工作（不会提交、创建标签或发布）；package.json、src/version.ts、server.json 和 docs/assets/ecosystem.json 中的版本会同步更新
• 发布分支必须通过 npx tsx scripts/gate.ts --publish --require-all——所有步骤都必须通过，包括 veraPDF，不得跳过
• npm 发布通过 GitHub Actions Trusted Publishing（OIDC）处理，无需 NPM_TOKEN，并在受保护的环境中进行：工作流会检查标签是否与软件包版本一致，运行发布门禁并使用 --provenance 发布；第二个作业会为 tarball（构建来源证明）生成证明，并附上 CycloneDX SBOM，二者都会附加到 GitHub Release
• 每个 Linux 和 Windows 作业都以 step-security/harden-runner 开始（该 action 不支持 macOS；macOS 作业是文档记录在案的例外），检出时使用 persist-credentials: false，使用 npm ci --ignore-scripts 安装，并在最小权限的 permissions 下运行；actions 均通过提交 SHA 固定；veraPDF 作业为阻断项
• 人工参与流程：编码 Agent 负责准备和验证；维护者负责推送、创建拉取请求、打标签和发布（.github/AGENT_RULES.md）

请参阅 release-notes/TEMPLATE.md，了解规范结构和发布检查清单；发布流程请参阅 CONTRIBUTING.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 + colour bars, userUnit, RGB / CMYK / Gray outputIntent, metadata, creationDate)
├── pdfx.ts                     # pdfx: 'pdfx4' conformance target + the static conflicts refused before the build
├── color.ts                    # shared colour fragment: CMYK operand string / percent tuple beside each historical form, toEngineColor()
├── typography.ts               # the typography fragment (12 opt-in keys) + TypographyOptions mapper
├── reproducible.ts             # operator-pinned creation instant (PDFNATIVE_MCP_CREATION_DATE, SOURCE_DATE_EPOCH)
├── diagnostics.ts              # engine diagnostics sink (PDFA_* / PDFX_* / TYPOGRAPHY_*), strict escalation by code, 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 / typography (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/                        # TypeScript run by tsx — the full table is in scripts/README.md
├── gate.ts                     # THE quality gate (npm run gate / gate:fast; --publish --require-all on release branches)
├── generate-samples.ts         # npm run test:generate — the built server under TZ=UTC -> test-output/samples/
├── verify-samples.ts           # npm run verify:samples — the byte baseline (tests/_fixtures/samples.sha256.json)
├── generate-pdfa-corpus.ts     # npm run corpus:pdfa — the 41-file PDF/A + PDF/X-4 conformance corpus
├── validate-pdfa.ts            # npm run validate:pdfa — veraPDF (PASS/FAIL/XFAIL/XPASS; exit 0 / 1 / 2)
├── validate-pdfx.ts            # npm run validate:pdfx — in-process structural PDF/X-4 check, never skips
├── tool-shape.ts               # structural tools/list fingerprint (--write refreshes tests/_fixtures/tool-shape.json)
├── verify-docs.ts              # npm run verify:docs — the docs held to docs/assets/ecosystem.json and the source tree
├── release-prepare.ts          # mechanical version bump (never commits, tags or publishes)
├── build-claude-rules.ts       # npm run agents:rules — .github/instructions/ -> .claude/rules/
└── verify-issue.mjs            # governance draft checker (npm run verify:issue)
docs/
├── AGENT_CONTRACT.md           # the consumer contract for agents that USE the server (catalogue, decision tree, recipes, error codes)
├── AI_GUIDE.md, KNOWLEDGE_BASE.md, API_STABILITY.md
├── guides/                     # PDFA, PRINT, TYPOGRAPHY, REPRODUCIBLE, CHARTS, FORMS, ENCRYPTION, LTV, AI_GOVERNANCE, LOCAL_TESTING
└── assets/ecosystem.json       # the single source of every count and version quoted in the docs
examples/                       # 43 executable tools/call sequences (npm run examples:check)
AGENTS.md, CLAUDE.md            # repository rules for coding agents; .github/instructions/ holds the per-area rules
.claude/                        # shared agent settings, the fail-closed guard hook, generated rules, the release-audit skill
.github/workflows/              # ci (Node 22 / 24 on Linux, plus Windows and macOS, all running the gate, all required), publish, sample-regression, verapdf (blocking),
                                #   docs, codeql, scorecard, dependency-review, audit
.github/rulesets/               # branch and tag rulesets to import
tests/                          # vitest suites (one per tool / module), _fixtures/ (tool shape, sample baseline, engine-surface matrix,
                                #   the frozen 1.5.0 catalogue), tools/ (repository tooling)

---

🗺 路线图

v1.7.0 已发布（精美排版、CMYK 颜色、PDF/X-4、27 种 Unicode 文字、在所有主机上均可复现的输出、pdfnative 1.8），是在 v1.6.0（完整引擎覆盖——13 种块类型、布局选项、inspect_layout——PAdES LTV 阶梯、印刷生产、图表 v2、update_metadata、MCP 2026-07-28）的基础上推出的。完整计划——已发布的里程碑、进行中的工作和长期方向——见 ROADMAP.md。

仍暂缓的事项：

• redact_pdf — pdfnative 没有内容移除 API；仅通过覆盖层实现的“涂黑”会造成虚假的安全感。
• 自定义字体（操作端字体目录）以及 annotate_pdf 中的 link 注释——已列入路线图，但不会纳入 v1.7.0。
• 原生 ECDSA 验证——pdfnative 不导出 ecdsaVerifyHash；verify_pdf 对 P-256 继续使用纯 JS 路径。
• HTTP 页面流式传输——MCP 2026-07-28 仍不支持部分 structuredContent，因此大型结果仍会一次性返回。

有功能想法？欢迎提交 issue 或 PR。

---

⭐ 为项目点星

如果 pdfnative-mcp 对你有帮助，请给此仓库点个 ⭐——也可以为底层引擎 Nizoka/pdfnative 点星。星标能帮助更多人发现这个项目，并激励我们持续开发。

---

🤝 参与贡献

我们非常欢迎贡献。请阅读 CONTRIBUTING.md，查看未解决的问题，并遵守行为准则。

---

📄 许可证

MIT © 2026 Nizoka。第三方材料：THIRD-PARTY-NOTICES.md。

pdfnative-mcp 基于 pdfnative 和 Model Context Protocol TypeScript SDK 构建。