Sylphx PDF Reader MCP

https://github.com/sylphxai/pdf-reader-mcp
Admin
A production-ready Model Context Protocol server that enables AI agents with enterprise-grade PDF...
Tokens:55,504
Snippets:760
Trust Score:8.7
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone and Initialize Project

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/CONTRIBUTING.md

Commands to clone the repository and install dependencies using Bun.

```bash
git clone https://github.com/SylphxAI/pdf-reader-mcp.git
cd pdf-reader-mcp
bun install
bun run build
```

--------------------------------

### Install globally via npm

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/installation.md

Install the package globally for persistent access.

```bash
npm install -g @sylphx/citra
# or pin
npm install -g @sylphx/citra
```

--------------------------------

### Run local development commands

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/AGENTS.md

Standard commands for installing dependencies, running type checks, tests, and building the project.

```bash
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run check
bun run build
bun run docs:build
bun test test/project-control.test.ts
bun run check:ts-production-absence
```

--------------------------------

### Install PDF Reader MCP

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/stop-pdf-hallucinations.md

Global installation command for the PDF Reader MCP package.

```bash
npm install -g @sylphx/citra
```

--------------------------------

### Install Citra via npm

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/BRAND_PUBLISH.md

Commands to install the Citra package globally or execute it directly using npx.

```bash
npm i -g @sylphx/citra
# or
npx @sylphx/citra
```

--------------------------------

### Install historical TypeScript baseline

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/migration.md

Use this command to install the immutable 3.0.14 version for comparison or recovery purposes.

```bash
npm install -g @sylphx/pdf-reader-mcp@3.0.14
```

--------------------------------

### Execute publish gate verification scripts

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/temporary-rust-migration-fences.md

Run these commands to verify candidate admission and registry installation proofs during the migration process.

```bash
bun scripts/check-verified-candidate-admission.ts
bun run check:pure-rust-matrix
bun run check:registry-install-proof -- --registry --version=<ver>
```

--------------------------------

### Run Project Verification Commands

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/PROJECT.md

Execute the standard verification suite to ensure project integrity, including dependency installation, testing, and production checks.

```bash
bun install --frozen-lockfile
bun test test/project-control.test.ts
bun run typecheck
bun run check
bun run check:ts-production-absence
bun run package:smoke
```

--------------------------------

### Invoke Citra MCP

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/LOCAL_FIRST_FRONTIER.md

Starts the MCP on stdio using the latest version of the Citra package.

```bash
npx -y @sylphx/citra
```

--------------------------------

### Get structured document elements

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Retrieve stable page references and coordinates using semantic hints.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-3"
  }],
  "include_elements": true,
  "include_semantic_hints": true,
  "include_full_text": false,
  "include_metadata": true,
  "include_page_count": true,
  "include_images": false
}
```

--------------------------------

### Example URL-based Corpus Manifest

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Defines a benchmark case using a remote URL, requiring a SHA256 checksum for content verification.

```json
{
  "cases": [
    {
      "id": "public-report",
      "url": "https://example.org/public-report.pdf",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "document_archetype": "public benchmark report",
      "capability_tags": ["public_report", "selectable_text"],
      "expected": {
        "min_pages": 1,
        "min_text_chars": 500
      }
    }
  ]
}
```

--------------------------------

### Example Corpus Manifest JSON

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Defines the structure for benchmark cases, including document paths, archetypes, and expected assertion criteria.

```json
{
  "cases": [
    {
      "id": "agency-scan",
      "path": "./fixtures/agency-scan.pdf",
      "pages": [1],
      "document_archetype": "external scanned form",
      "capability_tags": ["external_scan", "ocr_text_layer"],
      "expected": {
        "min_pages": 1,
        "min_ocr_words": 20,
        "required_document_map_layers": ["ocr_text_layer", "page_geometry"]
      },
      "read_pdf_options": {
        "include_ocr_text_layer": true,
        "include_document_map": true
      }
    }
  ]
}
```

--------------------------------

### Get Layout Diagnostics

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Retrieves deterministic layout diagnostics to assess the reliability of reading order and document structure.

```APIDOC
## Get Layout Diagnostics

### Description
Use `include_layout_diagnostics` to determine if the local reading order is reliable before indexing or summarizing a page. It uses existing item geometry without additional OCR or vision dependencies.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_layout_diagnostics** (boolean) - Required - Set to true to enable diagnostics.
- **include_chunks** (boolean) - Optional - Include document chunks.
- **include_semantic_hints** (boolean) - Optional - Include semantic hints.
- **include_full_text** (boolean) - Optional - Include full text extraction.

### Response
- **profile** (object) - Layout profile data.
- **reading_order** (array) - Detected visual reading sequence.
- **confidence** (number) - Reliability score.
- **column_count** (integer) - Number of detected columns.
- **positioned_item_ratio** (number) - Ratio of positioned items.
- **signals** (object) - Diagnostic signals.
- **warnings** (array) - Optional diagnostic warnings.
```

--------------------------------

### Get An Agent Document Map

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use the document map configuration to retrieve a unified structure for PDF analysis. Enable include_document_map to consolidate various document outputs into a single navigable object.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_document_map": true,
  "include_full_text": false,
  "include_metadata": true,
  "include_page_count": true
}
```

