@sylphx/image-reader-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,34 +1,247 @@
-# Image Reader MCP
+<div align="center">
 
-> Evidence-first image reading for AI agents — metadata, OCR text, regions, and citeable evidence without generative LLM.
+# Iris
 
-**Status:** v0.1.0 shipped — `read_image` MCP tool available (metadata, dimensions, optional OCR, trust warnings).
+### Image evidence for agents 
 
-Orchestrated by [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp) — portfolio ADR lives there, not in pdf-reader-mcp.
+**Iris** (transitional package `@sylphx/image-reader-mcp`) — local-first image facts, not default VLM guesses.
 
-| Repository | Role |
+<p align="center">
+  <img src="https://mark.sylphx.com/api/v1/banner?type=holo&theme=tokyonight&text=image+reader+mcp&desc=Evidence-first+image+reading+for+AI+agents+%E2%80%94+metadata%2C+OCR+text%2C+regions%2C+and+ci&height=200&animation=rise&credit=0" alt="image-reader-mcp — Sylphx Mark banner" width="100%" />
+</p>
+
+### 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.
+
+[![npm version](https://img.shields.io/npm/v/@sylphx/image-reader-mcp?style=flat-square)](https://www.npmjs.com/package/@sylphx/image-reader-mcp)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)
+[![CI/CD](https://img.shields.io/github/actions/workflow/status/SylphxAI/image-reader-mcp/ci.yml?style=flat-square&label=CI/CD)](https://github.com/SylphxAI/image-reader-mcp/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-7.0-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+
+**Local-first** · **One smart `read_image` call** · **Evidence with bbox + provenance** · **23 tests**
+
+SOTA family roadmap: [docs/roadmap/sota-family-roadmap.md](docs/roadmap/sota-family-roadmap.md).
+
+[⭐ Star this repo](https://github.com/SylphxAI/image-reader-mcp) if agents should read images with facts, not vision-model guesses.
+· [Quick start](#quick-start) · [See it work](#see-it-work) · [Why not vision LLM guess?](#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).
+
+</div>
+
+---
+
+
+
+## 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](docs/specs/agent-image-read-contract.md)
+
+## Product docs
+
+| Doc | Purpose |
 | --- | --- |
-| [pdf-reader-mcp](https://github.com/SylphxAI/pdf-reader-mcp) | PDF (production) |
-| **image-reader-mcp** (this repo) | Image |
-| [video-reader-mcp](https://github.com/SylphxAI/video-reader-mcp) | Video |
-| [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp) | Unified read + delegate |
+| [docs/POSITIONING.md](docs/POSITIONING.md) | Strategic positioning |
+| [docs/COMPETITIVE.md](docs/COMPETITIVE.md) | Peer anchors and wedge |
+| [docs/EVIDENCE_CONTRACT.md](docs/EVIDENCE_CONTRACT.md) | Evidence = result contract |
+| [docs/TOOL_SURFACE.md](docs/TOOL_SURFACE.md) | Few clear tools policy |
+| [docs/PRODUCT_INDEPENDENCE.md](docs/PRODUCT_INDEPENDENCE.md) | This repo is SSOT |
+| [docs/IPPB.md](docs/IPPB.md) | Independent public product bar |
+| [docs/PUBLISH.md](docs/PUBLISH.md) | npm/git publish status |
+
+## The problem
 
-## Read vs interpret
+Images are not filenames. They are pixels, EXIF, orientation, embedded GPS,
+hidden metadata, and text that only exists if you OCR it with geometry.
 
-**Read** (this repo): extract facts, metadata, transcripts, regions, and timelines with provenance — **no generative LLM required**.
+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.
 
-**Interpret** (out of scope): summarize, classify, or answer open questions — belongs in the agent or an optional remote provider adapter.
+**Image Reader MCP is built for the moment your agent needs measurable facts about
+an image, not a creative caption.**
 
-## MCP surface
+## 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** — sharp + exifr on your machine |
+| Ship and pray | **23** unit tests on schema, metadata, OCR hooks, safety limits, doctor, and release gate |
 
-Primary tool: `read_image` — returns an Agent Media Twin JSON payload with filename, mime, dimensions, metadata (GPS redacted), optional OCR lines with bounding boxes, and trust warnings.
+## See it work
 
-## Quick start
+### Install (30 seconds)
+
+```bash
+npm install -g @sylphx/image-reader-mcp
+iris doctor
+claude mcp add iris -- npx @sylphx/image-reader-mcp
+```
+
+**Install once. Call once.**
+
+```bash
+claude mcp add image-reader -- npx @sylphx/image-reader-mcp
+```
+
+```json
+{
+  "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:
+
+```json
+{
+  "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 sharp can decode.
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add image-reader -- npx @sylphx/image-reader-mcp
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "image-reader": {
+      "command": "npx",
+      "args": ["@sylphx/image-reader-mcp"]
+    }
+  }
+}
+```
+
+### Any MCP Client
 
 ```bash
 npx @sylphx/image-reader-mcp
 ```
 
+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).
+
+```bash
+bun run benchmark:release-gate
+```
+
+Artifact: `benchmark-artifacts/image_reader_release_gate.json` — must report `status: passed` before release.
+
+## Development
+
+```bash
+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:
+
+```bash
+bun run check
+bun run typecheck
+bun run validate
+bun run benchmark:release-gate
+```
+
+Example `read_image` requests live in [`examples/`](examples/).
+
+## Support
+
+- [Issues](https://github.com/SylphxAI/image-reader-mcp/issues)
+- [npm package](https://www.npmjs.com/package/@sylphx/image-reader-mcp)
+- Portfolio orchestration: [smart-reader-mcp](https://github.com/SylphxAI/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](https://github.com/SylphxAI/image-reader-mcp)** — 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](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 |
+| [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 |
+| [TensorBlock MCP Index PR #1113](https://github.com/TensorBlock/awesome-mcp-servers/pull/1113) | Open — multimedia/document processing listing |
+| [MCP servers community issue #4500](https://github.com/modelcontextprotocol/servers/issues/4500) | Open — community server highlight |
+| [mcp.so listing issue #3068](https://github.com/chatmcp/mcpso/issues/3068) | Open — directory submission request |
+| [mcpservers.org submit](https://mcpservers.org/submit) | Not listed yet — free web-form submission |
+
+Know another MCP directory? [Open an issue](https://github.com/SylphxAI/image-reader-mcp/issues/new) with the link.
+
 ## License
 
-MIT © [SylphxAI](https://github.com/SylphxAI)
+MIT © [SylphxAI](https://github.com/SylphxAI)

package/bin/image-reader-mcp

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Image Reader MCP launcher — Rust rmcp only (fail-closed, no TS stdio fallback).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+resolve_rust_bin() {
+	if [[ -n "${IMAGE_READER_MCP_RUST_BIN:-}" && -x "${IMAGE_READER_MCP_RUST_BIN}" ]]; then
+		printf '%s\n' "${IMAGE_READER_MCP_RUST_BIN}"
+		return 0
+	fi
+
+	for candidate in \
+		"$ROOT/bin/native/image-reader-mcp-server" \
+		"$ROOT/target/release/image-reader-mcp-server" \
+		"$ROOT/target/debug/image-reader-mcp-server"; do
+		if [[ -x "$candidate" ]]; then
+			printf '%s\n' "$candidate"
+			return 0
+		fi
+	done
+
+	return 1
+}
+
+resolve_transport() {
+	if [[ -n "${IMAGE_READER_MCP_TRANSPORT:-}" ]]; then
+		printf '%s\n' "${IMAGE_READER_MCP_TRANSPORT}"
+		return 0
+	fi
+	if [[ -n "${MCP_TRANSPORT:-}" ]]; then
+		printf '%s\n' "${MCP_TRANSPORT}"
+		return 0
+	fi
+	printf '%s\n' "stdio"
+}
+
+if bin="$(resolve_rust_bin)"; then
+	transport="$(resolve_transport)"
+	if [[ "$transport" == "http" ]]; then
+		export MCP_TRANSPORT=http
+		export IMAGE_READER_MCP_TRANSPORT=http
+	fi
+	exec "$bin" "$@"
+fi
+
+echo "[image-reader-mcp] Rust MCP server (rmcp) is not built. Run: bun run build:rust" >&2
+exit 1