export_preview

Instructions

Implementation Reference

• src/lib/ops-render.ts:67-198 (handler)

  The main handler function that executes the export_preview tool logic. It decides whether to use ictool (Liquid Glass) or flat rendering, handles canvas backgrounds, zoom, and returns the result with inline base64 image support.

  export async function exportPreview(params: ExportPreviewParams): Promise<McpResult> {
    try {
      const useIctool = !params.flat && await ictoolAvailable();
  
      const renditionMap: Record<string, string> = { dark: 'Dark', tinted: 'TintedLight' };
      const rendition = params.appearance ? renditionMap[params.appearance] ?? 'Default' : 'Default';
  
      let buffer: Buffer;
      let renderer: string;
  
      if (useIctool) {
        const canvasBg = resolveCanvasBackgroundParam(params);
        const hasCanvas = canvasBg.type !== 'none' || params.zoom !== 1.0;
  
        const tmpPath = params.output_path + '.ictool.png';
        try {
          await renderWithIctool({
            bundlePath: params.bundle_path,
            outputPath: tmpPath,
            rendition,
            width: params.size,
            height: params.size,
          });
          const raw = await fs.readFile(tmpPath);
  
          if (hasCanvas) {
            // Canvas will be composited later — keep full squircle
            buffer = raw;
          } else {
            // No canvas — glass glyph without squircle outline.
            // 1. Scale down glyph in manifest (smaller relative to app outline)
            // 2. Render ictool at bigger size (outline pushed outside crop zone)
            // 3. Crop center at target size — outline gone, glyph at correct px
            // The two factors cancel: glyph pixels = same as normal render.
            const INSCRIBED_RATIO = 0.55;
            const renderSize = Math.ceil(params.size / INSCRIBED_RATIO);
  
            // Temporarily shrink layer scales in the manifest
            const { manifest } = await readIconBundle(params.bundle_path);
            const origScales: number[] = [];
            for (const group of manifest.groups) {
              for (const layer of group.layers) {
                const pos = layer.position ?? { scale: 1.0, 'translation-in-points': [0, 0] as [number, number] };
                if (!layer.position) layer.position = pos;
                origScales.push(pos.scale);
                pos.scale *= INSCRIBED_RATIO;
              }
            }
            await saveManifest(params.bundle_path, manifest);
  
            const tmpLarge = params.output_path + '.ictool-large.png';
            try {
              await renderWithIctool({
                bundlePath: params.bundle_path,
                outputPath: tmpLarge,
                rendition,
                width: renderSize,
                height: renderSize,
              });
              const largeRaw = await fs.readFile(tmpLarge);
  
              // Crop center at target size — squircle outline is outside
              const cropOffset = Math.round((renderSize - params.size) / 2);
              const cropped = await sharp(largeRaw)
                .extract({ left: cropOffset, top: cropOffset, width: params.size, height: params.size })
                .png()
                .toBuffer();
  
              // Composite onto fill-color canvas
              const fill = resolveFill(manifest, params.appearance);
              let bgColor = { r: 255, g: 255, b: 255 };
              if (fill && typeof fill === 'object' && 'solid' in fill) {
                const parts = fill.solid.split(':')[1]?.split(',').map(Number);
                if (parts && parts.length >= 3) {
                  bgColor = {
                    r: Math.round(parts[0] * 255),
                    g: Math.round(parts[1] * 255),
                    b: Math.round(parts[2] * 255),
                  };
                }
              }
              buffer = await sharp({
                create: { width: params.size, height: params.size, channels: 4, background: { ...bgColor, alpha: 255 } },
              })
                .composite([{ input: cropped, left: 0, top: 0 }])
                .png()
                .toBuffer();
            } finally {
              // Restore original scales
              let i = 0;
              for (const group of manifest.groups) {
                for (const layer of group.layers) {
                  if (layer.position && i < origScales.length) {
                    layer.position.scale = origScales[i++];
                  }
                }
              }
              await saveManifest(params.bundle_path, manifest);
              await fs.unlink(tmpLarge).catch(() => {});
            }
          }
        } finally {
          await fs.unlink(tmpPath).catch(() => {});
        }
        renderer = 'liquid-glass';
      } else {
        const { manifest, assets } = await readIconBundle(params.bundle_path);
        buffer = await renderPreview(manifest, assets, params.size, params.appearance);
        renderer = 'flat';
      }
  
      const canvasBg = resolveCanvasBackgroundParam(params);
  
      if (canvasBg.type !== 'none' || params.zoom !== 1.0) {
        const iconSize = Math.round(params.size * params.zoom);
        buffer = await compositeOnBackground(buffer, canvasBg, params.size, iconSize);
      }
  
      await fs.writeFile(params.output_path, buffer);
  
      const content: McpContentBlock[] = [
        { type: 'text', text: `Exported preview to ${params.output_path} (${params.size}x${params.size}, ${renderer}, zoom: ${params.zoom}x, bg: ${params.canvas_bg_image ? 'image' : params.canvas_bg_color ?? params.canvas_bg ?? 'none'})` },
      ];
      if (params.return_image !== false && buffer.length <= MAX_INLINE_IMAGE_BYTES) {
        content.push({ type: 'image', data: buffer.toString('base64'), mimeType: 'image/png' });
      }
      return { content };
    } catch (error: unknown) {
      const msg = error instanceof Error ? error.message : 'Unknown error';
      return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
    }
  }