--------------------------------

### Get a Text Layer

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Provides detailed text layer information including runs, lines, words, and character references.

```APIDOC
## Get a Text Layer

### Description
Use `include_text_layer` when an agent needs run, line, word, and character references with page-level ranges, estimated bounding boxes, and metadata coverage counts.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_text_layer** (boolean) - Required - Set to true to enable text layer extraction.

### Request Example
{
  "sources": [{"path": "/path/to/document.pdf", "pages": "1-5"}],
  "include_text_layer": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Get Citation-Ready Chunks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Retrieves document chunks with source references, supporting semantic hints and table extraction.

```APIDOC
## Get Citation-Ready Chunks

### Description
Use `include_chunks` when an agent needs retrieval chunks with source references. Enable `include_semantic_hints` to split chunks on deterministic heading boundaries, and enable `include_tables` when table chunks should be available.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_chunks** (boolean) - Required - Set to true to enable chunk extraction.
- **include_semantic_hints** (boolean) - Optional - Enable heading-based splitting.
- **include_tables** (boolean) - Optional - Enable table extraction.

### Request Example
{
  "sources": [{"path": "/path/to/document.pdf", "pages": "1-5"}],
  "include_chunks": true,
  "include_semantic_hints": true,
  "include_tables": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Get Document Signals

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Enable document-signal flags to retrieve structural PDF information beyond basic page text.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_outline": true,
  "include_annotations": true,
  "include_page_labels": true,
  "include_page_geometry": true,
  "include_permissions": true,
  "include_structure_tree": true,
  "include_form_fields": true,
  "include_attachments": true
}
```

--------------------------------

### read_pdf Request Structure

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-ocr-provider.md

Example JSON payload for the read_pdf command, specifying source files and enabling OCR and document map features.

```json
{
  "sources": [{ "path": "scan.pdf", "pages": "1-3" }],
  "include_document_map": true,
  "include_ocr_text_layer": true
}
```

--------------------------------

### Get Layout Diagnostics

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use include_layout_diagnostics to assess the reliability of local reading order before processing. This method is deterministic and relies on existing item geometry.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_layout_diagnostics": true,
  "include_chunks": true,
  "include_semantic_hints": true,
  "include_full_text": false
}
```

--------------------------------

### Request Citation-Ready Chunks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use include_chunks to get retrieval chunks with source references. Enable semantic hints for heading boundaries and tables for table extraction.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_chunks": true,
  "include_semantic_hints": true,
  "include_tables": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Get a Trust Report

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Generates a risk summary report for the document, including safety, layout, and table quality signals.

```APIDOC
## Get a Trust Report

### Description
Use `include_trust_report` when an agent needs one risk summary before using PDF content as instructions, evidence, or retrieval context.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_trust_report** (boolean) - Required - Set to true to enable trust report generation.
- **trust_report_redaction** (string) - Optional - Redaction level (e.g., "strict" or "off").

### Request Example
{
  "sources": [{"path": "/path/to/document.pdf", "pages": "1-5"}],
  "include_trust_report": true,
  "trust_report_redaction": "strict",
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Get Markdown Content

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use the include_markdown flag to retrieve clean, page-aware markdown context suitable for RAG or summarization tasks.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_markdown": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true,
  "include_images": false
}
```

--------------------------------

### Get An Agent Document Map

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Retrieves a navigable structure for a PDF document, linking pages to various elements like chunks, safety findings, and layout diagnostics.

```APIDOC
## Get An Agent Document Map

### Description
Use `include_document_map` when an agent needs one navigable structure for the PDF instead of separate page, element, text-layer, chunk, layout, and safety outputs.

### Request Body
- **sources** (array) - Required - List of document sources with path and page ranges.
- **include_document_map** (boolean) - Required - Whether to include the document map.
- **include_full_text** (boolean) - Optional - Whether to include full text.
- **include_metadata** (boolean) - Optional - Whether to include metadata.
- **include_page_count** (boolean) - Optional - Whether to include page count.

### Request Example
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_document_map": true,
  "include_full_text": false,
  "include_metadata": true,
  "include_page_count": true
}
```

--------------------------------

### Initialize Citra SDK

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/skills/citra/SKILL.md

Import the Citra SDK, create an instance, and read a PDF file from a specified path.

```ts
import { Citra } from '@sylphx/citra/sdk'
const citra = Citra.create()
const result = await citra.read({ path: '/abs/doc.pdf' })
```

--------------------------------

### Run Installed-Provider Benchmarks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-sota-final-bar.md

Executes benchmarks for optional OCR engines and visual-region providers, reporting quality metrics and capability coverage.

```bash
bun run benchmark:providers
```

--------------------------------

### Run local benchmark

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Executes the benchmark suite against the sample PDF.

```bash
bun run benchmark
```

