@iborymagic/aseprite-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,32 @@
 # Aseprite-MCP
 This server automates Aseprite workflows using the Model Context Protocol (MCP).  
-It enables AI, chat assistants, and automation pipelines to directly execute Aseprite tasks such as sprite sheet export, frame extraction, and metadata output.  
+It enables AI, chat assistants, and automation pipelines to directly execute Aseprite tasks such as sprite sheet export, frame extraction, and metadata output.
+
 *Lua-based automation and high-level sprite/tile generation features are not included yet.  
 *Aseprite must be installed in order to use this MCP server.  
 
+## Features Overview
+### V1 - Export/Utility
+Supports fundamental Aseprite export workflow:
+- `aseprite_check_environment`: Checks Aseprite installation status, executable path, and version
+- `aseprite_export_sheet`: Exports a sprite sheet as PNG + JSON
+- `aseprite_export_frames`: Exports each animation frame as an individual PNG file
+- `aseprite_export_metadata`: Exports Aseprite metadata in JSON format
+
+### 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)
+  - `remove_layer_by_name`: Removing specific layers
+  - `export_tag_frames`: Palette recoloring
+  - `recolor_palette`: Normalizing animation speed
+  - `normalize_animation_speed`: Exporting only specific animation tags
+  - `auto_crop_transparent`: Removing empty transparent borders around the sprite
+  - `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)
+
 ## How to use
 1) Run directly with npx
 ```bash
