@sylphx/image-reader-mcp 0.1.0 → 0.1.2

package/package.json

@@ -1,19 +1,24 @@
 {
   "name": "@sylphx/image-reader-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "mcpName": "io.github.SylphxAI/image-reader-mcp",
-  "description": "Evidence-first image reading for AI agents — metadata, OCR text, regions, and citeable evidence without generative LLM.",
+  "description": "Iris \u2014 Evidence-first image reading for AI agents \u2014 metadata, OCR text, regions, and citeable evidence without generative LLM.",
   "type": "module",
   "bin": {
-    "image-reader-mcp": "./dist/index.js"
+    "image-reader-mcp": "./bin/image-reader-mcp",
+    "iris": "./bin/image-reader-mcp"
   },
   "files": [
+    "bin/",
     "dist/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src/"
   ],
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/doctor-cli.js",
+    "./sdk": "./src/sdk.ts",
+    "./iris": "./src/sdk.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -39,7 +44,9 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "build": "bunup --no-dts",
+    "build:rust": "cargo build --release -p image-reader-core -p image-reader-cli -p image-reader-mcp-server && bun scripts/stage-rust-mcp.ts",
+    "test:rust": "cargo test",
+    "build": "bun build src/doctor-cli.ts --outdir dist --target node",
     "watch": "tsc --watch",
     "test": "bun test",
     "test:watch": "bun test --watch",
@@ -49,12 +56,16 @@
     "check": "biome check .",
     "check:fix": "biome check --write .",
     "validate": "bun run check && bun run typecheck && bun run test",
+    "doctor": "bun run src/doctor-cli.ts",
+    "benchmark:release-gate": "bun scripts/release-gate.ts",
     "sync:server-json": "bun scripts/sync-server-json.ts",
     "version-packages": "changeset version && bun run sync:server-json",
-    "start": "node dist/index.js",
+    "start": "./bin/image-reader-mcp",
     "clean": "rm -rf dist coverage",
-    "prepublishOnly": "bun run clean && bun run build",
-    "release": "bun run typecheck && bun run check && bun run build && bun test && changeset publish"
+    "prepublishOnly": "bun run clean && bun run build && bun run build:rust",
+    "release": "bun run typecheck && bun run check && bun run build && bun test && changeset publish",
+    "benchmark:public-proof": "bun scripts/public-proof.ts",
+    "brand:pack-plan": "bun scripts/brand-pack-plan.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -70,5 +81,6 @@
     "bunup": "0.16.31",
     "typescript": "^7.0.2"
   },
-  "packageManager": "bun@1.3.12"
+  "packageManager": "bun@1.3.12",
+  "private": false
 }

package/src/doctor-cli.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { formatDoctorReport, runDoctor } from './doctor.js';
+
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json') as { version: string };
+
+async function main(): Promise<void> {
+  const report = await runDoctor(packageJson.version);
+  console.log(formatDoctorReport(report));
+  process.exit(report.status === 'unavailable' ? 1 : 0);
+}
+
+main().catch((error: unknown) => {
+  console.error('[Image Reader MCP] Doctor error:', error);
+  process.exit(1);
+});

package/src/doctor.ts

