@layerporter/image-optimizer-mcp 0.1.0

package/src/server.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+import { ArtifactStore } from './artifact-store.js';
+import { artifactToolResult } from './artifact-result.js';
+import { TOOL_HANDLERS } from './tools.js';
+import { textResult } from './text-result.js';
+
+const CLOSED_TRANSFORM_ANNOTATIONS = Object.freeze({
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+});
+
+const OPEN_WORLD_READ_ANNOTATIONS = Object.freeze({
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+});
+
+export function createServer({ artifactStore = new ArtifactStore() } = {}) {
+  const server = new McpServer({
+    name: 'layerporter-image-optimizer',
+    version: '0.1.0',
+    title: 'LayerPorter Website Image Optimizer',
+    websiteUrl: 'https://layerporter.com/mcp/website-image-optimizer/',
+  });
+
+  server.registerResource(
+    'optimized-image-artifact',
+    new ResourceTemplate('layerporter-artifact://artifact/{id}', { list: undefined }),
+    {
+      title: 'Optimized image artifact',
+      description: 'Ephemeral verified binary output created by LayerPorter image optimization.',
+      mimeType: 'application/octet-stream',
+    },
+    async (uri, { id }) => {
+      const artifactId = Array.isArray(id) ? id[0] : String(id);
+      const artifact = await artifactStore.read(artifactId);
+      return {
+        contents: [{
+          uri: uri.href,
+          blob: artifact.buffer.toString('base64'),
+          mimeType: artifact.mimeType,
+          _meta: {
+            sha256: artifact.sha256,
+            size: artifact.size,
+            expiresAt: artifact.expiresAt,
+          },
+        }],
+      };
+    },
+  );
+
+  server.registerTool(
+    'analyze_page_images',
+    {
+      description: 'Analyze normalized browser/page image facts and return deterministic image findings.',
+      inputSchema: z.object({ snapshot: z.record(z.string(), z.unknown()) }),
+      annotations: CLOSED_TRANSFORM_ANNOTATIONS,
+    },
+    async ({ snapshot }) => textResult(await TOOL_HANDLERS.analyze_page_images(snapshot)),
+  );
+
+  server.registerTool(
+    'optimize_image',
+    {
+      description: 'Optimize one caller-provided image with bounded format, resize and no-regression guards. Accepted output is returned as a temporary MCP resource link, not embedded in model text.',
+      inputSchema: z.object({
+        imageBase64: z.string().min(1),
+        target: z.object({ width: z.number().int().positive().optional(), height: z.number().int().positive().optional() }).optional(),
+        policy: z.record(z.string(), z.unknown()).optional(),
+      }),
+      annotations: CLOSED_TRANSFORM_ANNOTATIONS,
+    },
+    async ({ imageBase64, target, policy }) => artifactToolResult(
+      await TOOL_HANDLERS.optimize_image({ buffer: Buffer.from(imageBase64, 'base64'), target, policy }),
+      artifactStore,
+    ),
+  );
+
+  server.registerTool(
+    'generate_responsive_variants',
+    {
+      description: 'Generate a bounded set of responsive image variants without upscaling. Accepted variants are exposed as temporary MCP resource links.',
+      inputSchema: z.object({
+        imageBase64: z.string().min(1),
+        widths: z.array(z.number().int().positive()).min(1).max(6),
+        maxVariants: z.number().int().min(1).max(6).optional(),
+        policy: z.record(z.string(), z.unknown()).optional(),
+      }),
+      annotations: CLOSED_TRANSFORM_ANNOTATIONS,
+    },
+    async ({ imageBase64, widths, maxVariants, policy }) => artifactToolResult(
+      await TOOL_HANDLERS.generate_responsive_variants({ buffer: Buffer.from(imageBase64, 'base64'), widths, maxVariants, policy }),
+      artifactStore,
+    ),
+  );
+
+  server.registerTool(
+    'compare_image_versions',
+    {
+      description: 'Compare original and candidate image versions for byte and guard regressions.',
+      inputSchema: z.object({
+        originalBase64: z.string().min(1),
+        candidateBase64: z.string().min(1),
+        policy: z.record(z.string(), z.unknown()).optional(),
+      }),
+      annotations: CLOSED_TRANSFORM_ANNOTATIONS,
+    },
+    async ({ originalBase64, candidateBase64, policy }) => textResult(await TOOL_HANDLERS.compare_image_versions({ original: Buffer.from(originalBase64, 'base64'), candidate: Buffer.from(candidateBase64, 'base64'), policy })),
+  );
+
+  server.registerTool(
+    'optimize_page_images',
+    {
+      description: 'Optimize a bounded batch of already-selected SAFE image items. Accepted outputs are temporary MCP resource links. Never writes to production.',
+      inputSchema: z.object({
+        items: z.array(z.object({
+          id: z.string().optional(),
+          imageBase64: z.string().min(1),
+          target: z.object({ width: z.number().int().positive().optional(), height: z.number().int().positive().optional() }).optional(),
+          policy: z.record(z.string(), z.unknown()).optional(),
+        })).max(20),
+        maxItems: z.number().int().min(1).max(20).optional(),
+        policy: z.record(z.string(), z.unknown()).optional(),
+      }),
+      annotations: CLOSED_TRANSFORM_ANNOTATIONS,
+    },
+    async ({ items, maxItems, policy }) => artifactToolResult(
+      await TOOL_HANDLERS.optimize_page_images({ items: items.map((item) => ({ ...item, buffer: Buffer.from(item.imageBase64, 'base64') })), maxItems, policy }),
+      artifactStore,
+    ),
+  );
+
+  server.registerTool(
+    'analyze_url_images',
+    {
+      description: 'Safely fetch a public HTTP(S) page and inspect a bounded set of image sources. HTTP fast mode does not claim browser rendered size, currentSrc or LCP.',
+      inputSchema: z.object({
+        url: z.string().min(1).max(2048),
+        maxImages: z.number().int().min(1).max(10).optional(),
+        policy: z.record(z.string(), z.unknown()).optional(),
+      }),
+      annotations: OPEN_WORLD_READ_ANNOTATIONS,
+    },
+    async ({ url, maxImages, policy }) => textResult(await TOOL_HANDLERS.analyze_url_images({ url, maxImages, policy })),
+  );
+
+  server.registerTool(
+    'optimize_url_images',
+    {
+      description: 'Safely fetch a public HTTP(S) page, recompress a bounded set of image sources at their original dimensions, verify byte savings, and return accepted outputs as temporary MCP resource links. Never writes to the website.',
+      inputSchema: z.object({
+        url: z.string().min(1).max(2048),
+        maxImages: z.number().int().min(1).max(10).optional(),
+        policy: z.record(z.string(), z.unknown()).optional(),
+      }),
+      annotations: OPEN_WORLD_READ_ANNOTATIONS,
+    },
+    async ({ url, maxImages, policy }) => artifactToolResult(
+      await TOOL_HANDLERS.optimize_url_images({ url, maxImages, policy }),
+      artifactStore,
+    ),
+  );
+
+  return server;
+}
+
+const artifactStore = new ArtifactStore();
+try {
+  await serveStdio(() => createServer({ artifactStore }));
+} finally {
+  await artifactStore.dispose();
+}

