lpc-spritesheet-mcp

<p align="center"> <img src="https://raw.githubusercontent.com/kanishka-namdeo/lpc-spritesheet-mcp/main/docs/img/hero.png" alt="lpc-spritesheet-mcp banner: a knight with a sword, an archer with a hood and bow, and a mage in a purple kimono, each rendered by this server, with the 13-by-54 universal sheet layout drawn at top right" width="1184"> </p> <p align="center"> <a href="https://www.npmjs.com/package/lpc-spritesheet-mcp"><img src="https://img.shields.io/npm/v/lpc-spritesheet-mcp.svg" alt="npm version"></a> <a href="https://github.com/kanishka-namdeo/lpc-spritesheet-mcp/actions/workflows/ci.yml"><img src="https://github.com/kanishka-namdeo/lpc-spritesheet-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="License: GPL-3.0"></a> <a href="./package.json"><img src="https://img.shields.io/badge/node-%E2%89%A520.11-green.svg" alt="Node.js >= 20.11"></a> </p>

Give an AI agent a character artist's hands. This is the Universal-LPC-Spritesheet-Character-Generator web app re-implemented as a headless Node.js MCP server: an agent describes a character, and gets back a game-ready 832×3456 spritesheet with the exact frame layout — no browser, no screenshotting, no manual export button. Want to see it first? Previews come back as animated GIFs. Want a whole village? One seeded call. Tired of discovering itemIds? Presets and an opt-in AI designer start from plain language.

<p align="center"> <img src="https://raw.githubusercontent.com/kanishka-namdeo/lpc-spritesheet-mcp/main/docs/img/demo.gif" alt="Terminal recording of a real MCP session: the server reports 657 items and 104 groups, tools/list returns the thirteen tools, list_animations reports the walk row block, and a get_preview call renders a hooded character's walk cycle animating in the stage panel" width="880"><br> _{A real session against <code>src/index.js</code> over stdio — every byte of JSON shown is what the server returned.<br> Only the typing timing is authored. Regenerate with <code>npm run demo</code> (<a href="https://github.com/kanishka-namdeo/lpc-spritesheet-mcp/blob/main/docs/img/demo-credits.csv">attribution</a>).} </p>

• 657 selectable items across 104 groups on the current asset pack: 6 body types (male, female, teen, child, muscular, pregnant), 91 hairstyles, 45 heads (human, beast, reptile, undead, …), clothes, armor, 40 weapons, 9 shields with heraldic patterns, hats, capes, tails, wings, prostheses, wheelchairs.
• Named palette recoloring for skin, hair, eyes, cloth, metal and wood — 22 skintones, 26 hair colors, a 75-color universal palette.
• 15 animation row blocks on the standard sheet: 13 run in all four directions, hurt and climb ship a single facing — that is exactly the 54 rows. Plus custom-animation blocks for wheelchairs and 128/192px oversize weapons and tools.
• Watch it walk. get_preview returns one direction's playback cycle as a strip PNG or a looping animated GIF — inline in the conversation, correct LPC playback order, transparency preserved.
• Surprise me, reproducibly. random_character rolls a coherent character from any seed (same seed → same character, forever) with gear profiles from bare to fancy; generate_batch populates a whole NPC village in one call — sheets, previews, a contact grid, a manifest and one rolled-up credits file. 18 curated presets (knight, mage, blacksmith, …) render in a single call via preset: "<name>".
• Engine-ready output. Every render returns rows, frame counts, playback cycles and custom-block offsets, and export_character fans the same character out into per-animation or per-frame PNGs with an atlas in five dialects — TexturePacker/Phaser JSON Hash (with a cycle-correct animations map), Aseprite JSON (frameTags), Godot 4 .tres SpriteFrames, libGDX .atlas, and Unity pre-sliced .png.meta — plus a manifest, so a game engine never has to guess the layout or slice the sheet itself.
• Opt-in AI design. Configure LPC_AI_API_KEY and design_character turns a plain-language brief ("a tanned blacksmith with a leather apron and a hammer") into selections, colors, a rationale and a preview. Without the key the server stays fully offline: no network calls, no telemetry, and one environment variable (LPC_ASSETS_DIR).
• Deterministic, and now proven. npm run golden records SHA-256 hashes of seven canonical renders against a pinned asset-pack revision, and the test suite fails if a render drifts.
• Attribution included. Each sheet gets -credits.csv / -credits.txt beside it naming the authors and licenses of the art actually used.

The server ships no art. It reads a local clone of the upstream asset pack and renders it, offline by default: no network calls, no telemetry, and one environment variable (LPC_ASSETS_DIR).

Install

The server needs the upstream asset pack once. Any of these three lines does it — pick one:

git clone --depth 1 https://github.com/LiberatedPixelCup/Universal-LPC-Spritesheet-Character-Generator ~/.lpc-spritesheet/lpc-generator-src
lpc-spritesheet-setup           # same thing, via the npm bin after `npm install -g lpc-spritesheet-mcp`
npm run setup-assets            # same thing, from a checkout of this repo

Then wire the server into an MCP client: npx -y lpc-spritesheet-mcp, or npm install -g it and run lpc-spritesheet-mcp. Prefer a checkout? git clone this repo and run node src/index.js. Updating assets is a git pull in the pack clone.

The pack is looked up in this order, and the first valid entry wins:

1. $LPC_ASSETS_DIR
2. ../lpc-generator-src (sibling of the package — the dev-checkout convention)
3. ~/.lpc-spritesheet/lpc-generator-src (where the setup command above clones)

A valid pack contains both sheet_definitions/ and spritesheets/. If none is found the server prints what it searched for and exits — it will not start half-configured.

