sprite-gen-mcp

MCP server wrapping the sprite-gen pipeline, with XAI/Grok image generation support.

What it does

Exposes the sprite-gen CLI as MCP tools so AI agents (e.g. OpenClaw/Gideon) can:

• Prepare sprite generation runs
• Generate frames for multiple animation states (idle, walk, run, jump, attack, …)
• Extract transparent frames from chroma-keyed output
• Compose final sprite atlases with real alpha channels
• Recolor variants, cutouts, background tiles, and more

Quick start

cp .env.example .env
# edit .env — add your XAI_API_KEY
docker compose up -d

The MCP SSE endpoint will be available at http://localhost:8000/sse.

Environment variables

Variable	Default	Description
XAI_API_KEY	—	XAI/Grok API key for image generation
PROVIDER	grok	Image provider: grok or codex
SPRITE_GEN_PATH	/usr/local/bin/sprite-gen	Path to sprite-gen CLI

MCP Tools

Tool	Description
sprite_prepare	Set up a run directory with request spec
sprite_gen_set	Generate frames for all animation states
sprite_extract	Extract transparent frames (chroma → alpha)
sprite_compose_atlas	Compose final sprite sheet + manifest
sprite_curation	Launch curation webview for frame review
sprite_video_set	Prepare video-to-loop sprite set
sprite_cutout	Extract clean transparent cutout from image
sprite_recolor	Generate colorway variants from an atlas
sprite_background_tile	Create repeating background tiles
sprite_list_run	Inspect run directory contents
sprite_get_manifest	Read frame layout manifest
sprite_list_dir	List files in a directory

CI/CD

Builds are handled by Forgejo Actions:

• linux/amd64 — standard runner
• linux/arm64 — Pi 5 runner (pi5 label)

Images are pushed to the Forgejo container registry at nidavellir.jriyuu.io.