package/src/text-result.js

@@ -0,0 +1,49 @@
+function binarySummary(value) {
+  return {
+    type: 'binary',
+    byteLength: value.byteLength,
+  };
+}
+
+export function sanitizeForText(value, seen = new WeakSet()) {
+  if (Buffer.isBuffer(value)) return binarySummary(value);
+
+  if (ArrayBuffer.isView(value)) {
+    return binarySummary(value);
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return { type: 'binary', byteLength: value.byteLength };
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeForText(item, seen));
+  }
+
+  if (!value || typeof value !== 'object') return value;
+
+  // Defend against objects that already came through Buffer.toJSON().
+  if (value.type === 'Buffer' && Array.isArray(value.data)) {
+    return { type: 'binary', byteLength: value.data.length };
+  }
+
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    result[key] = sanitizeForText(item, seen);
+  }
+
+  seen.delete(value);
+  return result;
+}
+
+export function textResult(value) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(sanitizeForText(value)),
+    }],
+  };
+}

package/src/tools.js

@@ -0,0 +1,81 @@
+import { analyzePageImages, inspectImage, optimizeImage } from './image-core/index.js';
+import { analyzeRemotePageImages, optimizeRemotePageImages } from './url-ingestion.js';
+
+function requireBuffer(value, name) {
+  if (!Buffer.isBuffer(value) || value.length === 0) throw new TypeError(`${name} must be a non-empty Buffer`);
+}
+
+export async function analyzePageImagesTool(input) {
+  return analyzePageImages(input);
+}
+
+export async function optimizeImageTool(input) {
+  requireBuffer(input.buffer, 'buffer');
+  return optimizeImage(input.buffer, { target: input.target, policy: input.policy });
+}
+
+export async function generateResponsiveVariantsTool(input) {
+  requireBuffer(input.buffer, 'buffer');
+  const original = await inspectImage(input.buffer, { policy: input.policy });
+  const widths = [...new Set((input.widths ?? []).filter((w) => Number.isInteger(w) && w > 0 && w <= original.width))]
+    .sort((a, b) => a - b)
+    .slice(0, Math.max(1, Math.min(input.maxVariants ?? 4, 6)));
+  const variants = [];
+  for (const width of widths) {
+    const result = await optimizeImage(input.buffer, { target: { width }, policy: input.policy });
+    variants.push({ width, ...result });
+  }
+  return { status: variants.some((v) => v.status === 'ACCEPT') ? 'ACCEPT' : 'REJECT', original, variants };
+}
+
+export async function compareImageVersionsTool(input) {
+  requireBuffer(input.original, 'original');
+  requireBuffer(input.candidate, 'candidate');
+  const original = await inspectImage(input.original, { policy: input.policy });
+  const candidate = await inspectImage(input.candidate, { policy: input.policy });
+  const savingsBytes = original.bytes - candidate.bytes;
+  const alphaRegression = original.hasAlpha && !candidate.hasAlpha;
+  const dimensionRegression = candidate.width > original.width || candidate.height > original.height;
+  return {
+    status: savingsBytes > 0 && !alphaRegression && !dimensionRegression ? 'ACCEPT' : 'REJECT',
+    original,
+    candidate,
+    savingsBytes,
+    savingsPercent: Number(((savingsBytes / original.bytes) * 100).toFixed(2)),
+    checks: { alphaRegression, dimensionRegression },
+  };
+}
+
+export async function optimizePageImagesTool(input) {
+  if (!Array.isArray(input.items)) throw new TypeError('items must be an array');
+  const items = input.items.slice(0, Math.max(1, Math.min(input.maxItems ?? 10, 20)));
+  const results = [];
+  for (const item of items) {
+    requireBuffer(item.buffer, 'item.buffer');
+    results.push({ id: item.id ?? null, ...(await optimizeImage(item.buffer, { target: item.target, policy: item.policy ?? input.policy })) });
+  }
+  return {
+    status: results.some((r) => r.status === 'ACCEPT') ? 'ACCEPT' : 'REJECT',
+    processed: results.length,
+    accepted: results.filter((r) => r.status === 'ACCEPT').length,
+    results,
+  };
+}
+
+export async function analyzeUrlImagesTool(input, options = {}) {
+  return analyzeRemotePageImages(input, options);
+}
+
+export async function optimizeUrlImagesTool(input, options = {}) {
+  return optimizeRemotePageImages(input, options);
+}
+
+export const TOOL_HANDLERS = {
+  analyze_page_images: analyzePageImagesTool,
+  optimize_image: optimizeImageTool,
+  generate_responsive_variants: generateResponsiveVariantsTool,
+  compare_image_versions: compareImageVersionsTool,
+  optimize_page_images: optimizePageImagesTool,
+  analyze_url_images: analyzeUrlImagesTool,
+  optimize_url_images: optimizeUrlImagesTool,
+};

