@iborymagic/aseprite-mcp 0.2.0 → 0.3.0

package/README.md

@@ -2,8 +2,8 @@
 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.
 
-*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.  
+*Currently, only character creation is possible, and not with images created through Aseprite.
 
 ## Features Overview
 ### V1 - Export/Utility
@@ -18,15 +18,27 @@ Adds deeper control using Aseprite Lua scripting, enabling safe AI-driven editin
 - `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
+  - `recolor_palette`: Palette recoloring
+  - `normalize_animation_speed`: Normalizing animation speed
   - `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)
 
+### V3 - Image Generation
+(+ Character Pipeline)
+- Adds connection with LLM and Image Generation AI, enabling import/export image in Aseprite.
+- Only available on Character Generation
+- `character_generate_concept`: Generating concept image using Generative AI
+- `character_import_from_concept`: Importing character concept from concept image
+- `character_generate_full`: Execute whole character generating pipeline
+  - `character_pipeline_analyze`: Analyze character concept image
+  - `character_pipeline_normalize`: Normalize your animations with fixed frames, crops, tags, etc.
+  - `character_pipeline_export`: Export animation in png + json format
+
+*You can change Image Generation AI by implementing ImageGenerator class in image-generator.ts
+
 ## How to use
 1) Run directly with npx
 ```bash
@@ -40,11 +52,11 @@ npm run build
 npx aseprite-mcp
 ```
 
