@shuji-bonji/pdf-reader-mcp
Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.
Needs to start: nothing
Contacts while installing and starting: nothing
What it contacted
Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.
Starting it
npx -y @shuji-bonji/pdf-reader-mcp@0.23.0
Installing a package runs its code. Use a sandbox for anything you have not read.
What its tools tell an agent
In the tool descriptions, nothing that talks about the user, other tools or private files, or uses hidden characters.
5 tools with commands in capitals or very long text
- Very long description in
read_text:3000 characters or more
- Very long description in
render_page:2563 characters or more
- Very long description in
summarize:2533 characters or more
- Very long description in
inspect_catalog:2524 characters or more
- Very long description in
extract_structured_text:3000 characters or more
Common and usually harmless: it is how many makers stress how a tool should be used.
Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.
Tools
get_page_count file_path, response_format
Get the total number of pages in a PDF document.
This is a lightweight operation that only reads the PDF header, not the full content.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
markdown (default) — the page count as a bare number, e.g. "126". This is the number the
pages arguments of the other tools are checked against.
json — { pageCount, scope }. scope.declaredCount is the /Count the root page tree node
declares (ISO 32000-2 §7.7.3.2), scope.pagesReached is the number of pages reached by
walking the page tree, and scope.pageTree says whether that walk could be done. The two
numbers can differ in a file whose writer got /Count wrong; this server reports both and
does not judge which is right. A value that could not be read is null, not 0.
Examples:
- Quick check before deciding which pages to extract
- Validate a PDF file is readableget_metadata file_path, response_format
Extract metadata from a PDF document including title, author, creation date, page count, PDF version, and structural information.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Metadata including: title, author, subject, keywords, creator, producer, creation/modification dates, page count, PDF version, linearized/encrypted/tagged/signature flags, file size.
The eight document-level fields are read from both the document information dictionary (ISO 32000-2 §14.3.3) and the XMP metadata stream (§14.3.2: dc:title, dc:creator, dc:description, pdf:Keywords, xmp:CreatorTool, pdf:Producer, xmp:CreateDate, xmp:ModifyDate). When both hold a value, PDF 2.0 and later use the XMP value (§14.3.3 deprecates the dictionary for this in PDF 2.0) and earlier versions use the dictionary — except the two dates, which use the dictionary in every version: §14.3.3 does not deprecate CreationDate and ModDate, and §14.5 compares PieceInfo's LastModified with the dictionary's ModDate. Values are returned as written: dictionary dates look like "D:20260915100000+09'00'", XMP dates like "2026-09-15T10:00:00+09:00".
metadataSources names the source of each field ("info", "xmp" or null). metadataConflicts lists fields where the two sources differ (dates compared as instants) — this server does not say which one is right. xmpMetadata says whether the stream was read, is absent, or is present but could not be read; "could not be read" is not "absent".
Examples:
- Get document properties for cataloging
- Check if a PDF is tagged (accessibility)
- Verify PDF version compatibilityread_text file_path, pages, response_format, split_columns, compact_whitespace
Extract text content from a PDF document with Y-coordinate-based reading order preservation.
Text is extracted page by page, sorted by vertical position (top to bottom) then horizontal position (left to right), providing natural reading order.
`/ActualText` replacements (ISO 32000-2 §14.9.4) are resolved, on both of the paths that clause defines: the `/ActualText` of a structure element, and the one in a `Span` marked-content property list — the latter occurs in untagged documents too. So a word carried as ActualText (ligature substitutes, hyphenation fixes) reads here the way a person viewing the page sees it, not in its glyph form.
For **tagged** PDFs, `extract_structured_text` is still the better tool when order matters: it returns text in logical content order (ISO 32000-2 §14.8.2.5), which this tool does not — read_text sorts by coordinate. Tables in tagged PDFs are best read with `extract_tables`.
For **untagged** multi-column PDFs (e.g. older 新旧対照表 PDFs that lack a structure tree), pass `split_columns: 2` or `3` to bucket items by X-coordinate left-to-right.
For Japanese form-style PDFs (帳票・様式) where U+3000 fullwidth spaces are used as visual indentation, pass `compact_whitespace: true` to collapse runs of whitespace to a single ASCII space. Cuts 20–40% of token consumption without losing content.
Args:
- file_path (string): Absolute path to a local PDF file
- pages (string, optional): Page range to extract. Format: "1-5", "3", or "1,3,5-7". **Omitting it means ALL pages** — on a large document that consumes the whole response budget in one call. Past ~50 pages, search_text first and pass an explicit range here.
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
- split_columns (1 | 2 | 3, optional): Column-aware reordering for untagged multi-column PDFs. Default 1 = existing Y-sort.
- compact_whitespace (boolean, optional): Collapse whitespace runs (incl. U+3000) to one ASCII space and trim each line. Default false.
Every page also reports how much of its text could be converted to Unicode (ISO 32000-2 §9.10.1): `extracted`, `no_text_layer` (no text-showing operator, image content present — reading it needs OCR or a rendered page), `not_extractable` (a font used here offers no route to Unicode, so text is missing or wrong), or `not_observed` (encrypted or unreadable content stream). An empty result is therefore never by itself evidence that a page has no text.
Two separate readings produce that answer: taking the characters off the page, and observing whether those characters have a route to Unicode. Either can fail on its own, so the response says which of the two was done, under `scope`. When the characters were taken but the observation could not run, the text is still returned and `extractability` is left off the pages — absent is not `extracted`. When the characters could not be taken but the observation ran, `text` is `null` (not `""`, which would say the page has no text) and the per-pagesearch_text file_path, query, pages, context_chars, max_results, response_format
Search for text within a PDF document. Returns matching locations with surrounding context.
Case-insensitive search across all or specified pages. Each match includes the page number, the matched text, and configurable surrounding context.
The search runs over the same text `read_text` returns, so `/ActualText` replacements (ISO 32000-2 §14.9.4) match: a word carried as ActualText (ligature substitutes, hyphenation fixes) is found under the spelling a viewer shows, not under its glyph form. Rarely, a page's marked content cannot be aligned with the extracted text and the replacement is left unresolved; when that happens on a search with no hits, the result carries a `note` naming those pages.
Args:
- file_path (string): Absolute path to a local PDF file
- query (string): Text to search for (case-insensitive, 1-500 chars)
- pages (string, optional): Page range to search. Omit for all pages.
- context_chars (number): Characters of context before/after match (default: 80)
- max_results (number): Maximum matches to return (default: 20, max: 100)
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Search matches with page number, matched text, and surrounding context, plus `scope` — which of the two readings behind the answer were done: searching the characters on the page, and observing whether those characters have a route to Unicode (ISO 32000-2 §9.10.1). When the search itself could not run, `totalMatches` and `matches` are `null` rather than `0` and `[]`: "could not search" and "searched and found nothing" are different answers.
Examples:
- Search entire PDF: { file_path: "/path/to/doc.pdf", query: "digital signature" }
- Search specific pages: { file_path: "/path/to/doc.pdf", query: "error", pages: "1-10" }read_images file_path, pages, format, quality, max_width, max_height
Extract embedded images from a PDF document as PNG or JPEG files.
Each image is returned as an MCP image content block, so a vision-capable model can look at it directly. A text block lists the metadata for all of them (page, index, size in the file, size returned, colour space, encoded bytes).
These are the image XObjects the page draws, not a picture of the page. A page whose content is vector drawing, or whose text is what you want to see, is not covered by this tool.
Response size is bounded: at most 4 MB of encoded image data per call. Images beyond the budget are named in the text block with the reason and are not returned — nothing is dropped silently. A 200 dpi A4 scan is ~11.6 MB of pixels on its own, so pass `pages`, `max_width` or `max_height` when working with scans.
Args:
- file_path (string): Absolute path to a local PDF file
- pages (string, optional): Page range. Format: "1-5", "3", or "1,3,5-7". **Omitting it means ALL pages** — on an image-heavy document that exhausts the byte budget immediately. Name the pages you need.
- format ('png' | 'jpeg', optional): Output encoding. Default 'png' (lossless). 'jpeg' is smaller and composites alpha over white.
- quality (1-100, optional): JPEG quality. Ignored for PNG.
- max_width (number, optional): Downscale images wider than this (area average). Never enlarges.
- max_height (number, optional): Downscale images taller than this.
Returns:
A text block with the metadata table and any omissions, then one image content block per returned image.
Examples:
- Extract all images: { file_path: "/path/to/doc.pdf" }
- A scanned page, small enough to look at: { file_path: "/path/to/scan.pdf", pages: "1", max_width: 1200, format: "jpeg" }13 more tools
read_url url, pages, response_format, split_columns, compact_whitespace
Fetch a PDF from a URL and extract its text content. Text is ALL this tool returns — see the scope note below.
Downloads the PDF from the specified URL, then extracts text with Y-coordinate-based reading order. Supports HTTP and HTTPS. Maximum file size: 50MB. Timeout: 30 seconds.
**Scope (#25):** the fetched bytes are discarded after extraction; this tool deliberately does not save them. Every other tool of this server takes a `file_path`, so to use search_text, inspect_structure, extract_tables, render_page or anything else on a URL's PDF, download the file to local disk FIRST (with whatever fetch capability the calling environment has) and pass its path. This keeps every tool of this server read-only with respect to the file system — writing files is not a reader's job. read_url exists for the one-shot case: "what does the document at this URL say?"
Like `read_text`, accepts `split_columns: 2 | 3` for **untagged** multi-column PDFs and `compact_whitespace: true` to collapse U+3000 / ASCII whitespace runs. Tagged PDFs should use `extract_tables` instead.
Args:
- url (string): URL pointing to a PDF file (HTTP or HTTPS)
- pages (string, optional): Page range to extract. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
- split_columns (1 | 2 | 3, optional): Column-aware reordering. Default 1 = existing Y-sort.
- compact_whitespace (boolean, optional): Collapse whitespace runs (incl. U+3000) to one ASCII space. Default false.
Returns:
`{ scope, pages }`, the same shape as read_text: `pages` is the extracted text by page number, and `scope` says which of the two readings behind it were done — taking the characters off the page, and observing whether those characters have a route to Unicode (ISO 32000-2 §9.10.1). Either can fail on its own; only when neither could be done is this an error, and it then names both reasons.
Examples:
- Read remote PDF: { url: "https://example.com/document.pdf" }
- Untagged 2-column PDF: { url: "https://...", split_columns: 2 }
- Japanese form: { url: "https://...", compact_whitespace: true }render_page file_path, pages, dpi, max_width, format, quality
Rasterise pages of a PDF to PNG or JPEG images, returned as MCP image content blocks.
This is the tool for documents whose text cannot be read as text: pages `read_text` reports as `no_text_layer` or `not_extractable`, vector drawings, forms, handwriting, stamps. It draws the PAGE — everything on it — where `read_images` only extracts the image XObjects a page happens to embed.
Rendering uses PDFium compiled to WebAssembly (optional dependency `@hyzyla/pdfium`). Note this is a different engine from the pdf.js this server reads text with; where their behaviour on a damaged file differs, neither output is evidence about the other. If the dependency is not installed, this tool says so and every other tool works normally.
`pages` is required — rendering is the most expensive operation here, and "all pages" of a large scan should be a decision, not a default. The response carries at most 4 MB of encoded images; pages past the budget are named with the reason, not dropped.
Args:
- file_path (string): Absolute path to a local PDF file
- pages (string, REQUIRED): Page range: "1-3", "5", "1,3,5-7".
- dpi (36-600, optional): Density, default 150. 150 reads well; 300 for small print.
- max_width (number, optional): Pixel-width cap; wins over dpi when smaller.
- format ('png' | 'jpeg', optional): Default 'png'. 'jpeg' is usually right for scans.
- quality (1-100, optional): JPEG quality.
Returns:
A text block that starts with "## Scope of this reading" (the pages requested, the pages rendered, and each page not rendered with the reason — present even when every page was rendered), then per-page metadata (point size, pixel size, effective dpi, bytes) and any omissions, then one image content block per rendered page.
Rasterising a page can take unbounded time — a tiling pattern (ISO 32000-2 §8.7.3.1) whose `/XStep` or `/YStep` is a near-zero magnitude asks for an astronomical number of tiles, and the clause forbids only zero. Each page therefore gets 20 seconds (`PDF_READER_RENDER_TIMEOUT_MS` overrides it); the rendering runs off the main thread, so a page that does not finish is stopped and named in the omissions rather than taking the server down with it. The pages rendered before it are still returned, and the pages after it are reported separately as not attempted — "could not be rendered" and "never started" are different answers.
Examples:
- A scanned page: { file_path: "/path/to/scan.pdf", pages: "1", format: "jpeg" }
- A diagram at high detail: { file_path: "/path/to/doc.pdf", pages: "3", dpi: 300 }summarize file_path, response_format
Generate a quick overview report of a PDF document.
Combines metadata, text presence check, image count, and a text preview from the first page into a single summary. Useful as a first step before deciding which detailed tools to use.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
`hasText` is decided from page 1's preview and cannot say *why* text is absent. `textExtractability` answers that over every page (ISO 32000-2 §9.10.1): `extracted`, `no_text_layer` (image content, no text-showing operator — the page needs OCR or a rendered image), `not_extractable` (a font used offers no route to Unicode), or `not_observed` (encrypted or unreadable content stream). `unreadablePages` lists the pages that are not `extracted`, with the reason.
`declaredConformance` is what the XMP packet (ISO 32000-2 §14.3.2) declares — PDF/A (`pdfaid`), PDF/UA (`pdfuaid`) and the W3C TDMRep rights statement (`tdm`) — as written. A PDF/UA declaration is the author's claim that the structure tree is complete, which is the cue to read through it rather than infer reading order; it is not a verdict (that is pdf-verify-mcp validate_conformance). All-null blocks mean the catalog has no /Metadata; `null` means the packet could not be read (see `scope`).
The summary ends with a `next` list: tool suggestions derived from the observations themselves (hasText false → render_page; PDF/UA declared or tagged → extract_structured_text / extract_tables; large page count → search_text before read_text). Each line names the observation it follows from; nothing is enforced and no ordering is implied.
Returns:
Summary including: page count, PDF version, file size, tagged/encrypted/signature flags, text presence, per-document text extractability, the pages that are not fully extractable, image count, a text preview from page 1, and the `next` suggestions.
Five separate readings produce that summary — the document information, the text of page 1, the image count, the extractability observation, and the XMP declarations — and any of them can fail on its own. `scope` says which were done. A field whose reading did not happen is `null`, never `0`, `false` or `""`: "not read" and "read and found nothing" are different answers, and `next` stays silent about any premise that was not observed.
Examples:
- Quick overview: { file_path: "/path/to/doc.pdf" }
- Machine-readable: { file_path: "/path/to/doc.pdf", response_format: "json" }inspect_structure file_path, response_format
Examine PDF internal object structure including catalog entries, page tree, and object statistics.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Catalog entries (keys and COS types), page tree info (page count, MediaBox samples), object statistics, and encryption status.
Object statistics report three separate counts:
- byType: the COS type of each indirect object (ISO 32000-2 §7.3) — one of
dict, stream, array, name, string, integer, real, boolean, null, ref
- byDocType: the /Type of each dictionary (Catalog, Pages, Page, Font, ObjStm, XRef, ...)
- unreadable: objects the cross-reference table names but that could not be read.
This is counted apart from totalObjects: 0 means "every object was read", not "nothing was checked".
Examples:
- Examine document catalog for structural features
- Count PDF objects and streams
- Check page dimensions across the documentinspect_catalog file_path, max_outline_items, include_xmp, response_format
List the document-level components hanging off the catalog dictionary (ISO 32000-2 §7.7.2, Table 29) — the parts of a PDF that are not page content and that page-oriented readers drop: bookmarks, layers, attachments, the XMP packet, and the actions that run when the document is opened.
Args:
- file_path (string): Absolute path to a local PDF file
- max_outline_items (integer, 1-500, default 50): how many bookmark items to list (count and depth cover the whole tree)
- include_xmp (boolean, default false): also return the XMP packet text (capped at 64 KiB)
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns, per entry:
- outlines (/Outlines, §12.3.3): item count, depth, and the first items with title and target page
- optionalContent (/OCProperties, §8.11.4): every layer's /Name, and the default configuration's BaseState / ON / OFF counts
- embeddedFiles (/Names → /EmbeddedFiles, §7.7.4 / §7.11.4): file name, MIME type, size, /AFRelationship, description
- associatedFiles (/AF, §14.13): count at document level
- names: counts of the /Dests and /JavaScript name trees (document-level ECMAScript runs on open, §12.6.4.17)
- metadata (/Metadata, §14.3.2): packet size, namespaces present, and the DECLARED values of pdfaid:*, pdfuaid:part and the W3C TDMRep tdm:reservation / tdm:policy
- openAction (/OpenAction) and additionalActions (/AA, Table 200): action type (/S), target page or file or URI, whether /JS is present, length of the /Next chain
- collection (/Collection, §12.3.5): whether the document is a portfolio
Each entry distinguishes { status: "absent" } (the catalog has no such key — an observed fact) from { status: "unreadable", reason } (the key is there but its value could not be reached). An encrypted document whose key cannot be derived reports every entry as unreadable, never as absent.
This tool reports what is written. A pdfuaid:part declaration is a claim about the structure tree, not a verdict on it (that is pdf-verify-mcp validate_conformance); tdm:reservation is the rights holder's statement, and whether to honour it is the caller's decision; an action with /JS is reported, not judged.
Examples:
- Find out whether a document carries attachments, layers or bookmarks before deciding how to read it
- Read the XMP declarations (PDF/A, PDF/UA, TDMRep) that get_metadata, which reads the Info dictionary, does not see
- See what a document will execute when opened (/OpenAction, /AA, document-level JavaScript)inspect_tags file_path, response_format
Analyze the Tagged PDF structure tree for accessibility assessment.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Whether the PDF is tagged, the structure tree hierarchy with roles, max nesting depth, total element count, and role distribution (e.g., Document, P, H1, Table, Figure).
For an encrypted PDF whose key cannot be derived from the empty user password, isTagged and the counts are null and a note says why: the structure tree could not be read, which is not the same answer as "not tagged".
Examples:
- Check if a PDF is tagged for accessibility (PDF/UA)
- Inspect the tag hierarchy and role distribution
- Assess document structure qualityinspect_fonts file_path, response_format
List all fonts used in a PDF document with their properties.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Font name, type (TrueType, Type1, CIDFont, etc.), encoding, embedded/subset status, and pages where each font is used.
Examples:
- Check if all fonts are embedded (required for PDF/A, PDF/X)
- Identify font types and encodings
- Find which pages use specific fontsinspect_annotations file_path, pages, response_format
Extract and categorize all annotations in a PDF document.
Args:
- file_path (string): Absolute path to a local PDF file
- pages (string, optional): Page range. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Total annotation count, breakdown by subtype (Link, Widget, Highlight, Text, etc.) and by page, flags for links/forms/markup presence, and individual annotation details.
Examples:
- Check for form fields (Widget annotations)
- Find all links in a document
- Inventory markup annotations (highlights, comments)inspect_signatures file_path, response_format
Examine digital signature fields in a PDF document.
Args:
- file_path (string): Absolute path to a local PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Total signature field count, signed/unsigned breakdown, and details for each field (signer name, reason, location, signing time, filter/subFilter).
Note: This tool inspects signature field structure only. Cryptographic signature verification is not performed.
Examples:
- Check if a PDF has been digitally signed
- Inspect signer information and signing dates
- Verify signature field structureextract_tables file_path, pages, response_format
Extract every `<Table>` subtree from a Tagged PDF as a structured row/cell list,
optionally rendered as Markdown tables.
How it works: walks the document's StructTreeRoot depth-first (the same walker
as `extract_structured_text` / `inspect_tags`) and pulls cell text for each
`<TR>` → `<TH>/<TD>`, then collapses kerning whitespace (e.g. "消 費 税 法" →
"消費税法"). This sidesteps reading-order extraction's failure mode on
multi-column tables (typical of 新旧対照表 PDFs).
A Table that continues across a page break is ONE table (ISO 32000-2 §14.8.2.5
NOTE 2) — `pages` is an array, and a table touching the requested page range is
returned whole. Cell text honours `/ActualText` replacements (§14.9.4).
Args:
- file_path (string): Absolute path to a local PDF file
- pages (string, optional): Page range. Format: "1-5", "3", or "1,3,5-7". Omit for all pages.
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Markdown — `# Extracted Tables` summary block followed by one
`## Table N — Page(s) …` section per table with a GFM table.
JSON — `{ isTagged, tables: [{ pages, index, headerRows, bodyRows, footerRows }],
totalTables, pagesScanned, note? }`. `index` is the table's 1-based position
in logical content order, document-wide.
Limitations:
- Untagged PDFs return an empty result and a `note`.
- An encrypted PDF whose key cannot be derived from the empty user password returns
`isTagged`, `tables` and `totalTables` as `null` with a `note`: the structure
tree could not be read, which is not the same answer as "not tagged".
- colspan/rowspan are not honoured (cells are listed in source order).
- Nested tables are not emitted separately (their text appears in the outer cell).
Examples:
- Pull 新旧対照表 from a kaisei tsutatsu PDF for diffing
- Convert 帳票 (form template) tables into structured dataextract_structured_text file_path, pages, roles, include_bbox, response_format
Extract a tagged PDF's text in logical content order, with each piece labelled by its structure type.
This answers "what is the text of the H1?" — which read_text (flat, coordinate order),
inspect_tags (structure, no text) and extract_tables (text, tables only) each cannot.
Args:
- file_path (string): Absolute path to a local PDF file
- pages (string, optional): Page range ("1-5", "3", "1,3,5-7"). Omit for all pages.
An element that touches the range is returned whole, even if it continues outside it.
- roles (string[], optional): Structure types to include, e.g. ["H1","H2"] for an outline
- include_bbox (boolean): Also report where each element is drawn (default: false)
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
isTagged, the document language, and a flat list of elements in logical content order.
Each element has: role, depth (nesting; top level is 0), text, pages, and optionally
alt / label / rows / boxes / boxNote.
`scope` says which of the two readings behind that answer were done — reading the structure tree, and observing whether the characters under it have a route to Unicode (ISO 32000-2 §9.10.1). When the structure tree could not be read, `isTagged` and `elements` are `null` rather than `false` and `[]`: "not read" and "read and found no tags" are different answers.
The list is flat with a depth field rather than nested — a depth-first pre-order plus
depth encodes the tree exactly, so nothing is lost. Table is the exception and carries
rows, because a table is two-dimensional and depth cannot express "row 2, column 3".
Key properties:
- Order is a depth-first traversal of the document's structure tree, which is how
ISO 32000-2 §14.8.2.5 defines logical content order.
- An element that spans pages stays ONE element (pages is an array). A paragraph
split across a page break is returned as one paragraph, not two.
- ActualText replaces the glyphs when present (§14.9.4: "a replacement, not a
description"). Alt is reported separately in alt and never as text — it describes
content that has no text (§14.9.3), so it must not leak into the body.
- Lbl (a list bullet or number) is reported in label, not mixed into text.
- A list nested in an item is returned as its own L and LI elements right after the
parent item, never folded into the item's text. Inside the item's LBody (ISO 32000-1
Table 336) it sits one level below the LI, since LBody itself is not returned; as a
direct child of the parent L (ISO 32000-2 §14.8.4.8.2) it sits at the LI's level.
Either way the item's pages and boxes cover its own label and body only, like its text;
the nested L's own pages and boxes cover the nested items.
- Artifacts (page numbers, running heads) are excluded: §14.8.2.5 NOTE 3 puts them
outside the logical content order.
With include_bbox (answers "where is this paragraph?", so an annotation can be placed on it):
Each element gailocate_objects file_path, object_numbers, response_format
Report where the given objects sit on the page.
Bridges "which object" to "which coordinates": pdf-verify-mcp's verify_integrity names the objects an incremental update changed, and pdf-writer-mcp's add_annotation wants a page number and a rectangle. The rectangle is returned in PDF user space (origin bottom-left, pt, x1 < x2 and y1 < y2 — ISO 32000-1 §7.9.5 normalised form), which is exactly what add_annotation takes.
Args:
- file_path (string): Absolute path to a local PDF file
- object_numbers (number[]): Object numbers to locate, e.g. [25, 27]
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Per object: whether it exists, its /Type and /Subtype, and the places it occupies, each with the basis the coordinates rest on:
- annotation-rect — the object's own /Rect. Exact.
- page-box — the object is a page; the rectangle is its crop/media box.
- page-content-stream — the object draws the page; the rectangle is the WHOLE page, not the part that changed.
- page-resource — a font, image or colour space used by the page. No rectangle exists for it.
Limits (observations, not judgements):
- Narrowing a content stream to the paragraph that moved needs a content-stream walk with graphics state; this tool does not do it and says so rather than inventing a rectangle.
- An object that does not exist (freed by a later revision) is returned with found: false — not as "no coordinates".
- In an encrypted document, coordinates and types are still reliable (numbers and names are not encrypted, ISO 32000-1 §7.6.2) but field names are reported as null instead of mojibake.
Examples:
- Turn verify_integrity's "obj 27 was added after signing" into a page and rectangle
- Find which page a changed form field widget is on before annotating itcompare_structure file_path_1, file_path_2, response_format
Compare the internal structures of two PDF documents and identify differences.
Args:
- file_path_1 (string): Absolute path to the first PDF file
- file_path_2 (string): Absolute path to the second PDF file
- response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns:
Structural comparison including: property-by-property diff (page count, PDF version, encryption, tagged status, object counts, page dimensions, file size, catalog entries, signatures), font comparison (fonts unique to each file and shared fonts), and a summary.
The comparison needs both files, so an unreadable file is an error — but the error names which of the two could not be read, and says that the other one was fine.
Examples:
- Compare two versions of the same document
- Verify structural consistency across PDF exports
- Identify differences in PDF generation pipelinesDescriptions are the package's own words, cut at 3,000 characters. Treat them as data.
Install facts
| License | MIT |
|---|---|
| Needs | node >=20 |
| Source | github.com/shuji-bonji/pdf-reader-mcp |
| Install scripts | None declared by it or anything installed with it. |
| Tarball | sha512-2+58oo26fRthLrkNrRYIi0qbX/EZ5Jj4ndg5SGmJn6k5pI7u1Xsy29tuLzaJStgC6EMWuvSXVGDhabuSin2I6w== |
Check this report yourself
This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.
Report as JSONExact text and tokenHow to verify it
Show it on your README
[](https://bragproof.smaverk.com/r/%40shuji-bonji/pdf-reader-mcp)
New version out? Ask for a fresh report.