convez.ai
MCP Server
Shexiaoyun

aseprite-mcp

Shexiaoyun/aseprite-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Aseprite MCP Server - AI-assisted pixel art creation via Aseprite native Lua extension

Instalação

$npx convez-ai Shexiaoyun/aseprite-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Aseprite MCP Server

中文 | 日本語

AI-assisted pixel art creation for Aseprite via the Model Context Protocol (MCP).

Connect your favorite AI client (Claude, Cursor, DeepChat, etc.) directly to Aseprite. Draw, erase, fill, and manipulate your sprites using natural language instructions.


📐 Architecture

┌─────────────────────┐      stdio (MCP)       ┌──────────────────────────┐
│   AI Client         │  ◄──────────────────►  │   MCP Server (Node.js)   │
│   Claude / Cursor   │                        │   • Tool Registration    │
│   / DeepChat / ...  │                        │   • Request Routing      │
└─────────────────────┘                        │   • WebSocket Bridge     │
                                               └──────────┬───────────────┘
                                                          │ WebSocket
                                               ┌──────────▼───────────────┐
                                               │   Aseprite Extension     │
                                               │   (Lua + WebSocket)      │
                                               │   • Command Gateway      │
                                               │   • Tool Dispatcher      │
                                               │   • app.useTool() API    │
                                               └──────────────────────────┘

Why this direction?
Aseprite's WebSocket() API can only act as a client connecting to a URL. It cannot listen on a port. Therefore, the MCP Server must host the WebSocket Server, and the Aseprite extension connects to it.

Communication Flow

  1. AI Client sends a use_tool request via MCP stdio to the MCP Server
  2. MCP Server validates parameters, generates a request_id, and sends an AsepriteRequest over WebSocket
  3. Aseprite Extension receives the request, routes to the appropriate tool handler, and calls app.useTool()
  4. Aseprite Extension returns a tri-state response (completed / failed / rejected) with the same request_id
  5. MCP Server matches the response to the pending Promise and maps it to an MCP CallToolResult
  6. AI Client receives the result (success or detailed error)

🛠 Technology Stack

LayerTechnologyPurpose
AI ↔ MCP@modelcontextprotocol/sdkMCP protocol implementation over stdio
MCP ServerTypeScript / Node.jsTool registration, validation, request routing
WebSocket Bridgews (npm)WebSocket Server, heartbeat, request-timeout matching
ProtocolJSON (AsepriteRequest / AsepriteResponse)Tri-state response model
Aseprite ExtensionLua (Aseprite API v25+)WebSocket client, command gateway, tool dispatch
Tool ImplementationLua (app.useTool())Pixel-level drawing operations

Key Design Decisions

  • No external JSON library: Aseprite v1.3-rc5+ has built-in json.encode() / json.decode()
  • No uuid package: Node.js 19+ provides crypto.randomUUID() natively
  • Modular Lua architecture: Gateway dispatcher in mcp-bridge.lua, individual tools in tools/*.lua loaded via require()
  • Dual timeout strategy: WebSocket ping/pong heartbeat (30s) + per-request timeout (30s)
  • Zero-throw error propagation: All errors flow through Promise resolve/reject as structured AsepriteResponse

🚀 Getting Started

Prerequisites

  • Aseprite: v1.3-rc5 or later (app.apiVersion >= 25)
  • Node.js: v18 or later
  • AI Client: Claude Desktop, Cursor, DeepChat, or any MCP-compatible client

Step 1: Install the MCP Server

git clone https://github.com/your-org/aseprite-mcp.git
cd aseprite-mcp
npm install
npm run build

Step 2: Install the Aseprite Extension

  1. Locate the aseprite-extension/ folder in this repository
  2. Compress the folder contents into a .zip file
  3. Rename the .zip to .aseprite-extension
  4. Double-click the .aseprite-extension file, or install via:
    Aseprite → Edit → Preferences → Extensions → Add Extension
  5. Ensure the MCP Bridge extension is checked/enabled
  6. Restart Aseprite

After restarting, open the Aseprite console (F1) and confirm:

[MCP Bridge] [INFO] MCP Bridge v0.1 initializing...
[MCP Bridge] [INFO] Connected to MCP Server at ws://127.0.0.1:9876

Step 3: Configure Your AI Client

DeepChat

{
  "mcpServers": {
    "aseprite": {
      "name": "aseprite-mcp",
      "transport": "stdio",
      "command": "node",
      "args": [
        "C:\\path\\to\\aseprite-mcp\\dist\\index.js"
      ],
      "env": {
        "ASE_MCP_PORT": "9876"
      }
    }
  }
}

Claude Desktop

%APPDATA%\Claude\settings.json:

{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": ["C:\\path\\to\\aseprite-mcp\\dist\\index.js"],
      "env": { "ASE_MCP_PORT": "9876" }
    }
  }
}

Cursor

Settings → MCP → Add Server:

{
  "mcpServers": [
    {
      "name": "aseprite",
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\aseprite-mcp\\dist\\index.js"]
    }
  ]
}

Generic (MCP stdio-compatible)

{
  "command": "node",
  "args": ["/path/to/aseprite-mcp/dist/index.js"],
  "env": { "ASE_MCP_PORT": "9876" }
}

Port Configuration: Default WebSocket port is 9876. Override with --port CLI argument or ASE_MCP_PORT environment variable.


🎨 Example Prompts

Once connected, ask your AI to draw:

Draw a red pixel at (10, 10) using the pencil tool.
Erase the area from (5, 5) to (15, 15).
Fill the region around (20, 20) with blue color.
Draw a line from (0, 0) to (50, 50) in green.

📁 Project Structure

aseprite-mcp/
├── src/                          # TypeScript source
│   ├── index.ts                  # Entry point (bridge + MCP server)
│   ├── mcp-server.ts             # MCP Server & tool registration
│   ├── ws-bridge.ts              # WebSocket Server & request matching
│   ├── protocol.ts               # Message protocol types
│   ├── tools-proto.ts            # Tool type definitions
│   └── tools/
│       └── use-tool.ts           # use_tool MCP schema + handler
├── aseprite-extension/           # Aseprite Extension (Lua)
│   ├── package.json              # Extension manifest
│   ├── mcp-bridge.lua            # WebSocket client + command gateway
│   └── tools/
│       └── use-tool.lua          # use_tool command processor
├── dist/                         # Compiled JavaScript output
├── package.json                  # Node.js project config
└── tsconfig.json                 # TypeScript config

🧪 Development

# Build
npm run build

# Run
npm start

# Dev mode (build + run)
npm run dev

# Tests
npm test

# Watch mode
npm run watch

📄 License

MIT License. See LICENSE for details.

Ver o original no GitHub

Relacionados