@iborymagic/aseprite-mcp 0.3.6 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ Supports fundamental Aseprite export workflow:
 ### V2 - Lua Automation
 Adds deeper control using Aseprite Lua scripting, enabling safe AI-driven editing operations such as:
 - `aseprite_list_lua_templates`: Lists available Lua templates
-- `aseprite_run_lua_template`: Runs a predefined safe Lua automation(templates)
+- Predefined safe Lua automation(templates)
   - `remove_layer_by_name`: Removing specific layers
   - `recolor_palette`: Palette recoloring
   - `normalize_animation_speed`: Normalizing animation speed
@@ -23,7 +23,7 @@ Adds deeper control using Aseprite Lua scripting, enabling safe AI-driven editin
   - `export_layer_only`: Exporting only a specific layer as a flattened PNG image
   - `export_tag_frames`: Exporting all frames within a specific animation tag as individual PNG files
   - `merge_visible_layers`: Merging all currently visible layers into a single layer
-- `aseprite_run_lua`: Executes a raw Lua script (advanced / unsafe)
+- `aseprite_run_lua_script`: Executes a raw Lua script (advanced / unsafe)
 
 ## How to use
 1) Run directly with npx

package/build/index.js

@@ -36,10 +36,66 @@ server.registerTool("aseprite_export_metadata", {
     inputSchema: asepriteToolSchemas.aseprite_export_metadata,
 }, asepriteToolHandlers.aseprite_export_metadata);
 server.registerTool("aseprite_list_lua_templates", { description: "List available Aseprite Lua templates." }, luaToolHandlers.aseprite_list_lua_templates);
