Citra

Give your AI agent eyes for PDFs.

Citra is a local-first PDF evidence product for agents — fast, citeable, owned entirely in this repository.

Turn PDFs into structured text, tables, OCR, visual evidence, and page-level citations — locally — via SDK, CLI, or MCP.

Plain-text PDF tools make agents guess. Citra returns proof.
Package (transition): @sylphx/pdf-reader-mcp · bin pdf-reader-mcp

Product docs

Related MCP server: PDF Reader MCP Server

Why this exists

Most PDF tools dump text. Agents then invent page numbers, miss tables, and cite the wrong cell.

Citra returns an Agent Document Twin: markdown + structure + geometry + provenance your agent can actually trust.

Agent skill surface

See skills/citra/SKILL.md.

Install (30 seconds)

npm install -g @sylphx/pdf-reader-mcp

Or pin the current release:

npm install -g @sylphx/pdf-reader-mcp@4.1.1

One native binary is installed for your platform only (not all five).

Missing native package → fail closed (no silent engine switch).

Quick start

Claude Code

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

Claude Desktop / Codex / Cursor / VS Code / any MCP client

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

Dual-era hosts that send server/discover before initialize (e.g. Gemini Antigravity CLI) are supported on stdio — the server answers discovery and keeps the session open for the legacy handshake.

Stdio / HTTP

pdf-reader-mcp
MCP_TRANSPORT=http pdf-reader-mcp

SDK (programmatic)

Citra is not MCP-only. Apps and internal dogfood can call the same engine without a chat client.

TypeScript — spawn the native server as a client

import { Citra } from '@sylphx/pdf-reader-mcp/sdk';

const citra = Citra.create();
const { payload, isError } = await citra.read({
  sources: [{ path: '/absolute/path/to/doc.pdf' }],
  // auto defaults on when you omit include_* flags
});
if (isError) throw new Error(JSON.stringify(payload));
console.log(payload);

Low-level escape hatch: @sylphx/pdf-reader-mcp/pure-rust (createPureRustClient).

• Export: @sylphx/pdf-reader-mcp/sdk → Citra (read / search / evidence)

• Export: @sylphx/pdf-reader-mcp/pure-rust → createPureRustClient, resolvePureRustServerBinary, PureRustClient

• Tools (same as MCP): read_pdf · search_pdf · pdf_evidence

• Requires the platform optional native package (same as MCP install)

• Roadmap: idiomatic high-level @sylphx/citra package name + richer typed SDK; semantics stay isomorphic with CLI/MCP

CLI

npx pdf-reader-mcp --help   # transitional bin
# doctor / read paths: see package bin and docs/guide

MCP — see Quick start above (npx @sylphx/pdf-reader-mcp).

Independence: this product only. No central Instruments monorepo.

What you get

Three tools. One product surface.

Minimal call:

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

Flagship use cases

1. Financial reports — extract table cells agents can cite by page and geometry

2. Research papers — headings, reading order, page-level quotes

3. Scanned documents — OCR path with evidence, not a text soup

Install footprint (honest product comparison)

Compare full clean installs, not “JS wrapper tarball vs native executable”:

The native binary is multi-megabyte because it is the PDF intelligence engine (parser, server, rendering/table/OCR routing). That is expected and still yields a cleaner, smaller install than shipping PDF.js + a JS dependency tree.

Details: installed footprint comparison

Performance

Controlled same-host linux-x64 dual-mode A/B vs @sylphx/pdf-reader-mcp@3.0.14, using registry-installed 4.1.x natives:

persistent_warm includes a process-local cache for identical local path+options. First request in a process still pays full parse cost.

Also: install footprint is much smaller than TS 3.0.14 on measured linux-x64 (~3.4× less disk, ~205× fewer files), and the 4.1.0 native binary is smaller than 4.0.2 (strip/LTO).

Not a multi-host guarantee. Details: 4.1.0 report · claims policy

Engine note

Version 4 runs a native Rust engine on supported platforms via a thin Node launcher.

Local-first. Five platforms. One clean install.

Engineering history, recovery pins, and ADRs live under docs/migration.md — not the product pitch.

Product proof

• Before/after + flagship workflows

• Example demos

Docs

• Website / guide

• Installation

• Comparison

• Migration / recovery (secondary)

License

MIT

If this saves your agents from PDF hallucinations, star the repo and share a demo with your team.