-### Using with ChatGPT
-Add the following to your mcp.json
+### Using with Claude Desktop
+Add the following to your claude_desktop_config.json
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "aseprite-mcp": {
       "command": "npx",
       "args": ["-y", "aseprite-mcp"]
@@ -53,19 +65,8 @@ Add the following to your mcp.json
 }
 ```
 
-### Using with Claude
-Add the following to your servers.json
-```json
-{
-  "aseprite-mcp": {
-    "command": "npx",
-    "args": ["-y", "aseprite-mcp"]
-  }
-}
-```
-
 ### Using with Cursor
-Add the following to your .cursor.json
+Add the following to your mcp.json
 ```json
 {
   "mcpServers": {

package/build/aseprite/cli.js

@@ -2,14 +2,22 @@ import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { resolveAsepritePath } from "./env.js";
 const execAsync = promisify(exec);
-export async function runAsepriteCommand(args) {
+export async function runAsepriteCommand(args, timeout = 10_000) {
     const path = await resolveAsepritePath();
     const command = `"${path}" ${args.join(" ")}`;
     try {
-        const { stdout, stderr } = await execAsync(command);
-        return { command, stdout, stderr };
+        const { stdout, stderr } = await execAsync(command, { timeout });
+        return { command, stdout, stderr, timedOut: false };
     }
     catch (error) {
+        if (error.killed === true && error.code === null) {
+            return {
+                command,
+                stdout: "",
+                stderr: "Aseprite command timed out",
+                timedOut: true
+            };
+        }
         throw new Error(`Failed to run Aseprite command: ${command}\n${error instanceof Error ? error.message : String(error)}`);
     }
 }

package/build/aseprite/tools.js

@@ -135,11 +135,5 @@ export function createToolSchemas() {
             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/generator/image-generator.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import axios from "axios";
+export class StubImageGenerator {
+    async generate(params) {
+        throw new Error(`Image generator not configured. Tried to generate: "${params.prompt}" to ${params.outputPath}`);
+    }
+}
+export class StableDiffusionWebuiGenerator {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async generate(params) {
+        const url = `${this.baseUrl}/sdapi/v1/txt2img`;
+        const prompt = `${params.prompt}, ` +
+            `pixel art, retro 16-bit, clean outline, sharp edges, high contrast, game sprite`;
+        const negative = params.negativePrompt ??
+            "photo, realistic, blurry, lowres, smear, oil painting";
+        const body = {
+            prompt,
+            negative_prompt: negative,
+            width: params.width,
+            height: params.height,
+            steps: 28,
+            sampler_name: "DPM++ 2M",
+            cfg_scale: 7,
+            seed: params.seed ?? -1,
+            restore_faces: false,
+            tiling: false
+        };
+        const res = await axios.post(url, body, {
+            timeout: 1000 * 60 * 3
+        });
+        if (!res.data?.images?.length) {
+            throw new Error("Stable Diffusion returned no images");
+        }
+        const imgBase64 = res.data.images[0];
+        const buffer = Buffer.from(imgBase64, "base64");
+        const dir = path.dirname(params.outputPath);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(params.outputPath, buffer);
+        let seed = params.seed;
+        try {
+            const info = JSON.parse(res.data.info ?? "{}");
+            if (info.seed)
+                seed = info.seed;
+        }
+        catch { }
+        return {
+            imagePath: params.outputPath,
+            seed
+        };
+    }
+}

package/build/generator/tools.js

@@ -0,0 +1,210 @@
+import z from "zod";
+import { errorResult, successResult } from "../util.js";
+import { ensureSafePath } from "../aseprite/path.js";
+import path from "path";
+import fs from "node:fs/promises";
+import { runLuaScriptFile } from "../lua/cli.js";
+import { createToolHandlers as createPipelineToolHandlers } from "../pipeline/tools.js";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const toolSchemas = createToolSchemas();
+export function createToolHandlers() {
+    const character_generate_concept = async ({ params: { prompt, workspaceDir, fileName = "concept.png", width = 256, height = 256, seed, stylePreset = "pixel_art" } }, generator) => {
+        try {
+            const workspaceAbs = ensureSafePath(workspaceDir, { mustExist: false });
+            await fs.mkdir(workspaceAbs, { recursive: true });
+            const outputPath = path.join(workspaceAbs, fileName);
+            const result = await generator.generate({
+                prompt,
+                negativePrompt: undefined,
+                width,
+                height,
+                seed,
+                stylePreset,
+                outputPath
+            });
+            return successResult("character_generate_concept", {
+                prompt,
+                workspaceDir: workspaceAbs,
+                imagePath: result.imagePath,
+                seed: result.seed
+            });
+        }
+        catch (err) {
+            return errorResult("character_generate_concept", `Character generate concept failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const character_import_from_concept = async ({ params: { conceptImage, outputFile, spriteSize: spriteSizeParam = 0, animationSpec: animationSpecParam = "Idle:4" }, }) => {
+        try {
+            const conceptAbs = ensureSafePath(conceptImage, {
+                mustExist: true
+            });
+            const outputAbs = ensureSafePath(outputFile, {
+                mustExist: false
+            });
+            const spriteSize = spriteSizeParam ?? 0;
+            const animationSpec = animationSpecParam ?? "Idle:4";
+            // Lua templates are in the source directory, reference from project root
+            const luaScriptPath = path.join(process.cwd(), "src", "lua", "templates", "character_import_from_concept.lua");
+            const result = await runLuaScriptFile(luaScriptPath, {
+                conceptImage: conceptAbs,
+                outputFile: outputAbs,
+                spriteSize,
+                animationSpec
+            });
+            if (result.timedOut) {
+                return errorResult("character_import_from_concept", `Lua script timed out while importing from concept: ${luaScriptPath}`);
+            }
+            return successResult("character_import_from_concept", {
+                command: result.command,
+                conceptImage: conceptAbs,
+                outputFile: outputAbs,
+                spriteSize,
+                animationSpec
+            });
+        }
+        catch (err) {
+            return errorResult("character_import_from_concept", `Character import from concept failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const character_generate_full = async ({ params: { prompt, config, paths } }, generator) => {
+        try {
+            const spriteSize = config?.spriteSize ?? 32;
+            const animations = config?.animations ?? [
+                { name: "Idle", frames: 4 },
+                { name: "Walk", frames: 8 }
+            ];
+            const seed = config?.seed;
+            const charName = (paths.name ??
+                prompt
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, "_")
+                    .replace(/^_+|_+$/g, "")
+                    .slice(0, 32)) ||
+                "character";
+            const workspaceBase = ensureSafePath(paths.workspaceDir, {
+                mustExist: false
+            });
+            const exportBase = ensureSafePath(paths.exportDir, {
+                mustExist: false
+            });
+            const workspaceDir = path.join(workspaceBase, charName);
+            const exportDir = path.join(exportBase, charName);
+            await fs.mkdir(workspaceDir, { recursive: true });
+            await fs.mkdir(exportDir, { recursive: true });
+            const conceptResult = await character_generate_concept({
+                params: {
+                    prompt,
+                    workspaceDir,
+                    fileName: "concept.png",
+                    width: spriteSize * 8,
+                    height: spriteSize * 8,
+                    seed,
+                    stylePreset: "pixel_art"
+                }
+            }, generator);
+            const conceptContent = conceptResult.content?.[0];
+            const conceptJson = conceptContent
+                ? JSON.parse(conceptContent.text)
+                : null;
+            if (!conceptJson || !conceptJson.success) {
+                return errorResult("character_generate_full", {
+                    stage: "generate_concept",
+                    error: conceptJson?.error ?? "Concept generation failed"
+                });
+            }
+            const conceptImage = conceptJson.result.imagePath;
+            const animationSpec = animations
+                .map((a) => `${a.name}:${a.frames}`)
+                .join(",");
+            const outputFile = path.join(workspaceDir, `${charName}.aseprite`);
+            const importResult = await character_import_from_concept({
+                params: {
+                    conceptImage,
+                    outputFile,
+                    spriteSize,
+                    animationSpec
+                }
+            }, {});
+            const importContent = importResult.content?.[0];
+            const importJson = importContent ? JSON.parse(importContent.text) : null;
+            if (!importJson || !importJson.success) {
+                return errorResult("character_generate_full", {
+                    stage: "import_sprite",
+                    error: importJson?.error ?? "Sprite import failed"
+                });
+            }
+            const asepriteFile = importJson.result.outputFile;
+            const pipelineToolHandlers = createPipelineToolHandlers();
+            const buildResult = await pipelineToolHandlers.character_pipeline_build({
+                inputFile: asepriteFile,
+                exportDir
+            }, {});
+            const buildContent = buildResult.content?.[0];
+            const buildJson = buildContent ? JSON.parse(buildContent.text) : null;
+            if (!buildJson || !buildJson.success) {
+                return errorResult("character_generate_full", {
+                    stage: "pipeline_build",
+                    error: buildJson?.error ?? "Character pipeline build failed"
+                });
+            }
+            return successResult("character_generate_full", {
+                name: charName,
+                prompt,
+                spriteSize,
+                workspaceDir,
+                exportDir,
+                concept: conceptJson.result,
+                asepriteFile,
+                pipeline: buildJson.result
+            });
+        }
+        catch (err) {
+            return errorResult("character_generate_full", err instanceof Error ? err : new Error(String(err)));
+        }
+    };
+    return {
+        character_generate_concept: async (params, generator) => character_generate_concept(params, generator),
+        character_import_from_concept,
+        character_generate_full: async (params, generator) => character_generate_full(params, generator),
+    };
+}
+export function createToolSchemas() {
+    return {
+        character_generate_concept: z.object({
+            params: z.object({
+                prompt: z.string(),
+                workspaceDir: z.string(),
+                fileName: z.string().optional(),
+                width: z.number().optional(),
+                height: z.number().optional(),
+                seed: z.number().optional(),
+                stylePreset: z.string().optional(),
+            }),
+        }),
+        character_import_from_concept: z.object({
+            params: z.object({
+                conceptImage: z.string(),
+                outputFile: z.string(),
+                spriteSize: z.number().optional(),
+                animationSpec: z.string().optional(),
+            }),
+        }),
+        character_generate_full: z.object({
+            params: z.object({
+                prompt: z.string(),
+                config: z.object({
+                    spriteSize: z.number().optional(),
+                    animations: z.array(z.object({ name: z.string(), frames: z.number() })).optional(),
+                    seed: z.number().optional(),
+                }),
+                paths: z.object({
+                    workspaceDir: z.string(),
+                    exportDir: z.string(),
+                    name: z.string().optional(),
+                }),
+            }),
+        }),
+    };
+}

package/build/index.js

@@ -3,53 +3,75 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createToolHandlers as createAsepriteToolHandlers, createToolSchemas as createAsepriteToolSchemas } from "./aseprite/tools.js";
 import { createToolHandlers as createLuaToolHandlers, createToolSchemas as createLuaToolSchemas } from "./lua/tools.js";
+import { createToolHandlers as createCharacterPipelineToolHandlers, createToolSchemas as createCharacterPipelineToolSchemas } from "./pipeline/tools.js";
+import { createToolHandlers as createGeneratorToolHandlers, createToolSchemas as createGeneratorToolSchemas } from "./generator/tools.js";
+import { StableDiffusionWebuiGenerator } from "./generator/image-generator.js";
 const server = new McpServer({
     name: "aseprite-mcp",
     version: "0.1.0"
 });
 const asepriteToolSchemas = createAsepriteToolSchemas();
 const luaToolSchemas = createLuaToolSchemas();
+const characterPipelineToolSchemas = createCharacterPipelineToolSchemas();
+const generatorToolSchemas = createGeneratorToolSchemas();
 const asepriteToolHandlers = createAsepriteToolHandlers();
 const luaToolHandlers = createLuaToolHandlers();
-server.registerTool("aseprite_check_environment", {
-    description: "Check the environment of Aseprite",
-    inputSchema: undefined,
-    outputSchema: undefined,
-}, asepriteToolHandlers.aseprite_check_environment);
+const characterPipelineToolHandlers = createCharacterPipelineToolHandlers();
+const generatorToolHandlers = createGeneratorToolHandlers();
+server.registerTool("aseprite_check_environment", { description: "Check the environment of Aseprite" }, asepriteToolHandlers.aseprite_check_environment);
 server.registerTool("aseprite_export_sheet", {
     description: "Export Aseprite file to sprite sheet image",
     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: 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: 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_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,
-    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);
+server.registerTool("character_pipeline_analyze", {
+    description: "Analyze a character sprite",
+    inputSchema: characterPipelineToolSchemas.character_pipeline_analyze,
+}, characterPipelineToolHandlers.character_pipeline_analyze);
+server.registerTool("character_pipeline_normalize", {
+    description: "Normalize a character sprite",
+    inputSchema: characterPipelineToolSchemas.character_pipeline_normalize,
+}, characterPipelineToolHandlers.character_pipeline_normalize);
+server.registerTool("character_pipeline_export", {
+    description: "Export a character sprite",
+    inputSchema: characterPipelineToolSchemas.character_pipeline_export,
+}, characterPipelineToolHandlers.character_pipeline_export);
+server.registerTool("character_pipeline_build", {
+    description: "Build a character sprite",
+    inputSchema: characterPipelineToolSchemas.character_pipeline_build,
+}, characterPipelineToolHandlers.character_pipeline_build);
+const generator = new StableDiffusionWebuiGenerator("http://127.0.0.1:7860");
+server.registerTool("character_generate_concept", {
+    description: "Generate a character concept",
+    inputSchema: generatorToolSchemas.character_generate_concept,
+}, async (params) => generatorToolHandlers.character_generate_concept(params, generator));
+server.registerTool("character_import_from_concept", {
+    description: "Import a character from a concept",
+    inputSchema: generatorToolSchemas.character_import_from_concept,
+}, generatorToolHandlers.character_import_from_concept);
+server.registerTool("character_generate_full", {
+    description: "Generate a full character",
+    inputSchema: generatorToolSchemas.character_generate_full,
+}, async (params) => generatorToolHandlers.character_generate_full(params, generator));
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.log("Aseprite MCP server started");
 }
 main().catch(err => {
     console.error("MCP Error:", err);

package/build/lua/cli.js

@@ -0,0 +1,16 @@
+import { runAsepriteCommand } from "../aseprite/cli.js";
+import { ensureSafePath } from "../aseprite/path.js";
+export async function runLuaScriptFile(scriptPath, params) {
+    const args = ["--batch"];
+    if (typeof params.inputFile === "string") {
+        const inputAbs = ensureSafePath(params.inputFile, { mustExist: true });
+        args.push(`"${inputAbs}"`);
+    }
+    for (const [key, value] of Object.entries(params)) {
+        if (key === "inputFile" || value == null)
+            continue;
+        args.push("--script-param", `${key}="${String(value)}"`);
+    }
+    args.push("--script", `"${scriptPath}"`);
+    return runAsepriteCommand(args);
+}

package/build/lua/template.js

@@ -0,0 +1,79 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+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"],
+        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"],
+        scriptPath: path.join(__dirname, "templates", "normalize_animation_speed.lua")
+    },
+    {
+        id: "auto_crop_transparent",
+        description: "Automatically crops empty transparent borders of the sprite",
+        params: ["inputFile", "saveOutput"],
+        scriptPath: path.join(__dirname, "templates", "auto_crop_transparent.lua")
+    },
+    {
+        id: "merge_visible_layers",
+        description: "Merges currently visible layers and saves resulting flattened sprite",
+        params: ["inputFile", "saveOutput"],
+        scriptPath: path.join(__dirname, "templates", "merge_visible_layers.lua")
+    },
+    {
+        id: "export_layer_only",
+        description: "Exports only the specified layer to a flattened PNG",
+        params: ["inputFile", "layerName", "outputDir"],
+        scriptPath: path.join(__dirname, "templates", "export_layer_only.lua")
+    },
+    {
+        id: "export_tag_frames",
+        description: "Exports frames inside a specific animation tag to PNG files",
+        params: ["inputFile", "tag", "outputDir"],
+        optionalParams: ["filenamePrefix"],
+        scriptPath: path.join(__dirname, "templates", "export_tag_frames.lua")
+    },
+    {
+        id: "character_normalize",
+        description: "Normalizes frame durations inside all tags to a single target duration (in seconds).",
+        params: ["inputFile", "saveOutput", "targetMs"],
+        optionalParams: ["autoCrop"],
+        scriptPath: path.join(__dirname, "templates", "character_normalize.lua")
+    },
+    {
+        id: "character_export",
+        description: "Exports a character sprite",
+        params: ["inputFile", "exportDir", "sheetType", "format"],
+        scriptPath: path.join(__dirname, "templates", "character_export.lua")
+    },
+    {
+        id: "character_build",
+        description: "Builds a character sprite",
+        params: ["inputFile", "tempOutput", "exportDir", "normalizeOption", "exportOption"],
+        scriptPath: path.join(__dirname, "templates", "character_build.lua")
+    }
+];
+export function findLuaTemplate(id) {
+    return LUA_TEMPLATES.find(t => t.id === id);
+}

package/build/lua/tools.js

@@ -1,5 +1,6 @@
 import { errorResult, successResult } from "../util.js";
-import { findLuaTemplate, LUA_TEMPLATES, runLuaScript, runLuaTemplate } from "./templates.js";
+import { findLuaTemplate, LUA_TEMPLATES } from "./template.js";
+import { runLuaScriptFile } from "./cli.js";
 import { ensureSafePath } from "../aseprite/path.js";
 import path from "node:path";
 import z from "zod";
@@ -27,16 +28,27 @@ export function createToolHandlers() {
             return errorResult("aseprite_run_lua_template", new Error(`Missing required params: ${missing.join(", ")}`));
         }
         try {
-            const result = await runLuaTemplate(template, params);
+            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 stderrTrimmed = result.stderr.trim();
+            const stdoutTrimmed = result.stdout.trim();
+            if (stderrTrimmed && stderrTrimmed.includes("ERROR:")) {
+                return errorResult("aseprite_run_lua_template", `Script execution failed: ${stderrTrimmed}`);
+            }
+            if (stdoutTrimmed && stdoutTrimmed.includes("ERROR:")) {
+                return errorResult("aseprite_run_lua_template", `Script execution failed: ${stdoutTrimmed}`);
+            }
             return successResult("aseprite_run_lua_template", {
                 command: result.command,
                 templateId,
-                stdout: result.stdout.trim(),
-                stderr: result.stderr.trim()
+                stdout: stdoutTrimmed,
+                stderr: stderrTrimmed
             });
         }
         catch (err) {
-            return errorResult("aseprite_run_lua_template", new Error(`Execution failed: ${err instanceof Error ? err.message : String(err)}`));
+            return errorResult("aseprite_run_lua_template", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     };
     const aseprite_run_lua_script = async ({ scriptPath, scriptContent, params = {} }) => {
@@ -50,15 +62,26 @@ export function createToolHandlers() {
                 await fs.writeFile(tempPath, String(scriptContent), "utf8");
                 luaFilePath = tempPath;
             }
-            const result = await runLuaScript(luaFilePath, params);
+            const result = await runLuaScriptFile(luaFilePath, params);
+            if (result.timedOut) {
+                return errorResult("aseprite_run_lua_script", `Lua script timed out while executing script: ${luaFilePath}`);
+            }
+            const stderrTrimmed = result.stderr.trim();
+            const stdoutTrimmed = result.stdout.trim();
+            if (stderrTrimmed && stderrTrimmed.includes("ERROR:")) {
+                return errorResult("aseprite_run_lua_script", `Script execution failed: ${stderrTrimmed}`);
+            }
+            if (stdoutTrimmed && stdoutTrimmed.includes("ERROR:")) {
+                return errorResult("aseprite_run_lua_script", `Script execution failed: ${stdoutTrimmed}`);
+            }
             return successResult("aseprite_run_lua_script", {
                 command: result.command,
-                stdout: result.stdout.trim(),
-                stderr: result.stderr.trim()
+                stdout: stdoutTrimmed,
+                stderr: stderrTrimmed
             });
         }
         catch (err) {
-            return errorResult("aseprite_run_lua_script", new Error(`Execution failed: ${err instanceof Error ? err.message : String(err)}`));
+            return errorResult("aseprite_run_lua_script", `Execution failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     };
     return {
@@ -83,11 +106,5 @@ export function createToolSchemas() {
             .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/build/pipeline/character.js

@@ -0,0 +1,66 @@
+export function analyzeCharacterFromMetadata(inputFile, metaJson) {
+    const framesArray = Object.values(metaJson.frames);
+    const totalFrames = framesArray.length;
+    const width = metaJson.meta.size?.w ?? 0;
+    const height = metaJson.meta.size?.h ?? 0;
+    const tags = metaJson.meta.frameTags ?? [];
+    const tagAnalyses = [];
+    const warnings = [];
+    const recommendations = [];
+    const recommendedTags = ["Idle", "Walk", "Attack"];
+    for (const tag of tags) {
+        const { name, from, to } = tag;
+        const durationPattern = [];
+        const issues = [];
+        for (let i = from; i <= to; i++) {
+            const frame = framesArray[i];
+            if (frame) {
+                durationPattern.push(frame.duration);
+            }
+            else {
+                issues.push(`missing_frame_index_${i}`);
+            }
+        }
+        if (durationPattern.length > 1) {
+            const first = durationPattern[0];
+            const inconsistent = durationPattern.some((duration) => duration !== first);
+            if (inconsistent) {
+                issues.push("duration_inconsistent");
+            }
+        }
+        tagAnalyses.push({
+            name,
+            frames: to - from + 1,
+            from,
+            to,
+            durationPattern,
+            issues
+        });
+    }
+    const existingTagNames = new Set(tags.map((tag) => tag.name));
+    for (const tag of recommendedTags) {
+        const exists = Array.from(existingTagNames).some((tagName) => tagName.toLowerCase() === tag.toLowerCase());
+        if (!exists) {
+            warnings.push(`Missing recommended animation tag: ${tag}`);
+        }
+    }
+    if (tags.length === 0) {
+        warnings.push("No frame tags found. Consider defining Idle/Walk/Attack tags.");
+        recommendations.push("Define basic animation tags like Idle, Walk, and Attack.");
+    }
+    if (tagAnalyses.some((tagAnalysis) => tagAnalysis.issues.includes("duration_inconsistent"))) {
+        warnings.push("Some tags have inconsistent frame durations.");
+        recommendations.push("Normalize frame durations for smoother animations.");
+    }
+    return {
+        file: inputFile,
+        sprite: {
+            width,
+            height,
+            frames: totalFrames
+        },
+        tags: tagAnalyses,
+        warnings,
+        recommendations
+    };
+}

package/build/pipeline/tools.js

@@ -0,0 +1,226 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import z from "zod";
+import { errorResult, successResult } from "../util.js";
+import { analyzeCharacterFromMetadata } from "./character.js";
+import { ensureSafePath } from "../aseprite/path.js";
+import { runAsepriteCommand } from "../aseprite/cli.js";
+import { runLuaScriptFile } from "../lua/cli.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const toolSchemas = createToolSchemas();
+export function createToolHandlers() {
+    const character_pipeline_analyze = async ({ inputFile }) => {
+        try {
+            const inputAbs = ensureSafePath(inputFile, { mustExist: true });
+            const tempJsonPath = path.join(os.tmpdir(), `${inputFile}-analyze-${Date.now()}.json`);
+            const args = [
+                "--batch",
+                `"${inputAbs}"`,
+                "--data",
+                `"${tempJsonPath}"`,
+                "--list-tags",
+                "--list-layers"
+            ];
+            const result = await runAsepriteCommand(args);
+            const metaJson = await fs.readFile(tempJsonPath, "utf8");
+            const parsedMeta = JSON.parse(metaJson);
+            const analysis = analyzeCharacterFromMetadata(inputAbs, parsedMeta);
+            return successResult("character_pipeline_analyze", {
+                command: result.command,
+                inputFile: inputAbs,
+                analysis,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim(),
+            });
+        }
+        catch (err) {
+            return errorResult("character_pipeline_analyze", `Character analysis failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const character_pipeline_normalize = async ({ inputFile, saveOutput, targetMs, autoCrop }) => {
+        try {
+            const inputAbs = ensureSafePath(inputFile, { mustExist: true });
+            const baseDir = path.dirname(inputAbs);
+            const baseName = path.basename(inputAbs, path.extname(inputAbs));
+            const outputPath = saveOutput ??
+                path.join(baseDir, `${baseName}_normalized.aseprite`);
+            const outputAbs = ensureSafePath(outputPath, { mustExist: false });
+            const targetDuration = targetMs ?? 100;
+            const autoCropEnabled = autoCrop ?? true;
+            // Lua templates are in the source directory, reference from project root
+            const luaScriptPath = path.join(process.cwd(), "src", "lua", "templates", "character_normalize.lua");
+            const result = await runLuaScriptFile(luaScriptPath, {
+                inputFile: inputAbs,
+                saveOutput: outputAbs,
+                targetMs: targetDuration,
+                autoCrop: autoCropEnabled
+            });
+            if (result.timedOut) {
+                return errorResult("character_pipeline_normalize", "Lua script timed out while normalizing character");
+            }
+            return successResult("character_pipeline_normalize", {
+                command: result.command,
+                inputFile: inputAbs,
+                outputFile: outputAbs,
+                targetMs: targetDuration,
+                autoCrop: autoCropEnabled,
+                stdout: result.stdout.trim(),
+                stderr: result.stderr.trim(),
+            });
+        }
+        catch (err) {
+            return errorResult("character_pipeline_normalize", `Character normalization failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const character_pipeline_export = async ({ inputFile, exportDir, sheetType = "packed", format = "json-hash" }) => {
+        try {
+            const inputAbs = ensureSafePath(inputFile, { mustExist: true });
+            const exportDirAbs = ensureSafePath(exportDir, { mustExist: false });
+            await fs.mkdir(exportDirAbs, { recursive: true });
+            const tempJsonPath = path.join(os.tmpdir(), `${inputFile}-export-${Date.now()}.json`);
+            const metaArgs = [
+                "--batch",
+                `"${inputAbs}"`,
+                "--data",
+                `"${tempJsonPath}"`,
+                "--list-tags"
+            ];
+            await runAsepriteCommand(metaArgs);
+            const metaJson = await fs.readFile(tempJsonPath, "utf8");
+            const parsedMeta = JSON.parse(metaJson);
+            const tags = parsedMeta.meta.frameTags ?? [];
+            if (tags.length === 0) {
+                return errorResult("character_pipeline_export", "No tags found in sprite. Define animation tags before export.");
+            }
+            const baseName = path.basename(inputAbs, path.extname(inputAbs));
+            const generated = [];
+            for (const tag of tags) {
+                const tagName = tag.name;
+                const safeTag = tagName.toLowerCase();
+                const pngPath = path.join(exportDirAbs, `${baseName}_${safeTag}.png`);
+                const jsonPath = path.join(exportDirAbs, `${baseName}_${safeTag}.json`);
+                const args = [
+                    "--batch",
+                    `"${inputAbs}"`,
+                    "--tag",
+                    `"${tagName}"`,
+                    "--sheet",
+                    `"${pngPath}"`,
+                    "--data",
+                    `"${jsonPath}"`,
+                    "--sheet-type",
+                    sheetType,
+                    "--format",
+                    format
+                ];
+                await runAsepriteCommand(args);
+                generated.push({
+                    tag: tagName,
+                    png: pngPath,
+                    json: jsonPath,
+                    frames: tag.to - tag.from + 1
+                });
+            }
+            return successResult("character_pipeline_export", {
+                inputFile: inputAbs,
+                exportDir: exportDirAbs,
+                sheetType,
+                format,
+                generated,
+            });
+        }
+        catch (err) {
+            return errorResult("character_pipeline_export", `Character export failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const character_pipeline_build = async ({ inputFile, tempOutput, exportDir, normalizeOption = { targetMs: 100, autoCrop: true }, exportOption = { sheetType: "packed", format: "json-hash" } }) => {
+        try {
+            const inputAbs = ensureSafePath(inputFile, { mustExist: true });
+            const baseDir = path.dirname(inputAbs);
+            const baseName = path.basename(inputAbs, path.extname(inputAbs));
+            const normalizedOutput = tempOutput ??
+                path.join(baseDir, `${baseName}_normalized.aseprite`);
+            const exportDirAbs = ensureSafePath(exportDir, { mustExist: false });
+            const analyzeResponse = await character_pipeline_analyze({ inputFile: inputAbs }, {});
+            const analyzeContent = analyzeResponse.content[0];
+            const analyzeParsed = JSON.parse(analyzeContent.text);
+            if (!analyzeParsed.success) {
+                return errorResult("character_pipeline_build", analyzeParsed.error);
+            }
+            const normalizeResponse = await character_pipeline_normalize({
+                inputFile: inputAbs,
+                saveOutput: normalizedOutput,
+                targetMs: normalizeOption.targetMs,
+                autoCrop: normalizeOption.autoCrop,
+            }, {});
+            const normalizeContent = normalizeResponse.content[0];
+            const normalizeParsed = JSON.parse(normalizeContent.text);
+            if (!normalizeParsed.success) {
+                return errorResult("character_pipeline_build", normalizeParsed.error);
+            }
+            const exportResponse = await character_pipeline_export({
+                inputFile: normalizedOutput,
+                exportDir: exportDirAbs,
+                sheetType: exportOption.sheetType,
+                format: exportOption.format,
+            }, {});
+            const exportContent = exportResponse.content[0];
+            const exportParsed = JSON.parse(exportContent.text);
+            if (!exportParsed.success) {
+                return errorResult("character_pipeline_build", exportParsed.error);
+            }
+            return successResult("character_pipeline_build", {
+                inputFile: inputAbs,
+                normalizedFile: normalizedOutput,
+                exportDir: exportDirAbs,
+                analyze: analyzeParsed.result,
+                normalize: normalizeParsed.result,
+                export: exportParsed.result,
+            });
+        }
+        catch (err) {
+            return errorResult("character_pipeline_build", `Character pipeline failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    return {
+        character_pipeline_analyze,
+        character_pipeline_normalize,
+        character_pipeline_export,
+        character_pipeline_build,
+    };
+}
+export function createToolSchemas() {
+    return {
+        character_pipeline_analyze: z.object({
+            inputFile: z.string(),
+        }),
+        character_pipeline_normalize: z.object({
+            inputFile: z.string(),
+            saveOutput: z.string().optional(),
+            targetMs: z.number().optional(),
+            autoCrop: z.boolean().optional(),
+        }),
+        character_pipeline_export: z.object({
+            inputFile: z.string(),
+            exportDir: z.string(),
+            sheetType: z.enum(["packed", "rows"]).optional(),
+            format: z.enum(["json-hash", "json-array"]).optional(),
+        }),
+        character_pipeline_build: z.object({
+            inputFile: z.string(),
+            tempOutput: z.string().optional(),
+            exportDir: z.string(),
+            normalizeOption: z.object({
+                targetMs: z.number().optional(),
+                autoCrop: z.boolean().optional(),
+            }).optional(),
+            exportOption: z.object({
+                sheetType: z.enum(["packed", "rows"]).optional(),
+                format: z.enum(["json-hash", "json-array"]).optional(),
+            }).optional(),
+        }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iborymagic/aseprite-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for using Aseprite API",
   "main": "index.js",
   "type": "module",
@@ -18,7 +18,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "zod": "^4.2.1"
+    "axios": "^1.13.2",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^25.0.0",