# aseprite-mcp

[English](README.md) | [中文](README_CN.md)

A TypeScript [Aseprite](https://www.aseprite.org/) MCP (Model Context Protocol) server.

It exposes Aseprite to LLM clients like Claude as 76 tools (drawing, layers, frames/cels, tilemaps, palettes, animation tweens, transforms, spritesheet export, ...), driving Aseprite headlessly by generating Lua scripts.

## How it works

Each tool turns a high-level intent into a Lua script, then runs it with `Aseprite -b --script <tmp.lua>` and returns the result. The Lua is wrapped in `xpcall`, so runtime errors come back with a full traceback.

## Requirements

- **Node.js ≥ 20** (developed on Node 24)
- **Aseprite** (CLI-capable; Steam or standalone install both work)

## Install

**From npm (recommended):**

```bash
npm install -g @letsagents/aseprite-mcp
```

After install, the `aseprite-mcp` command is available (see [Run](#run) and the MCP client config below).

**From source (development):**

```bash
git clone https://github.com/letsagents/aseprite-mcp.git
cd aseprite-mcp
npm install
npm run build      # tsc -> dist/
```

## Locating the Aseprite executable

The Aseprite binary is resolved in this priority order:

1. CLI flag `--aseprite-path <PATH>`
2. Environment variable `ASEPRITE_PATH`
3. `PATH` search (`aseprite` / `aseprite.exe`)
4. Common Windows install locations (Program Files, Steam, `%LOCALAPPDATA%\Programs\Aseprite`)
5. Error if none of the above is found

If your Aseprite is in a non-standard location (e.g. a Steam library on another drive), set it explicitly:

```bash
# Replace with the path to your Aseprite executable
export ASEPRITE_PATH="/path/to/your/Aseprite.exe"
```

## Output paths

This server **does not configure an output directory**. **Every `filename` argument must be an absolute path**, provided by the caller (you, or the LLM after asking you). If the LLM doesn't know where to save, it asks you for the output location before invoking the tool. There is no `--output-dir` flag, no `ASEPRITE_OUTPUT_DIR` env var, and no default output directory.

## Run

```bash
# After a global npm install:
aseprite-mcp

# From source:
npm start           # node dist/index.js
# Or during development:
npm run dev         # tsx src/index.ts (no build needed)
```

### Connect your MCP client

Standard stdio server, supporting Claude Code / Cursor / Cline / Codex, etc. For Claude Code, `.mcp.json`:

```jsonc
{
  "mcpServers": {
    "aseprite": {
      "type": "stdio",
      // Use the bin name after a global npm install; from source use "node" + the absolute path to dist/index.js
      "command": "aseprite-mcp",
      "env": {
        // Only needed when Aseprite isn't in a standard install location; otherwise the whole env block can be omitted
        "ASEPRITE_PATH": "/path/to/your/Aseprite.exe"
      }
    }
  }
}
```

Other clients (Cursor `.cursor/mcp.json` / Codex `config.toml`, etc.) use the same shape, just a different file location.

## Scripts

| Script | What it does |
|---|---|
| `npm run build` | Compile `src/` to `dist/` (excludes tests) |
| `npm run dev` | Run directly via `tsx` (no build) |
| `npm start` | Run the compiled server |
| `npm test` | Run all unit tests (`node:test`, zero extra deps) |
| `npm run typecheck` | `tsc --noEmit` type check |

## Tests

Tests use Node's built-in [`node:test`](https://nodejs.org/api/test.html) runner — no test framework dependency. They are pure unit tests (assertions on generated Lua strings + handler logic via a mock runner); **no test requires a real Aseprite install**.

```bash
npm test
```

## Project layout

```
src/
├── index.ts          # entry: CLI args + Aseprite location + stdio transport
├── server.ts         # McpServer: tools + 2 resources + 1 prompt
├── context.ts        # Ctx { runner, verbose }
├── runner.ts         # LuaRunner interface + RunOutcome
├── error.ts          # AsepriteError + JSON-RPC error code mapping
├── aseprite/         # path resolution + subprocess spawn (xpcall wrapper)
├── lua/              # color parsing, Lua escaping, emit/* (per-domain Lua gen)
└── tools/            # per-domain tool registration (schema + handler)
```

## Development guide

See [`AGENTS.md`](AGENTS.md) (cross-tool project instructions, shared by Codex / Cursor / Copilot / Gemini; architecture conventions + red lines + quick reference). The Claude Code entry is [`CLAUDE.md`](CLAUDE.md).

## License

[MIT](LICENSE)