# Reported issues for PDF Reader (PDF Agent Stack) Pod holds 16 of 16 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects. Back to [PDF Reader (PDF Agent Stack)](/mcp/pdf-reader-pdf-agent-stack). ## Most discussed ### [Bug]: `inspect_structure` / `inspect_fonts` が暗号化 PDF で失敗する ## 再現手順 1. 国税庁の PDF を取得 (`Linearized: Yes / Encrypted: Yes` の典型例) ``` curl -O https://www.nta.go.jp/law/tsutatsu/kihon/shohi/kaisei/0025004-026/pdf/01.pdf ``` 2. `inspect_structure` を呼ぶ。 ```json { "tool": "inspect_structure", "args": { "file_path": "/path/to/01.pdf" } } ``` 3. エラー: `Error: Expected instance of PDFDict, but got instance of undefined` 4. `inspect_fonts` でも同じエラー。 ## 期待動作 同じファイルに対して `read_text` / `get_metadata` / `inspect_tags` は **正常に動く** (Tagged PDF として 691… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/3) · 2026-05-06 · closed · 1 comment ### read_url が返すのはテキストだけで、URL 上の PDF に対して他の 15 ツールを使う経路が無い # read_url が返すのはテキストだけで、URL 上の PDF に対して他の 15 ツールを使う経路が無い ## 観測 `read_url` は「URL から取得 → テキスト抽出」を 1 回で完結させ、取得したバイト列を残さない。 そのため URL 上の PDF に対して、次のいずれも実行できない。 - `search_text` / `inspect_structure` / `inspect_signatures` / `inspect_tags` - `extract_structured_text` / `extract_tables` - `compare_structure` - 他 MCP（pdf-verify-mcp の `verify_signatures` など）への受け渡し 行政サイトの公開 PDF のように、URL からしか手に入らない文書に対して、 できることが「本文テキストを読む」だけに限られる。 ## 提案（案が 2 つあり、判断が要る） ### 案 A: `read_url` に `save_path` を足す… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/25) · 2026-08-22 · closed · 0 comments ### 大きな文書・テキストが取れない文書のとき、次にどのツールを呼ぶかを出力側から示していない # 大きな文書・テキストが取れない文書のとき、次にどのツールを呼ぶかを出力側から示していない ## 背景 各ツールの description は「このツールが何をするか」は十分に書いているが、 「今回の観測結果を踏まえて次に何を呼ぶか」は、ほぼ `read_text` の 「タグ付きなら extract_structured_text を推奨」だけになっている。 その結果、次の 2 つの状況で呼び出し側が高コストな経路に入りやすい。 1. **ページ数が多い文書** `read_text` は `pages` を省略すると全ページを返す。既定値が「全ページ」なので、 500 ページの PDF に対して最初の 1 回でコンテキストを使い切ることが起きる。 2. **テキストが取れない文書** `summarize` は `hasText: false` を返すが、そのとき何をすればよいかを示していない。 ## 提案（reader 側は誘導まで。手順の強制はしない） - `summarize` の出力に `next` 相当の note… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/24) · 2026-08-22 · closed · 0 comments ### ページのラスタライズ（render_page）が無く、テキストが取れない文書の次の一手が存在しない # ページのラスタライズ（render_page）が無く、テキストが取れない文書の次の一手が存在しない ## 背景 `summarize` は `hasText` を返すので、「この PDF からはテキストが取れない」ことは判定できる。 しかし判定した後に呼ぶツールが無い。 現行の `read_images` は**埋め込み画像 XObject の抽出**であって、ページの描画結果ではない。 スキャン PDF はページ全体が 1 個の画像 XObject になっていることが多いため結果的に 用が足りる場合があるが、次のケースは満たさない。 - ベクター描画の図・グラフ（XObject が無いので 0 件になる） - 文字と画像が混在したページ（版面の見た目が復元できない） - JPX / JBIG2 / 一部のマスク（`read_images` 側で「detected だが decode できない」と返る経路が実装済み） - 手書き・押印・レイアウト依存の帳票 ## 提案 tier1 に `render_page` を追加する。 ``` render_page({… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/23) · 2026-08-22 · closed · 0 comments ### read_images が返す base64 は生ピクセルで、視覚モデルが受け取れない／サイズが制御されていない # read_images が返す base64 は生ピクセルで、視覚モデルが受け取れない／サイズが制御されていない ## 観測 `src/services/pdfjs-service.ts` の `extractImages` は、pdf.js の `page.objs.get()` が返す `imgData.data` をそのまま `Buffer.from(...).toString('base64')` している。 `imgData.data` はデコード済みの**生ピクセル列**であって、PNG / JPEG などの画像ファイルではない。 `tests/fixtures/image-kinds.pdf` を pdfjs-dist 5.x で直接読んだ実測値: | name | kind | 寸法 | data のバイト数 | 先頭 8 バイト | |---|---|---|---|---| | img_p0_1 | 2 (RGB_24BPP) | 8×8 | 192 = 8×8×3 | `ff0000ff0300ff06` | | img_p0_2 | 3… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/22) · 2026-08-22 · closed · 0 comments ### read_text が「テキストが無い」と「抽出できない」を区別できない # [pdf-reader-mcp] read_text が「テキストが無い」と「抽出できない」を区別できない **対象リポジトリ: pdf-reader-mcp（stack ではない）/ 対象バージョン: v0.11.2** `read_text` は「抽出できたテキスト」を返すか「空」を返すかの **2 値**しか持たない。 ISO 32000-2 が明示的に区別している 3 つの状態が、呼び出し側から見て 1 つに潰れている。 これは pdf-verify-mcp の `/Prev 0` 問題（歩けない ≠ 変更なし → リンクを 3 値で返す）と **同じ形のバグ**であり、同じ直し方をする。 ## 現象（2026-08-13 実測・v0.11.2 / plugin 経由ローカル） ### 1. 空ページと「テキスト層が無いページ」が同じ出力になる ``` read_text(tests/fixtures/empty.pdf) → ## Page 1 （空行） ``` スキャン… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/21) · 2026-08-13 · closed · 0 comments ### 構造要素/オブジェクト → 描画座標（bbox）の解決を提供する（add_annotation の rect を family 内で決められない） ## ギャップ 「この段落／この構造要素に注釈を付けたい」を **描画座標（ページ + 矩形 bbox）へ落とす手段が family に無い**。 - writer の `add_annotation` は `rect`（座標）を必須で要求する。 - reader の `extract_structured_text` は構造要素とテキストは返すが、**bbox を返さない**。 - `inspect_structure` も構造は返すが座標は返さない。 結果として、`specs/12-use-cases.md` UC-7（署名エラー箇所を注釈で差し戻す）の**ステップ 4 が完遂できない** — 「どの要素か」は分かっても「どの座標に注釈を置くか」を family 内で解決できない。 ## 提案 reader が **構造要素/オブジェクト → 描画座標（ページ番号 + 矩形）** を返す。 - 既存ツール（`extract_structured_text` / `inspect_structure`）に bbox を追加するか、専用ツールを新設する。 - MCID ↔… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/20) · 2026-07-24 · closed · 0 comments ### read_text / search_text で /ActualText を解決する（#15 は明示で閉じた。同一サーバ内で本文の答えが割れる状態は残っている） ## これは何の続きか [#15](https://github.com/shuji-bonji/pdf-reader-mcp/issues/15) は **v0.9.0 で「明示」により閉じた** — `read_text` / `search_text` の description に生グリフである旨を書き、tagged 文書で `search_text` が 0 件だったときに `extract_structured_text` へ誘導する note を返すようにした。 pdfjs の `getTextContent` が `/ActualText` を textContent に出さないため、置換の解決自体は見送っている。 **明示は緩和であって解決ではない。** 本 Issue は解決本体を追う。 ## 症状（v0.9.0 公開版で再実測・2026-07-19） `tests/fixtures/structured.pdf` に対して: | ツール | 結果 | |---|---| | `read_text` | `"… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/18) · 2026-07-19 · closed · 0 comments ## Most recent ### formatStructuredTextMarkdown: pages を join('–') するため、文書全域の要素で数千個のページ番号が列挙される ## 症状 `(pages ${element.pages.join('–')})` のため、Document 要素（ISO PDF では全 1023 ページに跨る）が `(pages 1–2–3–…–1023)` と全列挙され、応答が数十 KB 膨張して truncate を圧迫する。 `pages="383-384"` のような絞り込みでも、範囲に触れる祖先要素（Document/Part）は丸ごと返る設計（それ自体は §14.8.2.5 NOTE 2 に忠実で正しい）なので必ず発生する。 ## 修正の方向 連続 run を `383–386`、非連続を `1–5, 9, 12–20` 形式に圧縮（**表示のみ**。JSON の `pages` 配列はそのまま）。副次効果として、構造木に載らないページの欠番（ISO PDF では p.1002 / p.1020）が圧縮表示だと一目で見える。 詳細: `Document-Note/mcps/PDFfamily/reviews/spec-reader-cross-check-2026-07-19.md` Issue 案 4 [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/17) · 2026-07-19 · closed · 0 comments ### formatStructuredTextMarkdown: 表セル内の "|" を GFM エスケープしない（extract_tables はする） ## 症状 `extract_structured_text`（markdown）の Table 行で、セル内の `|𝑦|` などがそのまま出力され GFM 表の列が壊れる。`extract_tables` は同じセルを `\|` にエスケープしており、同一リポジトリ内で挙動が割れている。 ## 再現 ISO 32000-2 EC3 PDF, `pages="384"` — Line 行の `−|𝑦| { exch pop abs neg }` で列がずれる。 ## 修正 `src/utils/formatter.ts` の `formatStructuredTextMarkdown` の rows 出力（`row.map((c) => c.text).join(' | ')`）に `extract_tables` と同じエスケープを適用。 詳細: `Document-Note/mcps/PDFfamily/reviews/spec-reader-cross-check-2026-07-19.md` Issue 案 3 [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/16) · 2026-07-19 · closed · 0 comments ### read_text / search_text が ActualText を解決せず、extract_structured_text と「文書の本文」が食い違う（§14.9.4） ## 症状 `tests/fixtures/structured.pdf`（グリフは `` Dif`cult ``、構造要素の `/ActualText` は `Difficult`）で: | ツール | 結果 | |---|---| | `extract_structured_text` | `"Difficult"` ✅ | | `read_text` | `` "Dif`cult" ``（生グリフ） | | `search_text("Difficult")` | **0 件** | **同一サーバ内で「この PDF に Difficult と書いてあるか」の答えがツールにより Yes/No に割れる。** ## 条文根拠 ISO 32000-2 §14.9.4: > The ActualText value **shall** be used as **a replacement, not a description**, for the content, providing text that is equivalent to what a person… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/15) · 2026-07-19 · closed · 0 comments ### extract_tables: 旧ページ単位走査のため、ページ跨ぎ Table 要素が「空 1 セルの幻テーブル」に分裂する（C-1 の残党。M-8 walker への載せ替え） ## 症状 ISO 32000-2 EC3 PDF pp.383–388 で `extract_tables` は **8 表**を返す。うち 3 表（383#2 / 384#2 / 385#2）は「ヘッダ 1 セル・中身空」の**幻テーブル**。実体は pp.383–386 を跨ぐ 1 つの Table StructElem が各ページで輪切りにされたもの。 同じ領域で `extract_structured_text`（M-8 walker）は正しく 4 表を返し、跨ぎ要素の `pages: [383,384,385,386]` も正確（pdf-lib による構造木の直接ダンプと完全一致）。 ## 原因 v0.8.0 の C-1 で `inspect_tags` は StructTreeRoot 走査に載せ替えたが、**`extract_tables` は旧ページ単位経路のまま**。`page.getStructTree()` のページ併合はページ跨ぎ要素を分裂させる — C-1 で「合成物は事実ではない」と判断したのと同じ failure mode。 ## 実害… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/14) · 2026-07-19 · closed · 0 comments ### pdf-reader-mcp の実装が PDF 仕様（ISO 32000 / 14289 等）通りかを、pdf-spec-mcp を典拠に監査 # pdf-reader-mcp 仕様適合レビュー（pdf-spec-mcp 照合） - 実施日: 2026-07-17 - 対象: pdf-reader-mcp v0.6.3（src/ 全15ツール + services 3ファイル） - 照合仕様: ISO 32000-2:2020 (EC3) / ISO 14289-1:2014 (PDF/UA-1) — いずれも pdf-spec-mcp で原文取得 - 手法: 静的照合（条項 ⇔ 実装）＋ 動的検証（pdf-writer-mcp 生成のタグ付きPDFで実ツール実行、正規表現の単体実行、PDFバイナリの展開確認） ## 総評 15ツール中、tier1（read_text / search_text / get_page_count / get_metadata / summarize / read_url / read_images）は座標ベースの抽出が主体で仕様逸脱はほぼなし（read_images を除く）。tier2/3 の仕様依存部分は概ね正しい設計だが、**High 2件・Medium 3件・Low… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/13) · 2026-07-17 · closed · 0 comments ### [Enhancement]: 連続する全角空白 (U+3000) の整形オプション ## 背景 日本語 PDF を `read_text` で抽出すると、視覚的なインデントを表現する U+3000 が **大量に連続** してテキストに残る。 実例 (jimu-unei 01.pdf): ``` ( ) 自 年 月 日 法 有 （ 年 月 日） 有 有 ``` ## 提案 - `read_text` のオプション: `compactWhitespace: true` - 連続する空白文字 (` `, `\t`, U+3000) を **1 個** に縮約 - ただし表組み構造のヒントとして 2 個以上は意味的に「区切り」と解釈する option `whitespaceAsSeparator: true` も検討 - デフォルトは `false` (後方互換) ## 影響度 LLM のトークン消費削減と reading 性向上。直接的な改善効果が大きい。 [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/7) · 2026-05-06 · closed · 0 comments ### [Feature]: 並列カラム (multi-column) PDF の column-aware 抽出 ## 背景 Issue shuji-bonji/pdf-reader-mcp#5 と関連するが、こちらは **TaggedPDF でない** PDF (古い PDF / スキャン PDF / Untagged) で並列カラムを取りたいケース。 新旧対応表 (PDF A: `b0025003-111.pdf`) は 1 ページ・タグ未調査だが、「改正後 / 改正前」が 2 カラム並列で配置されている。Tagged が無い場合でも X-coordinate のクラスタリングで 2 カラム検出は可能。 ## 提案 - `read_text` に `splitColumns: 2` または `autoDetectColumns: true` を追加 - カラム数を auto detect する場合は X 座標ヒストグラムで谷を見つけるアルゴリズム - 出力は左カラム → 右カラムの順で **改行で完全に区切る** ## 影響度 houki-nta-mcp / e-Gov-law / 各種白書 PDF など、日本の公文書全般で頻出のレイアウト。 [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/6) · 2026-05-06 · closed · 0 comments ### Tagged PDF の Table 構造を Markdown テーブルとして抽出するモードを追加 ## 背景 `read_text` は Y-coordinate ベースの reading order で抽出するため、横並び 2 カラム (新旧対照表) や帳票の表組みが **完全にプレーン化** され、左右の対応関係が消失する。 実例 (kaisei 01.pdf 1 ページ目を `read_text` で抽出した結果の抜粋): ``` ⑴ 法人番号を有する課税事業者 法人番号 （行政手続における特定の個 ⑴ 法人番号を有する課税事業者 法人番号 （行政手続における特定の個 人を識別するための番号の利用等に関する法律（平成 25 年法律第 27 人を識別するための番号の利用等に関する法律（平成 25 年法律第 27 号）第２条 第 16 項 《定義》に規定する「法人番号」をいう。 ）及びその 号）第２条 第 15 項 《定義》に規定する「法人番号」をいう。 ）及びその ``` 左 = 改正後 / 右 = 改正前 だが、テキストレベルで連結されているため、LLM が「16 項 が改正後 / 15 項… [Read the thread](https://github.com/shuji-bonji/pdf-reader-mcp/issues/5) · 2026-05-06 · closed · 0 comments The remaining reports are on [the project's issue tracker](https://github.com/shuji-bonji/pdf-reader-mcp/issues).