PDF Agent Stack

日本語

English

日本語

English

Appearance

導入手順 ​

前提: Node.js 20+。全サーバー npx で起動できるためグローバルインストールは不要です。

Step 1 — 最小構成（pdf-reader） ​

jsonc
{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-reader-mcp@latest"],
    },
  },
}

環境変数なしで動きます。まず PDF を 1 つ読んで動作確認してください。

Step 2 — pdf-spec ​

仕様コーパスの配置 ​

このステップを飛ばすと pdf-spec は 1 問も答えられません。 pdf-spec-mcp は仕様 PDF 本体を同梱しません（ISO 文書のため再配布できません）。仕様の原文は利用者が入手して配置します — 幸い、中核文書はすべて正規ルートで無償入手できます。

入手先含まれる文書
PDF Association: Sponsored ISO standards → ISO 32000-2 バンドルISO 32000-2:2020（Errata Collection 3 収録）+ ISO TS 32001 / 32002 / 32003 / 32004
同ページ → PDF/UA バンドルISO 14289-1:2014（PDF/UA-1）+ ISO 14289-2:2024（PDF/UA-2）+ ISO TS 32005
Adobe 公開版 PDF32000_2008.pdfISO 32000-1:2008（PDF 1.7）

sponsored 版は、Adobe・Apryse・Foxit などスポンサー企業の拠出により PDF Association が無償公開している正規の ISO 文書です（無償ですが海賊版の類ではありません）。 ダウンロードした PDF を 1 つのディレクトリに置き、pdf-spec-mcp の設定にPDF_SPEC_DIR としてそのディレクトリを指定すれば、ファイル名パターンで自動判別されます。 （例: PDF32000_2008.pdf, ISO_32000-2_2020...pdf, ISO-14289-1-2014-sponsored.pdf など 17 文書）。

PDF_SPEC_DIR の設定 ​

jsonc
{
  "mcpServers": {
    "pdf-spec": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-spec-mcp@latest"],
      "env": { "PDF_SPEC_DIR": "/path/to/pdf-specs" },
    },
  },
}

WARNING

PDF_SPEC_DIR は必須です。このコーパスは PDF Agent Stack の規範知識の根拠そのもの — 条文を引用して言い切れる（T1）のは、手元に原文があるからです。ISO 19005 (PDF/A) と ETSI PAdES はコーパス外です — 何が引けないかは list_specs の coverage.gaps を確認してください。

/plugin とホストごとの書き場所 ​

/plugin install pdf-spec-mcp@shuji-bonji で入れた場合も、PDF_SPEC_DIR はホストの設定に絶対パスで書きます。プラグインの plugin.json は "PDF_SPEC_DIR": "${PDF_SPEC_DIR}" です。

ホスト${PDF_SPEC_DIR}書く場所
Claude Codesettings.json やシェルの値に展開するClaude の MCP / プラグイン設定の env
Grok Build 1.0.30プラグイン env では展開しない。リテラルのまま渡ると起動に失敗する（実測: REGISTRY_ERROR）~/.grok/config.toml の [mcp_servers.pdf-spec]

Grok Build の config.toml では、同じキーの ${VAR} は展開します。プラグイン経由と、config.toml 直書きでは扱いが違います。実測では config.toml に絶対パスを書いたあと、grok inspect の出典が config になり、list_specs が 17 文書を返しました。

toml
[mcp_servers.pdf-spec]
command = "npx"
args = ["-y", "@shuji-bonji/pdf-spec-mcp@latest"]
env = { PDF_SPEC_DIR = "/absolute/path/to/pdf-specs" }

PDF_WRITER_FONT も同じ差があります。Claude Code の settings.json に書いた値は、Grok Build が起動した pdf-writer プロセスには乗りません。Grok Build では [mcp_servers.pdf-writer] の env に絶対パスを書くか、呼び出しのたびに fontPath を付けます。未設定の日本語生成は FONT_REQUIRED です。

Step 3 — pdf-verify（veraPDF と信頼アンカー） ​