Try it now

No MCP client required — the official protocol inspector drives the server from a shell. The inspector starts the server with a clean environment, so if your asset pack lives outside the two automatic locations, pass -e LPC_ASSETS_DIR=<path> (drop the flag when the pack is in ~/.lpc-spritesheet/lpc-generator-src or a sibling lpc-generator-src/):

# list the thirteen tools and their schemas
npx -y @modelcontextprotocol/inspector --cli node src/index.js --method tools/list \
  -e LPC_ASSETS_DIR=/path/to/lpc-generator-src

# or render an ANIMATED walk cycle: the GIF comes back inline
npx -y @modelcontextprotocol/inspector --cli node src/index.js --method tools/call \
  --tool-name get_preview --tool-arg animation=walk --tool-arg format=gif \
  --tool-arg scale=3 --tool-arg bodyType=female \
  -e LPC_ASSETS_DIR=/path/to/lpc-generator-src

# or roll a villager from a seed
npx -y @modelcontextprotocol/inspector --cli node src/index.js --method tools/call \
  --tool-name random_character --tool-arg seed=riverford-1 \
  -e LPC_ASSETS_DIR=/path/to/lpc-generator-src

# or drive it interactively: browse 657 items, call tools, view the result
npx @modelcontextprotocol/inspector node src/index.js

MCP client configuration

All of these run the same stdio server. LPC_ASSETS_DIR is optional — omit it if the pack is in one of the two automatic locations above. To enable the opt-in AI designer, add LPC_AI_API_KEY (any OpenAI-compatible endpoint via LPC_AI_BASE_URL, default Dashscope's; model via LPC_AI_MODEL: qwen3.7-plus, kimi-k2.5 — the fast default — or qwen3.6-plus). Without the key the server is fully offline and design_character answers with a setup error.

<details> <summary>With the AI designer enabled (any client, env block)</summary>

{
  "mcpServers": {
    "lpc-spritesheet": {
      "command": "npx",
      "args": ["-y", "lpc-spritesheet-mcp"],
      "env": {
        "LPC_AI_API_KEY": "sk-…",
        "LPC_AI_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/v1",
        "LPC_AI_MODEL": "kimi-k2.5"
      }
    }
  }
}

</details> <details> <summary>Claude Desktop (<code>claude_desktop_config.json</code>)</summary>

{
  "mcpServers": {
    "lpc-spritesheet": {
      "command": "npx",
      "args": ["-y", "lpc-spritesheet-mcp"]
    }
  }
}

</details> <details> <summary>Claude Code (<code>claude mcp add</code>)</summary>

claude mcp add lpc-spritesheet -- npx -y lpc-spritesheet-mcp

</details> <details> <summary>Cursor / VS Code / generic stdio client, with a custom asset location</summary>

{
  "mcpServers": {
    "lpc-spritesheet": {
      "command": "npx",
      "args": ["-y", "lpc-spritesheet-mcp"],
      "env": { "LPC_ASSETS_DIR": "D:/assets/lpc-generator-src" }
    }
  }
}

</details> <details> <summary>ZCode (<code>~/.zcode/cli/config.json</code>)</summary>

{
  "mcp": {
    "servers": {
      "lpc-spritesheet": { "type": "stdio", "command": "npx", "args": ["-y", "lpc-spritesheet-mcp"] }
    }
  }
}

</details>

The thirteen tools

| Tool | Purpose | |---|---| | list_categories | All selection groups (body, hair, head, clothes, legs, shoes, weapon, hat, shield, tail, wings, …) with item counts and whether they take colors. Start here. | | list_items | One category: exact itemIds, display names, pre-sliced variants, valid recolors — deduplicated into a response-level palettes map. Filter with search, page with limit/offset, shrink with fields; the response is byte-budgeted, so check truncated/nextOffset. | | list_palettes | Color names per material (body, hair, eye, cloth, metal, wood, all), with each material's default. | | list_animations | The row layout of every animation (rows, frame counts, playback cycles, y-offsets) plus the custom blocks, which items provide them, and whether any item does. | | list_presets | The curated preset library (knight, mage, blacksmith, farmer, rogue, royal, child, zombie, lizardfolk, wheelchair user, …) — renderable in one call with preset: "<name>". | | generate_spritesheet | Render the full universal sheet; returns the path, layout, warnings, credits, the upstream generatorUrl and the asset-pack revision. | | get_animation | Render, then crop ONE animation into its own PNG — standard row block or custom block. | | get_preview | Render, then crop one direction's playback cycle, upscaled 1–8× — as a strip PNG or a looping animated GIF (format: "gif"). Small enough to return inline, so you also get the image itself, not just a path. | | export_character | Render, then fan out into a directory bundle: sheet.png, an atlas in one of five dialects (texturepacker, aseprite, godot, libgdx, unity) with cycle-correct playback sequences, manifest.json, and either one PNG per animation row block (mode: "animation") or one per frame (mode: "frames"), plus credits. | | random_character | Roll a coherent character from a seed — same seed, same character, forever. Gear profiles (bare/civilian/soldier/fancy), a completeness guarantee for core rows, ready-to-render selections/colors and an inline walk preview. | | generate_batch | Populate a village in one call: N seeded characters → per-character sheets/previews/credits + index.png contact grid + manifest.json + one rolled-up credits file. | | design_character | (Opt-in, needs LPC_AI_API_KEY) Turn a natural-language brief into ready-to-render selections/colors — catalog-grounded, validated, self-healing, with the model's rationale and an inline preview. | | validate_sheet | Audit instead of render: the port's row-block ta