--------------------------------

### Get Document Signals

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Retrieves structural metadata and document-level signals from a PDF.

```APIDOC
## Get Document Signals

### Description
Use document-signal flags to retrieve PDF structure information beyond simple page text.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_outline** (boolean) - Optional - Include document outline.
- **include_annotations** (boolean) - Optional - Include annotations.
- **include_page_labels** (boolean) - Optional - Include page labels.
- **include_page_geometry** (boolean) - Optional - Include page geometry data.
- **include_permissions** (boolean) - Optional - Include document permissions.
- **include_structure_tree** (boolean) - Optional - Include document structure tree.
- **include_form_fields** (boolean) - Optional - Include form field data.
- **include_attachments** (boolean) - Optional - Include file attachments.
```

--------------------------------

### Access CLI Help

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/README.md

Display the help menu for the CLI tool.

```bash
npx -y @sylphx/citra --help
```

--------------------------------

### Get an Accessibility Report

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Evaluates the document's accessibility features and tagging structure.

```APIDOC
## Get an Accessibility Report

### Description
Use `include_accessibility_report` when an agent needs to understand whether the PDF exposes reliable tagged structure for navigation, headings, figures, links, forms, and assisted reading workflows.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_accessibility_report** (boolean) - Required - Set to true to enable accessibility report generation.

### Request Example
{
  "sources": [{"path": "/path/to/document.pdf", "pages": "1-5"}],
  "include_accessibility_report": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Run Full Release Benchmark Suite

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-sota-final-bar.md

Runs all benchmarks with strict provider requirements and writes release artifacts to the specified directory.

```bash
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts MCP_PDF_PROVIDER_BENCHMARK_REQUIRED=true bun run benchmark:all
```

--------------------------------

### Get HTML

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Extracts escaped page-aware HTML from a PDF for preview or downstream conversion.

```APIDOC
## Get HTML

### Description
Use `include_html` when a workflow needs escaped page-aware HTML for preview, export, or downstream conversion.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_html** (boolean) - Required - Set to true to enable HTML extraction.
- **include_full_text** (boolean) - Optional - Include full text.
- **include_metadata** (boolean) - Optional - Include metadata.
- **include_page_count** (boolean) - Optional - Include page count.

