Github · GitHub Repository Radar
SylphxAI pdf-reader-mcp
Give your AI agent eyes for PDFs — structured text, tables, OCR, visual evidence, and page-level citations via MCP. Native Rust, local-first.
Stars
914
Forks
81
Watchers: 914
Language
License: MIT License
Repository Radar Score
53 / 100
Growth
- 7d
- +0
- 30d
- +0
- %
- 0.0%
Not enough metric snapshots yet to chart growth for this repository.
Score breakdown
- popularity 52
- growth 0
- activity 90
- freshness 100
- community 90
Need help integrating this stack?
Our team builds with modern open-source stacks. Tell us what you are shipping.
Get a quote →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
npx -y @sylphx/citraNo 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 |
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 |
- Zero-config — real
npxMCP, 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.
| 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 |
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:
{
"sources": [{ "path": "/absolute/path/to/report.pdf" }]
}- 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
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).
| 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 |
MCP (default agent path)
npx -y @sylphx/citraClaude Desktop / Cursor / VS Code / Codex
{
"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
npx -y @sylphx/citra --helpSDK
@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)
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
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
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.
Stop PDF hallucinations. Give agents proof.
npx -y @sylphx/citra
Repository Radar analysis
Deterministic insights derived from public metadata and our observations — not personal testing or reviews.
Why this repository is interesting
- Maintained recently (last push 3 weeks ago).
Who should use it
- Developers working primarily with TypeScript
- Teams exploring AI tooling, agents, or ML infrastructure
- Platform and DevOps engineers
Potential use cases
- Reference or evaluate TypeScript open-source approaches in this domain
- Prototype AI/agent workflows or study reference architectures
- Evaluate automation, CI/CD, or infrastructure patterns
Strengths
- Recent repository activity
- README present in our index
- Declared license: MIT License
Limitations / considerations
- Insights are derived from public metadata and our observations — not a substitute for code review
What to watch
- Re-check last push, issues, and releases on GitHub before production adoption
Strong signals: Active maintenance
Source: GitHub (public metadata) + Repository Radar analysis. We do not claim ownership of third-party repositories.
Similar repositories
n8n-io/n8n
★ 203,331 · TypeScript · radar 67
koala73/worldmonitor
★ 85,478 · TypeScript · radar 67
lobehub/lobehub
★ 82,201 · TypeScript · radar 67
langgenius/dify
★ 154,353 · TypeScript · radar 66
toeverything/AFFiNE
★ 72,155 · TypeScript · radar 66
CherryHQ/cherry-studio
★ 51,404 · TypeScript · radar 65