@@ -53,9 +76,3 @@ Add the following to your .cursor.json
   }
 }
 ```
-
-## Tools
-- `aseprite_check_environment`: Checks Aseprite installation status, executable path, and version
-- `aseprite_export_sheet`: Exports a sprite sheet as PNG + JSON
-- `aseprite_export_frames`: Exports each animation frame as an individual PNG file
-- `aseprite_export_metadata`: Exports Aseprite metadata in JSON format

package/build/aseprite/env.js

@@ -33,7 +33,7 @@ function getSteamVdfPaths() {
                 path.join(os.homedir(), "Library/Application Support/Steam/steamapps/libraryfolders.vdf")
             ];
         default:
-            // linux
+            // Linux
             return [
                 path.join(os.homedir(), ".steam/steam/steamapps/libraryfolders.vdf"),
                 path.join(os.homedir(), ".local/share/Steam/steamapps/libraryfolders.vdf")
@@ -81,7 +81,8 @@ export function getSteamAsepritePaths() {
                     case "darwin":
                         paths.push(path.join(lib, "steamapps/common/Aseprite/Aseprite.app/Contents/MacOS/aseprite"));
                         break;
-                    default: // linux
+                    default:
+                        // Linux
                         paths.push(path.join(lib, "steamapps/common/Aseprite/aseprite"));
                         break;
                 }

package/build/aseprite/tools.js

@@ -0,0 +1,145 @@
+import z from "zod";
+import { resolveAsepritePath } from "./env.js";
+import { runAsepriteCommand } from "./cli.js";
+import { errorResult, successResult } from "../util.js";
+import { ensureSafePath } from "./path.js";
+import { readFileSync } from "node:fs";
+const toolSchemas = createToolSchemas();
+export function createToolHandlers() {
+    const aseprite_check_environment = async () => {
+        try {
+            const asepritePath = await resolveAsepritePath();
+            const { stdout: version } = await runAsepriteCommand(["--version"]);
+            return successResult("aseprite_check_environment", { path: asepritePath, version });
+        }
+        catch (e) {
+            return errorResult("aseprite_check_environment", e instanceof Error ? e.message : String(e));
+        }
+    };
+    const aseprite_export_sheet = async ({ inputFile, outputSheet, sheetType = "packed", dataFile, tag }) => {
+        try {
+            const inputAbsPath = ensureSafePath(inputFile, { mustExist: true });
+            const sheetAbsPath = ensureSafePath(outputSheet, { createDirIfNeeded: true });
+            const dataAbsPath = dataFile ? ensureSafePath(dataFile, { createDirIfNeeded: true }) : undefined;
+            const args = [
+                "--batch",
+                `"${inputAbsPath}"`,
+                "--sheet",
+                `"${sheetAbsPath}"`,
+                "--sheet-type",
+                sheetType
+            ];
+            if (tag)
+                args.push("--tag", `"${tag}"`);
+            if (dataAbsPath)
+                args.push("--data", `"${dataAbsPath}"`);
+            const result = await runAsepriteCommand(args);
+            return successResult("aseprite_export_sheet", {
+                command: result.command,
+                inputFile: inputAbsPath,
+                outputSheet: sheetAbsPath,
+                sheetType,
+                dataFile: dataAbsPath ? dataAbsPath : undefined,
+                tag: tag ? tag : undefined,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim(),
+            });
+        }
+        catch (e) {
+            return errorResult("aseprite_export_sheet", e instanceof Error ? e.message : String(e));
+        }
+    };
+    const aseprite_export_frames = async ({ inputFile, outputPattern, tag }) => {
+        try {
+            const inputAbsPath = ensureSafePath(inputFile, { mustExist: true });
+            const outputAbsPath = ensureSafePath(outputPattern, { createDirIfNeeded: true });
+            const args = [
+                "--batch",
+                `"${inputAbsPath}"`,
+                "--save-as",
+                `"${outputAbsPath}"`
+            ];
+            if (tag)
+                args.push("--tag", `"${tag}"`);
+            const result = await runAsepriteCommand(args);
+            return successResult("aseprite_export_frames", {
+                command: result.command,
+                inputFile: inputAbsPath,
+                outputPattern: outputAbsPath,
+                tag: tag ? tag : undefined,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim(),
+            });
+        }
+        catch (e) {
+            return errorResult("aseprite_export_frames", e instanceof Error ? e.message : String(e));
+        }
+    };
+    const aseprite_export_metadata = async ({ inputFile, dataFile, format }) => {
+        try {
+            const inputAbsPath = ensureSafePath(inputFile, { mustExist: true });
+            const dataAbsPath = ensureSafePath(dataFile, { createDirIfNeeded: true });
+            const args = [
+                "--batch",
+                `"${inputAbsPath}"`,
+                "--data",
+                `"${dataAbsPath}"`
+            ];
+            if (format)
+                args.push("--format", `"${format}"`);
+            const result = await runAsepriteCommand(args);
+            let metaText = "";
+            try {
+                metaText = readFileSync(dataAbsPath, "utf8");
+            }
+            catch (e) {
+                metaText = `Failed to read metadata: ${e instanceof Error ? e.message : String(e)}`;
+            }
+            return successResult("aseprite_export_metadata", {
+                command: result.command,
+                inputFile: inputAbsPath,
+                dataFile: dataAbsPath,
+                format: format ? format : undefined,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim(),
+                metadata: metaText,
+            });
+        }
+        catch (e) {
+            return errorResult("aseprite_export_metadata", e instanceof Error ? e.message : String(e));
+        }
+    };
+    return {
+        aseprite_check_environment,
+        aseprite_export_sheet,
+        aseprite_export_frames,
+        aseprite_export_metadata
+    };
+}
+export function createToolSchemas() {
+    return {
+        aseprite_export_sheet: z.object({
+            inputFile: z.string(),
+            outputSheet: z.string(),
+            sheetType: z.enum(["rows", "columns", "packed"]).optional().default("packed"),
+            dataFile: z.string().optional(),
+            tag: z.string().optional(),
+        }),
+        aseprite_export_frames: z.object({
+            inputFile: z.string(),
+            outputPattern: z.string(),
+            tag: z.string().optional(),
+        }),
+        aseprite_export_metadata: z.object({
+            inputFile: z.string(),
+            dataFile: z.string(),
+            format: z.string().optional(),
+        }),
+        aseprite_output_result: z.object({
+            content: z.array(z.object({
+                type: z.literal("text"),
+                text: z.string(),
+            })),
+        }),
+    };
+}

package/build/index.js

@@ -1,33 +1,51 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createToolHandlers, createToolSchemas } from "./tools.js";
+import { createToolHandlers as createAsepriteToolHandlers, createToolSchemas as createAsepriteToolSchemas } from "./aseprite/tools.js";
+import { createToolHandlers as createLuaToolHandlers, createToolSchemas as createLuaToolSchemas } from "./lua/tools.js";
 const server = new McpServer({
     name: "aseprite-mcp",
     version: "0.1.0"
 });
-const toolSchemas = createToolSchemas();
-const toolHandlers = createToolHandlers();
+const asepriteToolSchemas = createAsepriteToolSchemas();
+const luaToolSchemas = createLuaToolSchemas();
+const asepriteToolHandlers = createAsepriteToolHandlers();
+const luaToolHandlers = createLuaToolHandlers();
 server.registerTool("aseprite_check_environment", {
     description: "Check the environment of Aseprite",
     inputSchema: undefined,
     outputSchema: undefined,
-}, toolHandlers.aseprite_check_environment);
+}, asepriteToolHandlers.aseprite_check_environment);
 server.registerTool("aseprite_export_sheet", {
     description: "Export Aseprite file to sprite sheet image",
-    inputSchema: toolSchemas.aseprite_export_sheet,
-    outputSchema: toolSchemas.aseprite_output_result,
-}, toolHandlers.aseprite_export_sheet);
+    inputSchema: asepriteToolSchemas.aseprite_export_sheet,
+    outputSchema: asepriteToolSchemas.aseprite_output_result,
+}, asepriteToolHandlers.aseprite_export_sheet);
 server.registerTool("aseprite_export_frames", {
     description: "Export each frame of Aseprite file",
-    inputSchema: toolSchemas.aseprite_export_frames,
-    outputSchema: toolSchemas.aseprite_output_result,
-}, toolHandlers.aseprite_export_frames);
+    inputSchema: asepriteToolSchemas.aseprite_export_frames,
+    outputSchema: asepriteToolSchemas.aseprite_output_result,
+}, asepriteToolHandlers.aseprite_export_frames);
 server.registerTool("aseprite_export_metadata", {
     description: "Export metadata json from Aseprite file",
-    inputSchema: toolSchemas.aseprite_export_metadata,
-    outputSchema: toolSchemas.aseprite_output_result,
-}, toolHandlers.aseprite_export_metadata);
+    inputSchema: asepriteToolSchemas.aseprite_export_metadata,
+    outputSchema: asepriteToolSchemas.aseprite_output_result,
+}, asepriteToolHandlers.aseprite_export_metadata);
+server.registerTool("aseprite_list_lua_templates", {
+    description: "List available Aseprite Lua templates.",
+    inputSchema: undefined,
+    outputSchema: undefined,
+}, 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,
+    outputSchema: luaToolSchemas.lua_output_result,
+}, luaToolHandlers.aseprite_run_lua_template);
+server.registerTool("aseprite_run_lua_script", {
+    description: "Run a raw Lua script (advanced / unsafe).",
+    inputSchema: luaToolSchemas.aseprite_run_lua_script,
+    outputSchema: luaToolSchemas.lua_output_result,
+}, luaToolHandlers.aseprite_run_lua_script);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/build/lua/templates.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureSafePath } from "../aseprite/path.js";
+import { runAsepriteCommand } from "../aseprite/cli.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const LUA_TEMPLATES = [
+    {
+        id: "remove_layer_by_name",
+        description: "Removes a layer with a given name and saves to a new file (or overwrites).",
+        params: ["inputFile", "layerName"],
+        optionalParams: ["saveOutput"],
+        scriptPath: path.join(__dirname, "templates", "remove_layer_by_name.lua")
+    },
+    {
+        id: "export_tag_frames",
+        description: "Exports only the frames of a specific tag as PNG images.",
+        params: ["inputFile", "tag", "outputDir"],
+        optionalParams: ["filenamePrefix"],
+        scriptPath: path.join(__dirname, "templates", "export_tag_frames.lua")
+    },
+    {
+        id: "recolor_palette",
+        description: "Recolors the palette based on a mapping of from->to colors.",
+        params: ["inputFile", "saveOutput", "mapping"],
+        optionalParams: [],
+        scriptPath: path.join(__dirname, "templates", "recolor_palette.lua")
+    },
+    {
+        id: "normalize_animation_speed",
+        description: "Normalizes all frame durations to a single target duration (in seconds).",
+        params: ["inputFile", "saveOutput", "targetDuration"],
+        optionalParams: [],
+        scriptPath: path.join(__dirname, "templates", "normalize_animation_speed.lua")
+    }
+];
+export function findLuaTemplate(id) {
+    return LUA_TEMPLATES.find(t => t.id === id);
+}
+export async function runLuaTemplate(template, params) {
+    return runLua(template, params);
+}
+export async function runLuaScript(scriptPath, params) {
+    return runLua(scriptPath, params);
+}
+export async function runLua(script, params) {
+    const args = ["--batch"];
+    if (typeof params.inputFile === "string") {
+        const inputAbs = ensureSafePath(params.inputFile, { mustExist: true });
+        args.push(`"${inputAbs}"`);
+    }
+    const scriptPath = typeof script === "string" ? script : script.scriptPath;
+    args.push("--script", `"${scriptPath}"`);
+    for (const [key, value] of Object.entries(params)) {
+        if (key === "inputFile" || value == null)
+            continue;
+        args.push("--script-param", `${key}=${value}`);
+    }
+    return runAsepriteCommand(args);
+}

package/build/lua/tools.js

@@ -0,0 +1,93 @@
+import { errorResult, successResult } from "../util.js";
+import { findLuaTemplate, LUA_TEMPLATES, runLuaScript, runLuaTemplate } from "./templates.js";
+import { ensureSafePath } from "../aseprite/path.js";
+import path from "node:path";
+import z from "zod";
+import os from "node:os";
+import fs from "node:fs/promises";
+const toolSchemas = createToolSchemas();
+export function createToolHandlers() {
+    const aseprite_list_lua_templates = async () => {
+        return successResult("aseprite_list_lua_templates", {
+            templates: LUA_TEMPLATES.map(template => ({
+                id: template.id,
+                description: template.description,
+                params: template.params,
+                optionalParams: template.optionalParams ?? []
+            }))
+        });
+    };
+    const aseprite_run_lua_template = async ({ templateId, params = {} }) => {
+        const template = findLuaTemplate(templateId);
+        if (!template) {
+            return errorResult("aseprite_run_lua_template", 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(", ")}`));
+        }
+        try {
+            const result = await runLuaTemplate(template, params);
+            return successResult("aseprite_run_lua_template", {
+                command: result.command,
+                templateId,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim()
+            });
+        }
+        catch (err) {
+            return errorResult("aseprite_run_lua_template", new Error(`Execution failed: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    };
+    const aseprite_run_lua_script = async ({ scriptPath, scriptContent, params = {} }) => {
+        try {
+            let luaFilePath;
+            if (scriptPath) {
+                luaFilePath = ensureSafePath(scriptPath, { mustExist: true });
+            }
+            else {
+                const tempPath = path.join(os.tmpdir(), `aseprite-mcp-${Date.now()}.lua`);
+                await fs.writeFile(tempPath, String(scriptContent), "utf8");
+                luaFilePath = tempPath;
+            }
+            const result = await runLuaScript(luaFilePath, params);
+            return successResult("aseprite_run_lua_script", {
+                command: result.command,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim()
+            });
+        }
+        catch (err) {
+            return errorResult("aseprite_run_lua_script", new Error(`Execution failed: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    };
+    return {
+        aseprite_list_lua_templates,
+        aseprite_run_lua_template,
+        aseprite_run_lua_script
+    };
+}
+;
+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()
+        })
+            .refine(v => !!v.scriptPath || !!v.scriptContent, {
+            message: "Either scriptPath or scriptContent is required."
+        }),
+        lua_output_result: z.object({
+            content: z.array(z.object({
+                type: z.literal("text"),
+                text: z.string()
+            }))
+        })
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iborymagic/aseprite-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for using Aseprite API",
   "main": "index.js",
   "type": "module",
@@ -14,19 +14,24 @@
     "build": "tsc",
     "start": "node build/index.js",
     "dev": "npm run build && npm run start",
-    "test": "jest --runInBand --slient=false"
+    "test": "vitest"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@types/jest": "^30.0.0",
     "@types/node": "^25.0.0",
-    "jest": "^30.2.0",
-    "ts-jest": "^29.4.6",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
   },
   "author": "iborymagic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iborymagic/aseprite-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/iborymagic/aseprite-mcp/issues"
+  },
   "license": "MIT"
 }