{
  "markdown": "<!-- Marketing: promise → CTA → comparison → why → demo → tools → docs -->\n<div align=\"center\">\n\n# Iris\n\n### Image evidence for agents — not vision-model guesses.\n\n**Local-first image facts** your agent can cite: dimensions, metadata, regions, optional OCR with boxes.\n\n**Canonical** [`@sylphx/iris`](https://www.npmjs.com/package/@sylphx/iris) · **bin** `iris` · **live** `0.2.1`\n\n[![npm version](https://img.shields.io/npm/v/@sylphx/iris?style=flat-square)](https://www.npmjs.com/package/@sylphx/iris)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)\n[![stars](https://img.shields.io/github/stars/SylphxAI/image-reader-mcp?style=flat-square)](https://github.com/SylphxAI/image-reader-mcp/stargazers)\n\n</div>\n\n## Zero-config in one line\n\n```bash\nnpx -y @sylphx/iris\n```\n\nNo API key. No global install. Starts a **stdio MCP server** agents can spawn immediately.\n\n| Client | Setup |\n| --- | --- |\n| **Any agent / CLI** | `npx -y @sylphx/iris` |\n| **Claude Code** | `claude mcp add iris -- npx -y @sylphx/iris` |\n| **Desktop / Cursor / VS Code / Codex** | `\"command\": \"npx\", \"args\": [\"-y\", \"@sylphx/iris\"]` |\n\n## Why Iris feels unfairly good\n\nYour agent looked at the image. **Did it see the truth?**\n\n| Vision model guess | **Iris** |\n| --- | --- |\n| Facts vary by model | **Deterministic media twin** |\n| OCR paraphrased | Optional OCR **with bboxes + confidence** |\n| Cloud API by default | **Local-first**, no key required for core path |\n| Setup: keys + SDKs | **`npx -y` — done** |\n| Brand mix | `@sylphx/iris` · bin `iris` · brand-sole `serverInfo.name=iris` |\n\n### Five reasons teams pick Iris\n\n1. **Zero-config MCP** — real one-liner for agents.\n2. **Facts over captions** — measurable fields agents can defend.\n3. **Local-first** — geometry/OCR/layout without default cloud VLM.\n4. **Fail closed** — missing native binary does not silently invent an engine.\n5. **Family ready** — compose with Citra (PDF), Cue (video), Locus (code).\n\n## What agents get\n\nPrimary surface centers on **`read_image`** (Agent Media Twin). Optional advanced paths stay evidence-shaped.\n\nMinimal call:\n\n```json\n{ \"path\": \"/absolute/path/to/photo.jpg\" }\n```\n\n### Flagship use cases\n\n1. **Screenshots & UI captures** — dimensions, text regions, layout without VLM paraphrase  \n2. **Document photos** — OCR lines with geometry for citation  \n3. **Trust / privacy** — EXIF/GPS handling and trust warnings when requested  \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\n\n## See objects (L2, optional)\n\nWith a local Florence-class sidecar or Ollama, the same `read_image` can return **open-vocab objects** with pixel bboxes and scores:\n\n```json\n{ \"path\": \"/abs/photo.jpg\", \"include_semantics\": true, \"semantics_prompt\": \"people and animals\" }\n```\n\nObjects are `scored_non_locator` evidence — deterministic L0/L1 facts (geometry/OCR/layout) stay authoritative and always on.\n\n## Read images (not vague vision)\n\nIris is **local-first**: geometry + OCR + **layout blocks** + **agent_map** so a text-only agent can understand picture architecture without a vision model.\n\nSpec: [docs/specs/agent-image-read-contract.md](docs/specs/agent-image-read-contract.md)\n\n**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.\n\n## See it work\n\n### Why Iris wins for agents\n\n1. **Zero-config** — `npx -y @sylphx/iris` starts MCP on stdio.\n2. **Facts over captions** — structure agents can cite, not free-text “I see a chart”.\n3. **Local-first** — files never leave the machine by default.\n4. **Family** — pair with Citra (PDF), Cue (video), Locus (code).\n\n## MCP Tool Surface\n\n| Tool | Use it when the agent needs to... |\n| --- | --- |\n| `read_image` | Read a local image and return dimensions, mime, metadata, optional OCR, and trust warnings. |\n\nSupported formats: PNG, JPEG, GIF, WebP, TIFF, and other formats the **Rust decode engine** supports (optional sharp covers additional formats when installed).\n\n## Quick Start\n\n### Claude Code\n\n```bash\n```\n\n### Claude Desktop\n\nAdd this to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"iris\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sylphx/iris\"]\n    }\n  }\n}\n```\n\n### Any MCP Client\n\n```bash\nnpx -y @sylphx/iris\n```\n\nNode.js `>=22.13` is required. Optional OCR uses a local Tesseract adapter when\ninstalled — no cloud credentials required by default.\n\n## Security model\n\n- **Local-first** — `read_image` resolves paths on the local machine; no cloud vision API by default.\n- **GPS redaction** — location metadata is stripped from agent-facing output unless explicitly opted in.\n- **Size and format limits** — oversized or unsupported inputs return structured errors, not partial guesses.\n- **Optional OCR** — Tesseract runs locally when installed; missing OCR is reported as `available: false`, not silent failure.\n- **Trust warnings** — suspicious EXIF, orientation, or metadata anomalies surface in `trust_warnings` for agent verification.\n\n## Release proof\n\nClaims are backed by CI `benchmark:release-gate` and the shipped-path matrix (Rust-default route, no legacy Node engine on primary tools).\n\n```bash\nbun run benchmark:release-gate\n```\n\nArtifact: `benchmark-artifacts/image_reader_release_gate.json` — must report `status: passed` before release.\n\n## Development\n\n```bash\ngit clone https://github.com/SylphxAI/image-reader-mcp.git\ncd image-reader-mcp\nbun install\nbun run build\nbun test\nbun run doctor\nbun run benchmark:release-gate\n```\n\nUseful checks:\n\n```bash\nbun run check\nbun run typecheck\nbun run validate\nbun run benchmark:release-gate\n```\n\nExample `read_image` requests live in [`examples/`](examples/).\n\n## Support\n\n- [Issues](https://github.com/SylphxAI/image-reader-mcp/issues)\n- [npm package](https://www.npmjs.com/package/@sylphx/iris)\n- Portfolio orchestration: [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)\n\n## Help this reach more builders\n\nIf vision-model guesses have wasted your context, your citations, or your trust\nin agent output, you are exactly who this project is for.\n\n**[⭐ Star the repo](https://github.com/SylphxAI/image-reader-mcp)** — it is the\nfastest way to help more agent builders find evidence-first image reading. Share\nit in your MCP client setup, team wiki, or agent stack README.\n\n### Discovery (in progress)\n\n| Channel | Status |\n| --- | --- |\n| [Glama MCP directory](https://glama.ai/mcp/servers/SylphxAI/image-reader-mcp) | Listed — [claim server](https://glama.ai/mcp/servers/SylphxAI/image-reader-mcp/admin) for full discoverability |\n| [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.SylphxAI/image-reader-mcp) | Listed — `io.github.SylphxAI/image-reader-mcp` @ v0.1.0 |\n| [TensorBlock MCP Index PR #1113](https://github.com/TensorBlock/awesome-mcp-servers/pull/1113) | Open — multimedia/document processing listing |\n| [MCP servers community issue #4500](https://github.com/modelcontextprotocol/servers/issues/4500) | Open — community server highlight |\n| [mcp.so listing issue #3068](https://github.com/chatmcp/mcpso/issues/3068) | Open — directory submission request |\n| [mcpservers.org submit](https://mcpservers.org/submit) | Not listed yet — free web-form submission |\n\nKnow another MCP directory? [Open an issue](https://github.com/SylphxAI/image-reader-mcp/issues/new) with the link.\n\n## License\n\nMIT © [SylphxAI](https://github.com/SylphxAI)\n",
  "bytes": 8225,
  "sha": "03009f1892eb4f2e184ae69cc8067e57ebd66bbcc3216c25eb10441a10065370",
  "repo_slug": "sylphxai/image-reader-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sylphxai_image_reader_mcp_9cc62f4b/readme"
}