Pdf Reader Mcp Server

PDF Reader MCP サーバー

English | 日本語

PDF の内部構造の解読に特化した MCP（Model Context Protocol）サーバーです。

一般的な PDF MCP サーバーがテキスト抽出の薄いラッパーであるのに対し、このプロジェクトは PDF ドキュメントの内部構造の読み取りと分析に重点を置いています。pdf-spec-mcp と組み合わせることで、仕様に基づいた構造分析と検証ができます。

PDF ファミリー

サーバー	役割
pdf-spec-mcp	PDF 仕様に関する知識（ISO 32000、PDF/A、PDF/UA）
pdf-reader-mcp（このサーバー）	PDF の内部構造を読み取って調査 — PDF に「何が含まれているか」
pdf-verify-mcp	真正性の検証 —「本物かどうか」：暗号署名の検証、改ざん検出、PAdES レベル、PDF/A 検証、暗号化 PDF の復号

pdf-reader-mcp は署名の構造（inspect_signatures）を調査します。暗号署名の検証、信頼性／失効の評価、PDF/A 適合性の検証には、pdf-verify-mcp を使用してください。

機能

3 つの階層に整理された18 個のツール：

Tier 1：基本操作

ツール	説明
get_page_count	軽量なページ数の取得
get_metadata	メタデータ全体の抽出（タイトル、作成者、PDF バージョンなど）
read_text	Y 座標による読み上げ順でテキストを抽出します（タグなしの複数段 PDF では任意指定の split_columns: 2 | 3、日本語の帳票では compact_whitespace を使用できます）。/ActualText による置換を解決します（§14.9.4。構造要素のパスと Span マーク付きコンテンツのパスの両方に対応）。ページごとのテキスト抽出可能性（§9.10.1）を報告するため、空の結果を空白ページと誤認することはありません。タグ付き PDF の論理的な順序には、extract_structured_text を推奨します
search_text	前後のコンテキストを含む全文検索です。/ActualText を含め、read_text が返すものと同じテキストを検索するため、ヒットした内容は読者が目にするものと一致します（マーク付きコンテンツを整列できなかったページがある場合は note に示されます）
read_images	埋め込み画像 XObject をPNG または JPEG ファイルとして返します。MCP の画像コンテンツブロックとして返されるため、ビジョンモデルで読み取れます。max_width／max_height は面積平均で縮小します。応答にはバイト数の上限があり、除外された項目は名前で示されます
read_url	リモートの PDF を取得してテキストを抽出します。それ以外の処理は行いません。バイト列は保存されません。URL の PDF に対して他の 17 個のツールを使うには、先にダウンロードしてローカルパスを渡してください（「read_url and the read-only boundary」を参照）
render_page	PDFium-WASM（オプションの依存関係 @hyzyla/pdfium）を使ってページをPNG／JPEGにラスタライズします。テキスト抽出可能性が no_text_layer／not_extractable を示す場合の次の手段です。ベクターアートやフォームを含め、ページ全体を描画します
summarize	概要レポートをすばやく作成します（メタデータ＋テキスト＋画像数＋ドキュメントごとのテキスト抽出可能性）

Tier 2：構造の検査