-server.registerTool("aseprite_run_lua_template", {
-    description: "Run a predefined Aseprite Lua template with parameters.",
-    inputSchema: luaToolSchemas.aseprite_run_lua_template,
-}, luaToolHandlers.aseprite_run_lua_template);
+server.registerTool("auto_crop_transparent", {
+    description: "Automatically crops empty transparent borders of the sprite",
+    inputSchema: luaToolSchemas.auto_crop_transparent,
+}, luaToolHandlers.auto_crop_transparent);
+server.registerTool("merge_visible_layers", {
+    description: "Merges all currently visible layers into a single layer",
+    inputSchema: luaToolSchemas.merge_visible_layers,
+}, luaToolHandlers.merge_visible_layers);
+server.registerTool("normalize_animation_speed", {
+    description: "Normalizes all frame durations to a single target duration (in seconds)",
+    inputSchema: luaToolSchemas.normalize_animation_speed,
+}, luaToolHandlers.normalize_animation_speed);
+server.registerTool("recolor_palette", {
+    description: "Recolors the palette based on a mapping of from->to colors",
+    inputSchema: luaToolSchemas.recolor_palette,
+}, luaToolHandlers.recolor_palette);
+server.registerTool("remove_layer_by_name", {
+    description: "Removes a layer with a given name and saves to a new file (or overwrites)",
+    inputSchema: luaToolSchemas.remove_layer_by_name,
+}, luaToolHandlers.remove_layer_by_name);
+server.registerTool("export_layer_only", {
+    description: "Exports only the specified layer to a flattened PNG",
+    inputSchema: luaToolSchemas.export_layer_only,
+}, luaToolHandlers.export_layer_only);
+server.registerTool("export_tag_frames", {
+    description: "Exports frames inside a specific animation tag to PNG files",
+    inputSchema: luaToolSchemas.export_tag_frames,
+}, luaToolHandlers.export_tag_frames);
+server.registerTool("get_is_layer_exists", {
+    description: "Checks if a layer exists in the active sprite",
+    inputSchema: luaToolSchemas.get_is_layer_exists,
+}, luaToolHandlers.get_is_layer_exists);
+server.registerTool("get_is_tag_exists", {
+    description: "Checks if a tag exists in the active sprite",
+    inputSchema: luaToolSchemas.get_is_tag_exists,
+}, luaToolHandlers.get_is_tag_exists);
+server.registerTool("get_palette_info", {
+    description: "Gets information about the palette of the active sprite",
+    inputSchema: luaToolSchemas.get_palette_info,
+}, luaToolHandlers.get_palette_info);
+server.registerTool("get_selection_bounds", {
+    description: "Gets the bounds of the selection in the active sprite",
+    inputSchema: luaToolSchemas.get_selection_bounds,
+}, luaToolHandlers.get_selection_bounds);
+server.registerTool("get_tag_list", {
+    description: "Gets a list of all tags in the active sprite",
+    inputSchema: luaToolSchemas.get_tag_list,
+}, luaToolHandlers.get_tag_list);
+server.registerTool("get_layer_list", {
+    description: "Gets a list of all layers in the active sprite",
+    inputSchema: luaToolSchemas.get_layer_list,
+}, luaToolHandlers.get_layer_list);
+server.registerTool("get_frame_info", {
+    description: "Gets information about the current frame",
+    inputSchema: luaToolSchemas.get_frame_info,
+}, luaToolHandlers.get_frame_info);
+server.registerTool("get_active_sprite_info", {
+    description: "Gets information about the active sprite",
+    inputSchema: luaToolSchemas.get_active_sprite_info,
+}, luaToolHandlers.get_active_sprite_info);
 server.registerTool("aseprite_run_lua_script", {
     description: "Run a raw Lua script (advanced / unsafe).",
     inputSchema: luaToolSchemas.aseprite_run_lua_script,

package/build/lua/template.js

@@ -53,6 +53,54 @@ export const LUA_TEMPLATES = [
         params: ["inputFile", "tag", "outputDir"],
         optionalParams: ["filenamePrefix"],
         scriptPath: path.join(__dirname, "templates", "export_tag_frames.lua")
+    },
+    {
+        id: "get_is_layer_exists",
+        description: "Checks if a layer exists in the active sprite",
+        params: ["layerName"],
+        scriptPath: path.join(__dirname, "templates", "get_is_layer_exists.lua")
+    },
+    {
+        id: "get_is_tag_exists",
+        description: "Checks if a tag exists in the active sprite",
+        params: ["tagName"],
+        scriptPath: path.join(__dirname, "templates", "get_is_tag_exists.lua")
+    },
+    {
+        id: "get_palette_info",
+        description: "Gets information about the palette of the active sprite",
+        params: [],
+        scriptPath: path.join(__dirname, "templates", "get_palette_info.lua")
+    },
+    {
+        id: "get_selection_bounds",
+        description: "Gets the bounds of the selection in the active sprite",
+        params: [],
+        scriptPath: path.join(__dirname, "templates", "get_selection_bounds.lua")
+    },
+    {
+        id: "get_tag_list",
+        description: "Gets a list of all tags in the active sprite",
+        params: [],
+        scriptPath: path.join(__dirname, "templates", "get_tag_list.lua")
+    },
+    {
+        id: "get_layer_list",
+        description: "Gets a list of all layers in the active sprite",
+        params: [],
+        scriptPath: path.join(__dirname, "templates", "get_layer_list.lua")
+    },
+    {
+        id: "get_frame_info",
+        description: "Gets information about the current frame",
+        params: [],
+        scriptPath: path.join(__dirname, "templates", "get_frame_info.lua")
+    },
+    {
+        id: "get_active_sprite_info",
+        description: "Gets information about the active sprite",
+        params: [],
+        scriptPath: path.join(__dirname, "templates", "get_active_sprite_info.lua")
     }
 ];
 export function findLuaTemplate(id) {

package/build/lua/tools.js

@@ -18,40 +18,319 @@ export function createToolHandlers() {
             }))
         });
     };
