PolyDoc

polydoc-mcp

PolyDoc 用の MCP サーバーです。PolyDoc は、HTML または URL を PDF に変換し、スクリーンショットを撮影し、EU 準拠の 電子請求書（Factur-X / ZUGFeRD ハイブリッド PDF/A-3）を生成する REST API です。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	セルフホスト環境またはステージング環境で使用する URL です。
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、クレジット）とともに絶対パスが返されます。スクリーンショットでは、インライン画像ブロックも返されます。バイトデータを base64 として受け取るには returnBase64: true を渡します（データ量が大きくなります。ファイルシステムを利用できないクライアント向けです）。
• クラウドストレージ：delivery: "cloudStorage" と presignedUrl を設定します。アップロード URL が返されます。
• Webhook：delivery: "webhook" と webhook オブジェクト（{ url, async?, method?, headers? }）を設定します。

PDF/A と PDF/UA

polydoc_html_to_pdf では、pdfOptions 内に 2 つの準拠ターゲットを指定できます。

{
  "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