### Request Example
{
  "sources": [{"path": "/path/to/document.pdf", "pages": "1-5"}],
  "include_html": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Execute Performance Benchmarking Suite

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/performance/same-host-ab-contract.md

Commands to build the Rust binary and execute the A/B performance suite, including registry-based testing and admissibility checks.

```bash
bun run build:rust
# local binary diagnostic
bun run perf:same-host-ab-suite

# formal-ish registry binary path
MCP_PDF_PERF_RUST_FROM_REGISTRY=1 bun run perf:same-host-ab-suite
bun run perf:same-host-ab-suite -- --require-admissible
```

--------------------------------

### Reproduce Footprint Measurements

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/performance/installed-footprint-comparison.md

Commands to view package metadata and execute the footprint measurement script for specific versions.

```bash
# metadata
npm view @sylphx/pdf-reader-mcp@3.0.14 dist.unpackedSize dependencies
npm view @sylphx/pdf-reader-mcp@4.0.2 dist.unpackedSize dependencies

# clean install footprint (example)
bun scripts/perf/measure-installed-footprint.ts --version=4.0.2
bun scripts/perf/measure-installed-footprint.ts --version=3.0.14
```

--------------------------------

### Run Benchmark Scripts

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/benchmark.md

Commands to execute performance benchmarks, full benchmark profiles, and the SOTA release gate.

```bash
# Performance benchmark only
bun run benchmark

# All benchmark profiles
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:all

# Provider-certified release artifacts
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts MCP_PDF_PROVIDER_BENCHMARK_REQUIRED=true bun run benchmark:all
bun run benchmark:release-artifacts

# Run the SOTA release gate
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:release-gate
```

--------------------------------

### Build and execute Rust benchmarks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/why-rust.md

Commands to compile the Rust project and run the benchmark suite with specified iterations and warmup cycles.

```bash
bun run build:rust
bun run benchmark:pure-rust -- --iterations 20 --warmup 3 \
  --output benchmark-artifacts/pdf_pure_rust_benchmark.json
```

--------------------------------

### Get a Document AST

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Retrieves a semantic tree representation of the document including sections, paragraphs, tables, and images.

```APIDOC
## Get a Document AST

### Description
Use `include_document_ast` when an agent needs a semantic tree instead of flat page text. The AST includes nodes for page, section, paragraph, list item, caption, header, footer, table, and image.

### Request Body
- **sources** (array) - Required - List of document paths and page ranges.
- **include_document_ast** (boolean) - Required - Set to true to enable AST extraction.

### Request Example
{
  "sources": [{"path": "/path/to/document.pdf", "pages": "1-5"}],
  "include_document_ast": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Initialize read_pdf with smart sampling

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use this to sample a document when the structure is unknown.

```json
{
  "sources": [{ "path": "doc.pdf" }]
}
```

--------------------------------

### Development and Maintenance Commands

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/CONTRIBUTING.md

Commonly used commands for linting, testing, building, and benchmarking the project.

```bash
bun run check          # Lint and format check (Biome)
bun run check:fix      # Auto-fix lint and format issues
bun run typecheck      # TypeScript type checking
bun test               # Run tests
bun run test:cov       # Run tests with coverage
bun run build          # Build the package
bun run package:smoke  # Verify package tarball
bun run docs:build     # Build docs site
bun run benchmark      # Run performance benchmark
```

--------------------------------

### Request Trust Report

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use include_trust_report to get a risk summary for the document. Redaction can be set to strict for sensitive data.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_trust_report": true,
  "trust_report_redaction": "strict",
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Run Quality Benchmark

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Executes the deterministic quality benchmark suite. The command outputs a report and exits with a non-zero status if quality gates are not met.

```bash
bun run benchmark:quality
```

--------------------------------

### Inspect a PDF document

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use the inspect operation to get a route profile without performing a full document read.

```json
{
  "operation": "inspect",
  "sources": [{ "path": "/path/to/document.pdf" }],
  "sample_pages": 5,
  "include_metadata": true
}
```

--------------------------------

### Run Benchmark with External Manifest

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Executes the benchmark using a custom manifest file to include licensed or domain-specific PDF fixtures.

```bash
bun scripts/benchmark-pdf-corpus.ts --corpus-manifest ./corpus-manifest.json
```

--------------------------------

### Run Public Provider Accuracy Manifest

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Verifies public PDF downloads and region crops without requiring local OCR or vision models.

```bash
MCP_PDF_PROVIDER_MANIFEST_ALLOW_DOWNLOADS=true \
  bun run benchmark:provider-manifest-crops \
  --provider-manifest ./corpus/public-provider-accuracy.json \
  --provider-manifest-cache-dir ./.cache/pdf-corpus
```

--------------------------------

### Run Benchmark with Remote URL Manifest

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Executes the benchmark with network download permissions enabled, specifying a cache directory for verified PDF assets.

```bash
MCP_PDF_CORPUS_ALLOW_DOWNLOADS=true \
  bun scripts/benchmark-pdf-corpus.ts \
  --corpus-manifest ./corpus/public-url-corpus.json \
  --corpus-cache-dir ./.cache/pdf-corpus
```

--------------------------------

### Quality Gate and Benchmark Execution Commands

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

Run these commands to perform comprehensive quality checks, type validation, testing, and benchmark generation prior to package publication.

```bash
bun run check
bun run typecheck
bun run test:cov
bun run build
bun run package:smoke
bun run docs:build
bun run benchmark:quality
bun run benchmark:providers
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:all
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:release-gate
bun run release:preflight
```

--------------------------------

### Execute Release Gate Benchmark

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-sota-final-bar.md

Runs the release gate benchmark against artifacts to ensure all quality and coverage requirements are met.

```bash
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:release-gate
```

--------------------------------

### Configure PDF Reader MCP for Desktop Clients

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/examples/README.md

Standard JSON configuration for MCP-compatible desktop environments.

```json
{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}
```

--------------------------------

### Configure MCP for Desktop Clients

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/README.md

Add the MCP server to your Claude Desktop, Cursor, or VS Code configuration.

```json
{
  "mcpServers": {
    "citra": {
      "command": "npx",
      "args": ["-y", "@sylphx/citra"]
    }
  }
}
```

--------------------------------

### Execute verification command sequence

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/whole-product-independent-review-package.md

Run these commands in order to verify the project state against the current main branch and ensure all contracts and smoke tests pass.

```bash
git fetch origin main
git rev-parse origin/main   # record as candidate SHA
bun run check:pure-rust-matrix
bun run check:semantic-contracts
bun run check:agent-task-corpus
bun run test:agent-task-eval
bun run check:pure-rust-exports
bun run smoke:native-launcher
bun run smoke:native-package-resolve
```

--------------------------------

### Run Provider-Scoring Benchmark

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Scores provider performance against public PDF crops using a configured visual-region provider.

```bash
MCP_PDF_PROVIDER_MANIFEST_ALLOW_DOWNLOADS=true \
  MCP_PDF_REGION_ANALYSIS_PRESET=ollama \
  MCP_PDF_REGION_ANALYSIS_MODEL=llava \
  bun run benchmark:provider-manifest \
  --provider-manifest ./corpus/public-provider-accuracy.json \
  --provider-manifest-cache-dir ./.cache/pdf-corpus
```

--------------------------------

### Read a PDF with default settings

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use read_pdf to process an unfamiliar document with automatic sampling and extraction.

```json
{
  "sources": [{ "path": "/path/to/document.pdf" }]
}
```

--------------------------------

### Enable Layout Diagnostics

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use include_layout_diagnostics to retrieve page profiles and reading-order confidence.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_layout_diagnostics": true,
  "include_chunks": true,
  "include_full_text": false
}
```

--------------------------------

### Configure PDF Source

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/stop-pdf-hallucinations.md

JSON configuration for specifying the path to a PDF file for the agent to process.

```json
{
  "sources": [{ "path": "/absolute/path/to/your.pdf" }]
}
```

--------------------------------

### Run adobe-cmap-parser tests

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/vendor/adobe-cmap-parser/README.md

Execute the test suite for the vendored crate from the workspace root.

```bash
cargo test -p adobe-cmap-parser
```

--------------------------------

### Run Strict Provider Benchmark

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Forces the benchmark to fail if optional providers are missing, suitable for release environments.

```bash
MCP_PDF_PROVIDER_BENCHMARK_REQUIRED=true bun run benchmark:providers
```

--------------------------------

### Run directly or via HTTP

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/installation.md

Execute the server directly or specify the HTTP transport mode.

```bash
npx @sylphx/citra
# or after global install
citra
```

```bash
MCP_TRANSPORT=http citra
```

--------------------------------

### Enable Semantic Hints

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use include_semantic_hints to add deterministic structure labels to text elements.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_semantic_hints": true,
  "include_full_text": false
}
```

--------------------------------

### Generate benchmark artifacts

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Runs all benchmarks and outputs JSON artifacts to the specified directory.

```bash
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:all
```

```bash
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts MCP_PDF_PROVIDER_BENCHMARK_REQUIRED=true bun run benchmark:all
```

--------------------------------

### Enable Text Layer Evidence

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use include_text_layer to retrieve granular run, line, and word references.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_text_layer": true,
  "include_full_text": false
}
```