package/src/url-ingestion.js

@@ -0,0 +1,228 @@
+import { inspectImage, optimizeImage } from './image-core/index.js';
+import { secureFetch } from './secure-fetch.js';
+
+const DEFAULTS = Object.freeze({
+  maxImages: 4,
+  maxPageBytes: 2 * 1024 * 1024,
+  maxImageBytes: 8 * 1024 * 1024,
+  maxTotalImageBytes: 24 * 1024 * 1024,
+  timeoutMs: 8000,
+  maxRedirects: 3,
+  concurrency: 2,
+});
+
+function decodeHtmlEntities(value) {
+  return value
+    .replace(/&/gi, '&')
+    .replace(/"/gi, '"')
+    .replace(/'|'/gi, "'")
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+    .replace(/&#([0-9]+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10)));
+}
+
+function parseAttributes(tag) {
+  const attrs = {};
+  const re = /\b([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g;
+  for (const match of tag.matchAll(re)) attrs[match[1].toLowerCase()] = decodeHtmlEntities(match[2] ?? match[3] ?? match[4] ?? '');
+  return attrs;
+}
+
+function firstSrcsetUrl(srcset) {
+  if (typeof srcset !== 'string' || !srcset.trim()) return null;
+  const first = srcset.split(',')[0]?.trim();
+  if (!first) return null;
+  return first.split(/\s+/)[0] || null;
+}
+
+function positiveInt(value) {
+  const number = Number.parseInt(value ?? '', 10);
+  return Number.isInteger(number) && number > 0 ? number : null;
+}
+
+export function extractImageRefs(html, pageUrl, maxImages = DEFAULTS.maxImages) {
+  if (typeof html !== 'string') throw new TypeError('html must be a string');
+  const limit = Math.max(1, Math.min(maxImages, 10));
+  const refs = [];
+  const seen = new Set();
+  let imgTagCount = 0;
+
+  for (const match of html.matchAll(/<img\b[^>]*>/gi)) {
+    imgTagCount += 1;
+    if (refs.length >= limit) continue;
+    const attrs = parseAttributes(match[0]);
+    const rawSrc = attrs.src || firstSrcsetUrl(attrs.srcset);
+    if (!rawSrc) continue;
+
+    let url;
+    try {
+      url = new URL(rawSrc, pageUrl);
+    } catch {
+      continue;
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || seen.has(url.href)) continue;
+    seen.add(url.href);
+    refs.push({
+      url: url.href,
+      src: attrs.src ?? null,
+      srcset: attrs.srcset ?? null,
+      sizes: attrs.sizes ?? null,
+      widthAttr: positiveInt(attrs.width),
+      heightAttr: positiveInt(attrs.height),
+      loading: attrs.loading ?? null,
+      fetchPriority: attrs.fetchpriority ?? null,
+      altPresent: Object.prototype.hasOwnProperty.call(attrs, 'alt'),
+    });
+  }
+
+  return { imgTagCount, refs };
+}
+
+async function mapBounded(items, concurrency, worker) {
+  const out = new Array(items.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(concurrency, 3)) }, async () => {
+    while (true) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= items.length) return;
+      out[index] = await worker(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+function contentType(headers) {
+  const value = headers?.['content-type'];
+  return Array.isArray(value) ? value[0] ?? '' : value ?? '';
+}
+
+function staticObservations(ref) {
+  const observations = [];
+  if (!(ref.widthAttr && ref.heightAttr)) observations.push('missing_width_height_attributes');
+  if (!ref.srcset) observations.push('missing_srcset');
+  if (ref.srcset && !ref.sizes) observations.push('missing_sizes');
+  return observations;
+}
+
+export async function loadUrlImages(input, options = {}) {
+  const cfg = { ...DEFAULTS, ...(options.limits ?? {}) };
+  const maxImages = Math.max(1, Math.min(input.maxImages ?? cfg.maxImages, 10));
+  const fetchImpl = options.fetchImpl ?? secureFetch;
+
+  const page = await fetchImpl(input.url, {
+    maxBytes: cfg.maxPageBytes,
+    timeoutMs: cfg.timeoutMs,
+    maxRedirects: cfg.maxRedirects,
+    accept: 'text/html,application/xhtml+xml',
+  });
+  if (page.status < 200 || page.status >= 300) throw new Error(`page_http_${page.status}`);
+  if (!/^(text\/html|application\/xhtml\+xml)\b/i.test(contentType(page.headers))) throw new Error('page_content_type_not_html');
+
+  const html = new TextDecoder('utf-8', { fatal: false }).decode(page.body);
+  const extracted = extractImageRefs(html, page.url, maxImages);
+  let acceptedImageBytes = 0;
+
+  const results = await mapBounded(extracted.refs, cfg.concurrency, async (ref) => {
+    try {
+      const response = await fetchImpl(ref.url, {
+        maxBytes: cfg.maxImageBytes,
+        timeoutMs: cfg.timeoutMs,
+        maxRedirects: cfg.maxRedirects,
+        accept: 'image/*',
+      });
+      if (response.status < 200 || response.status >= 300) return { status: 'SKIP', sourceUrl: ref.url, reason: `image_http_${response.status}`, html: ref };
+      const mimeType = contentType(response.headers).split(';')[0].trim().toLowerCase();
+      if (!mimeType.startsWith('image/')) return { status: 'SKIP', sourceUrl: ref.url, reason: 'image_content_type_invalid', html: ref };
+
+      const metadata = await inspectImage(response.body, { policy: input.policy });
+      const responseBytes = response.body.length;
+      if (acceptedImageBytes + responseBytes > cfg.maxTotalImageBytes) return { status: 'SKIP', sourceUrl: ref.url, reason: 'total_image_byte_budget', html: ref };
+      acceptedImageBytes += responseBytes;
+
+      return {
+        status: 'FETCHED',
+        sourceUrl: response.url,
+        mimeType,
+        redirects: response.redirects.length,
+        html: ref,
+        observations: staticObservations(ref),
+        image: metadata,
+        buffer: response.body,
+      };
+    } catch (error) {
+      return { status: 'SKIP', sourceUrl: ref.url, reason: error?.code ?? error?.message ?? 'image_fetch_failed', html: ref };
+    }
+  });
+
+  return {
+    mode: 'http_fast',
+    browserMetrics: false,
+    page: {
+      requestedUrl: input.url,
+      finalUrl: page.url,
+      httpStatus: page.status,
+      bytes: page.body.length,
+      redirects: page.redirects.length,
+      imgTagCount: extracted.imgTagCount,
+      selectedImageCount: extracted.refs.length,
+    },
+    images: results,
+    fetched: results.filter((item) => item.status === 'FETCHED').length,
+    skipped: results.filter((item) => item.status === 'SKIP').length,
+    fetchedImageBytes: acceptedImageBytes,
+  };
+}
+
+function withoutBuffers(value) {
+  if (Array.isArray(value)) return value.map(withoutBuffers);
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === 'buffer' && Buffer.isBuffer(item)) continue;
+    out[key] = withoutBuffers(item);
+  }
+  return out;
+}
+
+export async function analyzeRemotePageImages(input, options = {}) {
+  const loaded = await loadUrlImages(input, options);
+  return {
+    status: loaded.fetched > 0 ? 'OK' : 'NO_IMAGES',
+    ...withoutBuffers(loaded),
+    safetyNote: 'HTTP fast mode reports static image facts only; it does not claim rendered size, currentSrc, LCP, or browser-selected candidates.',
+  };
+}
+
+export async function optimizeRemotePageImages(input, options = {}) {
+  const loaded = await loadUrlImages(input, options);
+  const results = [];
+
+  for (const item of loaded.images) {
+    if (item.status !== 'FETCHED') {
+      results.push(withoutBuffers(item));
+      continue;
+    }
+    const optimization = await optimizeImage(item.buffer, { policy: input.policy });
+    results.push({
+      sourceUrl: item.sourceUrl,
+      mimeType: item.mimeType,
+      html: item.html,
+      observations: item.observations,
+      original: item.image,
+      optimization,
+    });
+  }
+
+  const accepted = results.filter((item) => item.optimization?.status === 'ACCEPT').length;
+  return {
+    status: accepted > 0 ? 'ACCEPT' : 'REJECT',
+    mode: 'http_fast_same_dimensions',
+    browserMetrics: false,
+    page: loaded.page,
+    processed: results.filter((item) => item.optimization).length,
+    accepted,
+    results,
+    safetyNote: 'URL mode never auto-resizes from HTML layout hints. It only recompresses at the original dimensions; browser-aware resize requires measured rendered facts or an explicit target.',
+  };
+}