simplepixelart-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Comficker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# simplepixelart-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server that gives AI assistants (Claude, Cursor, Windsurf, VS Code…) real pixel art tools: turn any image into pixel art, extract a palette, recolour sprites to PICO-8 or Game Boy colours, and upscale without blur.
+
+Runs locally, works on PNG and JPEG files or image URLs, no API keys, no native dependencies.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `pixelate_image` | Image → pixel art. Shrinks to a pixel grid (e.g. 64 px wide), reduces to N colours with median cut or maps to a named palette, saves a PNG (optionally upscaled for preview). |
+| `extract_palette` | Pulls the main colours out of an image and returns hex codes plus a GIMP / Aseprite `.gpl` palette. |
+| `remap_palette` | Recolours existing pixel art so every pixel uses a palette colour — PICO-8, Sweetie 16, ENDESGA 32, Game Boy, 1-bit or your own hex list. |
+| `upscale_pixel_art` | Nearest-neighbour upscale by a whole number, so pixels stay sharp. |
+| `list_palettes` | Lists the built-in palettes. |
+
+## Install
+
+Add it to your MCP client config. For Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and most other clients:
+
+```json
+{
+  "mcpServers": {
+    "pixel-art": {
+      "command": "npx",
+      "args": ["-y", "simplepixelart-mcp"]
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add pixel-art -- npx -y simplepixelart-mcp
+```
+
+Requires Node.js 18 or newer.
+
+## Examples
+
+Ask your assistant things like:
+
+- "Turn `~/photos/cat.jpg` into 48 px wide pixel art with the PICO-8 palette, and save an 8x preview."
+- "Extract a 6-colour palette from this screenshot and give me the .gpl file."
+- "Recolour every sprite in `assets/` to the Game Boy palette."
+- "Upscale `hero.png` 10x for the store page."
+
+## Use it as a library
+
+```js
+import { loadImage, pixelate, saveImage } from 'simplepixelart-mcp/src/pixel.js'
+
+const img = await loadImage('photo.jpg')
+const { display, palette } = pixelate(img, { width: 64, palette: 'sweetie-16', scale: 8 })
+await saveImage(display, 'photo-pixel.png')
+```
+
+## Want to edit the result?
+
+The tools get you a clean starting grid; the fun part is fixing it by hand. Open the PNG in [SimplePixelArt](https://simplepixelart.com/), a free online [pixel art editor](https://simplepixelart.com/editor) with layers, animation and tileset tools, or try its in-browser [pixel art converter](https://simplepixelart.com/converter) for live adjustments. No account needed.
+
+## Development
+
+```bash
+npm install
+npm test        # starts the server over stdio and calls every tool
+```
+
+## License
+
+MIT © Comficker

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "simplepixelart-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for pixel art: turn images into pixel art, extract and remap palettes (PICO-8, Game Boy, ENDESGA 32…), and upscale sprites without blur.",
+  "type": "module",
+  "bin": { "simplepixelart-mcp": "src/index.js" },
+  "main": "src/pixel.js",
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": { "start": "node src/index.js", "test": "node test/run.js" },
+  "keywords": ["mcp", "model-context-protocol", "pixel-art", "pixelate", "palette", "sprite", "gamedev", "image-to-pixel-art", "pico-8", "claude", "cursor"],
+  "homepage": "https://simplepixelart.com/",
+  "repository": { "type": "git", "url": "git+https://github.com/comficker/pixel-art-mcp.git" },
+  "bugs": { "url": "https://github.com/comficker/pixel-art-mcp/issues" },
+  "author": "Comficker (https://simplepixelart.com)",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^7.0.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// MCP server (stdio) exposing the pixel art operations in pixel.js as tools.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { basename, dirname, extname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import {
+  PALETTES, loadImage, saveImage, pixelate, medianCut, downscale, remap, resolvePalette, upscale, usedColors, rgbToHex, toGpl,
+} from './pixel.js'
+
+const server = new McpServer({ name: 'simplepixelart-mcp', version: '0.1.0' })
+
+/** Default output next to a local input (or in the temp dir for URLs). */
+function outPath(input, suffix, output) {
+  if (output) return output
+  const dir = /^https?:\/\//.test(input) ? tmpdir() : dirname(input)
+  const name = basename(input.split('?')[0], extname(input.split('?')[0])) || 'image'
+  return join(dir, `${name}-${suffix}.png`)
+}
+const text = t => ({ content: [{ type: 'text', text: t }] })
+const paletteHelp = `Palette name (${Object.keys(PALETTES).join(', ')}) or hex colours like "#1a1c2c,#5d275d"`
+
+server.registerTool('pixelate_image', {
+  title: 'Image to pixel art',
+  description: 'Turn a photo or illustration into pixel art: shrink it to a pixel grid, reduce it to a few colours (or a named palette) and save a PNG. Accepts a local PNG/JPEG path or an http(s) URL.',
+  inputSchema: {
+    input: z.string().describe('Path or URL of a PNG or JPEG image'),
+    width: z.number().int().min(4).max(512).default(64).describe('Width of the pixel grid in pixels (height keeps the aspect ratio)'),
+    colors: z.number().int().min(2).max(64).default(16).describe('Number of colours when no palette is given'),
+    palette: z.string().optional().describe(paletteHelp),
+    scale: z.number().int().min(1).max(32).default(1).describe('Upscale factor for the saved PNG, nearest neighbour (e.g. 8 for a crisp preview)'),
+    output: z.string().optional().describe('Where to save the PNG (defaults next to the input)'),
+  },
+}, async ({ input, width, colors, palette, scale, output }) => {
+  const img = await loadImage(input)
+  const r = pixelate(img, { width, colors, palette, scale })
+  const path = await saveImage(r.display, outPath(input, `pixel-${r.pixel.width}x${r.pixel.height}`, output))
+  return text(`Saved ${r.pixel.width}x${r.pixel.height} pixel art (${r.palette.length} colours${scale > 1 ? `, shown at ${scale}x` : ''}) to ${path}\nPalette: ${r.palette.join(' ')}\nEdit it further in the free online pixel art editor: https://simplepixelart.com/editor`)
+})
+
+server.registerTool('extract_palette', {
+  title: 'Extract palette',
+  description: 'Pull the main colours out of an image (median cut). Returns hex codes plus a GIMP/Aseprite .gpl palette.',
+  inputSchema: {
+    input: z.string().describe('Path or URL of a PNG or JPEG image'),
+    colors: z.number().int().min(2).max(64).default(8).describe('How many colours to extract'),
+  },
+}, async ({ input, colors }) => {
+  const img = downscale(await loadImage(input), 256)
+  const hexes = medianCut(img, colors).map(rgbToHex)
+  return text(`${hexes.join(' ')}\n\n${toGpl(hexes, basename(input))}`)
+})
+
+server.registerTool('remap_palette', {
+  title: 'Recolour to a palette',
+  description: 'Recolour an existing pixel art image so every pixel uses a colour from the given palette (e.g. PICO-8 or Game Boy). Size is kept.',
+  inputSchema: {
+    input: z.string().describe('Path or URL of a PNG or JPEG image'),
+    palette: z.string().describe(paletteHelp),
+    output: z.string().optional().describe('Where to save the PNG'),
+  },
+}, async ({ input, palette, output }) => {
+  const img = remap(await loadImage(input), resolvePalette(palette))
+  const path = await saveImage(img, outPath(input, 'remap', output))
+  return text(`Saved ${img.width}x${img.height} image using ${usedColors(img).length} colours to ${path}`)
+})
+
+server.registerTool('upscale_pixel_art', {
+  title: 'Upscale without blur',
+  description: 'Scale pixel art up by a whole number with nearest neighbour, so pixels stay sharp (for previews, store pages or social posts).',
+  inputSchema: {
+    input: z.string().describe('Path or URL of a PNG image'),
+    scale: z.number().int().min(2).max(64).default(8),
+    output: z.string().optional(),
+  },
+}, async ({ input, scale, output }) => {
+  const img = upscale(await loadImage(input), scale)
+  const path = await saveImage(img, outPath(input, `x${scale}`, output))
+  return text(`Saved ${img.width}x${img.height} to ${path}`)
+})
+
+server.registerTool('list_palettes', {
+  title: 'List built-in palettes',
+  description: 'List the built-in pixel art palettes and their colours.',
+  inputSchema: {},
+}, async () => text(Object.entries(PALETTES).map(([k, v]) => `${k} (${v.split(' ').length}): ${v.split(' ').map(h => '#' + h).join(' ')}`).join('\n') +
+  '\n\nBrowse thousands more palettes at https://simplepixelart.com/palettes'))
+
+await server.connect(new StdioServerTransport())

