PolyDoc

polydoc-mcp

适用于 PolyDoc 的 MCP 服务。PolyDoc 是一个 REST API，可将 HTML 或 URL 转换为 PDF、捕获屏幕截图，并生成符合欧盟要求的电子发票（Factur-X / ZUGFeRD 混合 PDF/A-3）。它让 MCP 客户端（Claude Desktop、Claude Code、Cursor 等）可以直接驱动 PolyDoc。

PDF 输出可以采用 PDF/A（归档）和 PDF/UA-1（无障碍，ISO 14289-1）标准。默认情况下，两者均尽力生成符合标准的文件；对任一选项设置 verify，即可使用 veraPDF 验证结果，并在文件不符合标准时失败，而不是返回该文件。

工具

• polydoc_html_to_pdf - 将 HTML、URL 或已保存的模板转换为 PDF（布局、边距、页面格式、页面范围、书签、带标签的 PDF、PDF/A 和 PDF/UA 合规性）。
• polydoc_screenshot - 将 HTML、URL 或模板转换为 PNG / JPEG / WebP，并可控制视口和设备像素比。图像较小时，会以内嵌预览的形式返回。
• polydoc_generate_einvoice - 根据结构化发票数据生成 Factur-X 或 ZUGFeRD 混合 PDF/A-3，支持 basic、en16931 和 extended 配置文件。
• polydoc_test_credentials - 使用最简沙盒渲染验证配置的 API 密钥（不会消耗生产环境配额）。

内容可以来自 URL、内联的 HTML 字符串或已保存的模板（使用 Liquid templateData）。下载文件会写入本地目录，并返回文件路径；也可以将文件传送到云存储（预签名 URL）或通过 webhook 传送。

安装

需要 Node.js >= 20.15。此项目已发布到 npm，因此客户端可以使用 npx 运行：

npx -y polydoc-mcp

服务完全通过环境变量进行配置（见下文）。

配置

变量	必需	默认值	说明
POLYDOC_API_KEY	是	-	来自 dashboard.polydoc.tech 的 API 密钥。
POLYDOC_SANDBOX	否	false	默认沙盒模式（带水印、受速率限制）。工具调用可以按请求覆盖此设置。
POLYDOC_BASE_URL	否	https://api.polydoc.tech	用于可自托管实例或预发布环境的覆盖值。
POLYDOC_OUTPUT_DIR	否	OS 临时目录 + /polydoc	下载文件的写入位置。输出文件不会写到此文件夹以外。

客户端设置

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings > Developer > Edit Config）：

{
  "mcpServers": {
    "polydoc": {
      "command": "npx",
      "args": ["-y", "polydoc-mcp"],
      "env": {
        "POLYDOC_API_KEY": "your-key",
        "POLYDOC_OUTPUT_DIR": "/Users/you/Documents/polydoc"
      }
    }
  }
}

Claude Code

claude mcp add polydoc -e POLYDOC_API_KEY=your-key -- npx -y polydoc-mcp

Cursor

使用与 Claude Desktop 相同的 mcpServers 配置块，添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）。

输出和传送

• 下载（默认）：文件会写入 POLYDOC_OUTPUT_DIR，并返回绝对路径以及元数据（大小、转换 ID、额度）。屏幕截图也会返回内嵌图像块。传入 returnBase64: true 还可以将字节以 base64 形式返回（数据量较大；适用于没有文件系统的客户端）。
• 云存储：设置 delivery: "cloudStorage" 和 presignedUrl。系统会返回上传 URL。
• Webhook：设置 delivery: "webhook" 和一个 webhook 对象（{ url, async?, method?, headers? }）。

PDF/A 和 PDF/UA

polydoc_html_to_pdf 在 pdfOptions 中接受两个合规性目标：

{
  "pdfOptions": {
    "pdfa": { "level": "3b", "verify": true },
    "pdfua": { "verify": true }
  }
}

pdfa.level 可以是 1b、2b 或 3b。设置 pdfua 会强制进行带标签的渲染，因此无需同时设置 tagged。

如果未设置 verify，输出将尽力符合标准：目标是符合标准，但如果工具链无法满足所有可由机器检查的规则，请求仍会成功。如果设置 verify: true，veraPDF 将验证结果；如果文件不符合标准，系统会返回 422，而不是返回该文件。当下游系统无论如何都会拒绝不合格文件时，请使用此选项。

工具的架构中没有的选项？

每个转换工具都有一个 advanced 对象，会与请求正文进行深度合并，因此任何未作为带类型字段公开的 API 功能（例如 pdf.watermark、pdf.encryption、render、request）仍可使用。请参阅 docs.polydoc.tech 中的字段参考。

示例

每种方案的工具输入示例都位于 examples/：使用模板生成的品牌 PDF、URL 截图，以及 ZUGFeRD / EN 16931 电子发票。

开发

• yarn install
• yarn build - 编译到 dist/
• yarn lint
• yarn test - 单元测试（请求构建器、输出隔离、工具处理程序）和内存中的 MCP 往返测试
• POLYDOC_API_KEY=your-key yarn test:integration - 针对沙盒运行实时冒烟测试
• yarn scrub:check - 检查源代码和文档中是否有破折号

直接运行构建好的服务进行快速检查：

POLYDOC_API_KEY=your-key node dist/index.js

许可证

MIT