io.github.SylphxAI/citra — MCP Server

The MCP server “io.github.SylphxAI/citra” provides local-first PDF evidence support for agents. Its scope is described as enabling PDF structure extraction, table handling, OCR, and citations. The server offering is presented as an SDK and CLI, with MCP included as an additional interface.

🛠️ Key Features

Local-first PDF evidence processing for agents
PDF structure support
Table support
OCR support
Citation support
Provides SDK · CLI · MCP

🚀 Use Cases

Supplying agents with structured PDF evidence
Extracting and citing information from PDFs, including OCR-derived content
Handling PDFs with tables for downstream agent workflows

⚡ Developer Benefits

Access via MCP alongside SDK and CLI
Supports agent-oriented outputs that include structure, tables, OCR, and citations

⚠️ Limitations

No additional technical constraints (e.g., file limits, supported languages) are stated in the provided data.

Citra

Give your AI agent eyes for PDFs — with proof.

Local-first PDF evidence for agents. Structured text, tables, OCR, visual crops, and page-level citations your agent can defend — not invent.

Canonical package @sylphx/citra · bin citra · MCP io.github.SylphxAI/citra · live 5.0.0

Zero-config in one line

bash

npx -y @sylphx/citra

No Docker. No API key. No global install. Spawns a stdio MCP server agents can use immediately.

Client	Setup
Any agent / CLI	`npx -y @sylphx/citra`
Claude Code	`claude mcp add citra -- npx -y @sylphx/citra`
Claude Desktop / Cursor / VS Code / Codex	`"command": "npx", "args": ["-y", "@sylphx/citra"]`
Global CLI	`npm i -g @sylphx/citra` → `citra`

Why Citra feels unfairly good

Plain-text PDF tools make agents guess. Citra returns an Agent Document Twin they can cite.

Pain today	With Citra
Page numbers invented or missing	Page + geometry + provenance
Tables flattened into soup	Rows · columns · cells · bounding boxes
Scanned PDFs become noise	OCR path linked to evidence
Install / config / “hope it works”	`npx -y` — done
Silent engine fallbacks	Fail closed if the native binary is missing

Five reasons teams pick Citra

Zero-config — real npx MCP, not a 20-step bootstrap.
Evidence, not vibes — citations agents can show a human.
Local-first — PDFs stay on the machine; no required cloud vision API.
Brand-sole — one package, one bin, one story (@sylphx/citra / citra).
Instrument family — compose with Iris (image), Cue (video), Spine, Lookout, Locus.

See the difference

Plain text vs evidence

Without evidence	With Citra
“Revenue was about $12M”	“Page 14, Table 3, cell (row 4, col 2) = `$12.4M`”
Lost table structure	Rows, columns, cells, bounding boxes
Scanned PDF = garbage text	OCR with page-linked evidence
Hidden / adversarial text ignored	Trust signals when requested

What you get

Three tools. One product surface.

Tool	What agents use it for
`read_pdf`	Smart default: markdown, tables, structure, OCR, citations
`search_pdf`	Find page + snippet matches before deep reading
`pdf_evidence`	Crops, renders, inspect, focused evidence ops

Minimal call:

json

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

Flagship use cases

Financial reports — extract table cells agents can cite by page and geometry
Research papers — headings, reading order, page-level quotes
Scanned documents — OCR path with evidence, not a text soup

Platforms

One optional native package is selected for your host only:

Platform	Native package
macOS arm64	`@sylphx/citra-darwin-arm64`
macOS x64	`@sylphx/citra-darwin-x64`
Linux x64	`@sylphx/citra-linux-x64-gnu`
Linux arm64	`@sylphx/citra-linux-arm64-gnu`
Windows x64	`@sylphx/citra-win32-x64-msvc`

Missing native → fail closed (no silent TypeScript PDF engine).

Product docs

Doc	Purpose
docs/POSITIONING.md	Strategic positioning
docs/COMPETITIVE.md	Peer anchors and wedge
docs/EVIDENCE_CONTRACT.md	Evidence = result contract
docs/TOOL_SURFACE.md	Few clear tools policy
docs/PRODUCT_INDEPENDENCE.md	This repo is SSOT
docs/IPPB.md	Independent public product bar
docs/PUBLISH.md	npm / git publish status
docs/guide/installation.md	Install & host config
skills/citra/SKILL.md	Agent skill surface

Surfaces (MCP · CLI · SDK)

MCP (default agent path)

bash

npx -y @sylphx/citra

Claude Desktop / Cursor / VS Code / Codex

json

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

Dual-era hosts that send server/discover before initialize (e.g. Gemini Antigravity CLI) are supported on stdio.

CLI

bash

npx -y @sylphx/citra --help

SDK

@sylphx/citra/sdk → Citra (read / search / evidence)
@sylphx/citra/pure-rust → low-level client helpers
Same tools as MCP: read_pdf · search_pdf · pdf_evidence
Requires the platform optional native package (same as MCP)

Install footprint (honest)

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

Metric (measured clean install, linux-x64)	Historical TS `3.0.14`	Sole-Rust `4.1.0` lineage
Main package on disk	~403 KB	~77 KB
Full `node_modules`	~82.3 MiB	~24.4 MiB (~3.4× smaller)
Installed files	4,101	20 (~205× fewer)
Production npm deps	PDF.js + MCP TS SDK + more	`{}` + one platform native

The native binary is multi-megabyte because it is the PDF engine. That is expected — and still a cleaner install than shipping PDF.js + a large JS tree.

Details: installed footprint comparison

Performance (method-bounded)

Controlled same-host linux-x64 dual-mode A/B vs historical @sylphx/pdf-reader-mcp@3.0.14, using registry-installed sole-Rust natives (measured on the 4.1.x lineage; method applies to current sole-Rust packages):

Mode	What it measures	Result
`persistent_warm`	long-lived server, repeated identical local `read_pdf` after warm-up	≥ ~10× median latency improvement on all 8 required fixture classes
`startup_inclusive`	spawn + initialize + one task	large advantage on the same fixtures

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

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

Engine note

Current production is a native Rust engine on supported platforms via a thin Node launcher.

Local-first. Five platform packages. One clean install. Fail closed without the matching native.

Unusually formed or broken ToUnicode CMaps are handled without crashing; the release binary is panic-unwind so a worker-thread panic fails the request instead of aborting the process (#608).

Engineering history and recovery pins: docs/migration.md — not the product pitch.

Product proof & links

Stop PDF hallucinations. Give agents proof.

bash

npx -y @sylphx/citra

Citra

io.github.SylphxAI/citra — MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

Citra

Give your AI agent eyes for PDFs — with proof.

Zero-config in one line

Why Citra feels unfairly good

Five reasons teams pick Citra

See the difference

What you get

Flagship use cases

Platforms

Product docs

Surfaces (MCP · CLI · SDK)

Install footprint (honest)

Performance (method-bounded)

Engine note

Product proof & links

Install

Related servers