@sylphx/image-reader-mcp 0.1.0 → 0.1.1

package/src/mcp.ts

@@ -0,0 +1,302 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer as createHttpServer, type Server as HttpServer } 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 type {
+  CallToolResult,
+  ContentBlock,
+  ImageContent,
+  TextContent,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+export const text = (value: string): TextContent => ({ type: 'text', text: value });
+
+export const image = (data: string, mimeType: string): ImageContent => ({
+  type: 'image',
+  data,
+  mimeType,
+});
+
+export const toolError = (message: string): CallToolResult => ({
+  content: [text(message)],
+  isError: true,
+});
+
+export type ToolHandlerResult = CallToolResult | ContentBlock | readonly ContentBlock[];
+
+export type ToolHandler<TInput> = (args: {
+  input: TInput;
+  ctx: unknown;
+}) => ToolHandlerResult | Promise<ToolHandlerResult>;
+
+export interface ToolDefinition<TInput = unknown> {
+  description: string;
+  inputSchema: z.ZodType<TInput>;
+  handler(args: { input: TInput; ctx: unknown }): ToolHandlerResult | Promise<ToolHandlerResult>;
+}
+
+class ToolBuilder<TInput = unknown> {
+  readonly #description: string | undefined;
+  readonly #inputSchema: z.ZodType<TInput> | undefined;
+
+  constructor(descriptionValue?: string, inputSchema?: z.ZodType<TInput>) {
+    this.#description = descriptionValue;
+    this.#inputSchema = inputSchema;
+  }
+
+  description(value: string): ToolBuilder<TInput> {
+    return new ToolBuilder(value, this.#inputSchema);
+  }
+
+  input<TSchema extends z.ZodType>(schema: TSchema): ToolBuilder<z.infer<TSchema>> {
+    return new ToolBuilder(this.#description, schema as z.ZodType<z.infer<TSchema>>);
+  }
+
+  handler(handler: ToolHandler<TInput>): ToolDefinition<TInput> {
+    return {
+      description: this.#description ?? '',
+      inputSchema: this.#inputSchema ?? (z.object({}) as z.ZodType<TInput>),
+      handler,
+    };
+  }
+}
+
+export const tool = (): ToolBuilder => new ToolBuilder();
+
+interface StdioTransportConfig {
+  kind: 'stdio';
+}
+
+interface HttpTransportConfig {
+  kind: 'http';
+  port: number;
+  hostname: string;
+  cors?: string;
+  apiKey?: string;
+}
+
+type TransportConfig = StdioTransportConfig | HttpTransportConfig;
+
+export const stdio = (): StdioTransportConfig => ({ kind: 'stdio' });
+
+export const http = (config: {
+  port: number;
+  hostname: string;
+  cors?: string;
+  apiKey?: string;
+}): HttpTransportConfig => ({ kind: 'http', ...config });
+
+interface CreateServerOptions {
+  name: string;
+  version: string;
+  instructions?: string;
+  tools: Record<string, ToolDefinition<unknown>>;
+  transport: TransportConfig;
+}
+
+interface ServerHandle {
+  start(): Promise<void>;
+  close(): Promise<void>;
+}
+
+const isCallToolResult = (result: ToolHandlerResult): result is CallToolResult =>
+  typeof result === 'object' && result !== null && 'content' in result;
+
+const isContentArray = (result: ToolHandlerResult): result is readonly ContentBlock[] =>
+  Array.isArray(result);
+
+const normalizeToolResult = (result: ToolHandlerResult): CallToolResult => {
+  if (isContentArray(result)) return { content: [...result] };
+  if (isCallToolResult(result)) return result;
+  return { content: [result] };
+};
+
+const withCors = (res: import('node:http').ServerResponse, origin: string | undefined) => {
+  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'
+  );
+};
+
+const isApiKeyValid = (
+  configuredKey: string,
+  presented: string | string[] | undefined
+): boolean => {
+  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);
+};
+
+const unauthorized = (res: import('node:http').ServerResponse) => {
+  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' },
+    })
+  );
+};
+
+const ensureStreamableAcceptHeader = (req: import('node:http').IncomingMessage) => {
+  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');
+};
+
+const handleNonMcpRoute = (
+  req: import('node:http').IncomingMessage,
+  res: import('node:http').ServerResponse,
+  pathname: string,
+  transportConfig: HttpTransportConfig
+): boolean => {
+  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;
+};
+
+const handleHttpRequest = async (
+  req: import('node:http').IncomingMessage,
+  res: import('node:http').ServerResponse,
+  mcpServer: McpServer,
+  transportConfig: HttpTransportConfig
+): Promise<void> => {
+  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 as unknown as Parameters<McpServer['connect']>[0]);
+    await transport.handleRequest(req, res);
+  } finally {
+    await mcpServer.close();
+  }
+};
+
+const startHttpServer = async (
+  serverInfo: Pick<CreateServerOptions, 'name' | 'version' | 'instructions' | 'tools'>,
+  transportConfig: HttpTransportConfig
+): Promise<{ mcpServer: McpServer; httpServer: HttpServer }> => {
+  const mcpServer = buildMcpServer(serverInfo);
+  const httpServer = createHttpServer((req, res) => {
+    void handleHttpRequest(req, res, mcpServer, transportConfig);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(transportConfig.port, transportConfig.hostname, () => {
+      httpServer.off('error', reject);
+      resolve();
+    });
+  });
+
+  return { mcpServer, httpServer };
+};
+
+const buildMcpServer = ({
+  name,
+  version,
+  instructions,
+  tools,
+}: Pick<CreateServerOptions, 'name' | 'version' | 'instructions' | 'tools'>): McpServer => {
+  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;
+};
+
+export const createServer = (options: CreateServerOptions): ServerHandle => {
+  let mcpServer: McpServer | undefined;
+  let httpServer: HttpServer | undefined;
+
+  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<void>((resolve, reject) => {
+        serverToClose.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    },
+  };
+};