@@ -0,0 +1,216 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
+import { resolveRustCliBinary } from './engine/rust-decode.js';
+import { listTesseractLanguages } from './utils/ocr.js';
+import { IMAGE_SAFETY_LIMITS } from './utils/safety.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export type DoctorStatus = 'ok' | 'warn' | 'fail';
+
+export interface DoctorCheck {
+  id: string;
+  status: DoctorStatus;
+  message: string;
+}
+
+export interface DoctorReport {
+  profile: 'image_reader_doctor';
+  version: string;
+  status: 'ready' | 'degraded' | 'unavailable';
+  checks: DoctorCheck[];
+}
+
+const probeTesseract = (): DoctorCheck => {
+  const result = spawnSync('tesseract', ['--version'], {
+    encoding: 'utf8',
+    timeout: 2_500,
+  });
+
+  if (result.status === 0) {
+    const versionLine = (result.stdout || result.stderr || '').split('\n')[0]?.trim();
+    const langs = listTesseractLanguages();
+    const langNote = langs.available ? ` languages=[${langs.languages.join(',') || 'none'}]` : '';
+    return {
+      id: 'tesseract',
+      status: 'ok',
+      message: versionLine
+        ? `Tesseract available (${versionLine})${langNote}`
+        : `Tesseract available${langNote}`,
+    };
+  }
+
+  return {
+    id: 'tesseract',
+    status: 'warn',
+    message:
+      'Tesseract is not installed. OCR is optional; read_image still returns dimensions and metadata.',
+  };
+};
+
+const probeSharp = async (): Promise<DoctorCheck> => {
+  try {
+    const buffer = await sharp({
+      create: {
+        width: 1,
+        height: 1,
+        channels: 3,
+        background: { r: 0, g: 0, b: 0 },
+      },
+    })
+      .png()
+      .toBuffer();
+
+    if (buffer.length === 0) {
+      return {
+        id: 'sharp',
+        status: 'fail',
+        message: 'sharp failed to produce a probe image buffer.',
+      };
+    }
+
+    return {
+      id: 'sharp',
+      status: 'ok',
+      message: `sharp decode pipeline is available (v${sharp.versions.sharp}).`,
+    };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      id: 'sharp',
+      status: 'fail',
+      message: `sharp probe failed: ${message}`,
+    };
+  }
+};
+
+const probeSafetyLimits = (): DoctorCheck => {
+  if (IMAGE_SAFETY_LIMITS.maxFileBytes > 0 && IMAGE_SAFETY_LIMITS.maxPixels > 0) {
+    return {
+      id: 'safety_limits',
+      status: 'ok',
+      message: `Safety limits active: ${IMAGE_SAFETY_LIMITS.maxFileBytes} bytes, ${IMAGE_SAFETY_LIMITS.maxPixels} pixels.`,
+    };
+  }
+
+  return {
+    id: 'safety_limits',
+    status: 'fail',
+    message: 'Safety limits are not configured.',
+  };
+};
+
+const probeRustDecodeCli = (): DoctorCheck => {
+  const binary = resolveRustCliBinary();
+  if (binary !== 'image-reader-cli' && existsSync(binary)) {
+    return {
+      id: 'rust_decode_cli',
+      status: 'ok',
+      message: `Rust decode CLI is available at ${binary}.`,
+    };
+  }
+
+  const release = path.join(here, '../target/release/image-reader-cli');
+  const debug = path.join(here, '../target/debug/image-reader-cli');
+  if (existsSync(release) || existsSync(debug)) {
+    return {
+      id: 'rust_decode_cli',
+      status: 'ok',
+      message: 'Rust decode CLI is built locally.',
+    };
+  }
+
+  return {
+    id: 'rust_decode_cli',
+    status: 'warn',
+    message:
+      'Rust decode CLI is not built. Run `cargo build --release` to enable the default Rust probe and region crop path.',
+  };
+};
+
+const probeRustDecodeFlag = (): DoctorCheck => {
+  if (process.env['IMAGE_READER_USE_RUST_DECODE'] === '0') {
+    return {
+      id: 'rust_decode_flag',
+      status: 'warn',
+      message: 'IMAGE_READER_USE_RUST_DECODE=0 forces the sharp fallback adapter path.',
+    };
+  }
+
+  if (process.env['IMAGE_READER_USE_RUST_DECODE'] === '1') {
+    return {
+      id: 'rust_decode_flag',
+      status: 'ok',
+      message:
+        'IMAGE_READER_USE_RUST_DECODE=1 routes probe and region evidence through the Rust core.',
+    };
+  }
+
+  const binary = resolveRustCliBinary();
+  if (binary !== 'image-reader-cli' && existsSync(binary)) {
+    return {
+      id: 'rust_decode_flag',
+      status: 'ok',
+      message: 'Rust decode CLI is built; probe and region evidence default to the Rust core.',
+    };
+  }
+
+  return {
+    id: 'rust_decode_flag',
+    status: 'warn',
+    message:
+      'Rust decode CLI is not built. sharp remains the default probe path until `cargo build --release`.',
+  };
+};
+
+const probeNode = (): DoctorCheck => {
+  const version = process.versions.node;
+  const major = Number.parseInt(version.split('.')[0] ?? '0', 10);
+  if (major >= 22) {
+    return {
+      id: 'node',
+      status: 'ok',
+      message: `Node.js ${version} meets the >=22.13 requirement.`,
+    };
+  }
+
+  return {
+    id: 'node',
+    status: 'warn',
+    message: `Node.js ${version} is below the recommended >=22.13 runtime.`,
+  };
+};
+
+const aggregateStatus = (checks: DoctorCheck[]): DoctorReport['status'] => {
+  if (checks.some((check) => check.status === 'fail')) {
+    return 'unavailable';
+  }
+  if (checks.some((check) => check.status === 'warn')) {
+    return 'degraded';
+  }
+  return 'ready';
+};
+
+export async function runDoctor(version: string): Promise<DoctorReport> {
+  const checks = [
+    probeNode(),
+    probeSafetyLimits(),
+    probeRustDecodeCli(),
+    probeRustDecodeFlag(),
+    await probeSharp(),
+    probeTesseract(),
+  ];
+  return {
+    profile: 'image_reader_doctor',
+    version,
+    status: aggregateStatus(checks),
+    checks,
+  };
+}
+
+export function formatDoctorReport(report: DoctorReport): string {
+  return JSON.stringify(report, null, 2);
+}