ツール	説明
inspect_structure	オブジェクトツリーとカタログ辞書の分析
inspect_catalog	カタログから文書レベルのインベントリを取得します（ISO 32000-2 §7.7.2）：ブックマーク（/Outlines）、レイヤー（/OCProperties）、添付ファイル（/EmbeddedFiles、/AFRelationship を含む）、宣言された pdfaid / pdfuaid / W3C TDMRep（tdm:reservation）の値を含む XMP パケット、および文書を開いたときに実行されるもの（/OpenAction、/AA、文書レベルの JavaScript）。各項目には absent または unreadable のいずれかが示され、両者が混同されることはありません。宣言は記載どおりに報告され、検証はされません
inspect_tags	タグ付き PDF の構造ツリーを視覚化します
inspect_fonts	フォントのインベントリ（埋め込み／サブセット／種類の検出）
inspect_annotations	注釈の一覧（サブタイプ別に分類）
inspect_signatures	電子署名フィールドの構造分析
extract_structured_text	タグ付き PDF のテキストを論理的なコンテンツ順で抽出します（ISO 32000-2 §14.8.2.5）。各要素には構造タイプ（H1 / P / Table …）のラベルが付きます。/ActualText を解決し、/Alt とリストラベルを分離し、複数ページにまたがる要素も分割せずに保持します。include_bbox: true を指定すると、各要素が描画される位置が追加されます。ページごとに1つの矩形で、add_annotation が受け取る形式です
extract_tables	タグ付き PDF の <Table> サブツリーを Markdown の表に変換します（列を保持）。ページ区切りをまたぐ表は1つの表として扱われます（pages 配列）
locate_objects	オブジェクト番号からページと矩形を特定します。pdf-writer-mcp の add_annotation が受け取る座標形式です。pdf-verify-mcp の verify_integrity が示す「どのオブジェクトが変更されたか」を「その位置」につなげます。各位置には basis が記載されます。注釈自身の /Rect は正確な位置を示しますが、コンテンツストリームで示せるのは「ページ全体」だけです

Tier 3：比較

ツール	説明
compare_structure	2つの PDF 間の構造差分（プロパティとフォント）

validate_tagged と validate_metadata は削除されました（0.7.0 から非推奨）。このサーバーは PDF に含まれる内容を報告しますが、規格に対する合否は返しません。PDF/UA または PDF/A への適合性を検証するには、pdf-verify-mcp の validate_conformance（flavour: "pdfua-1"、"pdfa-*"、…）を使用してください。これらのツールが以前確認していた情報には、こちらの inspect_tags（構造ツリー）と get_metadata（メタデータフィールド）を使用してください。