package/src/schemas/readImage.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+
+export const boundingBoxSchema = z.object({
+  x: z.number().describe('Left edge in pixels.'),
+  y: z.number().describe('Top edge in pixels.'),
+  width: z.number().describe('Width in pixels.'),
+  height: z.number().describe('Height in pixels.'),
+});
+
+export const ocrLineSchema = z.object({
+  text: z.string(),
+  bbox: boundingBoxSchema,
+  confidence: z.number().min(0).max(100).optional(),
+});
+
+export const imageDimensionsSchema = z.object({
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+});
+
+export const readImageArgsSchema = z.object({
+  path: z.string().min(1).describe('Path to the local image file (absolute or relative to cwd).'),
+  include_metadata: z
+    .boolean()
+    .optional()
+    .describe('Include EXIF, XMP, and IPTC metadata when present. Defaults to true.'),
+  include_ocr: z
+    .boolean()
+    .optional()
+    .describe(
+      'Attempt OCR via the local Tesseract adapter when installed. Defaults to false; gracefully skips when unavailable.'
+    ),
+  ocr_languages: z
+    .array(z.string().min(1))
+    .optional()
+    .describe('OCR language codes for Tesseract (e.g. ["eng"]). Defaults to ["eng"].'),
+  ocr_min_confidence: z
+    .number()
+    .min(0)
+    .max(100)
+    .optional()
+    .describe('Drop OCR words below this Tesseract confidence (0-100). Defaults to 0.'),
+  include_ocr_words: z
+    .boolean()
+    .optional()
+    .describe('When OCR is enabled, also return word-level bbox evidence. Defaults to false.'),
+  region: boundingBoxSchema
+    .optional()
+    .describe('Optional pixel region to crop and attach as citeable evidence.'),
+  include_region_image: z
+    .boolean()
+    .optional()
+    .describe(
+      'When region is set, include base64 PNG bytes of the cropped region. Defaults to false.'
+    ),
+  max_region_dimension: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Maximum width or height when resizing the cropped region for evidence.'),
+});
+
+export const agentMediaTwinSchema = z.object({
+  filename: z.string(),
+  mime: z.string(),
+  dimensions: imageDimensionsSchema,
+  orientation: z.number().int().optional(),
+  color_space: z.string().optional(),
+  has_alpha: z.boolean().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  ocr: z
+    .object({
+      available: z.boolean(),
+      skipped_reason: z.string().optional(),
+      route: z.string().optional(),
+      languages: z.array(z.string()).optional(),
+      languages_warning: z.string().optional(),
+      line_count: z.number().int().nonnegative().optional(),
+      dropped_low_confidence: z.number().int().nonnegative().optional(),
+      lines: z.array(ocrLineSchema),
+      words: z
+        .array(
+          z.object({
+            text: z.string(),
+            bbox: boundingBoxSchema,
+            confidence: z.number().min(0).max(100).optional(),
+          })
+        )
+        .optional(),
+    })
+    .optional(),
+  region_evidence: z
+    .object({
+      bbox: boundingBoxSchema,
+      dimensions: imageDimensionsSchema,
+      region_hash: z.string(),
+      mime: z.string(),
+      route: z.string(),
+      resized: z.boolean().optional(),
+      image_base64: z.string().optional(),
+    })
+    .optional(),
+  trust_warnings: z.array(z.string()),
+});
+
+export type ReadImageArgs = z.infer<typeof readImageArgsSchema>;
+export type AgentMediaTwin = z.infer<typeof agentMediaTwinSchema>;
+export type OcrLine = z.infer<typeof ocrLineSchema>;
+export type BoundingBox = z.infer<typeof boundingBoxSchema>;