package/src/engine/rust-decode.ts

@@ -0,0 +1,145 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { BoundingBox } from '../schemas/readImage.js';
+import { ErrorCode, ImageError } from '../utils/errors.js';
+
+export type RustImageProbe = {
+  format: string;
+  mime: string;
+  width: number;
+  height: number;
+  pixelCount: number;
+  hasAlpha: boolean;
+  colorType: string;
+  sourceHash: string;
+  fileSize: number;
+  route: string;
+};
+
+export type RustRegionEvidence = {
+  bbox: BoundingBox;
+  width: number;
+  height: number;
+  pixelCount: number;
+  regionHash: string;
+  mime: string;
+  route: string;
+  resized: boolean;
+  imageBase64?: string;
+};
+
+type RustProbeEnvelope =
+  | { status: 'ok'; probe: RustImageProbe }
+  | { status: 'error'; code: string; message: string };
+
+type RustCropEnvelope =
+  | { status: 'ok'; region_evidence: RustRegionEvidence }
+  | { status: 'error'; code: string; message: string };
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export function resolveRustCliBinary(): string {
+  const env = process.env['IMAGE_READER_CLI'];
+  if (env && existsSync(env)) {
+    return env;
+  }
+
+  const release = path.join(here, '../../target/release/image-reader-cli');
+  if (existsSync(release)) {
+    return release;
+  }
+
+  const debug = path.join(here, '../../target/debug/image-reader-cli');
+  if (existsSync(debug)) {
+    return debug;
+  }
+
+  return 'image-reader-cli';
+}
+
+export function isRustCliAvailable(): boolean {
+  return resolveRustCliBinary() !== 'image-reader-cli';
+}
+
+export function shouldUseRustDecodeEngine(): boolean {
+  if (process.env['IMAGE_READER_USE_RUST_DECODE'] === '0') {
+    return false;
+  }
+  if (process.env['IMAGE_READER_USE_RUST_DECODE'] === '1') {
+    return true;
+  }
+  return isRustCliAvailable();
+}
+
+const invokeRustCli = (tool: string, input: Record<string, unknown>): unknown => {
+  const binary = resolveRustCliBinary();
+  const payload = JSON.stringify({ tool, input });
+
+  const result = spawnSync(binary, [], {
+    input: payload,
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+
+  if (result.error) {
+    throw new ImageError(
+      ErrorCode.InvalidRequest,
+      `Failed to launch image decode engine: ${result.error.message}`
+    );
+  }
+
+  if (result.status !== 0) {
+    throw new ImageError(
+      ErrorCode.InvalidRequest,
+      result.stderr || `Image decode engine exited with status ${result.status}`
+    );
+  }
+
+  return JSON.parse(result.stdout) as unknown;
+};
+
+const mapErrorCode = (code: string): ErrorCode =>
+  code === 'INVALID_PARAMS' ? ErrorCode.InvalidParams : ErrorCode.InvalidRequest;
+
+export function probeImageViaRustEngine(filePath: string, maxFileBytes: number): RustImageProbe {
+  const envelope = invokeRustCli('image_probe', {
+    path: filePath,
+    max_file_bytes: maxFileBytes,
+  }) as RustProbeEnvelope;
+
+  if (envelope.status !== 'ok') {
+    throw new ImageError(mapErrorCode(envelope.code), envelope.message);
+  }
+
+  return envelope.probe;
+}
+
+export function cropRegionViaRustEngine(input: {
+  filePath: string;
+  maxFileBytes: number;
+  maxPixels: number;
+  region: BoundingBox;
+  maxRegionDimension?: number | undefined;
+  includeRegionImage?: boolean | undefined;
+}): RustRegionEvidence {
+  const envelope = invokeRustCli('crop_region', {
+    path: input.filePath,
+    max_file_bytes: input.maxFileBytes,
+    max_pixels: input.maxPixels,
+    region: input.region,
+    ...(input.maxRegionDimension !== undefined
+      ? { max_region_dimension: input.maxRegionDimension }
+      : {}),
+    ...(input.includeRegionImage !== undefined
+      ? { include_region_image: input.includeRegionImage }
+      : {}),
+  }) as RustCropEnvelope;
+
+  if (envelope.status !== 'ok') {
+    throw new ImageError(mapErrorCode(envelope.code), envelope.message);
+  }
+
+  return envelope.region_evidence;
+}

package/src/handlers/readImage.ts

@@ -0,0 +1,255 @@
+import fs, { stat } from 'node:fs/promises';
+import path from 'node:path';
+import exifr from 'exifr';
+import sharp from 'sharp';
+import {
+  cropRegionViaRustEngine,
+  probeImageViaRustEngine,
+  shouldUseRustDecodeEngine,
+} from '../engine/rust-decode.js';
+import { text, tool, toolError } from '../mcp.js';
+import { type AgentMediaTwin, readImageArgsSchema } from '../schemas/readImage.js';
+import { applyImageIntelligence } from '../utils/applyImageIntelligence.js';
+import { ErrorCode, ImageError } from '../utils/errors.js';
+import { collectTrustWarnings, redactGpsFields } from '../utils/metadata.js';
+import { runTesseractOcr } from '../utils/ocr.js';
+import { resolvePath } from '../utils/pathUtils.js';
+import { IMAGE_SAFETY_LIMITS, validateImageSafety } from '../utils/safety.js';
+
+const mimeFromFormat = (format: string | undefined): string => {
+  switch (format) {
+    case 'jpeg':
+      return 'image/jpeg';
+    case 'png':
+      return 'image/png';
+    case 'webp':
+      return 'image/webp';
+    case 'gif':
+      return 'image/gif';
+    case 'tiff':
+      return 'image/tiff';
+    case 'avif':
+      return 'image/avif';
+    case 'heif':
+      return 'image/heif';
+    default:
+      return format ? `image/${format}` : 'application/octet-stream';
+  }
+};
+
+const readMetadata = async (
+  filePath: string,
+  includeMetadata: boolean
+): Promise<{ metadata?: Record<string, unknown>; trustWarnings: string[] }> => {
+  if (!includeMetadata) {
+    return { trustWarnings: [] };
+  }
+
+  try {
+    const parsed = await exifr.parse(filePath, {
+      tiff: true,
+      xmp: true,
+      iptc: true,
+      icc: false,
+      jfif: false,
+      ihdr: false,
+      mergeOutput: true,
+    });
+
+    if (!parsed || typeof parsed !== 'object' || Object.keys(parsed).length === 0) {
+      return {
+        trustWarnings: ['No EXIF, XMP, or IPTC metadata was found in this image.'],
+      };
+    }
+
+    const rawMetadata = parsed as Record<string, unknown>;
+    const { metadata, hadGps } = redactGpsFields(rawMetadata);
+    const trustWarnings = collectTrustWarnings(rawMetadata, hadGps);
+    return { metadata, trustWarnings };
+  } catch {
+    return {
+      trustWarnings: ['Metadata extraction failed or metadata is not present in this image.'],
+    };
+  }
+};
+
+export const readImage = tool()
+  .description(
+    'Evidence-first image reader for agents (read, not vague vision). Returns Agent Media Twin: geometry, metadata, OCR lines/words, layout blocks, text agent_map, optional palette, optional non-authority LLM caption. Local-first; generative path off by default.'
+  )
+  .input(readImageArgsSchema)
+  .handler(async ({ input }) => {
+    let resolvedPath: string;
+
+    try {
+      resolvedPath = resolvePath(input.path);
+    } catch (error: unknown) {
+      if (error instanceof ImageError) {
+        return toolError(error.message);
+      }
+      throw error;
+    }
+
+    try {
+      await fs.access(resolvedPath);
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : 'File not found.';
+      return toolError(`Unable to read image at '${input.path}': ${message}`);
+    }
+
+    try {
+      const fileStat = await stat(resolvedPath);
+      validateImageSafety({ fileSizeBytes: fileStat.size });
+
+      const includeMetadata = input.include_metadata ?? true;
+      const includeOcr = input.include_ocr ?? false;
+      const ocrLanguages = input.ocr_languages ?? ['eng'];
+      const useRustDecode = shouldUseRustDecodeEngine();
+
+      let twin: AgentMediaTwin;
+
+      if (useRustDecode) {
+        const probe = probeImageViaRustEngine(resolvedPath, IMAGE_SAFETY_LIMITS.maxFileBytes);
+        validateImageSafety({
+          fileSizeBytes: probe.fileSize,
+          width: probe.width,
+          height: probe.height,
+        });
+
+        const { metadata: extractedMetadata, trustWarnings } = await readMetadata(
+          resolvedPath,
+          includeMetadata
+        );
+
+        twin = {
+          filename: path.basename(resolvedPath),
+          mime: probe.mime,
+          dimensions: {
+            width: probe.width,
+            height: probe.height,
+          },
+          has_alpha: probe.hasAlpha,
+          color_space: probe.colorType,
+          trust_warnings: [
+            `Decode route: ${probe.route} (source hash ${probe.sourceHash.slice(0, 12)}…).`,
+            ...trustWarnings,
+          ],
+        };
+
+        if (extractedMetadata !== undefined) {
+          twin.metadata = extractedMetadata;
+        }
+      } else {
+        const image = sharp(resolvedPath, { failOn: 'none' });
+        const metadata = await image.metadata();
+        validateImageSafety({
+          fileSizeBytes: fileStat.size,
+          width: metadata.width,
+          height: metadata.height,
+        });
+
+        const { metadata: extractedMetadata, trustWarnings } = await readMetadata(
+          resolvedPath,
+          includeMetadata
+        );
+
+        twin = {
+          filename: path.basename(resolvedPath),
+          mime: mimeFromFormat(metadata.format),
+          dimensions: {
+            width: metadata.width ?? 0,
+            height: metadata.height ?? 0,
+          },
+          trust_warnings: [...trustWarnings],
+        };
+
+        if (metadata.orientation !== undefined) {
+          twin.orientation = metadata.orientation;
+        }
+        if (metadata.space !== undefined) {
+          twin.color_space = metadata.space;
+        }
+        if (metadata.hasAlpha !== undefined) {
+          twin.has_alpha = metadata.hasAlpha;
+        }
+
+        if (extractedMetadata !== undefined) {
+          twin.metadata = extractedMetadata;
+        }
+      }
+      if (twin.dimensions.width <= 0 || twin.dimensions.height <= 0) {
+        throw new ImageError(
+          ErrorCode.InvalidRequest,
+          `Unable to determine image dimensions for '${input.path}'.`
+        );
+      }
+
+      if (includeOcr) {
+        const ocr = runTesseractOcr(resolvedPath, {
+          languages: ocrLanguages,
+          minConfidence: input.ocr_min_confidence ?? 0,
+          includeWords: input.include_ocr_words ?? false,
+        });
+        twin.ocr = {
+          available: ocr.available,
+          lines: ocr.lines,
+          route: ocr.route,
+          languages: ocr.languages,
+          line_count: ocr.line_count,
+          dropped_low_confidence: ocr.dropped_low_confidence,
+          ...(ocr.skipped_reason !== undefined ? { skipped_reason: ocr.skipped_reason } : {}),
+          ...(ocr.languages_warning !== undefined
+            ? { languages_warning: ocr.languages_warning }
+            : {}),
+          ...(ocr.words !== undefined ? { words: ocr.words } : {}),
+        };
+      }
+
+      twin = await applyImageIntelligence(twin, resolvedPath, input, includeOcr);
+
+      if (input.region !== undefined) {
+        if (!useRustDecode) {
+          throw new ImageError(
+            ErrorCode.InvalidRequest,
+            'Region evidence requires the Rust decode engine. Build image-reader-cli or set IMAGE_READER_USE_RUST_DECODE=1.'
+          );
+        }
+
+        const evidence = cropRegionViaRustEngine({
+          filePath: resolvedPath,
+          maxFileBytes: IMAGE_SAFETY_LIMITS.maxFileBytes,
+          maxPixels: IMAGE_SAFETY_LIMITS.maxPixels,
+          region: input.region,
+          ...(input.max_region_dimension !== undefined
+            ? { maxRegionDimension: input.max_region_dimension }
+            : {}),
+          includeRegionImage: input.include_region_image ?? false,
+        });
+
+        twin.region_evidence = {
+          bbox: evidence.bbox,
+          dimensions: {
+            width: evidence.width,
+            height: evidence.height,
+          },
+          region_hash: evidence.regionHash,
+          mime: evidence.mime,
+          route: evidence.route,
+          ...(evidence.resized ? { resized: evidence.resized } : {}),
+          ...(evidence.imageBase64 !== undefined ? { image_base64: evidence.imageBase64 } : {}),
+        };
+        twin.trust_warnings.push(
+          `Region evidence: ${evidence.route} (hash ${evidence.regionHash.slice(0, 12)}…).`
+        );
+      }
+
+      return text(JSON.stringify(twin, null, 2));
+    } catch (error: unknown) {
+      if (error instanceof ImageError) {
+        return toolError(error.message);
+      }
+
+      const message = error instanceof Error ? error.message : 'Unknown image read failure.';
+      return toolError(`Failed to read image '${input.path}': ${message}`);
+    }
+  });