sprite-canon

Servidor MCP que mantiene los sprites de juegos generados por IA con el aspecto de UN solo juego.

Un personaje, tres atuendos: las filas azul y roja son llamadas a sprite_repaint, no regeneraciones. Mismo orden de sombreado, misma silueta, mismo resultado cada vez.

Los generadores de IA son excelentes creando un sprite bonito y pésimos haciendo que coincida con el anterior. Pide el mismo personaje dos veces y la paleta se desvía, el atuendo muta, el nuevo sombrero flota 3 píxeles por encima de la cabeza: cada recurso está bien por separado, y el juego se ve mal ensamblado. Regenerar "hasta que coincida" no converge; quema dinero y no puedes comparar el resultado.

sprite-canon adopta el enfoque opuesto, extraído de un proyecto de juego real que generó ~4,000 fotogramas y aprendió cada lección de la manera difícil:

1. Tus reglas de consistencia se convierten en datos — un sprite-canon.json ("el canon") que contiene la paleta, regiones de color con nombre (piel, atuendo, contorno…), escala relativa y umbrales de verificación. Se guarda junto a tus recursos.

2. La verificación es numérica, no visual. No puedes revisar a ojo 96 variantes de atuendo × 8 direcciones × 4 fotogramas. sprite_verify devuelve números duros de aprobado/fallo para los defectos que realmente importan: píxeles fuera de paleta, accesorios que tiemblan entre fotogramas, una región que está brillante por detrás y oscura por delante, un repintado que tocó la cara.

3. Las correcciones son operaciones de píxeles deterministas, no regeneración. Repintar una región sobre una nueva rampa de color preserva el sombreado y las siluetas, nunca toca regiones protegidas y produce el mismo resultado cada vez. Una variante de atuendo es una llamada de herramienta, no una lotería de prompts.

Instalación

Claude Desktop — un archivo, sin configuración

1. Descarga sprite-canon.mcpb desde la última versión.

2. En Claude Desktop, abre Configuración → Extensiones (menú ☰ → Archivo → Configuración en Windows).

3. Arrastra el archivo .mcpb a la página de Extensiones, revisa y haz clic en Instalar.

(Hacer doble clic en el archivo también funciona si tu sistema operativo tiene registrada la asociación .mcpb — arrastrar y soltar siempre funciona. Alternativa: Extensiones → Configuración avanzada → Instalar extensión → elige el archivo.)

Eso es toda la instalación: el paquete incluye sus propias dependencias, y Claude Desktop proporciona el runtime de Node. Requiere la aplicación Claude Desktop — para Claude Code ver más abajo.

Claude Code / otros clientes MCP

git clone https://github.com/useka12-eng/sprite-canon
cd sprite-canon && npm install

Luego regístralo en el .mcp.json de tu proyecto (o en cualquier configuración de cliente MCP):

{
  "mcpServers": {
    "sprite-canon": {
      "command": "node",
      "args": ["/path/to/sprite-canon/src/mcp/server.mjs"]
    }
  }
}

Requiere Node 18+. Sin dependencias nativas — los códecs PNG/GIF son autónomos.

Compilar el paquete tú mismo

npx @anthropic-ai/mcpb pack . dist/sprite-canon.mcpb

Related MCP server: mcp-spritesheet-forge

Herramientas

Las entradas pueden ser PNG, GIF animados o hojas de sprites PNG (cellW/cellH).

El flujo de trabajo

canon_init      → learn the palette from your existing good assets
canon_learn     → sample skin / outfit / outline once; mark face + outline protected
sprite_measure  → read the numbers before placing anything ("where do the eyes start?")
sprite_repaint  → make variants deterministically (outfits, teams, seasons)
sprite_verify   → prove it: face untouched, nothing left over, no jitter, on palette
sprite_sheet    → look at the result as a sheet, zoomed, before it enters the game

Lecciones que esta herramienta codifica

No son hipotéticas — cada una se manifestó primero como un defecto real:

• Mide, no asumas proporciones. Un ala de sombrero colocada al "52% de la altura de la cabeza" aterrizó exactamente sobre los ojos: en una cabeza de 20px los ojos están a 7–9px de la parte superior, así que cada proporción fija los golpea. sprite_measure informa dónde comienza realmente la cara, por fotograma.

• Repinta con un rango de luminancia fijo. Normalizar por imagen mapea el mismo color fuente a diferentes salidas dependiendo de cuánto de la región es visible — nuestro sombrero estaba brillante por detrás, oscuro por delante. El canon registra el rango de cada región una vez; el repintado siempre lo usa.

• Protege las regiones estructuralmente. "Ten cuidado alrededor de la cara" falla a escala. protected: true significa que el repintado no puede tocarla y la verificación prueba que no lo hizo.

• Parchea las paletas GIF, no re-codifiques. Los colores de un GIF indexado viven en sus tablas de color — globales y locales por fotograma (parchear solo la tabla global es el clásico medio-arreglo). Sustituir entradas de tabla re-viste cada fotograma en perfecta sincronía con cero pérdida.

• Las definiciones de región tienen huecos; censa. 12 píxeles sueltos del color antiguo que sobreviven a un repintado son invisibles al ojo y obvios para leftover. Cuando se dispara, el censo de canon_info muestra qué colores no cubren tus regiones.

La tabla de escala

La comprobación scale de sprite_verify lee canon.scale.heights — tamaños relativos en unidades de un recurso de referencia (la entrada igual a 1). Ninguna herramienta escribe esta sección todavía; añádela a sprite-canon.json a mano:

"scale": { "heights": { "hero": 1, "house": 3.4, "chicken": 0.45 } }

Luego verifica con scaleNames mapeando los nombres base de archivo a esas claves. Esto detecta el clásico "la casa es más pequeña que el héroe" una semana antes de que tus jugadores lo hagan.

Notas prácticas

• Pasa siempre canonPath (o un archivo sobre el que el canon se encuentre). El directorio de trabajo de un servidor MCP stdio pertenece al cliente, no a tu proyecto, por lo que las herramientas se niegan a adivinar desde el cwd.

• Límites de códec: PNG debe ser de 8 bits, no entrelazado, RGB/RGBA/paleta (los casos comunes de pixel art; archivos de 16 bits o entrelazados se rechazan con un error claro). El codificador GIF es exacto hasta 255 colores opacos por archivo — más allá, ajuste a la paleta más cercana.

• sprite_sheet devuelve la imagen en línea hasta ~800 KB; hojas más grandes devuelven solo la ruta del archivo.

• Las hojas de sprites hacen un viaje de ida y vuelta celda por celda: las celdas vacías permanecen vacías, nada se compacta.

Lo que esto no es

• No es un generador. Combínalo con lo que sea que haga tu arte (PixelLab, Aseprite, Gemini, píxeles a mano); sprite-canon es la capa que mantiene los resultados coherentes.

• No es un empaquetador de atlas / herramienta de colisiones — sprite-tools cubre eso bien.

• No es magia: dedicas ~10 minutos una vez por proyecto a enseñarle tu canon. Esa inversión es exactamente lo que hace que cada verificación y corrección posterior sea confiable.

Desarrollo

npm test          # unit + end-to-end MCP tests (22)

La suite de pruebas incluye pruebas de regresión para cada error que una revisión adversarial multi-agente encontró en v0.1 — compactación de celdas de hoja, semántica de disposición GIF, respuestas de falso éxito, pases de verificación cero silenciosos. Si una falla, un error que ya existió una vez está de vuelta.

MIT