そのままでも動きます（内蔵 ~15 ルールの PDF/A サブセット + PDF/UA 12 ルール）。本格運用では veraPDF を導入してください。

  1. veraPDF をインストール
  2. PATH に通すか、PDF_VERIFY_VERAPDF に実行パスを指定
jsonc
{
  "mcpServers": {
    "pdf-verify": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-verify-mcp@latest"],
      "env": {
        "PDF_VERIFY_VERAPDF": "/usr/local/bin/verapdf",
        "PDF_VERIFY_TRUST_ANCHORS": "/path/to/trust-anchors",
      },
    },
  },
}

PDF_VERIFY_TRUST_ANCHORS（PEM/DER 証明書のディレクトリ）を設定すると署名者の証明書チェーンを評価できます。未設定の場合、署名の「valid」は暗号計算が合っていることだけを意味し、署名者が本人であることは意味しません（trust: not_evaluated）。

Step 4 — pdf-writer（日本語フォント） ​

標準フォント（Helvetica）は ASCII のみです。日本語を出すには埋め込み可能な単一フェイスフォント（.ttf / .otf、Variable font 不可）が必要です。Noto Sans JP の static 版を推奨します。

jsonc
{
  "mcpServers": {
    "pdf-writer": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/pdf-writer-mcp@latest"],
      "env": { "PDF_WRITER_FONT": "/path/to/NotoSansJP-Regular.otf" },
    },
  },
}

PDF_WRITER_FONT を設定すると各ツールの fontPath を省略できます。出力は必ず outputPath（絶対パス）を指定してください — 省略すると PDF 全体が base64 で返り、応答が溢れます。

Step 5 — スモークテスト ​

各サーバー 1 ツールずつ叩いて確認します。

サーバー確認プロンプト例
pdf-reader「この PDF のページ数とメタデータを見せて」
pdf-spec「ISO 32000-2 で注釈の /Contents は何を要求されている？」
pdf-verify「この PDF の完全性を検証して」
pdf-writer「"Hello 日本語" と書いた PDF を ~/tmp/test.pdf に作って」

Step 6 — Skill の導入 ​

pdf-trust（受入監査）・pdf-publish（納品）・pdf-read（読み取り）を Skill として追加すると、複数の MCP をどの順に呼び、判定をどう読み、どの形式のレポートにまとめるかが決まります。

  • pdf-trust は pdf-verify が必須。evaluate_policy を使うので最低 v0.7.0+、v0.29.0+ 推奨（v0.21.0 で verify_signatures / detect_pades_level の JSON 最上位が配列から辞書に変わり、v0.27.0〜v0.28.0 で失効と検証時刻の判定が変わり、v0.29.0 で JSON を文字数で切らなくなった）
  • pdf-publish は pdf-writer が必須。品質ゲート水準 conformance では pdf-verify も必須（scope が入った v0.20.0+ 推奨）
  • pdf-read は pdf-reader が必須（v0.15.1+ 推奨。v0.14.0 以上で動作）

環境変数一覧 ​

変数サーバー必須用途
PDF_SPEC_DIRpdf-spec必須仕様 PDF コーパスのディレクトリ
PDF_SPEC_CACHE_DIRpdf-spec任意索引のディスクキャッシュ（v0.5.0+。既定 ${XDG_CACHE_HOME:-~/.cache}/pdf-spec-mcp）。PDF_SPEC_CACHE=off で無効
PDF_READER_CONCURRENCYpdf-reader任意read_url のリモート取得の同時実行数。既定 4
PDF_READER_RENDER_TIMEOUT_MSpdf-reader任意render_page の 1 ページあたりの制限時間。既定 20,000 ms
PDF_VERIFY_VERAPDFpdf-verify任意veraPDF 実行パス（無ければ PATH 探索 → 内蔵ルール）
PDF_VERIFY_TRUST_ANCHORSpdf-verify任意信頼アンカー証明書のディレクトリ
PDF_WRITER_FONTpdf-writerCJK 出力に実質必須既定フォント（単一フェイス .ttf/.otf）

既定値まで含めた一覧は 環境変数リファレンス にあります。

MIT Licensed

© shuji-bonji