Iris

Zero-config (no install)

npx -y @sylphx/iris

Starts the MCP server on stdio (agents / Codex / Claude Desktop).

Image evidence for agents

Canonical package: @sylphx/iris · bin iris

Iris — Rust-first local image facts (@sylphx/iris) local image facts, not default VLM guesses. sharp/exifr are optional, not required for MCP.

Your agent looked at the image. Did it see the truth?

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).

See objects (L2, optional)

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.

Read images (not vague vision)

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.

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 |

The problem

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.

Why not vision LLM guess?

| 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 |

See it work

Install (30 seconds)

npm install -g @sylphx/iris
iris doctor
claude mcp add iris -- npx @sylphx/iris

Install once. Call once.

{
  "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.

MCP Tool Surface

| 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).

Quick Start

Claude Code

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "iris": {
      "command": "npx",
      "args": ["@sylphx/iris"]
    }
  }
}

Any MCP Client

npx @sylphx/iris

Node.js >=22.13 is required. Optional OCR uses a local Tesseract adapter when installed — no cloud credentials required by default.

Security model

• Local-first — read_image resolves 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_warnings for agent verification.

Release proof

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-gate

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

Development

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-gate

Useful checks:

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

Example read_image requests live in examples/.

Support

• Issues
• npm package
• Portfolio orchestration: smart-reader-mcp

Help this reach more builders

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.

Discovery (in progress)

| 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.

License

MIT © SylphxAI