内容
# pdfnative-mcp
> **模型上下文协议（MCP）服务器**，用于连接 [pdfnative](https://github.com/Nizoka/pdfnative) 库——一个零依赖、符合ISO 32000-1的PDF引擎——与任何兼容MCP的AI客户端（Claude Desktop、Cursor、Continue、ChatGPT、Zed等）。
[](https://www.npmjs.com/package/pdfnative-mcp)
[](https://www.npmjs.com/package/pdfnative-mcp)
[](https://nodejs.org)
[](LICENSE)
[](https://github.com/Nizoka/pdfnative-mcp/actions/workflows/ci.yml)
[](https://modelcontextprotocol.io)
[](https://www.typescriptlang.org/)
[](https://scorecard.dev/viewer/?uri=github.com/Nizoka/pdfnative-mcp)
[](https://github.com/Nizoka/pdfnative-mcp/actions/workflows/codeql.yml)
---
## ✨ 功能
`pdfnative-mcp` 为任何MCP主机提供 **14种生产级工具**：
| 工具 | 目的 |
| --- | --- |
| `generate_basic_pdf` | 从结构化块（标题、段落、列表、分页符）生成多页A4文档。嵌入换行符自动分成段落。可选 `pdfA`。 |
| `add_barcode` | 在单页PDF中添加二维码、Code 128、EAN-13、Data Matrix、PDF417等。 |
| `add_international_text` | 添加24种脚本（包括**拉丁文**和COLRv1**彩色表情符号**）并支持双向和OpenType形状；每文档支持多语言。 |
| `add_table` | 生成带有智能字段（换行、重复表头、斑马纹、标题、最小行高、单元格填充）的表格报告。 |
| `add_form` | 创建带有文本字段、复选框、单选按钮、下拉菜单的交互式AcroForm PDF。 |
| `embed_image` | 将JPEG或PNG图像（base64）嵌入到带有标题的PDF文档中。 |
| `prepare_signature_placeholder` | 两步签名工作流的第一步 - 创建带有 `/Sig` AcroForm占位符的PDF。 |
| `sign_pdf` | 应用PAdES兼容的CMS签名（RSA-SHA256 / ECDSA-SHA256 P-256）。自动注入占位符（如果需要）。 |
| `verify_pdf` | 验证PDF中的每个PAdES签名（完整性 + 签名值 + 可选的链信任）。 |
| `validate_pdf` *(v1.1.0 新增)* | 验证Tagged PDF的PDF/UA（ISO 14289-1）结构一致性（只读）。 |
| `add_attachment` | 生成带有嵌入文件（Factur-X / ZUGFeRD发票）的PDF/A-3文档。 |
| `extract_attachments` | 只读提取嵌入文件（Factur-X / ZUGFeRD XML往返）并带有字节对字节的有效载荷。 |
| `extract_text` | 从非加密PDF中进行尽力而为的纯文本提取。 |
| `inspect_pdf` | 只读检查：PDF版本、页数、加密、PDF/A声明、签名、附件、占位符状态。 |
**v1.2.0 新增：**
- 🆕 **工具 `extract_attachments`** - 从PDF中读取嵌入文件（完成Factur-X / ZUGFeRD往返）并带有字节对字节的有效载荷、文件名过滤器和`includeData: false`元数据探测。
- 💧 **水印** - `generate_basic_pdf` 和 `add_table` 接受可选的水印（文本、不透明度、角度、颜色、位置）在每页上渲染。
- 🌐 **Unicode `normalize`** - 在 `generate_basic_pdf` 和 `add_international_text` 上选择 `NFC`/`NFD`/`NFKC`/`NFKD`。
- 🪙 **节省令牌的读取** - 只读工具（`inspect_pdf`、`verify_pdf`、`validate_pdf`、`extract_text`、`extract_attachments`）接受可选的 `verbosity: 'summary'` 和 `fields: […]` 输入，以获得 ~90% 更小的响应， 而不损失代理分支的字段。 默认值保持不变。
- 🪙 **无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](https://github.com/Nizoka/pdfnative)：欧元符号 / 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密钥，1小时TTL，256 MiB LRU。
- 🆕 **`_meta.apiVersion`** 和每个工具的 **`_meta.examples`** 用于AI代理发现 - 请参阅 [`docs/API_STABILITY.md`](docs/API_STABILITY.md)。
- 🆕 **AI代理指南：** [`docs/AI_GUIDE.md`](docs/AI_GUIDE.md) - 决策树 + 常见陷阱。 另请参阅根目录 [`AGENTS.md`](AGENTS.md) 操作手册。
- 🆕 **PDF/A作者指南：** [`docs/guides/PDFA.md`](docs/guides/PDFA.md)。
- 🛠 **环境变量重命名：** `PDFNATIVE_MCP_OUTPUT_DIR`（以前为 `PDFNATIVE_MPC_OUTPUT_DIR`；旧名称仍然有效，并带有一次性弃用警告）。
- ⏭ **延迟到v1.1：** `merge_pdfs`、`split_pdf`、`redact_pdf`（需要pdfnative页面树基元尚未导出）。
所有工具都支持两种输出模式：
- **`base64`** *(默认)* - 生成的PDF作为嵌入的 `resource` 内容块返回一次（`data:application/pdf;base64,…` URI）；`structuredContent`仅携带 `{ mode, sizeBytes }`。
- **`file`** - PDF写入通过 `PDFNATIVE_MCP_OUTPUT_DIR` 配置的沙盒目录中。 除非设置此变量，否则文件输出被禁用； 绝对路径、路径遍历、非`.pdf`扩展名和NUL字节全部被拒绝。
> **从v1.1.0升级：** 唯一的行为变化是base64模式下的字节 不再复制到 `structuredContent.base64`。 改为从嵌入的 `resource` 块中读取：
```diff
- 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
```
### 为什么选择pdfnative？
`pdfnative-mcp` 继承了底层引擎的所有保证：
- **零运行时依赖** - 纯JavaScript，无原生绑定。
- **ISO 32000-1（PDF 1.7）** 合规输出。
- **PDF/A-1b/2b/3b**，**AES-128/256加密**，**AcroForm**，**数字签名**。
- **16种Unicode脚本**，内置双向重排序，阿拉伯语位置形状，泰文/天竺文/孟加拉语/泰米尔语OpenType形状。
- 可树状摇动的ESM构建。
---
## 🚀 安装
```bash
# 使用npx直接运行（推荐MCP客户端）
npx -y pdfnative-mcp
# 或全局安装
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）：
```json
{
"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`）：
```json
{
"mcpServers": {
"pdfnative": {
"command": "npx",
"args": ["-y", "pdfnative-mcp"],
"env": { "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs" }
}
}
}
```
**Windsurf / Cline / Roo Code** 在其各自的MCP配置文件中使用相同的形状。
### 环境变量
| 变量 | 目的 |
| --- | --- |
| `PDFNATIVE_MCP_OUTPUT_DIR` | 绝对路径到沙盒目录。 **启用 `outputMode: 'file'`必填** |
| `PDFNATIVE_MCP_CACHE_DIR` | 绝对路径以启用持久的SHA-256密钥结果缓存（1小时TTL，256 MiB LRU）。 未设置时，缓存被禁用。 |
| `PDFNATIVE_MCP_PORT` | 设置为有效端口（1-65535）时，在 `http://127.0.0.1:<port>/mcp` 而不是stdio上启动HTTP服务器。 |
---
## 🛠 工具参考
### `generate_basic_pdf`
```jsonc
{
"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"
}
```
### `add_barcode`
```jsonc
{
"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`
```jsonc
{
"title": "مرحبا بالعالم",
"lang": "ar",
"paragraphs": [
"هذا اختبار للنص العربي مع تشكيل OpenType ومحارف ثنائية الاتجاه.",
"Mixed content: العربية + English ✓"
]
}
```
支持的 `lang` 代码： `ar`、`he`、`th`、`ja`、`zh`、`ko`、`el`、`hi`、`bn`、`ta`、`ru`、`ka`、`hy`、`tr`、`vi`、`pl`、`latin`、`emoji`.
多脚本文档 - 传递数组或逗号分隔列表：
```jsonc
{
"title": "Mixed Script",
"lang": ["ar", "emoji"],
"paragraphs": ["العربية مع رموز 🎉🚀"],
"pdfA": "pdfa2u"
}
```
### `sign_pdf`
从v1.0.0开始，`sign_pdf` 变成 `sign_pdf` 自动注入 `/Sig` 占位符 - 您可以在一次调用中使用 **任何** PDF 签名：
```jsonc
{
"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"
}
```
PEM → DER 转换：
```bash
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
```
> 仅当您需要自定义占位符（例如更大的 `placeholderBytes` 用于 >4096 位 RSA 密钥）时，请使用 `prepare_signature_placeholder`。否则，请直接调用 `sign_pdf`。
---
### `add_table`
```jsonc
{
"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`
```jsonc
{
"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 }
],
"outputMode": "base64"
}
```
### `embed_image`
```jsonc
{
"title": "Product Photo",
"imageBase64": "<base64-encoded JPEG bytes>",
"mimeType": "image/jpeg",
"caption": "Front view of Model X",
"width": 400,
"outputMode": "base64"
}
```
> **注意：** pdfnative 不支持 alpha 通道 PNG（颜色类型 6）。在嵌入之前，请预处理此类图像以删除 alpha 通道。
### `prepare_signature_placeholder`
```jsonc
{
"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 断言和 AI 代理在操作 PDF 之前需要了解 PDF。
```jsonc
{
"pdfBase64": "<base64 PDF>",
"pages": true,
"check": ["pdfa", "signed", "attachments"]
}
```
返回：
```jsonc
{
"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'` 中的任意值。`checksPassed` 是所有请求的检查的 AND 运算。
### `validate_pdf`
只读 **PDF/UA（ISO 14289-1）** 结构一致性检查，用于 Tagged PDF。使用任何工具生成可访问的文档时使用 `pdfA`（例如 `pdfA: 'pdfa2u'`），然后验证结果：
```jsonc
{ "pdfBase64": "<tagged-pdf-base64>" }
```
返回：
```jsonc
{
"standard": "pdf-ua-1",
"valid": true,
"errors": [], // 阻止结构违规（当有效时为空）
"warnings": [], // 非阻塞最佳实践建议
"summary": "PDF/UA 结构前提条件成立。"
}
```
它验证目录 `/MarkInfo /Marked true`、`/StructTreeRoot`（+ `/ParentTree`）、`/Metadata`（XMP）、`/Lang` 和每页 MCID 唯一性。这是快速的开发者时间门控 - **不是** 替换完整的参考验证器（veraPDF），它还检查字体、颜色和渲染。
### `verify_pdf`、`add_attachment`、`extract_text`
请参阅 [`docs/AI_GUIDE.md`](docs/AI_GUIDE.md) 和参考资料中的专用章节 [`docs/KNOWLEDGE_BASE.md`](docs/KNOWLEDGE_BASE.md)。可在 [`examples/`](examples/) 目录中找到现成的示例。
---
## 🔐 安全模型
`pdfnative-mcp` 在 **主机进程** 中运行，并公开stdio服务器。它 **不** 打开网络套接字，也不执行配置的沙盒目录以外的任何I/O操作。
- **文件写入** 由 `PDFNATIVE_MCP_OUTPUT_DIR` 控制。当未设置时，`file` 输出模式被拒绝，并返回 `SecurityError`。
- **路径解析** 拒绝绝对路径、遍历序列 (`..`)、NUL 字节和 `.pdf` 以外的任何扩展名。
- **输出大小** 每调用限制为 50 MB。
- **输入** 在每个工具的边界处针对严格的JSON模式 + Zod运行时检查进行验证。
有关负责任的披露过程，请参阅 [SECURITY.md](SECURITY.md)。
---
## 🧪 本地开发
```bash
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
```
通过stdio进行服务器烟雾测试：
```bash
node dist/cli.js
```
# 在另一个终端中，通过标准输入发送 JSON-RPC 初始化请求（例如，使用 mcp-inspector）。
> **贡献者：** 查看 [docs/guides/LOCAL_TESTING.md](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-notes/vX.Y.Z.md`
- npm 发布由 GitHub Actions Trusted Publishing（OIDC）处理，无需 `NPM_TOKEN`
查看 `release-notes/TEMPLATE.md` 以获取规范的结构和发布检查清单。
---
## 📚 项目结构
```
src/
├── cli.ts # 标准输入输出入口点（#!/usr/bin/env node）
├── index.ts # 公共库导出
├── server.ts # McpServer 工厂 + 工具注册表
├── output.ts # 沙盒文件写入器 / base64 发射器
├── text.ts # 新行消毒器（Safe PDF/A）
├── errors.ts # ToolError，SecurityError
└── tools/
├── generate-basic-pdf.ts
├── add-barcode.ts
├── sign-pdf.ts
├── add-international-text.ts
├── add-table.ts
├── add-form.ts
├── embed-image.ts
├── inspect-pdf.ts
├── verify-pdf.ts
├── validate-pdf.ts
├── add-attachment.ts
├── extract-text.ts
└── prepare-signature-placeholder.ts
tests/ # vitest 套件
```
---
## 🗺 路线图
v1.1.0 已发布。完整的计划 — 已发布的里程碑、正在进行的工作和长期方向 — 存放在 [ROADMAP.md](ROADMAP.md) 中。
**阻塞上游（页面树操作）：**
- `merge_pdfs`、`split_pdf`、`redact_pdf` — pdfnative 尚未导出构建这些功能所需的安全页面树操作原语。它们仍在路线图中，阻塞在上游 API 上。
有功能想法？打开一个问题或拉取请求。
---
## ⭐ 星标项目
如果 `pdfnative-mcp` 对您有帮助，请 ⭐ 这个仓库 — 同时考虑为底层引擎 [Nizoka/pdfnative](https://github.com/Nizoka/pdfnative) 点赞。星标帮助其他人发现项目并激励持续开发。
---
## 🤝 贡献
非常欢迎贡献。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，查看 [开放问题](https://github.com/Nizoka/pdfnative-mcp/issues)，并遵循 [行为准则](CODE_OF_CONDUCT.md)。
---
## 📄 许可证
[MIT](LICENSE) © 2026 Nizoka
`pdfnative-mcp` 建立在 [`pdfnative`](https://github.com/Nizoka/pdfnative) 和 [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) 之上。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器