Aseprite MCP Tools

Instructions

Implementation Reference

• aseprite_mcp/tools/canvas.py:91-124 (handler)

  The 'add_frame' tool handler that validates input, builds the script using 'LuaBuilder', and executes it.

  @mcp.tool()
  async def add_frame(filename: str, after_frame: Optional[int] = None) -> str:
      """Add a new frame to the Aseprite file.
  
      Args:
          filename: Name of the Aseprite file to modify
          after_frame: Frame index after which to add the new frame (0-based, optional)
      """
      try:
          # Validate inputs
          file_path = validate_file_path(filename, must_exist=True)
          
          # Build Lua script
          builder = LuaBuilder()
          builder.add_line('local spr = app.activeSprite')
          builder.if_condition('not spr')
          builder.add_line('error("No active sprite")')
          builder.end_if()
          builder.add_line()
          builder.begin_transaction()
          builder.add_frame(after_frame)
          builder.end_transaction()
          builder.save_sprite()
          
          # Execute script
          cmd = get_command()
          success, output = cmd.execute_lua_script(builder.build(), str(file_path))
          
          return f"New frame added successfully to {file_path}"
          
      except (ValidationError, AsepriteError) as e:
          return f"Failed to add frame: {e}"
      except Exception as e:
          return f"Unexpected error: {e}"

• aseprite_mcp/core/lua_builder.py:217-223 (helper)

  The helper method in 'LuaBuilder' that generates the actual Lua code for adding a frame to an Aseprite sprite.

  def add_frame(self, after_frame: Optional[int] = None) -> 'LuaBuilder':
      """Add a new frame to the sprite."""
      if after_frame is not None:
          self.add_line(f'app.activeSprite:newFrame({after_frame + 1})')  # Lua is 1-indexed
      else:
          self.add_line('app.activeSprite:newFrame()')
      return self