--------------------------------

### Execute core admission check

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/whole-product-independent-review-package-4.0.0-sole-rust.md

Runs the core admission verification script using the specified Rust binary path.

```bash
PDF_READER_MCP_RUST_BIN=target/release/pdf-reader-mcp-server bun run check:sole-rust-core
```

--------------------------------

### Execute production capability parity checks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/why-rust.md

Commands to build the Rust project and run contract tests to ensure parity with existing production capabilities.

```bash
bun run build:rust
bun test test/production/capabilityParity.contract.test.ts --timeout=600000
bun run check:production-contract
```

--------------------------------

### Configure Citra for various clients

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/README.md

Commands and configuration snippets for integrating Citra with different AI agent environments.

```bash
npx -y @sylphx/citra
```

```bash
claude mcp add citra -- npx -y @sylphx/citra
```

```json
"command": "npx", "args": ["-y", "@sylphx/citra"]
```

```bash
npm i -g @sylphx/citra
```

```bash
citra
```

--------------------------------

### Run PDF Reader MCP with HTTP Transport

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/examples/README.md

Execute the server with HTTP transport enabled for remote connectivity.

```bash
MCP_TRANSPORT=http MCP_API_KEY=your-secret npx @sylphx/pdf-reader-mcp
```

--------------------------------

### Enable document map and visual enrichments

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use the document map for structured navigation and visual enrichments for region-specific analysis.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_document_map": true,
  "include_visual_enrichments": true,
  "max_visual_enrichments": 8,
  "include_full_text": false
}
```

--------------------------------

### Run local agent-task tests

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/agent-task-corpus/README.md

Executes the local test suite including extraction, search, and visual enrichment tasks.

```bash
bun run check:agent-task-corpus
bun run test:agent-task-smoke
bun run test:agent-task-eval
```

--------------------------------

### Persist Benchmark Artifacts

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

Use this command to generate and persist benchmark JSON artifacts specifically for release review purposes.

```bash
MCP_PDF_BENCHMARK_OUTPUT_DIR=./benchmark-artifacts bun run benchmark:release-artifacts
```

--------------------------------

### Run public URL agent-task tests

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/agent-task-corpus/README.md

Executes public URL evaluation tasks, including calibration and cached comparison modes.

```bash
# download + measure TS baseline + compare pure-Rust
bun run test:agent-task-public-eval:calibrate

# compare pure-Rust using cached PDFs + committed public baseline
bun run test:agent-task-public-eval
```

--------------------------------

### Enable Source Chunks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use include_chunks for citation-ready content with element IDs and bounding boxes.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_chunks": true,
  "include_semantic_hints": true,
  "include_full_text": false
}
```

--------------------------------

### Configure PDF Reader MCP for VS Code

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/examples/README.md

Configuration format for the VS Code Copilot Chat MCP settings file.

```json
{
  "servers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}
```

--------------------------------

### Enable Markdown Output

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use include_markdown to receive page-aware Markdown content in the response.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_markdown": true,
  "include_full_text": false
}
```

--------------------------------

### Batch multiple PDF sources

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Process multiple files in a single request to improve throughput.

```json
{
  "sources": [
    { "path": "doc1.pdf" },
    { "path": "doc2.pdf" },
    { "path": "doc3.pdf" }
  ],
  "include_full_text": true,
  "include_metadata": false,
  "include_page_count": false,
  "include_images": false
}
```

--------------------------------

### Enable Document Signals

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use these flags to retrieve structural metadata like outlines and geometry without full text extraction.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_outline": true,
  "include_structure_tree": true,
  "include_page_geometry": true,
  "include_full_text": false
}
```

