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).

Most discussed

[Bug]: `inspect_structure` / `inspect_fonts` が暗号化 PDF で失敗する

再現手順

国税庁の PDF を取得 (Linearized: Yes / Encrypted: Yes の典型例)

curl -O https://www.nta.go.jp/law/tsutatsu/kihon/shohi/kaisei/0025004-026/pdf/01.pdf

inspect_structure を呼ぶ。

{ "tool": "inspect_structure", "args": { "file_path": "/path/to/01.pdf" } }

エラー: Error: Expected instance of PDFDict, but got instance of undefined
inspect_fonts でも同じエラー。

期待動作

同じファイルに対して read_text / get_metadata / inspect_tags は 正常に動く (Tagged PDF として 691…

Read the thread · 2026-05-06 · closed · 1 comment

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 · 2026-08-22 · closed · 0 comments

大きな文書・テキストが取れない文書のとき、次にどのツールを呼ぶかを出力側から示していない

背景

各ツールの description は「このツールが何をするか」は十分に書いているが、「今回の観測結果を踏まえて次に何を呼ぶか」は、ほぼ read_text の「タグ付きなら extract_structured_text を推奨」だけになっている。

その結果、次の 2 つの状況で呼び出し側が高コストな経路に入りやすい。

ページ数が多い文書 read_text は pages を省略すると全ページを返す。既定値が「全ページ」なので、 500 ページの PDF に対して最初の 1 回でコンテキストを使い切ることが起きる。
テキストが取れない文書 summarize は hasText: false を返すが、そのとき何をすればよいかを示していない。

提案（reader 側は誘導まで。手順の強制はしない）

summarize の出力に next 相当の note…

Read the thread · 2026-08-22 · closed · 0 comments

ページのラスタライズ（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).

Reported issues for PDF Reader (PDF Agent Stack)

Most discussed

[Bug]: inspect_structure / inspect_fonts が暗号化 PDF で失敗する

再現手順

期待動作

read_url が返すのはテキストだけで、URL 上の PDF に対して他の 15 ツールを使う経路が無い

read_url が返すのはテキストだけで、URL 上の PDF に対して他の 15 ツールを使う経路が無い

観測

提案（案が 2 つあり、判断が要る）

案 A: read_url に save_path を足す…

大きな文書・テキストが取れない文書のとき、次にどのツールを呼ぶかを出力側から示していない

大きな文書・テキストが取れない文書のとき、次にどのツールを呼ぶかを出力側から示していない

背景

提案（reader 側は誘導まで。手順の強制はしない）

ページのラスタライズ（render_page）が無く、テキストが取れない文書の次の一手が存在しない

ページのラスタライズ（render_page）が無く、テキストが取れない文書の次の一手が存在しない

背景

提案

[Bug]: `inspect_structure` / `inspect_fonts` が暗号化 PDF で失敗する

案 A: `read_url` に `save_path` を足す…