-    const aseprite_run_lua_template = async ({ templateId, params = {} }) => {
+    const run_lua_template = async ({ templateId, params }) => {
         const template = findLuaTemplate(templateId);
         if (!template) {
-            return errorResult("aseprite_run_lua_template", new Error(`Unknown templateId: ${templateId}`));
+            throw new Error(`Unknown templateId: ${templateId}`);
         }
         const missing = template.params.filter(key => !params.hasOwnProperty(key));
         if (missing.length > 0) {
-            return errorResult("aseprite_run_lua_template", new Error(`Missing required params: ${missing.join(", ")}`));
+            throw new Error(`Missing required params: ${missing.join(", ")}`);
         }
+        const result = await runLuaScriptFile(template.scriptPath, params);
+        if (result.timedOut) {
+            throw new Error(`Lua script timed out while executing template: ${templateId}`);
+        }
+        const stderrTrimmed = result.stderr.trim();
+        const stdoutTrimmed = result.stdout.trim();
+        if (stderrTrimmed && stderrTrimmed.includes("ERROR:")) {
+            throw new Error(`Script execution failed: ${stderrTrimmed}`);
+        }
+        if (stdoutTrimmed && stdoutTrimmed.includes("ERROR:")) {
+            throw new Error(`Script execution failed: ${stdoutTrimmed}`);
+        }
+        return {
+            command: result.command,
+            stdout: stdoutTrimmed,
+            stderr: stderrTrimmed,
+        };
+    };
+    const auto_crop_transparent = async ({ saveOutput, inputFile }) => {
         try {
-            const result = await runLuaScriptFile(template.scriptPath, params);
-            if (result.timedOut) {
-                return errorResult("aseprite_run_lua_template", `Lua script timed out while executing template: ${templateId}`);
+            const result = await run_lua_template({
+                templateId: "auto_crop_transparent",
+                params: {
+                    inputFile,
+                    saveOutput: ensureSafePath(saveOutput, { createDirIfNeeded: true })
+                }
+            });
+            return successResult("auto_crop_transparent", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("auto_crop_transparent", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const merge_visible_layers = async ({ saveOutput, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "merge_visible_layers",
+                params: {
+                    inputFile,
+                    saveOutput: ensureSafePath(saveOutput, { createDirIfNeeded: true })
+                }
+            });
+            return successResult("merge_visible_layers", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("merge_visible_layers", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const normalize_animation_speed = async ({ saveOutput, targetDuration, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "normalize_animation_speed",
+                params: {
+                    inputFile,
+                    saveOutput: ensureSafePath(saveOutput, { createDirIfNeeded: true }),
+                    targetDuration
+                }
+            });
+            return successResult("normalize_animation_speed", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("normalize_animation_speed", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const recolor_palette = async ({ saveOutput, mapping, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "recolor_palette",
+                params: {
+                    saveOutput: ensureSafePath(saveOutput, { createDirIfNeeded: true }),
+                    mapping,
+                    inputFile
+                }
+            });
+            return successResult("recolor_palette", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("recolor_palette", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const remove_layer_by_name = async ({ layerName, saveOutput, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "remove_layer_by_name",
+                params: {
+                    layerName,
+                    saveOutput: ensureSafePath(saveOutput, { createDirIfNeeded: true }),
+                    inputFile
+                }
+            });
+            return successResult("remove_layer_by_name", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("remove_layer_by_name", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const export_layer_only = async ({ layerName, outputDir, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "export_layer_only",
+                params: {
+                    layerName,
+                    outputDir: ensureSafePath(outputDir, { createDirIfNeeded: true }),
+                    inputFile
+                }
+            });
+            return successResult("export_layer_only", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("export_layer_only", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const export_tag_frames = async ({ tag, outputDir, filenamePrefix, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "export_tag_frames",
+                params: {
+                    tag,
+                    outputDir: ensureSafePath(outputDir, { createDirIfNeeded: true }),
+                    filenamePrefix: filenamePrefix,
+                    inputFile
+                }
+            });
+            return successResult("export_tag_frames", {
+                command: result.command,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
+        catch (err) {
+            return errorResult("export_tag_frames", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_is_layer_exists = async ({ layerName, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_is_layer_exists",
+                params: { layerName, inputFile }
+            });
+            // Parse the boolean result from stdout
+            // Aseprite outputs Lua return values as JSON
+            const stdoutTrimmed = result.stdout.trim();
+            let exists;
+            if (stdoutTrimmed === "") {
+                // Empty stdout might mean false or error
+                exists = false;
             }
-            const stderrTrimmed = result.stderr.trim();
+            else {
+                try {
+                    // Aseprite outputs Lua return values as JSON
+                    const parsed = JSON.parse(stdoutTrimmed);
+                    exists = parsed === true;
+                }
+                catch {
+                    // If not valid JSON, try string comparison
+                    exists = stdoutTrimmed.toLowerCase() === "true" || stdoutTrimmed === "1";
+                }
+            }
+            return successResult("get_is_layer_exists", exists);
+        }
+        catch (err) {
+            return errorResult("get_is_layer_exists", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_is_tag_exists = async ({ tagName, inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_is_tag_exists",
+                params: { tagName, inputFile }
+            });
+            // Parse the boolean result from stdout
+            // Aseprite outputs Lua return values as JSON
             const stdoutTrimmed = result.stdout.trim();
-            if (stderrTrimmed && stderrTrimmed.includes("ERROR:")) {
-                return errorResult("aseprite_run_lua_template", `Script execution failed: ${stderrTrimmed}`);
+            let exists;
+            if (stdoutTrimmed === "") {
+                // Empty stdout might mean false or error
+                exists = false;
             }
-            if (stdoutTrimmed && stdoutTrimmed.includes("ERROR:")) {
-                return errorResult("aseprite_run_lua_template", `Script execution failed: ${stdoutTrimmed}`);
+            else {
+                try {
+                    // Aseprite outputs Lua return values as JSON
+                    const parsed = JSON.parse(stdoutTrimmed);
+                    exists = parsed === true;
+                }
+                catch {
+                    // If not valid JSON, try string comparison
+                    exists = stdoutTrimmed.toLowerCase() === "true" || stdoutTrimmed === "1";
+                }
             }
-            return successResult("aseprite_run_lua_template", {
-                command: result.command,
-                templateId,
-                stdout: stdoutTrimmed,
-                stderr: stderrTrimmed
+            return successResult("get_is_tag_exists", exists);
+        }
+        catch (err) {
+            return errorResult("get_is_tag_exists", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_palette_info = async ({ inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_palette_info",
+                params: { inputFile }
+            });
+            // Parse the JSON result from stdout
+            const parsedResult = JSON.parse(result.stdout.trim());
+            return successResult("get_palette_info", parsedResult);
+        }
+        catch (err) {
+            return errorResult("get_palette_info", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_selection_bounds = async ({ inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_selection_bounds",
+                params: { inputFile }
+            });
+            // Parse the JSON result from stdout
+            const parsedResult = JSON.parse(result.stdout.trim());
+            return successResult("get_selection_bounds", parsedResult);
+        }
+        catch (err) {
+            return errorResult("get_selection_bounds", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_tag_list = async ({ inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_tag_list",
+                params: { inputFile }
+            });
+            // Parse the JSON result from stdout
+            const parsedResult = JSON.parse(result.stdout.trim());
+            return successResult("get_tag_list", parsedResult);
+        }
+        catch (err) {
+            return errorResult("get_tag_list", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_layer_list = async ({ inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_layer_list",
+                params: { inputFile }
+            });
+            // Parse the JSON result from stdout
+            const parsedResult = JSON.parse(result.stdout.trim());
+            return successResult("get_layer_list", parsedResult);
+        }
+        catch (err) {
+            return errorResult("get_layer_list", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_frame_info = async ({ inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_frame_info",
+                params: { inputFile }
+            });
+            // Parse the JSON result from stdout
+            const parsedResult = JSON.parse(result.stdout.trim());
+            return successResult("get_frame_info", parsedResult);
+        }
+        catch (err) {
+            return errorResult("get_frame_info", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const get_active_sprite_info = async ({ inputFile }) => {
+        try {
+            const result = await run_lua_template({
+                templateId: "get_active_sprite_info",
+                params: { inputFile }
             });
+            // Parse the JSON result from stdout
+            const parsedResult = JSON.parse(result.stdout.trim());
+            return successResult("get_active_sprite_info", parsedResult);
         }
         catch (err) {
-            return errorResult("aseprite_run_lua_template", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
+            return errorResult("get_active_sprite_info", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     };
-    const aseprite_run_lua_script = async ({ scriptPath, scriptContent, params = {} }) => {
+    const aseprite_run_lua_script = async ({ scriptPath, scriptContent, params }) => {
         try {
             let luaFilePath;
             if (scriptPath) {
@@ -86,25 +365,97 @@ export function createToolHandlers() {
     };
     return {
         aseprite_list_lua_templates,
-        aseprite_run_lua_template,
-        aseprite_run_lua_script
+        aseprite_run_lua_script,
+        auto_crop_transparent,
+        merge_visible_layers,
+        normalize_animation_speed,
+        recolor_palette,
+        remove_layer_by_name,
+        export_layer_only,
+        export_tag_frames,
+        get_is_layer_exists,
+        get_is_tag_exists,
+        get_palette_info,
+        get_selection_bounds,
+        get_tag_list,
+        get_layer_list,
+        get_frame_info,
+        get_active_sprite_info,
     };
 }
 ;
 export function createToolSchemas() {
     return {
-        aseprite_run_lua_template: z.object({
-            templateId: z.string(),
-            params: z.record(z.string(), z.any()).optional()
-        }),
         aseprite_run_lua_script: z
             .object({
             scriptPath: z.string().optional(),
             scriptContent: z.string().optional(),
-            params: z.record(z.string(), z.any()).optional()
+            params: z.object({
+                inputFile: z.string(),
+            }).passthrough()
         })
             .refine(v => !!v.scriptPath || !!v.scriptContent, {
             message: "Either scriptPath or scriptContent is required."
         }),
+        auto_crop_transparent: z.object({
+            saveOutput: z.string(),
+            inputFile: z.string(),
+        }),
+        merge_visible_layers: z.object({
+            saveOutput: z.string(),
+            inputFile: z.string(),
+        }),
+        normalize_animation_speed: z.object({
+            saveOutput: z.string(),
+            targetDuration: z.number(),
+            inputFile: z.string(),
+        }),
+        recolor_palette: z.object({
+            saveOutput: z.string(),
+            mapping: z.string(),
+            inputFile: z.string(),
+        }),
+        remove_layer_by_name: z.object({
+            layerName: z.string(),
+            saveOutput: z.string(),
+            inputFile: z.string(),
+        }),
+        export_layer_only: z.object({
+            layerName: z.string(),
+            outputDir: z.string(),
+            inputFile: z.string(),
+        }),
+        export_tag_frames: z.object({
+            tag: z.string(),
+            outputDir: z.string(),
+            filenamePrefix: z.string().optional(),
+            inputFile: z.string(),
+        }),
+        get_is_layer_exists: z.object({
+            layerName: z.string(),
+            inputFile: z.string(),
+        }),
+        get_is_tag_exists: z.object({
+            tagName: z.string(),
+            inputFile: z.string(),
+        }),
+        get_palette_info: z.object({
+            inputFile: z.string(),
+        }),
+        get_selection_bounds: z.object({
+            inputFile: z.string(),
+        }),
+        get_tag_list: z.object({
+            inputFile: z.string(),
+        }),
+        get_layer_list: z.object({
+            inputFile: z.string(),
+        }),
+        get_frame_info: z.object({
+            inputFile: z.string(),
+        }),
+        get_active_sprite_info: z.object({
+            inputFile: z.string(),
+        }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iborymagic/aseprite-mcp",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "MCP server for using Aseprite API",
   "main": "index.js",
   "type": "module",