package/src/pixel.js

@@ -0,0 +1,166 @@
+// Pixel art image operations on plain RGBA buffers: load/save PNG and JPEG,
+// downscale by area averaging, median-cut quantise, palette remap and
+// nearest-neighbour upscale. No native dependencies.
+import { readFile, writeFile } from 'node:fs/promises'
+import { PNG } from 'pngjs'
+import jpeg from 'jpeg-js'
+
+export const PALETTES = {
+  'pico-8': '000000 1D2B53 7E2553 008751 AB5236 5F574F C2C3C7 FFF1E8 FF004D FFA300 FFEC27 00E436 29ADFF 83769C FF77A8 FFCCAA',
+  'sweetie-16': '1A1C2C 5D275D B13E53 EF7D57 FFCD75 A7F070 38B764 257179 29366F 3B5DC9 41A6F6 73EFF7 F4F4F4 94B0C2 566C86 333C57',
+  'endesga-32': 'BE4A2F D77643 EAD4AA E4A672 B86F50 733E39 3E2731 A22633 E43B44 F77622 FEAE34 FEE761 63C74D 3E8948 265C42 193C3E 124E89 0099DB 2CE8F5 FFFFFF C0CBDC 8B9BB4 5A6988 3A4466 262B44 181425 FF0044 68386C B55088 F6757A E8B796 C28569',
+  'game-boy': '0F380F 306230 8BAC0F 9BBC0F',
+  '1-bit': '000000 FFFFFF',
+}
+
+const hexToRgb = h => [0, 2, 4].map(i => parseInt(h.replace('#', '').slice(i, i + 2), 16))
+export const rgbToHex = c => '#' + c.map(v => v.toString(16).padStart(2, '0')).join('')
+
+/** Palette from a known name or a list of hex colours. */
+export function resolvePalette(p) {
+  if (!p) return null
+  if (Array.isArray(p)) return p.map(hexToRgb)
+  const known = PALETTES[String(p).toLowerCase()]
+  if (known) return known.split(' ').map(hexToRgb)
+  const list = String(p).split(/[\s,]+/).filter(Boolean)
+  if (list.every(h => /^#?[0-9a-f]{6}$/i.test(h))) return list.map(hexToRgb)
+  throw new Error(`Unknown palette "${p}". Use one of ${Object.keys(PALETTES).join(', ')} or a list of hex colours.`)
+}
+
+/** Load a PNG or JPEG from a path or http(s) URL into { width, height, data: RGBA }. */
+export async function loadImage(input) {
+  let buf
+  if (/^https?:\/\//.test(input)) {
+    const res = await fetch(input)
+    if (!res.ok) throw new Error(`Could not fetch ${input}: HTTP ${res.status}`)
+    buf = Buffer.from(await res.arrayBuffer())
+  } else {
+    buf = await readFile(input)
+  }
+  if (buf[0] === 0x89 && buf[1] === 0x50) {
+    const png = PNG.sync.read(buf)
+    return { width: png.width, height: png.height, data: new Uint8ClampedArray(png.data) }
+  }
+  if (buf[0] === 0xff && buf[1] === 0xd8) {
+    const j = jpeg.decode(buf, { useTArray: true, formatAsRGBA: true })
+    return { width: j.width, height: j.height, data: new Uint8ClampedArray(j.data) }
+  }
+  throw new Error('Unsupported image format: only PNG and JPEG are supported.')
+}
+
+export async function saveImage(img, path) {
+  const png = new PNG({ width: img.width, height: img.height })
+  png.data = Buffer.from(img.data)
+  await writeFile(path, PNG.sync.write(png))
+  return path
+}
+
+/** Downscale to `width` pixels wide (aspect kept) by averaging each source block. */
+export function downscale(img, width) {
+  const w = Math.max(1, Math.min(width, img.width))
+  const h = Math.max(1, Math.round(img.height * w / img.width))
+  const out = new Uint8ClampedArray(w * h * 4)
+  const sx = img.width / w, sy = img.height / h
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const x0 = Math.floor(x * sx), x1 = Math.max(x0 + 1, Math.floor((x + 1) * sx))
+      const y0 = Math.floor(y * sy), y1 = Math.max(y0 + 1, Math.floor((y + 1) * sy))
+      let r = 0, g = 0, b = 0, a = 0, n = 0
+      for (let yy = y0; yy < y1; yy++) {
+        for (let xx = x0; xx < x1; xx++) {
+          const i = (yy * img.width + xx) * 4, al = img.data[i + 3]
+          r += img.data[i] * al; g += img.data[i + 1] * al; b += img.data[i + 2] * al; a += al; n++
+        }
+      }
+      const o = (y * w + x) * 4
+      if (a > 0) { out[o] = r / a; out[o + 1] = g / a; out[o + 2] = b / a }
+      out[o + 3] = a / n >= 128 ? 255 : 0 // pixel art is hard-edged: no partial alpha
+    }
+  }
+  return { width: w, height: h, data: out }
+}
+
+const opaque = img => {
+  const px = []
+  for (let i = 0; i < img.data.length; i += 4) if (img.data[i + 3] >= 128) px.push([img.data[i], img.data[i + 1], img.data[i + 2]])
+  return px
+}
+
+/** Median cut: split the colour box with the widest channel range until `n` boxes. */
+export function medianCut(img, n) {
+  const px = opaque(img)
+  if (!px.length) return []
+  let boxes = [px]
+  while (boxes.length < n) {
+    let best = -1, bi = -1, ch = 0
+    boxes.forEach((b, i) => {
+      if (b.length < 2) return
+      for (let c = 0; c < 3; c++) {
+        let lo = 255, hi = 0
+        for (const p of b) { if (p[c] < lo) lo = p[c]; if (p[c] > hi) hi = p[c] }
+        if (hi - lo > best) { best = hi - lo; bi = i; ch = c }
+      }
+    })
+    if (bi < 0 || best === 0) break
+    const b = boxes[bi].sort((p, q) => p[ch] - q[ch])
+    const mid = b.length >> 1
+    boxes.splice(bi, 1, b.slice(0, mid), b.slice(mid))
+  }
+  return boxes.map(b => [0, 1, 2].map(c => Math.round(b.reduce((s, p) => s + p[c], 0) / b.length)))
+}
+
+const dist = (a, b) => {
+  // Weighted RGB distance: close enough to perceptual for small palettes.
+  const r = (a[0] + b[0]) / 2, dr = a[0] - b[0], dg = a[1] - b[1], db = a[2] - b[2]
+  return (2 + r / 256) * dr * dr + 4 * dg * dg + (2 + (255 - r) / 256) * db * db
+}
+
+/** Map every opaque pixel to its nearest palette colour. */
+export function remap(img, palette) {
+  const out = new Uint8ClampedArray(img.data)
+  const cache = new Map()
+  for (let i = 0; i < out.length; i += 4) {
+    if (out[i + 3] < 128) { out[i + 3] = 0; continue }
+    const key = (out[i] << 16) | (out[i + 1] << 8) | out[i + 2]
+    let c = cache.get(key)
+    if (!c) {
+      const p = [out[i], out[i + 1], out[i + 2]]
+      c = palette.reduce((best, q) => dist(p, q) < dist(p, best) ? q : best, palette[0])
+      cache.set(key, c)
+    }
+    out[i] = c[0]; out[i + 1] = c[1]; out[i + 2] = c[2]; out[i + 3] = 255
+  }
+  return { width: img.width, height: img.height, data: out }
+}
+
+export function upscale(img, scale) {
+  const s = Math.max(1, Math.floor(scale))
+  const w = img.width * s, h = img.height * s
+  const out = new Uint8ClampedArray(w * h * 4)
+  const src = new Uint32Array(img.data.buffer, img.data.byteOffset, img.width * img.height)
+  const dst = new Uint32Array(out.buffer)
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) dst[y * w + x] = src[((y / s) | 0) * img.width + ((x / s) | 0)]
+  return { width: w, height: h, data: out }
+}
+
+/** Colours actually present, most used first. */
+export function usedColors(img) {
+  const n = new Map()
+  for (let i = 0; i < img.data.length; i += 4) {
+    if (img.data[i + 3] < 128) continue
+    const h = rgbToHex([img.data[i], img.data[i + 1], img.data[i + 2]])
+    n.set(h, (n.get(h) || 0) + 1)
+  }
+  return [...n.entries()].sort((a, b) => b[1] - a[1]).map(e => e[0])
+}
+
+/** Image → pixel art: downscale, quantise (or map to a palette), optionally upscale for display. */
+export function pixelate(img, { width = 64, colors = 16, palette, scale = 1 } = {}) {
+  let out = downscale(img, width)
+  const pal = resolvePalette(palette) || medianCut(out, colors)
+  out = remap(out, pal)
+  return { pixel: out, display: scale > 1 ? upscale(out, scale) : out, palette: usedColors(out) }
+}
+
+export const toGpl = (hexes, name = 'Palette') =>
+  `GIMP Palette\nName: ${name}\nColumns: 8\n#\n` + hexes.map(h => { const [r, g, b] = hexToRgb(h); return `${String(r).padStart(3)} ${String(g).padStart(3)} ${String(b).padStart(3)}\t${h}` }).join('\n') + '\n'