Iris (transitional package @sylphx/image-reader-mcp) — Rust-first local image facts, not default VLM guesses. sharp/exifr are optional, not required for MCP.
Evidence-first image reading for AI agents. One call turns any local image into an Agent Media Twin — dimensions, metadata, optional OCR with bounding boxes, and trust warnings you can cite without asking a vision LLM to guess.
Local-first · One smart read_image call · Evidence with bbox + provenance · 23 tests
SOTA family roadmap: docs/roadmap/sota-family-roadmap.md.
⭐ Star this repo if agents should read images with facts, not vision-model guesses. · Quick start · See it work · Why not vision LLM guess?
This repository is product SSOT. Sibling agent tools live in separate repos. Each instrument is an independent repository (marketplace + stars).
With a local Florence-class sidecar or Ollama, the same read_image can return open-vocab objects with pixel bboxes and scores:
{ "path": "/abs/photo.jpg", "include_semantics": true, "semantics_prompt": "people and animals" }Objects are scored_non_locator evidence — deterministic L0/L1 facts (geometry/OCR/layout) stay authoritative and always on.
Iris is local-first: geometry + OCR + layout blocks + agent_map so a text-only agent can understand picture architecture without a vision model.
Spec: docs/specs/agent-image-read-contract.md
Local-first frontier: Rust decode, Tesseract native layout (no npm ML), optional Ollama VLM; cloud URL optional. Zero API key. Optional L2 local semantics (include_semantics) detects open-vocab objects (people/animals/things) with pixel bboxes via an official Florence-class sidecar (examples/florence-sidecar/) or Ollama -- never authority over OCR/layout locators.
| 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 |
Images are not filenames. They are pixels, EXIF, orientation, embedded GPS, hidden metadata, and text that only exists if you OCR it with geometry.
Most agent stacks route images through a vision LLM and get a plausible description. Dimensions get rounded. OCR text gets paraphrased. Metadata disappears. Citations become "the model said so." Then the agent hallucinates — confidently.
Image Reader MCP is built for the moment your agent needs measurable facts about an image, not a creative caption.
| Typical vision path | Image Reader MCP |
|---|---|
| "Describe this image" | Return filename, mime, dimensions, and structured metadata |
| Paraphrased OCR | Optional Tesseract lines with bounding boxes and confidence |
| GPS and EXIF leak into context | GPS redacted; trust warnings for suspicious metadata |
| No provenance | Agent Media Twin JSON with measurable, citeable fields |
| Cloud API by default | Local-first — Rust decode + optional Tesseract OCR; sharp/exifr only optional fallbacks |
| Ship and pray | 23 unit tests on schema, metadata, OCR hooks, safety limits, doctor, and release gate |
npm install -g @sylphx/image-reader-mcp
iris doctor
claude mcp add iris -- npx @sylphx/image-reader-mcpInstall once. Call once.
claude mcp add image-reader -- npx @sylphx/image-reader-mcp{
"path": "/absolute/path/to/photo.jpg",
"include_metadata": true,
"include_ocr": true
}read_image inspects the file locally and returns an Agent Media Twin — no
generative LLM required:
{
"filename": "photo.jpg",
"mime": "image/jpeg",
"dimensions": { "width": 4032, "height": 3024 },
"orientation": 1,
"metadata": {
"Make": "ExampleCamera",
"Model": "Pro X",
"DateTimeOriginal": "2026-03-15T14:22:10"
},
"ocr": {
"available": true,
"lines": [
{
"text": "INVOICE #1042",
"bbox": { "x": 120, "y": 48, "width": 310, "height": 36 },
"confidence": 92
}
]
},
"trust_warnings": []
}Abbreviated shape — optional OCR skips gracefully when Tesseract is not installed.
| Tool | Use it when the agent needs to... |
|---|---|
read_image |
Read a local image and return dimensions, mime, metadata, optional OCR, and trust warnings. |
Supported formats: PNG, JPEG, GIF, WebP, TIFF, and other formats the Rust decode engine supports (optional sharp covers additional formats when installed).
claude mcp add image-reader -- npx @sylphx/image-reader-mcpAdd this to claude_desktop_config.json:
{
"mcpServers": {
"image-reader": {
"command": "npx",
"args": ["@sylphx/image-reader-mcp"]
}
}
}npx @sylphx/image-reader-mcpNode.js >=22.13 is required. Optional OCR uses a local Tesseract adapter when
installed — no cloud credentials required by default.
- Local-first —
read_imageresolves paths on the local machine; no cloud vision API by default. - GPS redaction — location metadata is stripped from agent-facing output unless explicitly opted in.
- Size and format limits — oversized or unsupported inputs return structured errors, not partial guesses.
- Optional OCR — Tesseract runs locally when installed; missing OCR is reported as
available: false, not silent failure. - Trust warnings — suspicious EXIF, orientation, or metadata anomalies surface in
trust_warningsfor agent verification.
Claims are backed by CI benchmark:release-gate and the shipped-path matrix (Rust-default route, no legacy Node engine on primary tools).
bun run benchmark:release-gateArtifact: benchmark-artifacts/image_reader_release_gate.json — must report status: passed before release.
git clone https://github.com/SylphxAI/image-reader-mcp.git
cd image-reader-mcp
bun install
bun run build
bun test
bun run doctor
bun run benchmark:release-gateUseful checks:
bun run check
bun run typecheck
bun run validate
bun run benchmark:release-gateExample read_image requests live in examples/.
- Issues
- npm package
- Portfolio orchestration: smart-reader-mcp
If vision-model guesses have wasted your context, your citations, or your trust in agent output, you are exactly who this project is for.
⭐ Star the repo — it is the fastest way to help more agent builders find evidence-first image reading. Share it in your MCP client setup, team wiki, or agent stack README.
| Channel | Status |
|---|---|
| Glama MCP directory | Listed — claim server for full discoverability |
| Official MCP Registry | Listed — io.github.SylphxAI/image-reader-mcp @ v0.1.0 |
| 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.
MIT © SylphxAI