@sylphx/image-reader-mcp 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,624 +0,0 @@
-#!/usr/bin/env node
-
-// src/index.ts
-import { createRequire } from "node:module";
-
-// src/handlers/readImage.ts
-import fs2 from "node:fs/promises";
-import path2 from "node:path";
-import exifr from "exifr";
-import sharp from "sharp";
-
-// src/mcp.ts
-import { createHash, timingSafeEqual } from "node:crypto";
-import { createServer as createHttpServer } from "node:http";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { z } from "zod";
-var text = (value) => ({ type: "text", text: value });
-var toolError = (message) => ({
-  content: [text(message)],
-  isError: true
-});
-
-class ToolBuilder {
-  #description;
-  #inputSchema;
-  constructor(descriptionValue, inputSchema) {
-    this.#description = descriptionValue;
-    this.#inputSchema = inputSchema;
-  }
-  description(value) {
-    return new ToolBuilder(value, this.#inputSchema);
-  }
-  input(schema) {
-    return new ToolBuilder(this.#description, schema);
-  }
-  handler(handler) {
-    return {
-      description: this.#description ?? "",
-      inputSchema: this.#inputSchema ?? z.object({}),
-      handler
-    };
-  }
-}
-var tool = () => new ToolBuilder;
-var stdio = () => ({ kind: "stdio" });
-var http = (config) => ({ kind: "http", ...config });
-var isCallToolResult = (result) => typeof result === "object" && result !== null && ("content" in result);
-var isContentArray = (result) => Array.isArray(result);
-var normalizeToolResult = (result) => {
-  if (isContentArray(result))
-    return { content: [...result] };
-  if (isCallToolResult(result))
-    return result;
-  return { content: [result] };
-};
-var withCors = (res, origin) => {
-  if (!origin)
-    return;
-  res.setHeader("Access-Control-Allow-Origin", origin);
-  res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, MCP-Protocol-Version, Mcp-Session-Id, X-API-Key");
-};
-var isApiKeyValid = (configuredKey, presented) => {
-  const provided = Array.isArray(presented) ? presented[0] : presented;
-  if (typeof provided !== "string" || provided.length === 0)
-    return false;
-  const expected = createHash("sha256").update(configuredKey).digest();
-  const actual = createHash("sha256").update(provided).digest();
-  return timingSafeEqual(expected, actual);
-};
-var unauthorized = (res) => {
-  res.writeHead(401, { "Content-Type": "application/json", "WWW-Authenticate": "X-API-Key" });
-  res.end(JSON.stringify({
-    jsonrpc: "2.0",
-    id: null,
-    error: { code: -32001, message: "Unauthorized: missing or invalid X-API-Key header" }
-  }));
-};
-var ensureStreamableAcceptHeader = (req) => {
-  const accept = req.headers.accept;
-  const acceptValues = Array.isArray(accept) ? accept.join(", ") : accept ?? "";
-  if (acceptValues.includes("application/json") && acceptValues.includes("text/event-stream")) {
-    return;
-  }
-  req.headers.accept = "application/json, text/event-stream";
-  const rawAcceptIndex = req.rawHeaders.findIndex((value, index) => index % 2 === 0 && value.toLowerCase() === "accept");
-  if (rawAcceptIndex >= 0) {
-    req.rawHeaders[rawAcceptIndex + 1] = "application/json, text/event-stream";
-    return;
-  }
-  req.rawHeaders.push("Accept", "application/json, text/event-stream");
-};
-var handleNonMcpRoute = (req, res, pathname, transportConfig) => {
-  if (pathname === "/mcp/health" && req.method === "GET") {
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ status: "ok" }));
-    return true;
-  }
-  if (pathname !== "/mcp") {
-    res.writeHead(404, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Not found" }));
-    return true;
-  }
-  if (req.method === "OPTIONS") {
-    res.writeHead(204);
-    res.end();
-    return true;
-  }
-  if (transportConfig.apiKey !== undefined && !isApiKeyValid(transportConfig.apiKey, req.headers["x-api-key"])) {
-    unauthorized(res);
-    return true;
-  }
-  return false;
-};
-var handleHttpRequest = async (req, res, mcpServer, transportConfig) => {
-  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? transportConfig.hostname}`);
-  withCors(res, transportConfig.cors);
-  if (handleNonMcpRoute(req, res, url.pathname, transportConfig))
-    return;
-  ensureStreamableAcceptHeader(req);
-  const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
-  try {
-    await mcpServer.connect(transport);
-    await transport.handleRequest(req, res);
-  } finally {
-    await mcpServer.close();
-  }
-};
-var startHttpServer = async (serverInfo, transportConfig) => {
-  const mcpServer = buildMcpServer(serverInfo);
-  const httpServer = createHttpServer((req, res) => {
-    handleHttpRequest(req, res, mcpServer, transportConfig);
-  });
-  await new Promise((resolve, reject) => {
-    httpServer.once("error", reject);
-    httpServer.listen(transportConfig.port, transportConfig.hostname, () => {
-      httpServer.off("error", reject);
-      resolve();
-    });
-  });
-  return { mcpServer, httpServer };
-};
-var buildMcpServer = ({
-  name,
-  version,
-  instructions,
-  tools
-}) => {
-  const mcpServer = new McpServer({ name, version }, {
-    ...instructions ? { instructions } : {}
-  });
-  for (const [toolName, definition] of Object.entries(tools)) {
-    mcpServer.registerTool(toolName, {
-      description: definition.description,
-      inputSchema: definition.inputSchema
-    }, async (input, ctx) => normalizeToolResult(await definition.handler({ input, ctx })));
-  }
-  return mcpServer;
-};
-var createServer = (options) => {
-  let mcpServer;
-  let httpServer;
-  return {
-    async start() {
-      if (options.transport.kind === "stdio") {
-        mcpServer = buildMcpServer(options);
-        await mcpServer.connect(new StdioServerTransport);
-        return;
-      }
-      const started = await startHttpServer(options, options.transport);
-      mcpServer = started.mcpServer;
-      httpServer = started.httpServer;
-    },
-    async close() {
-      await mcpServer?.close();
-      const serverToClose = httpServer;
-      if (!serverToClose)
-        return;
-      await new Promise((resolve, reject) => {
-        serverToClose.close((error) => {
-          if (error) {
-            reject(error);
-            return;
-          }
-          resolve();
-        });
-      });
-    }
-  };
-};
-
-// src/schemas/readImage.ts
-import { z as z2 } from "zod";
-var boundingBoxSchema = z2.object({
-  x: z2.number().describe("Left edge in pixels."),
-  y: z2.number().describe("Top edge in pixels."),
-  width: z2.number().describe("Width in pixels."),
-  height: z2.number().describe("Height in pixels.")
-});
-var ocrLineSchema = z2.object({
-  text: z2.string(),
-  bbox: boundingBoxSchema,
-  confidence: z2.number().min(0).max(100).optional()
-});
-var imageDimensionsSchema = z2.object({
-  width: z2.number().int().positive(),
-  height: z2.number().int().positive()
-});
-var readImageArgsSchema = z2.object({
-  path: z2.string().min(1).describe("Path to the local image file (absolute or relative to cwd)."),
-  include_metadata: z2.boolean().optional().describe("Include EXIF, XMP, and IPTC metadata when present. Defaults to true."),
-  include_ocr: z2.boolean().optional().describe("Attempt OCR via the local Tesseract adapter when installed. Defaults to false; gracefully skips when unavailable."),
-  ocr_languages: z2.array(z2.string().min(1)).optional().describe('OCR language codes for Tesseract (e.g. ["eng"]). Defaults to ["eng"].')
-});
-var agentMediaTwinSchema = z2.object({
-  filename: z2.string(),
-  mime: z2.string(),
-  dimensions: imageDimensionsSchema,
-  orientation: z2.number().int().optional(),
-  color_space: z2.string().optional(),
-  has_alpha: z2.boolean().optional(),
-  metadata: z2.record(z2.string(), z2.unknown()).optional(),
-  ocr: z2.object({
-    available: z2.boolean(),
-    skipped_reason: z2.string().optional(),
-    lines: z2.array(ocrLineSchema)
-  }).optional(),
-  trust_warnings: z2.array(z2.string())
-});
-
-// src/utils/errors.ts
-class ImageError extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options?.cause ? { cause: options.cause } : undefined);
-    this.code = code;
-    this.name = "ImageError";
-  }
-}
-
-// src/utils/metadata.ts
-var GPS_FIELD_PATTERN = /^(gps|geo|location|latitude|longitude|altitude|coordinates)/i;
-var GPS_NESTED_KEYS = new Set([
-  "latitude",
-  "longitude",
-  "altitude",
-  "lat",
-  "lon",
-  "lng",
-  "GPSLatitude",
-  "GPSLongitude",
-  "GPSAltitude",
-  "GPSLatitudeRef",
-  "GPSLongitudeRef",
-  "GPSAltitudeRef",
-  "GPSDateStamp",
-  "GPSTimeStamp",
-  "GPSProcessingMethod",
-  "GPSAreaInformation",
-  "GPSDOP",
-  "GPSMapDatum",
-  "GPSDestLatitude",
-  "GPSDestLongitude",
-  "GPSDestBearing",
-  "GPSDestDistance",
-  "GPSHPositioningError"
-]);
-var isGpsKey = (key) => GPS_FIELD_PATTERN.test(key) || GPS_NESTED_KEYS.has(key);
-var redactValue = (value) => {
-  if (Array.isArray(value)) {
-    return value.map((item) => redactValue(item));
-  }
-  if (value !== null && typeof value === "object") {
-    return redactGpsFields(value).metadata;
-  }
-  return "[redacted]";
-};
-var redactGpsFields = (metadata) => {
-  let hadGps = false;
-  const redacted = {};
-  for (const [key, value] of Object.entries(metadata)) {
-    if (key.toLowerCase() === "gps" && value !== null && typeof value === "object") {
-      hadGps = true;
-      redacted[key] = "[redacted]";
-      continue;
-    }
-    if (isGpsKey(key)) {
-      hadGps = true;
-      redacted[key] = redactValue(value);
-      continue;
-    }
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      const nested = redactGpsFields(value);
-      if (nested.hadGps)
-        hadGps = true;
-      redacted[key] = nested.metadata;
-      continue;
-    }
-    redacted[key] = value;
-  }
-  return { metadata: redacted, hadGps };
-};
-var collectTrustWarnings = (metadata, hadGps) => {
-  const warnings = [];
-  if (hadGps) {
-    warnings.push("GPS coordinates were present in metadata and have been redacted from the response.");
-  }
-  const software = metadata["Software"] ?? metadata["software"];
-  if (typeof software === "string" && /photoshop|gimp|ai|generative|midjourney|stable diffusion/i.test(software)) {
-    warnings.push(`EXIF Software field suggests possible editing or synthetic origin: "${software}".`);
-  }
-  const make = metadata["Make"] ?? metadata["make"];
-  const model = metadata["Model"] ?? metadata["model"];
-  if (typeof make === "string" && typeof model === "string" && /unknown|fake|synthetic/i.test(`${make} ${model}`)) {
-    warnings.push("Camera make/model metadata looks inconsistent or synthetic.");
-  }
-  return warnings;
-};
-
-// src/utils/ocr.ts
-import { spawnSync } from "node:child_process";
-var OCR_HEALTHCHECK_TIMEOUT_MS = 2500;
-var OCR_TIMEOUT_MS = 60000;
-var parseTesseractTsv = (raw) => {
-  const lines = raw.split(/\r?\n/).filter((line) => line.length > 0);
-  if (lines.length <= 1)
-    return [];
-  const rows = lines.slice(1).map((line) => line.split("\t"));
-  const lineMap = new Map;
-  for (const columns of rows) {
-    if (columns.length < 12)
-      continue;
-    const level = Number.parseInt(columns[0] ?? "", 10);
-    if (level !== 5)
-      continue;
-    const text2 = columns[11]?.trim() ?? "";
-    if (text2.length === 0)
-      continue;
-    const lineNum = Number.parseInt(columns[4] ?? "", 10);
-    const left = Number.parseInt(columns[6] ?? "", 10);
-    const top = Number.parseInt(columns[7] ?? "", 10);
-    const width = Number.parseInt(columns[8] ?? "", 10);
-    const height = Number.parseInt(columns[9] ?? "", 10);
-    const conf = Number.parseFloat(columns[10] ?? "");
-    if (!Number.isFinite(lineNum) || !Number.isFinite(left) || !Number.isFinite(top))
-      continue;
-    const bucket = lineMap.get(lineNum) ?? { words: [] };
-    bucket.words.push({
-      text: text2,
-      left,
-      top,
-      width: Number.isFinite(width) ? width : 0,
-      height: Number.isFinite(height) ? height : 0,
-      conf: Number.isFinite(conf) ? conf : 0
-    });
-    lineMap.set(lineNum, bucket);
-  }
-  const ocrLines = [];
-  for (const bucket of lineMap.values()) {
-    if (bucket.words.length === 0)
-      continue;
-    const sorted = [...bucket.words].sort((a, b) => a.left - b.left);
-    const text2 = sorted.map((word) => word.text).join(" ").trim();
-    if (text2.length === 0)
-      continue;
-    const left = Math.min(...sorted.map((word) => word.left));
-    const top = Math.min(...sorted.map((word) => word.top));
-    const right = Math.max(...sorted.map((word) => word.left + word.width));
-    const bottom = Math.max(...sorted.map((word) => word.top + word.height));
-    const confidenceValues = sorted.map((word) => word.conf).filter((value) => value >= 0);
-    const confidence = confidenceValues.length > 0 ? confidenceValues.reduce((sum, value) => sum + value, 0) / confidenceValues.length : undefined;
-    ocrLines.push({
-      text: text2,
-      bbox: {
-        x: left,
-        y: top,
-        width: Math.max(0, right - left),
-        height: Math.max(0, bottom - top)
-      },
-      ...confidence !== undefined ? { confidence } : {}
-    });
-  }
-  return ocrLines.sort((a, b) => a.bbox.y - b.bbox.y || a.bbox.x - b.bbox.x);
-};
-var isTesseractAvailable = () => {
-  const result = spawnSync("tesseract", ["--version"], {
-    timeout: OCR_HEALTHCHECK_TIMEOUT_MS,
-    windowsHide: true,
-    stdio: "ignore"
-  });
-  return result.status === 0;
-};
-var runTesseractOcr = (imagePath, languages) => {
-  if (!isTesseractAvailable()) {
-    return {
-      available: false,
-      skipped_reason: "Tesseract is not installed or not available on PATH.",
-      lines: []
-    };
-  }
-  const languageArg = languages.length > 0 ? languages.join("+") : "eng";
-  const result = spawnSync("tesseract", [imagePath, "stdout", "-l", languageArg, "tsv"], {
-    encoding: "utf8",
-    timeout: OCR_TIMEOUT_MS,
-    windowsHide: true,
-    maxBuffer: 10 * 1024 * 1024
-  });
-  if (result.error) {
-    return {
-      available: false,
-      skipped_reason: `Tesseract failed to start: ${result.error.message}`,
-      lines: []
-    };
-  }
-  if (result.status !== 0) {
-    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
-    return {
-      available: false,
-      skipped_reason: stderr.length > 0 ? stderr : `Tesseract exited with status ${String(result.status)}.`,
-      lines: []
-    };
-  }
-  const stdout = typeof result.stdout === "string" ? result.stdout : "";
-  return {
-    available: true,
-    lines: parseTesseractTsv(stdout)
-  };
-};
-
-// src/utils/pathUtils.ts
-import fs from "node:fs";
-import path from "node:path";
-var PROJECT_ROOT = process.cwd();
-var canonicalize = (p) => {
-  try {
-    return fs.realpathSync(p);
-  } catch (err) {
-    if (typeof err === "object" && err !== null && "code" in err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
-      const parent = path.dirname(p);
-      if (parent === p)
-        return p;
-      return path.join(canonicalize(parent), path.basename(p));
-    }
-    throw err;
-  }
-};
-var resolvePath = (userPath) => {
-  if (typeof userPath !== "string") {
-    throw new ImageError(-32602 /* InvalidParams */, "Path must be a string.");
-  }
-  const normalizedUserPath = path.normalize(userPath);
-  const resolved = path.isAbsolute(normalizedUserPath) ? normalizedUserPath : path.resolve(PROJECT_ROOT, normalizedUserPath);
-  return canonicalize(resolved);
-};
-
-// src/handlers/readImage.ts
-var mimeFromFormat = (format) => {
-  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";
-  }
-};
-var readMetadata = async (filePath, includeMetadata) => {
-  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;
-    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."]
-    };
-  }
-};
-var readImage = tool().description("Evidence-first image reader. Returns an Agent Media Twin with filename, mime, dimensions, metadata, optional OCR lines with bounding boxes, and trust warnings. No generative LLM is used.").input(readImageArgsSchema).handler(async ({ input }) => {
-  let resolvedPath;
-  try {
-    resolvedPath = resolvePath(input.path);
-  } catch (error) {
-    if (error instanceof ImageError) {
-      return toolError(error.message);
-    }
-    throw error;
-  }
-  try {
-    await fs2.access(resolvedPath);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "File not found.";
-    return toolError(`Unable to read image at '${input.path}': ${message}`);
-  }
-  try {
-    const image = sharp(resolvedPath, { failOn: "none" });
-    const metadata = await image.metadata();
-    const includeMetadata = input.include_metadata ?? true;
-    const includeOcr = input.include_ocr ?? false;
-    const ocrLanguages = input.ocr_languages ?? ["eng"];
-    const { metadata: extractedMetadata, trustWarnings } = await readMetadata(resolvedPath, includeMetadata);
-    const twin = {
-      filename: path2.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(-32600 /* InvalidRequest */, `Unable to determine image dimensions for '${input.path}'.`);
-    }
-    if (includeOcr) {
-      const ocr = runTesseractOcr(resolvedPath, ocrLanguages);
-      twin.ocr = {
-        available: ocr.available,
-        lines: ocr.lines,
-        ...ocr.skipped_reason !== undefined ? { skipped_reason: ocr.skipped_reason } : {}
-      };
-    }
-    return text(JSON.stringify(twin, null, 2));
-  } catch (error) {
-    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}`);
-  }
-});
-
-// src/index.ts
-var require2 = createRequire(import.meta.url);
-var packageJson = require2("../package.json");
-var transportType = process.env["MCP_TRANSPORT"] ?? "stdio";
-var httpPort = Number.parseInt(process.env["MCP_HTTP_PORT"] ?? "8080", 10);
-var httpHost = process.env["MCP_HTTP_HOST"] ?? "127.0.0.1";
-var apiKey = process.env["MCP_API_KEY"];
-var corsOrigin = process.env["MCP_CORS_ORIGIN"];
-var isLoopbackHost = (host) => host === "localhost" || host === "::1" || host === "127.0.0.1" || host.startsWith("127.");
-function createTransport() {
-  if (transportType === "http") {
-    return http({
-      port: httpPort,
-      hostname: httpHost,
-      ...corsOrigin ? { cors: corsOrigin } : {},
-      ...apiKey ? { apiKey } : {}
-    });
-  }
-  return stdio();
-}
-var server = createServer({
-  name: "image-reader-mcp",
-  version: packageJson.version,
-  instructions: "Evidence-first image reader MCP server. Use read_image to extract measurable facts — dimensions, metadata, optional OCR text with bounding boxes, and trust warnings — without generative LLM.",
-  tools: {
-    read_image: readImage
-  },
-  transport: createTransport()
-});
-async function main() {
-  await server.start();
-  if (transportType === "http") {
-    console.log(`[Image Reader MCP] Server running on http://${httpHost}:${httpPort}/mcp`);
-    console.log(`[Image Reader MCP] Health check: http://${httpHost}:${httpPort}/mcp/health`);
-    if (apiKey) {
-      console.log("[Image Reader MCP] API key authentication enabled (X-API-Key header)");
-    } else if (!isLoopbackHost(httpHost)) {
-      console.warn(`[Image Reader MCP] WARNING: bound to non-loopback host ${httpHost} with no API key. ` + "Any client that can reach this port can read every image this process can access. " + "Set MCP_API_KEY to require an X-API-Key header, or bind MCP_HTTP_HOST=127.0.0.1.");
-    }
-    if (corsOrigin) {
-      console.log(`[Image Reader MCP] CORS allowed origin: ${corsOrigin}`);
-    }
-    console.log("[Image Reader MCP] Project root:", process.cwd());
-  } else if (process.env["DEBUG_MCP"]) {
-    console.error("[Image Reader MCP] Server running on stdio");
-    console.error("[Image Reader MCP] Project root:", process.cwd());
-  }
-}
-main().catch((error) => {
-  console.error("[Image Reader MCP] Server error:", error);
-  process.exit(1);
-});