read_url と読み取り専用の境界 (#25)

read_url が返すのはテキストのみです。これは暗黙の動作ではなく、明示された方針です。取得したバイト列は抽出後に破棄されます。保存すると読み取りツールがファイルシステムに書き込むことになり、このサーバーのすべてのツールは読み取り専用だからです（readOnlyHint: true — 全18個）。

URL にある PDF に対して search_text、inspect_structure、extract_tables、render_page などを実行するには、まずファイルをダウンロードし、ローカルパスを渡してください。ダウンロードには、呼び出し元の環境が備える任意の取得機能を使用できます。取得は意図的に呼び出し元の責任としています。エージェント環境には常にファイルをダウンロードする方法があり、ファイルも書き込む読み取りツールは、純粋な観察ツールではなくなるためです。

URL にある文書の内容を一度だけ確認する場合は、引き続き read_url が適切なツールです。

テキストを読み取れないページもレンダリング可能です（#23）

以前は、summarize が hasText: false を報告すると行き詰まり、このサーバーでドキュメントをこれ以上読み取る方法はありませんでした。render_page がその問題を解決します。ページを PNG または JPEG にラスタライズして MCP の画像コンテンツブロックとして返すため、ビジョンモデルでスキャン画像、図、記入済みフォーム、手書き文字を読み取れます。

render_page({ file_path: "/path/to/scan.pdf", pages: "1-3", format: "jpeg" })

pages は必須です。レンダリングはここで最も負荷の高い処理なので、500 ページのスキャン画像の「全ページ」を対象にするかどうかは、デフォルトではなくユーザーが決めるべきです。read_images と同じ 4 MB のレスポンス上限が適用され、省略された項目も名前とともに示されます。

レンダリングには WebAssembly にコンパイルされた PDFium（オプションの依存関係である @hyzyla/pdfium）を使用します。WASM バイナリはどのプラットフォームでも同じバイト列なので、公開パッケージは npx が実行される場所を問わず同じように動作します。これが、ここでネイティブアドオンを使用していない理由です。この依存関係がインストールされていない場合、render_page はインストール方法を案内し、他のすべてのツールは通常どおり動作します。PDFium（BSD-3-Clause）は、このサーバーがテキストの読み取りに使用する pdf.js とは異なるエンジンです。エンジン間のレンダリングの違いをファイル自体のせいにしないよう、ツールの説明にもそのことを記載しています。

これを採用する前に測定しました。pdf.js と @napi-rs/canvas（1.0.7 と 0.1.80）の組み合わせは、画像を描画するページでプロセス全体をセグフォルトさせます。まさにこのツールが必要とされるページです。また、standardFontDataUrl が設定されていない場合は、ページが空白でレンダリングされます。

画像が画像ファイルとして返されるようになりました（#22）

以前の read_images は imgData.data（pdfjs の デコード済みピクセル）を Base64 に変換していました。8×8 の RGB 画像は 192 バイトで、PNG や JPEG のシグネチャがどこにもなかったため、どのビューアーでも開けず、ビジョンモデルでも読み取れませんでした。そもそも画像を抽出する理由は、そこにあります。

画像はエンコードされるようになりました（デフォルトはロスレスの PNG。ファイルサイズを小さくしたい場合は quality を指定して format: "jpeg" を使用します）。MCP の image コンテンツブロックとして返され、メタデータはテキストブロックに併記されます。どちらのエンコーダーもこのプロジェクト内に実装されており、ネイティブアドオンもプラットフォームごとのバイナリも必要ありません。

エンコード済み画像データのレスポンスは 4 MB に制限されます。200 dpi の A4 スキャン画像は、それだけで約 11.6 MB のピクセルデータになるため、上限を超える画像は破棄せず、理由とともに名前を示します。

read_images({ file_path: "/path/to/scan.pdf", pages: "1", max_width: 1200, format: "jpeg" })

read_images が返すのは、ページに配置された画像 XObject です。ページそのものの画像ではないため、ベクター描画とテキストは対象外です。

テキスト抽出可能性は 2 状態ではなく 3 状態です（#21）

以前の read_text はテキストがあるか、何もないかを返していました。しかし「何もない」状態には、異なる 3 つの意味がありました。ISO 32000-2 §9.10.1 ではそれらを区別しているため、このサーバーも同様に扱います。テキストを返すすべてのツール — read_text、read_url、search_text、extract_structured_text、summarize — は、ページごとに次の状態を報告します。

状態	条件	次に行うこと
extracted	使用されているすべてのフォントに、§9.10.2 に基づいて Unicode に変換する方法がある	テキストを使用します
no_text_layer	テキスト表示演算子（Tj TJ ' "）がなく、画像コンテンツがある	ページはピクセル画像です。OCR またはレンダリング済み画像が必要ですが、このサーバーはどちらも行いません
not_extractable	使用されているフォントに /ToUnicode、標準エンコーディング、既知の CID コレクションがない	テキストが欠落しているか、正しくありません。レポートにフォント名と該当条項が示されます
not_observed	暗号化されているか、コンテンツストリームを読み取れなかった	何も測定されていません。「何もない」と同じではありません

not_extractable は フォントごと に報告されるため、読み取り可能なフォントと読み取り不能なフォントが混在するページでは、部分的な欠落であることが示されます。完全なページとして扱われることはありません。

観測は pdf.js の出力ではなく、ファイルから行われます。pdf.js は読み込むすべてのフォントに toUnicode マップを合成するため、フォントに /ToUnicode CMap があるかどうかを pdf.js に問い合わせると、辞書に存在しないフォントも「ある」と回答されるからです。

インストール

npx（推奨）

npx @shuji-bonji/pdf-reader-mcp@latest

Claude Desktop

claude_desktop_config.json に追加します。

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

@latest を使用してください。 npx -y <pkg> の -y フラグは、インストール時の 確認を省略するだけで、更新を確認するものではありません。@latest を指定しないと、npx は初回に キャッシュしたバージョンを実行し続けるため、新しいリリースが 適用されません。古いバージョンを使っていると思われる場合は、 rm -rf ~/.npm/_npx を実行して、クライアントを再起動してください。

Claude Code

claude mcp add pdf-reader-mcp -- npx -y @shuji-bonji/pdf-reader-mcp@latest

ソースから実行

git clone https://github.com/shuji-bonji/pdf-reader-mcp.git
cd pdf-reader-mcp
npm install
npm run build

使用例

ページ数の取得

get_page_count({ file_path: "/path/to/document.pdf" })
→ 42

テキストの検索

search_text({
  file_path: "/path/to/spec.pdf",
  query: "digital signature",
  pages: "1-20",
  max_results: 10
})
→ Found 5 matches (page 3, 7, 12, 15, 18)

要約

summarize({ file_path: "/path/to/document.pdf" })
→ | Pages | 42 |
  | PDF Version | 2.0 |
  | Tagged | Yes |
  | Signatures | No |
  | Images | 15 |

構造の比較

compare_structure({
  file_path_1: "/path/to/v1.pdf",
  file_path_2: "/path/to/v2.pdf"
})
→ | Page Count  | 10 | 12 | ❌ |
  | PDF Version | 1.7 | 2.0 | ❌ |
  | Tagged      | true | true | ✅ |

構造化テキストの抽出（タグ付き PDF、論理順）

extract_structured_text({ file_path: "/path/to/report.pdf", pages: "1-2" })
→ # Structured Text
  - **Tagged**: Yes / **Language**: en-US / **Elements**: 7

  ## Logical Content Order

  - **Document** (pages 1–2)
    - **H1** (page 1) — Quarterly Report
    - **P** (pages 1–2) — This paragraph begins on page one and continues on page two.
    - **Table** (page 1)
      | Item | Amount |
      |---|---|
      | Sales | 100 |
    - **Figure** (page 2) — *alt:* A bar chart of sales

これは「H1 のテキストは何か？」という質問に答えるものです。read_text（フラットな 座標順）では答えられません。順序は構造ツリーの深さ優先走査です （ISO 32000-2 §14.8.2.5）。/ActualText はグリフを置き換え（§14.9.4）、 /Alt は本文テキストに含まれず（§14.9.3）、リストラベルは 個別に報告され、ページをまたぐ要素も 1 つの要素のままです。アウトラインを取得するには roles: ["H1", "H2"] を使用します。タグなし PDF では 理由とともに isTagged: false が返され、座標から推測することはありません。

include_bbox：要素の描画位置

extract_structured_text({ file_path: "/doc.pdf", roles: ["P"], include_bbox: true })
→ - **P** (page 1) — Measured paragraph
    - *bbox* p1 `(50.0, 297.5, 161.4, 308.6)` — text-extent
  - **Figure** (page 1)
    - *bbox* p1 `(50.0, 150.0, 110.0, 190.0)` — layout-attribute-bbox

矩形は PDF のデフォルトユーザー空間（原点は左下、pt、正規化済み）で表されます。 これは pdf-writer-mcp の add_annotation が受け取る形式と同じなので、「この段落に注釈を付ける」際に座標変換は 必要ありません。/Rotate や移動された /CropBox によって位置が変わることもありません。

basis は主張の確かさを示しますが、2 つの値の性質は異なります。

basis	内容
layout-attribute-bbox	ファイルが宣言する /BBox（ISO 32000-2 Table 379）を、/A または /C + /ClassMap を通じて読み取ったものです。作成者による記述をそのまま報告します。テキストのないコンテンツの唯一の情報源です
text-extent	要素のテキストから測定したものです。ベースラインの原点にフォントのアセント／ディセントを加えて算出します。グリフの輪郭ではなく、行ボックスを示します。画像やベクターアートは含まれません

ページをまたぐ要素では、ページごとに1 つの矩形が返されます。結合すると、 実際には存在しないページにコンテンツがあるように見えてしまいます。矩形のない要素では、 サイズ 0 の矩形を返す代わりに、理由を boxNote に記載します。

宣言はそのまま報告され、相互検証されます。 ファイルには不正な値が記載されていることがあります。 Well-Tagged PDF 1.0 と Tagged PDF Best Practice Guide の両方で、表紙の Figure は /BBox [-32768 -32768 32767 32767] を宣言しています。これは矩形としてあるべき場所に int16 のセンチネル値が置かれたものです。また、PDF32000_2008 では、545 件の宣言のうち 131 件が ページ端を越えています。この出力はそのまま add_annotation に渡すことを想定しているため、 宣言をページボックス（§7.7.3.3）および要素自身のテキストと照合します。いずれかと矛盾する場合は boxNote に報告し、矩形は変更せずに返します。

独立した正解データとの比較では、Well-Tagged PDF (WTPDF) 1.0 の 166 個の Link 構造要素を、同じリンクに対して作成者が設定した 173 個の Link 注釈の /Rect 値と比較しました。中央値の IoU は 0.972 で、重なりのないものはありませんでした。

テーブルの抽出（タグ付き PDF）

extract_tables({ file_path: "/path/to/kaisei-tsutatsu.pdf", pages: "1" })
→ # Extracted Tables
  - **Tagged**: Yes / **Pages Scanned**: 1 / **Tables Found**: 1

  ## Table 1 — Page 1

  | 改正後 | 改正前 |
  | --- | --- |
  | …第２条第 16 項《定義》… | …第２条第 15 項《定義》… |

ページ区切りをまたぐテーブルは 1 つのテーブルとして報告されます。 pages は配列です（例：## Table 3 — Pages 5–7）。指定した pages 範囲に 少しでもかかるテーブルは、全体が返されます。セルのテキストには /ActualText による 置き換えが反映されます（#18 以降、read_text と search_text も同様です）。 タグなし PDF では空の結果が返され、以下の列を考慮した代替手段を推奨する note が含まれます。

タグなしの複数列 PDF を読み取る

read_text({ file_path: "/path/to/older-shinkyu.pdf", split_columns: 2 })
→ // Plain Y-sort would interleave columns:
//   "改正後セル1   改正前セル1\n 改正後セル2   改正前セル2..."
//
// With split_columns: 2 the left column is emitted first, then the right:
//   "改正後セル1\n改正後セル2\n…\n\n改正前セル1\n改正前セル2\n…"

タグなしの複数列 PDF では、split_columns: 2 | 3 を使用します。適切な <Table> マークアップがあるタグ付き PDF では、（上記の）extract_tables を推奨します。

空白の圧縮（日本語フォーム）

read_text({ file_path: "/path/to/form.pdf", compact_whitespace: true })
→ // Original PDF uses U+3000 fullwidth space as visual indentation:
//   " (   )   自   年   月   日   法   有 （   年   月   日）   有   有"
//
// With compact_whitespace: true:
//   "( ) 自 年 月 日 法 有 （ 年 月 日） 有 有"
//
// Empirically reduces character count by ~40% on form PDFs.

compact_whitespace は split_columns と独立しているため、両方を組み合わせて使用できます。

Tech Stack

• TypeScript + MCP TypeScript SDK
• pdfjs-dist (Mozilla) — text/image extraction, tag tree, annotations
• normativepdf + @normativepdf/recover — COS object access, read from files whose cross-reference table does not follow ISO 32000-2 §7.5
• Vitest — unit + E2E testing (483 tests)
• Biome — linting + formatting
• Zod — input validation

Testing

npm test              # Run all tests (unit + E2E: 483 tests)
npm run test:e2e      # E2E tests only (283 tests)
npm run test:watch    # Watch mode

Architecture

pdf-reader-mcp/
├── src/
│   ├── index.ts              # MCP Server entry point
│   ├── constants.ts          # Shared constants
│   ├── types.ts              # Type definitions
│   ├── tools/
│   │   ├── tier1/            # Basic tools (7)
│   │   ├── tier2/            # Structure inspection (6)
│   │   ├── tier3/            # Validation & analysis (3)
│   │   └── index.ts          # Tool registration
│   ├── services/
│   │   ├── pdfjs-service.ts        # pdfjs-dist wrapper (parallel page processing)
│   │   ├── recover-service.ts      # @normativepdf/recover — opening a document,
│   │   │                           #   and how far it could be read (DocumentScope)
│   │   ├── structure-service.ts    # Catalog, page tree, object statistics
│   │   ├── font-service.ts         # Fonts named in each page's /Resources
│   │   ├── signature-service.ts    # Signature fields of the AcroForm (structure only)
│   │   ├── content-stream-service.ts  # Marked-content operators, text-showing tally
│   │   ├── struct-tree-service.ts  # Logical structure (tags, structured text)
│   │   ├── validation-service.ts   # Validation & comparison logic
│   │   └── url-fetcher.ts          # URL fetching
│   ├── schemas/              # Zod validation schemas
│   └── utils/
│       ├── pdf-helpers.ts    # PDF utilities (page range parsing, file I/O)
│       ├── batch-processor.ts # Batch processing for large PDFs
│       ├── formatter.ts      # Output formatting
│       └── error-handler.ts  # Error handling
└── tests/
    ├── tier1/                # Unit tests
    └── e2e/                  # E2E tests (16 suites, 283 tests)

Error Contract (houki-hub family)

Since v0.6.0, this MCP returns structured errors that follow the houki-hub family error contract, sharing a unified code vocabulary across the family. Combined with houki-egov-mcp / houki-nta-mcp, an LLM or Skill layer can interpret errors with consistent logic.

• docs/ERROR-CODES.md — error code vocabulary (houki-research-skill)
• docs/ERROR-HANDLING.md — handling policy / next_actions templates

Implementation is independent — no dependency on houki-abbreviations or other family packages. The reference implementation is houki-egov-mcp/src/errors.ts; pdf-reader-mcp's local definition is in src/errors.ts.

On error, every tool returns isError: true and the JSON-stringified LawServiceError in content[0].text:

{
  "error": "The file does not appear to be a valid PDF.",
  "code": "INVALID_PDF",
  "hint": "ファイルが破損していないか確認してください。",
  "next_actions": [
    {
      "action": "inspect_structure",
      "reason": "PDF が壊れている可能性があります。Catalog / Pages 等の構造を確認してください"
    }
  ],
  "detail": { "cause": "Invalid PDF structure" }
}

Codes used by pdf-reader-mcp

code	用途
INVALID_ARGUMENT	パス・URL・ページ範囲などクライアント側引数の不正
DOC_NOT_FOUND	ファイル未存在 (ENOENT)
INVALID_PDF	PDF として不正・破損
ENCRYPTED_PDF	暗号化 PDF (現状未対応)
UNSUPPORTED_PDF_FEATURE	サポート外の PDF 機能
FILE_TOO_LARGE	50MB 上限超過 (pdf-reader 固有)
SOURCE_API_ERROR	URL fetch の HTTP エラー (4xx/5xx)
SOURCE_TIMEOUT	リモート取得タイムアウト
SOURCE_UNAVAILABLE	DNS / 接続失敗
INTERNAL_ERROR	パーミッション拒否を含むその他バグ

Migration note (v0.5.x → v0.6.0)

旧 v0.5.x までは content[0].text に Error: ...\n\nSuggestion: ... という人間可読文字列を入れていました。v0.6.0 では同じ場所に JSON 文字列 が入ります。LLM 側でテキスト解釈に依存していた場合は、JSON.parse(content[0].text) での解釈に切り替えてください。isError: true フラグで構造化エラーかどうかを判定できます。

Pairing with pdf-spec-mcp

pdf-spec-mcp provides PDF specification knowledge (ISO 32000-2, etc.). With both servers enabled, an LLM can perform specification-aware workflows:

1. summarize — get a PDF overview
2. inspect_tags — examine the tag structure
3. pdf-spec-mcp get_requirements — fetch PDF/UA requirements
4. pdf-verify-mcp validate_conformance — check conformance (flavour: "pdfua-1")
5. compare_structure — diff before/after fixes

License

MIT