create_image_config

Instructions

Implementation Reference

• src/index.ts:535-575 (handler)

  Primary handler for create_image_config tool. Builds a config object from args (width, height, backgroundColor, format, quality, defaults, layers) and returns it as JSON with type 'image'.

  private async handleCreateImageConfig(args: any) {
    const config: any = {
      width: args.width || 1920,
      height: args.height || 1080,
      layers: args.layers || [],
    };
  
    // Optional properties
    if (args.backgroundColor !== undefined) {
      config.backgroundColor = args.backgroundColor;
    }
  
    if (args.format !== undefined) {
      config.format = args.format;
    }
  
    if (args.quality !== undefined) {
      config.quality = args.quality;
    }
  
    // Defaults system
    if (args.defaults !== undefined) {
      config.defaults = args.defaults;
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              type: 'image',
              config,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/index.ts:203-260 (schema)

  Input schema definition for create_image_config. Defines properties: width (number, default 1920), height (number, default 1080), backgroundColor (string), format (enum png/jpeg/webp), quality (number), defaults (object), and layers (array, required).

            inputSchema: {
              type: 'object',
              properties: {
                width: {
                  type: 'number',
                  description: 'Canvas width in pixels (max 4096px)',
                  default: 1920,
                },
                height: {
                  type: 'number',
                  description: 'Canvas height in pixels (max 4096px)',
                  default: 1080,
                },
                backgroundColor: {
                  type: 'string',
                  description: 'Background color (hex, rgb, or named). Default: transparent',
                },
                format: {
                  type: 'string',
                  description: 'Output format: png (default, transparent), jpeg (compressed), webp (modern)',
                  enum: ['png', 'jpeg', 'webp'],
                  default: 'png',
                },
                quality: {
                  type: 'number',
                  description: 'Quality for JPEG/WebP (1-100, default: 90)',
                  default: 90,
                },
                defaults: {
                  type: 'object',
                  description: 'Default properties for layers',
                  properties: {
                    layer: {
                      type: 'object',
                      description: 'Properties applied to all layers',
                    },
                    layerType: {
                      type: 'object',
                      description: 'Properties per layer type (text, image, rectangle, circle, gradient)',
                    },
                  },
                },
                layers: {
                  type: 'array',
                  description: `Array of layer objects (max 50). Layer types:
  - image: { type: "image", path, x/y/position, width, height, fit, opacity, rotation, blur, borderRadius }
  - text: { type: "text", text, x/y/position, fontSize, fontPath/googleFont, color, align, wrap, width, lineHeight, backgroundColor, opacity, rotation, blur }
  - rectangle: { type: "rectangle", x, y, width, height, fill, stroke, strokeWidth, opacity, rotation, blur, borderRadius }
  - circle: { type: "circle", x, y, width, height, fill, stroke, strokeWidth, opacity, blur }
  - gradient: { type: "gradient", x, y, width, height, gradient: { type: linear/radial, colors: [], direction: horizontal/vertical/diagonal }, opacity, rotation, blur }`,
                  items: {
                    type: 'object',
                  },
                },
              },
              required: ['layers'],
            },
          },

• src/index.ts:153-260 (registration)

  Tool registration in the ListTools handler: declares the tool with name 'create_image_config', a detailed description of image capabilities, and the inputSchema. Also registered in the CallTool switch statement at line 503-504.

          {
            name: 'create_image_config',
            description: `Create a JSON configuration for image generation based on jsoncut documentation.
            
  Returns a complete configuration object that can be used with the validate_config tool or submitted directly to the jsoncut API.
  
  **WORKFLOW:** 
  1. First get the schema (read resource schema://image or call get_image_schema) to understand all available options
  2. Create the configuration with this tool
  3. Call validate_config to verify the configuration (if user provided media file paths)
  
  **Image Structure:**
  - Layer-based system (rendered bottom to top, max 50 layers)
  - Canvas with dimensions, background color, and output format
  - Support for defaults to avoid repetition
  
  **Layer Types:**
  - image: Display uploaded images with fit modes (cover, contain, fill, inside, outside)
  - text: Text with custom fonts, alignment, wrapping, and effects
  - rectangle: Rectangular shapes with fill, stroke, and rounded corners
  - circle: Circular and elliptical shapes
  - gradient: Linear or radial color gradients
  
  **Positioning Options:**
  - x, y coordinates (pixels from top-left)
  - position strings: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right
  - position objects: { x: 0-1, y: 0-1, originX: left|center|right, originY: top|center|bottom }
  
  **Visual Effects:**
  - opacity: 0-1 transparency
  - rotation: degrees
  - blur: pixel radius
  - borderRadius: rounded corners (image, rectangle)
  
  **Text Features:**
  - Custom fonts via fontPath or Google Fonts via googleFont (format: 'FontName:weight' e.g. 'Roboto:600')
  - Text wrapping with width and lineHeight
  - Alignment: left, center, right
  - backgroundColor (single line only)
  
  **Output Formats:**
  - png: Lossless with transparency (default)
  - jpeg: Lossy compression (use quality parameter)
  - webp: Modern format with transparency and compression
  
  **Defaults System:**
  - defaults.layer: Properties for all layers
  - defaults.layerType.{type}: Properties for specific layer types
  
  File paths should be placeholders like "/image/2024-01-15/userXXX/filename.ext" or "/font/2024-01-15/userXXX/font.ttf".`,
            inputSchema: {
              type: 'object',
              properties: {
                width: {
                  type: 'number',
                  description: 'Canvas width in pixels (max 4096px)',
                  default: 1920,
                },
                height: {
                  type: 'number',
                  description: 'Canvas height in pixels (max 4096px)',
                  default: 1080,
                },
                backgroundColor: {
                  type: 'string',
                  description: 'Background color (hex, rgb, or named). Default: transparent',
                },
                format: {
                  type: 'string',
                  description: 'Output format: png (default, transparent), jpeg (compressed), webp (modern)',
                  enum: ['png', 'jpeg', 'webp'],
                  default: 'png',
                },
                quality: {
                  type: 'number',
                  description: 'Quality for JPEG/WebP (1-100, default: 90)',
                  default: 90,
                },
                defaults: {
                  type: 'object',
                  description: 'Default properties for layers',
                  properties: {
                    layer: {
                      type: 'object',
                      description: 'Properties applied to all layers',
                    },
                    layerType: {
                      type: 'object',
                      description: 'Properties per layer type (text, image, rectangle, circle, gradient)',
                    },
                  },
                },
                layers: {
                  type: 'array',
                  description: `Array of layer objects (max 50). Layer types:
  - image: { type: "image", path, x/y/position, width, height, fit, opacity, rotation, blur, borderRadius }
  - text: { type: "text", text, x/y/position, fontSize, fontPath/googleFont, color, align, wrap, width, lineHeight, backgroundColor, opacity, rotation, blur }
  - rectangle: { type: "rectangle", x, y, width, height, fill, stroke, strokeWidth, opacity, rotation, blur, borderRadius }
  - circle: { type: "circle", x, y, width, height, fill, stroke, strokeWidth, opacity, blur }
  - gradient: { type: "gradient", x, y, width, height, gradient: { type: linear/radial, colors: [], direction: horizontal/vertical/diagonal }, opacity, rotation, blur }`,
                  items: {
                    type: 'object',
                  },
                },
              },
              required: ['layers'],
            },
          },

• src/http-server.ts:149-306 (registration)

  Secondary registration in http-server.ts: registers the tool with name 'create_image_config', simpler schema, and routes to handleCreateImageConfig at line 260. The handler returns args as JSON string.

      tools: [
        {
          name: 'create_image_config',
          description:
            'Create a JSON configuration for image generation. Returns a complete image config that can be sent to the Jsoncut API. Supports multiple layer types (image, text, rectangle, circle, gradient) with advanced positioning and styling options.',
          inputSchema: {
            type: 'object',
            properties: {
              width: {
                type: 'number',
                description: 'Canvas width in pixels',
              },
              height: {
                type: 'number',
                description: 'Canvas height in pixels',
              },
              background: {
                type: 'string',
                description: 'Background color (hex, rgb, or rgba)',
              },
              format: {
                type: 'string',
                enum: ['png', 'jpeg', 'webp'],
                description: 'Output format',
              },
              layers: {
                type: 'array',
                description: 'Array of layer objects defining the composition',
              },
            },
            required: ['width', 'height', 'layers'],
          },
        },
        {
          name: 'create_video_config',
          description:
            'Create a JSON configuration for video generation. Returns a complete video config that can be sent to the Jsoncut API. Supports clips, multiple layer types, transitions, and audio.',
          inputSchema: {
            type: 'object',
            properties: {
              width: {
                type: 'number',
                description: 'Video width in pixels',
              },
              height: {
                type: 'number',
                description: 'Video height in pixels',
              },
              fps: {
                type: 'number',
                description: 'Frames per second',
              },
              clips: {
                type: 'array',
                description: 'Array of video clips',
              },
            },
            required: ['width', 'height', 'clips'],
          },
        },
        {
          name: 'validate_config',
          description:
            'Validate an image or video configuration against the Jsoncut API. Returns validation status, estimated token cost, and any errors.',
          inputSchema: {
            type: 'object',
            properties: {
              type: {
                type: 'string',
                enum: ['image', 'video'],
                description: 'Type of configuration to validate',
              },
              config: {
                type: 'object',
                description: 'The configuration to validate',
              },
              apiKey: {
                type: 'string',
                description: 'Optional API key (uses environment variable if not provided)',
              },
            },
            required: ['type', 'config'],
          },
        },
        {
          name: 'get_image_schema',
          description:
            'Get the complete JSON schema for image generation. Note: This schema is also available as an MCP resource at schema://image',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
        {
          name: 'get_video_schema',
          description:
            'Get the complete JSON schema for video generation. Note: This schema is also available as an MCP resource at schema://video',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
      ],
    }));
  
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;
  
      try {
        switch (name) {
          case 'create_image_config':
            return this.handleCreateImageConfig(args);
          case 'create_video_config':
            return this.handleCreateVideoConfig(args);
          case 'validate_config':
            return await this.handleValidateConfig(args);
          case 'get_image_schema':
            return this.handleGetImageSchema();
          case 'get_video_schema':
            return this.handleGetVideoSchema();
          default:
            throw new Error(`Unknown tool: ${name}`);
        }
      } catch (error: any) {
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
    });
  }
  
  private setupErrorHandling(): void {
    this.server.onerror = (error) => {
      console.error('[MCP Error]', error);
    };
  
    process.on('SIGINT', async () => {
      await this.server.close();
      process.exit(0);
    });
  }
  
  private handleCreateImageConfig(args: any) {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(args, null, 2),
        },
      ],
    };
  }

• src/http-server.ts:297-306 (handler)

  Secondary HTTP server handler for create_image_config. Returns args as a JSON string without building a structured config object (unlike the primary handler in index.ts).

  private handleCreateImageConfig(args: any) {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(args, null, 2),
        },
      ],
    };
  }