--------------------------------

### Configure Provider Status and Readiness

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-agent-native-pdf-inspection.md

Status object detailing the configuration and health check state for OCR and region analysis providers.

```json
"provider_status": {
          "ocr_pages": {
            "readiness": "ready",
            "provider": "command",
            "command_configured": true,
            "health": "not_checked",
            "health_check": "not_checked",
            "preset": "tesseract"
          },
          "analyze_regions": {
            "readiness": "not_configured",
            "provider": "command",
            "command_configured": false,
            "health": "not_checked",
            "health_check": "not_checked",
            "warnings": [
              "Set MCP_PDF_REGION_ANALYSIS_COMMAND, MCP_PDF_REGION_ANALYSIS_HTTP_URL, or MCP_PDF_REGION_ANALYSIS_PRESET=ollama/openai-compatible/lmstudio/llamacpp to enable analyze_regions."
            ]
          }
        }
```

--------------------------------

### Add PDF Reader MCP to Claude Code

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/examples/README.md

Use the CLI command to register the MCP server with Claude Code.

```bash
claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp
```

--------------------------------

### Run Corpus Benchmark

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Executes the standard corpus benchmark suite for end-to-end agent validation.

```bash
bun run benchmark:corpus
```

--------------------------------

### Request Text Layer

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use include_text_layer for detailed character, word, and line references with bounding boxes and metadata.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_text_layer": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Query PDF with Match Limits

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/stop-pdf-hallucinations.md

JSON configuration for performing a targeted search within a PDF document.

```json
{
  "sources": [{ "path": "/absolute/path/to/your.pdf" }],
  "query": "termination clause",
  "max_matches_per_source": 5
}
```

--------------------------------

### Render Page Evidence

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use the render_page operation to retrieve original page images for visual inspection or OCR routing. The tool defaults to the first page and enforces a 16MP render budget.

```json
{
  "operation": "render_page",
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-2"
  }],
  "scale": 2,
  "max_pages": 2
}
```

--------------------------------

### Run Package Smoke Test

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-sota-final-bar.md

Verifies the packed package tarball against expected contracts and runtime artifacts.

```bash
bun run package:smoke
```

--------------------------------

### Enable Structured Element Metadata

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Use include_elements to retrieve page-level element metadata for stable IDs and provenance.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_elements": true,
  "include_full_text": false
}
```

--------------------------------

### Configure PDF Reader MCP for Warp Terminal

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/examples/README.md

TOML configuration for integrating the MCP server into Warp Terminal.

```toml
[mcp.pdf-reader]
command = "npx"
args = ["@sylphx/pdf-reader-mcp"]
```

--------------------------------

### Add PDF Reader to Claude

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/stop-pdf-hallucinations.md

Command to register the PDF reader tool with the Claude MCP configuration.

```bash
claude mcp add pdf-reader -- npx @sylphx/citra
```

--------------------------------

### Render pages with explicit bounds

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Limit rendering scale and pixel budget to manage resource consumption during page evidence retrieval.

```json
{
  "operation": "render_page",
  "sources": [{ "path": "doc.pdf", "pages": "1-2" }],
  "scale": 2,
  "max_pages": 2,
  "max_pixels_per_page": 16000000
}
```

--------------------------------

### Enable layout diagnostics in read_pdf

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-layout-diagnostics.md

Include the include_layout_diagnostics flag in the read_pdf request to receive structural metadata.

```json
{
  "sources": [{ "path": "report.pdf", "pages": "1-5" }],
  "include_layout_diagnostics": true
}
```

--------------------------------

### Run Project Control Validation

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/project-control-gate.md

Execute the project control test suite and verify git diff integrity for control-plane-only changes.

```bash
bun test test/project-control.test.ts
git diff --check
```

--------------------------------

### read_pdf

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Profiles a PDF and returns an Agent Document Twin containing markdown, tables, and source evidence.

```APIDOC
## read_pdf

### Description
Profiles the PDF, chooses an extraction route, and returns the Agent Document Twin.

### Parameters
- **sources** (array) - Required - List of objects containing 'path' or 'url'.
- **auto_detail** (string) - Optional - Controls output depth (e.g., 'full').

### Request Example
{
  "sources": [{ "path": "/path/to/document.pdf" }],
  "auto_detail": "full"
}
```

--------------------------------

### read_pdf

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

Profiles a PDF, selects extraction options, and returns an Agent Document Twin.

```APIDOC
## read_pdf

### Description
Profiles the PDF, chooses high-value extraction options, and returns the Agent Document Twin in one response.