package/src/sdk.ts

@@ -0,0 +1,27 @@
+/**
+ * Iris SDK — programmatic image evidence API (Sylphx).
+ * Isomorphic with MCP tool `read_image`.
+ */
+import { readImage } from './handlers/readImage.js';
+import { readImageArgsSchema } from './schemas/readImage.js';
+
+export type IrisReadInput = {
+  path: string;
+  [key: string]: unknown;
+};
+
+export { readImageArgsSchema };
+
+export class Iris {
+  static create(): Iris {
+    return new Iris();
+  }
+
+  /** MCP: read_image */
+  async read(input: IrisReadInput) {
+    const parsed = readImageArgsSchema.parse(input);
+    return readImage.handler({ input: parsed, ctx: {} });
+  }
+}
+
+export default Iris;

package/src/utils/errors.ts

@@ -0,0 +1,18 @@
+// Custom error class for Image Reader MCP
+
+export enum ErrorCode {
+  InvalidParams = -32602,
+  InvalidRequest = -32600,
+  MethodNotFound = -32601,
+}
+
+export class ImageError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    options?: { cause?: Error | undefined }
+  ) {
+    super(message, options?.cause ? { cause: options.cause } : undefined);
+    this.name = 'ImageError';
+  }
+}

package/src/utils/metadata.ts

@@ -0,0 +1,108 @@
+const GPS_FIELD_PATTERN = /^(gps|geo|location|latitude|longitude|altitude|coordinates)/i;
+
+const 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',
+]);
+
+const isGpsKey = (key: string): boolean => GPS_FIELD_PATTERN.test(key) || GPS_NESTED_KEYS.has(key);
+
+const redactValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return redactGpsFields(value as Record<string, unknown>).metadata;
+  }
+
+  return '[redacted]';
+};
+
+export const redactGpsFields = (
+  metadata: Record<string, unknown>
+): { metadata: Record<string, unknown>; hadGps: boolean } => {
+  let hadGps = false;
+  const redacted: Record<string, unknown> = {};
+
+  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 as Record<string, unknown>);
+      if (nested.hadGps) hadGps = true;
+      redacted[key] = nested.metadata;
+      continue;
+    }
+
+    redacted[key] = value;
+  }
+
+  return { metadata: redacted, hadGps };
+};
+
+export const collectTrustWarnings = (
+  metadata: Record<string, unknown>,
+  hadGps: boolean
+): string[] => {
+  const warnings: string[] = [];
+
+  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;
+};