• src/lib/ops-render.ts:16-28 (schema)

  TypeScript interface defining all input parameters for the exportPreview handler.

  export interface ExportPreviewParams {
    bundle_path: string;
    output_path: string;
    size: number;
    appearance?: 'dark' | 'tinted';
    flat: boolean;
    canvas_bg?: string;
    apple_preset?: string;
    canvas_bg_color?: string;
    canvas_bg_image?: string;
    zoom: number;
    return_image?: boolean;
  }

• src/server.ts:163-181 (registration)

  Tool registration on the MCP server using server.tool(), including the name 'export_preview', description, Zod schema for params, and the handler binding.

  // ── Tool: export_preview ──
  server.tool(
    'export_preview',
    'Render a preview of an .icon bundle. Uses Apple\'s ictool for Liquid Glass rendering by default (falls back to flat composite if Icon Composer is not installed). Supports canvas backgrounds and zoom.',
    {
      bundle_path: z.string().describe('Path to .icon bundle'),
      output_path: z.string().describe('Output path for the PNG file'),
      size: z.number().min(16).max(2048).default(1024).describe('Output size in pixels'),
      appearance: z.optional(z.enum(['dark', 'tinted'])).describe('Appearance mode to preview (omit for default/light)'),
      flat: z.boolean().default(false).describe('Force flat composite rendering (skip ictool/Liquid Glass)'),
      canvas_bg: z.optional(z.enum(['none', 'light', 'dark', 'checkerboard', 'homescreen-light', 'homescreen-dark'])).describe('Simple preset canvas background'),
      apple_preset: z.optional(z.enum(['sine-purple-orange', 'sine-gasflame', 'sine-magenta', 'sine-green-yellow', 'sine-purple-orange-black', 'sine-gray'])).describe('Apple Icon Composer preset background (overrides canvas_bg)'),
      canvas_bg_color: z.optional(z.string()).describe('Custom hex color for canvas background'),
      canvas_bg_image: z.optional(z.string()).describe('Path to custom background image'),
      zoom: z.number().min(0.1).max(3.0).default(1.0).describe('Zoom level — icon size relative to canvas (1.0 = full canvas, 0.5 = half size)'),
      return_image: z.boolean().default(true).describe('Return the rendered image inline as base64 (default true)'),
    },
    async (params) => exportPreview(params),
  );

• src/server.ts:8-8 (registration)

  Import statement that brings exportPreview from ops-render into server.ts for registration.

  import { exportPreview, renderLiquidGlass, exportMarketing } from './lib/ops-render';

• src/lib/ops-render.ts:49-65 (helper)

  Helper function that resolves canvas background parameters (image, color, apple preset, or preset name) into a CanvasBackground object used by exportPreview.

  export function resolveCanvasBackgroundParam(params: {
    canvas_bg_image?: string;
    canvas_bg_color?: string;
    apple_preset?: string;
    canvas_bg?: string;
  }): CanvasBackground {
    if (params.canvas_bg_image) {
      return { type: 'image', path: params.canvas_bg_image };
    } else if (params.canvas_bg_color) {
      return { type: 'solid', color: params.canvas_bg_color };
    } else if (params.apple_preset) {
      return { type: 'apple-preset', name: params.apple_preset as ApplePresetName };
    } else if (params.canvas_bg && params.canvas_bg !== 'none') {
      return { type: 'preset', name: params.canvas_bg as any };
    }
    return { type: 'none' };
  }