### Parameters
- **include_* options** (optional) - Specific extraction options to override the smart default behavior.
```

--------------------------------

### Read a PDF with full detail

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Control the output depth of the read_pdf tool using the auto_detail parameter.

```json
{
  "sources": [{ "path": "/path/to/document.pdf" }],
  "auto_detail": "full"
}
```

--------------------------------

### Minimal PDF Reader Tool Call

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/README.md

The basic JSON structure required to invoke the PDF reader tool with a file path.

```json
{
  "sources": [{ "path": "/absolute/path/to/report.pdf" }]
}
```

--------------------------------

### Configure PDF Extraction Workflows

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/product-proof.md

JSON configuration objects for specific document processing tasks including financial reports, research papers, and scanned documents.

```json
{
  "sources": [{ "path": "/absolute/path/to/10-k.pdf" }],
  "include_tables": true,
  "include_markdown": true,
  "pages": [14]
}
```

```json
{
  "sources": [{ "path": "/absolute/path/to/paper.pdf" }],
  "include_full_text": true,
  "include_document_map": true
}
```

```json
{
  "sources": [{ "path": "/absolute/path/to/scan.pdf" }],
  "include_ocr_text_layer": true,
  "include_tables": true
}
```

--------------------------------

### Validate semantic contracts and agent tasks

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/semantic-contracts/README.md

Execute these commands to run semantic contract checks, corpus validation, and agent task smoke and evaluation tests.

```bash
bun run check:semantic-contracts
bun run check:agent-task-corpus
bun run test:agent-task-smoke
bun run test:agent-task-eval
```

--------------------------------

### Retrieve specific pages

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Extract content from specific pages or defined page ranges.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": [1, 3, 5]
  }],
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": false,
  "include_images": false
}
```

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5, 10, 15-20"
  }],
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": false,
  "include_images": false
}
```

--------------------------------

### Calibrate agent-task baseline

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/capability-first-admission-contract.md

Executes the calibration process to generate the agent-task corpus baseline for the TypeScript v3.0.14 implementation.

```bash
bun run test:agent-task-eval:calibrate
```

--------------------------------

### Benchmark PDF Corpus

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-sota-final-bar.md

Adds operator-supplied PDFs to the corpus artifact for benchmarking using a manifest file.

```bash
bun scripts/benchmark-pdf-corpus.ts --corpus-manifest ./corpus-manifest.json
```

```bash
MCP_PDF_CORPUS_MANIFEST=./corpus-manifest.json bun run benchmark:corpus
```

--------------------------------

### Request Document AST

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use include_document_ast to retrieve a semantic tree structure including sections, lists, and tables.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_document_ast": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### Define architecture boundary

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-14-pdf-intelligence-vnext.md

Conceptual flow of the MCP tool handler from orchestration through to rendering.

```text
MCP tool handler
  -> application/use case orchestration
    -> source loading and security policy
    -> engine adapter
    -> normalized document model
    -> renderers
```

--------------------------------

### Configure Safety Findings in Request

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/performance/index.md

Enable safety findings to scan for risk signals without requiring full text extraction in the response.

```json
{
  "sources": [{ "path": "doc.pdf", "pages": "1-5" }],
  "include_safety_findings": true,
  "include_full_text": false
}
```

--------------------------------

### Define PDF Source Object

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

Specify the location of a PDF file using either a local file path or a remote URL.

```json
{
  "path": "/absolute/path/to/file.pdf"
}
```

```json
{
  "url": "https://example.com/file.pdf"
}
```

--------------------------------

### Verify Claims with PDF Evidence

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/evidence-first.md

Executes focused operations like inspection, rendering, cropping, or OCR to verify specific claims.

```text
Agent → pdf_evidence(operation, sources) → inspect, render, crop, OCR, or analyze
```

--------------------------------

### Add to Claude Code

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/installation.md

Command to register the MCP server with Claude Code.

```bash
claude mcp add citra -- npx @sylphx/citra
```

--------------------------------

### read_pdf

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

The primary entrypoint for reading PDF documents. It supports automatic inspection or manual control over extraction options.

```APIDOC
## read_pdf

### Description
Reads a PDF document from a provided source. Can perform automatic inspection or precise manual extraction based on provided options.

