---

The problem

Agents receive files with misleading extensions, mixed portfolios, and formats that need different parsers. PDF needs evidence twins. Images need metadata and OCR geometry. Videos need ffprobe timelines — not one-size-fits-all text dumps.

Most stacks force the agent or the human to branch on extension, install the right tool, and hope delegation still returns citeable provenance. Wrong reader, wrong schema, silent partial reads. Then citations break — quietly.

Smart Reader MCP is built for the moment your agent needs one read tool that sniffs format and delegates with proof.

Why not manual format routing?

Typical routing path	Smart Reader MCP
Agent guesses format from extension	Magic-byte sniffing with extension fallback
Separate MCP configs per format	One read_media call delegates to the right sibling
Opaque passthrough results	Normalized envelope: source_path, detected_format, delegated_tool, raw_result
Re-implemented parsers in one repo	Delegates to @sylphx/pdf-reader-mcp, @sylphx/image-reader-mcp, @sylphx/video-reader-mcp
Cloud routing services	Local-first stdio delegation to sibling packages
Ship and pray	33 tests on sniffing, mislabeled routing, doctor, release gate, and delegation

See it work

Install once. Call once.

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

{
  "path": "/absolute/path/to/report.pdf"
}

read_media sniffs the file, spawns the matching sibling MCP server, and returns a provenance envelope:

{
  "source_path": "/absolute/path/to/report.pdf",
  "detected_format": "pdf",
  "delegated_tool": "read_pdf",
  "raw_result": {
    "page_count": 12,
    "title": "Q3 Report",
    "trust_report": { "warnings": [] }
  }
}

The raw_result field is the passthrough payload from the delegated reader (read_pdf, read_image, or read_video). Install the siblings you need:

npm install @sylphx/pdf-reader-mcp @sylphx/image-reader-mcp @sylphx/video-reader-mcp

Supported formats:

• PDF: .pdf
• Image: .png, .jpg, .jpeg, .gif, .webp, .tif, .tiff
• Video: .mp4, .m4v, .mkv, .mov, .webm

Sylphx Reader portfolio

Portfolio architecture lives here — this repo owns dispatch and the unified read tool. Format-specific repos own their own parsers and boundary ADRs.

Repository	Package	Role
pdf-reader-mcp	@sylphx/pdf-reader-mcp	PDF (production; independent project)
image-reader-mcp	@sylphx/image-reader-mcp	Image read
video-reader-mcp	@sylphx/video-reader-mcp	Video read
smart-reader-mcp (this repo)	@sylphx/smart-reader-mcp	Sniff + delegate + unified read_media

Full decision record: ADR-0002: Reader Portfolio Architecture.

Read vs interpret

• Read: metadata, OCR, subtitles, scenes, transcripts — deterministic, no generative LLM default.
• Interpret: summarization / VQA — agent or optional remote provider; out of scope for Reader MCP packages.

MCP Tool Surface

Tool	Use it when the agent needs to...
read_media	Read a local PDF, image, or video by sniffing format and delegating to the matching Sylphx Reader sibling.

Quick Start

Claude Code

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

Claude Desktop

Add this to claude_desktop_config.json:

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

Any MCP Client

npx @sylphx/smart-reader-mcp

Node.js >=22.13 is required. Delegation resolves locally installed sibling packages first, then falls back to npx -y @sylphx/<reader>-mcp.

Security model

• Local paths only — read_media resolves files on disk; no remote fetch by default.
• Magic-byte sniffing — format detection uses file content, not extension alone.
• Sibling delegation — spawns known Sylphx Reader packages (@sylphx/pdf-reader-mcp, etc.) via npx -y; no arbitrary executables.
• Provenance envelope — detected_format, delegated_tool, and source_path are always returned for audit.

Release proof

Claims are backed by CI benchmark:release-gate and the shipped-path matrix (Rust sniff/policy route).

bun run benchmark:release-gate

Artifact: benchmark-artifacts/smart_reader_release_gate.json — must report status: passed before release.

Development

git clone https://github.com/SylphxAI/smart-reader-mcp.git
cd smart-reader-mcp
bun install
bun run build
bun test
bun run doctor
bun run benchmark:release-gate

Useful checks:

bun run check
bun run typecheck
bun run validate
bun run benchmark:release-gate

Example read_media requests live in examples/.

Support

• Issues
• npm package
• Portfolio ADR: ADR-0002

Help this reach more builders

If manual format routing has wasted your MCP configs, your agent prompts, or your trust in mixed-media workflows, you are exactly who this project is for.

⭐ Star the repo — it is the fastest way to help more agent builders find one-call media reading. Share it in your MCP client setup, team wiki, or agent stack README.

Discovery (in progress)

Channel	Status
Glama MCP directory	Listed — claim server for full discoverability
Official MCP Registry	Listed — io.github.SylphxAI/smart-reader-mcp @ v0.1.1
TensorBlock MCP Index PR #1113	Open — multimedia/document processing listing
MCP servers community issue #4500	Open — community server highlight
mcp.so listing issue #3068	Open — directory submission request
mcpservers.org submit	Not listed yet — free web-form submission

Know another MCP directory? Open an issue with the link.

License

MIT © SylphxAI