Photopea MCP Server

Instructions

Implementation Reference

• src/tools/layer.ts:42-57 (registration)

  Registration of 'photopea_add_fill_layer' tool with MCP server, including title, description, input schema, and handler binding

  server.registerTool("photopea_add_fill_layer", {
    title: "Add Fill Layer",
    description: "Add a non-destructive solid color fill layer that covers the entire canvas. Unlike fill_selection, this creates a separate adjustment-style layer that can be toggled, recolored, or deleted without affecting other layers. Use set_layer_properties to change its opacity or blend mode.",
    inputSchema: {
      type: z.enum(["solid"]).describe("Fill layer type (currently only 'solid' is supported)"),
      color: z.string().regex(/^#[0-9a-fA-F]{6}$/).describe("Fill color as hex string (e.g. #ff0000)"),
      name: z.string().optional().describe("Display name for the fill layer in the layers panel"),
    },
    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
  }, async (params) => {
    const script = buildAddFillLayer(params);
    bridge.sendActivity({ type: "activity", id: "", tool: "add_fill_layer", summary: `Add ${params.type} fill layer` });
    const result = await bridge.executeScript(script);
    if (!result.success) return { isError: true, content: [{ type: "text" as const, text: result.error || "Failed to add fill layer" }] };
    return { content: [{ type: "text" as const, text: `Fill layer (${params.type}) added` }] };
  });

• src/bridge/script-builder.ts:227-250 (helper)

  Helper function that builds Photopea-compatible JavaScript to create a solid fill layer by converting hex color to RGB, creating a new layer, and filling the entire canvas

  export function buildAddFillLayer(params: AddFillLayerParams): string {
    const { type, color, name } = params;
    const lines: string[] = [];
  
    if (type === "solid" && color) {
      const { r, g, b } = hexToRgb(color);
      lines.push(solidColorLines("_fillColor", r, g, b));
      lines.push(`var _layer = app.activeDocument.artLayers.add();`);
      if (name !== undefined) {
        lines.push(`_layer.name = '${escapeString(name)}';`);
      }
      lines.push(`app.activeDocument.selection.selectAll();`);
      lines.push(`app.activeDocument.selection.fill(_fillColor);`);
      lines.push(`app.activeDocument.selection.deselect();`);
    } else {
      lines.push(`var _layer = app.activeDocument.artLayers.add();`);
      if (name !== undefined) {
        lines.push(`_layer.name = '${escapeString(name)}';`);
      }
    }
  
    lines.push(`app.echoToOE('ok');`);
    return lines.join("\n");
  }

• src/bridge/types.ts:110-114 (schema)

  TypeScript interface defining the parameter schema for the AddFillLayer tool

  export interface AddFillLayerParams {
    type: "solid";
    color?: string;
    name?: string;
  }