### Parameters
#### Request Body
- **sources** (array) - Required - Array of objects containing either a "path" (string) or "url" (string).
- **auto** (boolean) - Optional - Defaults to true when no explicit include_* options are supplied. Inspects each source and chooses high-value extraction options.
- **auto_detail** (string) - Optional - "fast", "balanced", or "full". Sets automatic extraction depth.
- **sample_pages** (number) - Optional - Maximum pages sampled during automatic inspection.
- **pages** (array/string) - Optional - Page selection (number array or range string).
- **include_full_text** (boolean) - Optional - Include concatenated text.
- **include_metadata** (boolean) - Optional - Include PDF metadata.
- **include_page_count** (boolean) - Optional - Include total page count.
- **include_images** (boolean) - Optional - Include embedded image metadata and base64 payloads.
- **include_tables** (boolean) - Optional - Include selectable-text and OCR-derived tables.
- **include_elements** (boolean) - Optional - Include structured text, image, and table elements.
- **include_markdown** (boolean) - Optional - Include markdown rendering.
- **include_html** (boolean) - Optional - Include HTML rendering.
- **include_chunks** (boolean) - Optional - Include citation-ready chunks.
- **include_text_layer** (boolean) - Optional - Include direction-aware run, line, word, and character evidence.
- **include_layout_diagnostics** (boolean) - Optional - Include reading-order and page-layout confidence.
- **include_document_map** (boolean) - Optional - Include page, element, chunk, OCR, and routing map.
- **include_document_ast** (boolean) - Optional - Include semantic AST for document nodes.
- **include_safety_findings** (boolean) - Optional - Include prompt-injection and visual-spoofing findings.
- **include_trust_report** (boolean) - Optional - Include consolidated risk report.
- **trust_report_redaction** (string) - Optional - "standard", "strict", or "off". Redaction policy for trust-report.
- **include_accessibility_report** (boolean) - Optional - Include accessibility report.
- **include_ocr_text_layer** (boolean) - Optional - Include OCR page text and PDF-coordinate word boxes.
- **include_visual_enrichments** (boolean) - Optional - Include bbox-grounded visual-region candidates.
```

--------------------------------

### Search PDF for Specific Queries

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/evidence-first.md

Performs a targeted lookup to return source-backed matches with provenance before reading the full document.

```text
Agent → search_pdf(sources, query) → literal matches with page/box provenance
```

--------------------------------

### Define analyze_regions request structure

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-region-analysis-provider.md

Use this JSON structure to define the PDF source path, specific regions to analyze, and processing parameters like scale and language.

```json
{
  "sources": [{
    "path": "documents/report.pdf",
    "regions": [{
      "id": "chart-1",
      "page": 2,
      "bounding_box": { "left": 72, "bottom": 240, "right": 540, "top": 520 },
      "padding": 8
    }]
  }],
  "scale": 2,
  "max_regions": 10,
  "languages": ["eng"]
}
```

--------------------------------

### Define PDF engine and renderer interfaces

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-14-pdf-intelligence-vnext.md

TypeScript interfaces for modular PDF engine adapters and document renderers.

```ts
interface PdfEngine {
  readonly name: string;
  parse(source: LoadedPdfSource, options: EngineOptions): Promise<ParsedDocument>;
}

interface PdfRenderer<T> {
  render(document: ParsedDocument, options: RenderOptions): T;
}
```

--------------------------------

### Configure read_pdf for accessibility reporting

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-accessibility-report.md

Set include_accessibility_report to true in the request payload to receive the accessibility analysis.

```json
{
  "sources": [{ "path": "document.pdf", "pages": "1-5" }],
  "include_accessibility_report": true,
  "include_full_text": false
}
```

--------------------------------

### Read PDF with Agent Document Twin

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/articles/evidence-first.md

Profiles the PDF and returns a complete Agent Document Twin including markdown, tables, and metadata in a single call.

```text
Agent → read_pdf(sources) → Agent Document Twin
```

--------------------------------

### Inspect PDF metadata and structure

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

Use the inspect operation to retrieve metadata and sample pages from a specified PDF file.

```json
{
  "operation": "inspect",
  "sources": [{ "path": "/absolute/path/to/file.pdf" }],
  "sample_pages": 5,
  "include_metadata": true
}
```

--------------------------------

### pdf_evidence

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/api/index.md

Consolidates focused inspection, rendering, cropping, OCR, and visual analysis operations.

```APIDOC
## pdf_evidence

### Description
A specialist tool that consolidates focused inspect, render, crop, OCR, and visual analysis operations.
```

--------------------------------

### Process Multiple PDFs

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Define multiple local file paths or remote URLs in a single request object to process several documents at once.

```json
{
  "sources": [
    { "path": "/path/to/report.pdf" },
    { "path": "/path/to/invoice.pdf" },
    { "url": "https://example.com/whitepaper.pdf" }
  ],
  "include_full_text": true,
  "include_metadata": true,
  "include_page_count": true,
  "include_images": false
}
```

--------------------------------

### Request HTML Output

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/guide/getting-started.md

Use include_html to retrieve escaped page-aware HTML for preview or conversion tasks.

```json
{
  "sources": [{
    "path": "/path/to/document.pdf",
    "pages": "1-5"
  }],
  "include_html": true,
  "include_full_text": false,
  "include_metadata": false,
  "include_page_count": true
}
```

--------------------------------

### read_pdf Input Schema

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-15-agent-document-map-v3.md

The input object for the read_pdf tool, specifying the source file and the requirement for a document map.

```json
{
  "sources": [{ "path": "report.pdf", "pages": "1-5" }],
  "include_document_map": true
}
```

--------------------------------

### Define PDF reading request schema

Source: https://github.com/sylphxai/pdf-reader-mcp/blob/main/docs/specs/2026-06-14-pdf-intelligence-vnext.md

Initial JSON schema for configuring PDF reading requests, including source paths and inclusion flags for elements and metadata.

```json
{
  "sources": [{ "path": "report.pdf", "pages": "1-3" }],
  "include_elements": true,
  "include_full_text": false,
  "include_metadata": true,
  "include_page_count": true
}
```
Tokens:
Raw