generate_sprite

Instructions

Args:
    prompt: Description of the sprite to generate (e.g., "a blue slime monster")
    preset: Style preset to use (default, pixel_16, pixel_32, flat_ui, handpainted, etc.)
    width: Override width in pixels
    height: Override height in pixels
    negative_prompt: Additional things to avoid (appended to preset's negative prompt)
    seed: Random seed for reproducibility
    steps: Number of generation steps (more = higher quality but slower)
    save_to_file: Whether to save the image to disk
    filename: Custom filename (auto-generated if not provided)

Returns:
    JSON with base64 image data and metadata

Implementation Reference

• server/main.py:109-215 (handler)

  The complete handler function for the 'generate_sprite' tool. It is registered via the @mcp.tool() decorator. The function generates a sprite image using the backend (ComfyUI or mock), applies preset configurations, handles resizing, error handling, and optional file saving. The input schema is defined by the function parameters and docstring.

  @mcp.tool()
  async def generate_sprite(
      prompt: str,
      preset: str = "default",
      width: Optional[int] = None,
      height: Optional[int] = None,
      negative_prompt: Optional[str] = None,
      seed: Optional[int] = None,
      steps: Optional[int] = None,
      save_to_file: bool = False,
      filename: Optional[str] = None
  ) -> str:
      """Generate a single game sprite from a text description.
      
      Args:
          prompt: Description of the sprite to generate (e.g., "a blue slime monster")
          preset: Style preset to use (default, pixel_16, pixel_32, flat_ui, handpainted, etc.)
          width: Override width in pixels
          height: Override height in pixels
          negative_prompt: Additional things to avoid (appended to preset's negative prompt)
          seed: Random seed for reproducibility
          steps: Number of generation steps (more = higher quality but slower)
          save_to_file: Whether to save the image to disk
          filename: Custom filename (auto-generated if not provided)
      
      Returns:
          JSON with base64 image data and metadata
      """
      try:
          preset_config = get_preset(preset)
          
          # Build full prompt
          full_prompt = f"{preset_config.prompt_prefix}{prompt}{preset_config.prompt_suffix}"
          full_negative = preset_config.negative_prompt
          if negative_prompt:
              full_negative = f"{full_negative}, {negative_prompt}"
          
          # Use preset defaults or overrides
          img_width = width or preset_config.default_width
          img_height = height or preset_config.default_height
          gen_steps = steps or preset_config.steps
          
          render_width = img_width
          render_height = img_height
          should_downscale = (img_width < preset_config.default_width) or (img_height < preset_config.default_height)
          if should_downscale:
              render_width = preset_config.default_width
              render_height = preset_config.default_height
          
          
          # Generate image with timeout
          image_bytes = await asyncio.wait_for(
              backend.generate_image(
                  prompt=full_prompt,
                  negative_prompt=full_negative,
                  width=render_width,
                  height=render_height,
                  seed=seed,
                  steps=gen_steps,
                  cfg_scale=preset_config.cfg_scale,
                  sampler=preset_config.sampler,
                  scheduler=preset_config.scheduler
              ),
              timeout=300.0  # 5 minute timeout
          )
          
          
          if should_downscale:
              resample = Image.Resampling.NEAREST if preset.startswith("pixel") else Image.Resampling.LANCZOS
              image_bytes = resize_image(image_bytes, img_width, img_height, resample=resample)
          
          result = {
              "success": True,
              "backend": backend.get_name(),
              "backend_type": BACKEND_TYPE,
              "image_base64": image_to_base64(image_bytes),
              "width": img_width,
              "height": img_height,
              "preset": preset,
              "prompt": full_prompt,
              "hash": hash_image(image_bytes)
          }
          
          # Save to file if requested
          if save_to_file:
              output_dir = ensure_directory(OUTPUT_DIR / "sprites")
              fname = filename or generate_filename(prefix="sprite", suffix=preset)
              file_path = output_dir / fname
              file_path.write_bytes(image_bytes)
              result["file_path"] = str(file_path)
          
          return json.dumps(result, indent=2)
          
      except asyncio.TimeoutError:
          return json.dumps({
              "success": False,
              "error": "Generation timed out after 5 minutes",
              "backend": backend.get_name(),
              "backend_type": BACKEND_TYPE
          }, indent=2)
      except Exception as e:
          return json.dumps({
              "success": False,
              "error": str(e),
              "backend": backend.get_name(),
              "backend_type": BACKEND_TYPE
          }, indent=2)

• server/main.py:109-109 (registration)

  The @mcp.tool() decorator registers the generate_sprite function as an MCP tool.

  @mcp.tool()