{
"markdown": "\n\n\n# Citra\n\n### Give your AI agent eyes for PDFs — with proof.\n\n**Local-first PDF evidence for agents.** Structured text, tables, OCR, visual crops, and page-level citations your agent can **defend** — not invent.\n\n**Canonical package** [`@sylphx/citra`](https://www.npmjs.com/package/@sylphx/citra) · **bin** `citra` · **MCP** `io.github.SylphxAI/citra` · **live** `5.0.0`\n\n[](https://www.npmjs.com/package/@sylphx/citra)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/SylphxAI/pdf-reader-mcp/stargazers)\n\n
\n\n## Zero-config in one line\n\n```bash\nnpx -y @sylphx/citra\n```\n\nNo Docker. No API key. No global install. Spawns a **stdio MCP server** agents can use immediately.\n\n| Client | Setup |\n| --- | --- |\n| **Any agent / CLI** | `npx -y @sylphx/citra` |\n| **Claude Code** | `claude mcp add citra -- npx -y @sylphx/citra` |\n| **Claude Desktop / Cursor / VS Code / Codex** | `\"command\": \"npx\", \"args\": [\"-y\", \"@sylphx/citra\"]` |\n| **Global CLI** | `npm i -g @sylphx/citra` → `citra` |\n\n## Why Citra feels unfairly good\n\nPlain-text PDF tools make agents **guess**. Citra returns an **Agent Document Twin** they can **cite**.\n\n| Pain today | With Citra |\n| --- | --- |\n| Page numbers invented or missing | **Page + geometry + provenance** |\n| Tables flattened into soup | **Rows · columns · cells · bounding boxes** |\n| Scanned PDFs become noise | **OCR path linked to evidence** |\n| Install / config / “hope it works” | **`npx -y` — done** |\n| Silent engine fallbacks | **Fail closed** if the native binary is missing |\n\n### Five reasons teams pick Citra\n\n1. **Zero-config** — real `npx` MCP, not a 20-step bootstrap.\n2. **Evidence, not vibes** — citations agents can show a human.\n3. **Local-first** — PDFs stay on the machine; no required cloud vision API.\n4. **Brand-sole** — one package, one bin, one story (`@sylphx/citra` / `citra`).\n5. **Instrument family** — compose with Iris (image), Cue (video), Spine, Lookout, Locus.\n\n## See the difference\n\n\n\n| Without evidence | With Citra |\n| --- | --- |\n| “Revenue was about $12M” | “Page 14, Table 3, cell (row 4, col 2) = `$12.4M`” |\n| Lost table structure | Rows, columns, cells, bounding boxes |\n| Scanned PDF = garbage text | OCR with page-linked evidence |\n| Hidden / adversarial text ignored | Trust signals when requested |\n\n## What you get\n\nThree tools. One product surface.\n\n| Tool | What agents use it for |\n| --- | --- |\n| `read_pdf` | Smart default: markdown, tables, structure, OCR, citations |\n| `search_pdf` | Find page + snippet matches before deep reading |\n| `pdf_evidence` | Crops, renders, inspect, focused evidence ops |\n\nMinimal call:\n\n```json\n{\n \"sources\": [{ \"path\": \"/absolute/path/to/report.pdf\" }]\n}\n```\n\n### Flagship use cases\n\n1. **Financial reports** — extract table cells agents can cite by page and geometry \n2. **Research papers** — headings, reading order, page-level quotes \n3. **Scanned documents** — OCR path with evidence, not a text soup \n\n## Platforms\n\nOne **optional** native package is selected for **your** host only:\n\n| Platform | Native package |\n| --- | --- |\n| macOS arm64 | `@sylphx/citra-darwin-arm64` |\n| macOS x64 | `@sylphx/citra-darwin-x64` |\n| Linux x64 | `@sylphx/citra-linux-x64-gnu` |\n| Linux arm64 | `@sylphx/citra-linux-arm64-gnu` |\n| Windows x64 | `@sylphx/citra-win32-x64-msvc` |\n\nMissing native → **fail closed** (no silent TypeScript PDF engine).\n\n## Product docs\n\n| Doc | Purpose |\n| --- | --- |\n| [docs/POSITIONING.md](docs/POSITIONING.md) | Strategic positioning |\n| [docs/COMPETITIVE.md](docs/COMPETITIVE.md) | Peer anchors and wedge |\n| [docs/EVIDENCE_CONTRACT.md](docs/EVIDENCE_CONTRACT.md) | Evidence = result contract |\n| [docs/TOOL_SURFACE.md](docs/TOOL_SURFACE.md) | Few clear tools policy |\n| [docs/PRODUCT_INDEPENDENCE.md](docs/PRODUCT_INDEPENDENCE.md) | This repo is SSOT |\n| [docs/IPPB.md](docs/IPPB.md) | Independent public product bar |\n| [docs/PUBLISH.md](docs/PUBLISH.md) | npm / git publish status |\n| [docs/guide/installation.md](docs/guide/installation.md) | Install & host config |\n| [skills/citra/SKILL.md](./skills/citra/SKILL.md) | Agent skill surface |\n\n## Surfaces (MCP · CLI · SDK)\n\n**MCP (default agent path)**\n\n```bash\nnpx -y @sylphx/citra\n```\n\n**Claude Desktop / Cursor / VS Code / Codex**\n\n```json\n{\n \"mcpServers\": {\n \"citra\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@sylphx/citra\"]\n }\n }\n}\n```\n\nDual-era hosts that send `server/discover` before `initialize` (e.g. Gemini Antigravity CLI) are supported on stdio.\n\n**CLI**\n\n```bash\nnpx -y @sylphx/citra --help\n```\n\n**SDK**\n\n- `@sylphx/citra/sdk` → `Citra` (`read` / `search` / `evidence`)\n- `@sylphx/citra/pure-rust` → low-level client helpers \n- Same tools as MCP: `read_pdf` · `search_pdf` · `pdf_evidence` \n- Requires the platform optional native package (same as MCP)\n\n## Install footprint (honest)\n\nCompare **full clean installs**, not “JS wrapper tarball vs native executable”:\n\n| Metric (measured clean install, **linux-x64**) | Historical TS `3.0.14` | Sole-Rust `4.1.0` lineage |\n| --- | ---: | ---: |\n| Main package on disk | ~403 KB | ~77 KB |\n| Full `node_modules` | ~82.3 MiB | **~24.4 MiB** (~3.4× smaller) |\n| Installed files | 4,101 | **20** (~205× fewer) |\n| Production npm deps | PDF.js + MCP TS SDK + more | `{}` + **one** platform native |\n\nThe 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.\n\nDetails: [installed footprint comparison](docs/specs/performance/installed-footprint-comparison.md)\n\n## Performance (method-bounded)\n\nControlled **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):\n\n| Mode | What it measures | Result |\n| --- | --- | --- |\n| `persistent_warm` | long-lived server, repeated identical local `read_pdf` after warm-up | **≥ ~10×** median latency improvement on all 8 required fixture classes |\n| `startup_inclusive` | spawn + initialize + one task | large advantage on the same fixtures |\n\n`persistent_warm` includes a process-local cache for identical local path+options. First request in a process still pays full parse cost.\n\n**Not** a multi-host guarantee. Details: [4.1.0 report](docs/specs/performance/4.1.0-same-host-performance-report.md) · [claims policy](docs/specs/performance/4.1.0-performance-claims-policy.md)\n\n## Engine note\n\nCurrent production is a **native Rust engine** on supported platforms via a thin Node launcher.\n\n> Local-first. Five platform packages. One clean install. Fail closed without the matching native.\n\nUnusually 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](https://github.com/SylphxAI/pdf-reader-mcp/issues/608)).\n\nEngineering history and recovery pins: [docs/migration.md](docs/migration.md) — not the product pitch.\n\n## Product proof & links\n\n- [Website / guide](https://sylphxai.github.io/pdf-reader-mcp/)\n- [Product proof](docs/guide/product-proof.md)\n- [Benchmark](docs/benchmark.md)\n- [Installation](docs/guide/installation.md)\n- [npm](https://www.npmjs.com/package/@sylphx/citra)\n\n---\n\n\n\n**Stop PDF hallucinations. Give agents proof.**\n\n```bash\nnpx -y @sylphx/citra\n```\n\n
\n",
"bytes": 7832,
"sha": "a20321071cd73a1b31f0e2879185e2d8a86f87f99d96f6e6761058fff4c2dfbd",
"repo_slug": "sylphxai/pdf-reader-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_sylphxai_pdf_reader_mcp_a30ec702/readme"
}