@sylphx/image-reader-mcp 0.1.0 → 0.1.2

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,170 @@
+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.'),
+  include_layout: z
+    .boolean()
+    .optional()
+    .describe(
+      'When OCR lines exist, cluster them into reading-order text blocks (image architecture). Defaults to true when include_ocr is true.'
+    ),
+  include_agent_map: z
+    .boolean()
+    .optional()
+    .describe(
+      'Return a text-only agent_map so non-vision models can read image structure. Defaults to true.'
+    ),
+  include_palette: z
+    .boolean()
+    .optional()
+    .describe('Sample an approximate local color palette via sharp (not ML). Defaults to false.'),
+  include_optional_llm: z
+    .boolean()
+    .optional()
+    .describe(
+      'Optional caption via IRIS_OPTIONAL_LLM_URL. Off by default; never authority over OCR/layout 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(),
+  layout: z
+    .object({
+      policy: z.string(),
+      block_count: z.number().int().nonnegative(),
+      blocks: z.array(
+        z.object({
+          id: z.string(),
+          kind: z.literal('text_block'),
+          text: z.string(),
+          bbox: boundingBoxSchema,
+          line_count: z.number().int().nonnegative(),
+          reading_order: z.number().int().positive(),
+        })
+      ),
+      full_text: z.string(),
+      warnings: z.array(z.string()),
+    })
+    .optional(),
+  agent_map: z
+    .object({
+      policy: z.string(),
+      filename: z.string(),
+      mime: z.string(),
+      dimensions: imageDimensionsSchema,
+      outline: z.string(),
+      text_present: z.boolean(),
+      block_count: z.number().int().nonnegative(),
+      palette: z.array(z.object({ hex: z.string(), approx_share: z.number() })).optional(),
+      optional_llm: z
+        .object({
+          available: z.boolean(),
+          skipped_reason: z.string().optional(),
+          route: z.string().optional(),
+          caption: z.string().optional(),
+        })
+        .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/agentMap.ts

@@ -0,0 +1,93 @@
+/**
+ * Text-only Agent Map: lets a non-vision model "read" the image architecture.
+ * Deterministic, local-first. Optional LLM captions are layered elsewhere.
+ */
+
+import type { ImageLayout } from './layout.js';
+
+export type AgentImageMap = {
+  policy: 'agent_image_map_v1';
+  filename: string;
+  mime: string;
+  dimensions: { width: number; height: number };
+  /** Human/agent readable outline (markdown-ish, not prose hallucination). */
+  outline: string;
+  text_present: boolean;
+  block_count: number;
+  palette?: Array<{ hex: string; approx_share: number }>;
+  optional_llm?: {
+    available: boolean;
+    skipped_reason?: string;
+    route?: string;
+    caption?: string;
+  };
+};
+
+export function buildAgentImageMap(input: {
+  filename: string;
+  mime: string;
+  dimensions: { width: number; height: number };
+  layout?: ImageLayout;
+  ocrLineCount?: number;
+  palette?: Array<{ hex: string; approx_share: number }>;
+  optionalLlm?: AgentImageMap['optional_llm'];
+}): AgentImageMap {
+  const { width, height } = input.dimensions;
+  const blocks = input.layout?.blocks ?? [];
+  const textPresent = (input.ocrLineCount ?? 0) > 0 || blocks.length > 0;
+
+  const lines: string[] = [
+    `# Image map: ${input.filename}`,
+    `- mime: ${input.mime}`,
+    `- size: ${width}×${height}px`,
+    `- text_present: ${textPresent}`,
+    `- layout_blocks: ${blocks.length}`,
+  ];
+
+  if (input.palette && input.palette.length > 0) {
+    lines.push(
+      `- palette: ${input.palette.map((p) => `${p.hex}~${Math.round(p.approx_share * 100)}%`).join(', ')}`
+    );
+  }
+
+  if (blocks.length > 0) {
+    lines.push('', '## Reading-order text blocks');
+    for (const b of blocks) {
+      const preview = b.text.replace(/\s+/g, ' ').slice(0, 160);
+      lines.push(
+        `### ${b.id} (order ${b.reading_order}, ${b.line_count} lines)`,
+        `- bbox: x=${b.bbox.x} y=${b.bbox.y} w=${b.bbox.width} h=${b.bbox.height}`,
+        `- text: ${preview}${b.text.length > 160 ? '…' : ''}`,
+        ''
+      );
+    }
+  } else if (!textPresent) {
+    lines.push(
+      '',
+      '## Notes',
+      '- No OCR text recovered. Enable include_ocr for text architecture.',
+      '- Use crop_region / image_probe for geometry; optional LLM caption only if configured.'
+    );
+  }
+
+  if (input.optionalLlm?.available && input.optionalLlm.caption) {
+    lines.push('', '## Optional LLM caption (non-authority)', input.optionalLlm.caption);
+  } else if (input.optionalLlm && !input.optionalLlm.available) {
+    lines.push(
+      '',
+      `## Optional LLM: skipped (${input.optionalLlm.skipped_reason ?? 'not configured'})`
+    );
+  }
+
+  return {
+    policy: 'agent_image_map_v1',
+    filename: input.filename,
+    mime: input.mime,
+    dimensions: input.dimensions,
+    outline: lines.join('\n'),
+    text_present: textPresent,
+    block_count: blocks.length,
+    ...(input.palette ? { palette: input.palette } : {}),
+    ...(input.optionalLlm ? { optional_llm: input.optionalLlm } : {}),
+  };
+}

package/src/utils/applyImageIntelligence.ts

@@ -0,0 +1,68 @@
+import type { AgentMediaTwin, ReadImageArgs } from '../schemas/readImage.js';
+import { buildAgentImageMap } from './agentMap.js';
+import { buildLayoutFromOcrLines } from './layout.js';
+import { maybeOptionalImageCaption } from './optionalLlm.js';
+import { samplePalette } from './palette.js';
+
+/** Attach layout, palette, optional LLM, and agent_map to an Agent Media Twin. */
+export async function applyImageIntelligence(
+  twin: AgentMediaTwin,
+  resolvedPath: string,
+  input: ReadImageArgs,
+  includeOcr: boolean
+): Promise<AgentMediaTwin> {
+  const next: AgentMediaTwin = {
+    ...twin,
+    trust_warnings: [...twin.trust_warnings],
+  };
+
+  const includeLayout = input.include_layout ?? includeOcr;
+  if (includeLayout && next.ocr?.lines && next.ocr.lines.length > 0) {
+    const layout = buildLayoutFromOcrLines(
+      next.ocr.lines.map((line) => ({
+        text: line.text,
+        bbox: line.bbox,
+        ...(line.confidence !== undefined ? { confidence: line.confidence } : {}),
+      }))
+    );
+    next.layout = layout;
+    for (const warning of layout.warnings) {
+      next.trust_warnings.push(`layout: ${warning}`);
+    }
+  }
+
+  let palette: Array<{ hex: string; approx_share: number }> | undefined;
+  if (input.include_palette) {
+    try {
+      palette = await samplePalette(resolvedPath);
+    } catch {
+      next.trust_warnings.push('palette: sampling failed; continuing without palette.');
+    }
+  }
+
+  const optionalLlm = await maybeOptionalImageCaption({
+    path: resolvedPath,
+    mime: next.mime,
+    enabled: input.include_optional_llm ?? false,
+  });
+  if (optionalLlm.available) {
+    next.trust_warnings.push(
+      'optional_llm caption is non-authority; prefer OCR/layout locators for claims.'
+    );
+  }
+
+  const includeAgentMap = input.include_agent_map ?? true;
+  if (includeAgentMap) {
+    next.agent_map = buildAgentImageMap({
+      filename: next.filename,
+      mime: next.mime,
+      dimensions: next.dimensions,
+      ...(next.layout ? { layout: next.layout } : {}),
+      ocrLineCount: next.ocr?.line_count ?? next.ocr?.lines?.length ?? 0,
+      ...(palette ? { palette } : {}),
+      optionalLlm,
+    });
+  }
+
+  return next;
+}

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';
+  }
+}