pixelate-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PixelAOI
+
+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

@@ -0,0 +1,46 @@
+# pixelate-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that turns any image into
+**grid-perfect, true pixel art** — it auto-detects the native pixel grid and a
+sensible palette among other things like reauthoring of the image. Works in **Codex, Claude Desktop, and Cursor**.
+
+The heavy lifting runs in the cloud (Pixelate Cloud); this package is the small
+local connector that decodes your image and streams it to the service. You need
+a subscription key from **https://pixelaoi.pro**.
+
+## Use it
+
+Add to your MCP client config (Codex `~/.codex/config.toml`, Claude Desktop, or
+Cursor) — no install step needed, `npx` fetches it on demand:
+
+```toml
+[mcp_servers.pixelate]
+command = "npx"
+args = ["-y", "pixelate-mcp"]
+env = { PIXELATE_API_URL = "https://pixelate.pixelaoi.cloud", PIXELATE_API_KEY = "YOUR_KEY" }
+```
+
+Then ask your agent something like *"pixelate ./hero.png and save it next to the
+original."*
+
+## Tool: `pixelate_image`
+
+| arg | description |
+|-----|-------------|
+| `image_path` / `image_base64` / `image_url` | the source image (provide one) |
+| `auto` | auto-detect grid + palette (default `true`) |
+| `target_width` / `target_height` | output size when `auto` is off or no grid is found |
+| `colors` | palette size (omit to auto-pick) |
+| `seed` | determinism seed |
+| `output_path` | if set, saves the PNG there |
+
+Returns the pixel art as an image, plus a short summary.
+
+## Requirements
+
+- Node.js ≥ 18
+- A `PIXELATE_API_KEY` (subscribe at https://pixelaoi.pro)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import sharp from "sharp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_URL = (process.env.PIXELATE_API_URL || "").replace(/\/+$/, "");
+const API_KEY = process.env.PIXELATE_API_KEY || "";
+if (!API_URL || !API_KEY) {
+  console.error("pixelate-mcp: set PIXELATE_API_URL and PIXELATE_API_KEY environment variables.");
+  process.exit(1);
+}
+
+const stripDataUrl = (s) => {
+  const i = s.indexOf(",");
+  return s.startsWith("data:") && i !== -1 ? s.slice(i + 1) : s;
+};
+const errText = (text) => ({ content: [{ type: "text", text }], isError: true });
+
+async function jobReq(query, body) {
+  const res = await fetch(`${API_URL}/job?${query}`, {
+    method: "POST",
+    headers: body
+      ? { "content-type": "application/octet-stream", "x-api-key": API_KEY }
+      : { "x-api-key": API_KEY },
+    body: body ?? undefined,
+  });
+  const j = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${j.error || "request failed"}`);
+  if (!j.success) throw new Error(j.error || "job error");
+  return j;
+}
+
+const server = new McpServer({ name: "pixelate-mcp", version: "0.1.0" });
+
+server.tool(
+  "pixelate_image",
+  "Convert an image into grid-perfect, true pixel art. Auto-detects the native pixel grid and a sensible palette. Provide exactly one of image_path, image_base64, or image_url.",
+  {
+    image_path: z.string().optional().describe("Local path to the source image (png/jpg/webp)."),
+    image_base64: z.string().optional().describe("Base64-encoded image (alternative to image_path)."),
+    image_url: z.string().optional().describe("URL to fetch the image from (alternative to image_path)."),
+    auto: z.boolean().optional().describe("Auto-detect native grid + palette (default true)."),
+    target_width: z.number().int().positive().optional().describe("Output width; used when auto is off or no grid is detected."),
+    target_height: z.number().int().positive().optional().describe("Output height; used when auto is off or no grid is detected."),
+    colors: z.number().int().positive().optional().describe("Palette size; omit to auto-pick."),
+    seed: z.number().int().optional().describe("Determinism seed (default 42)."),
+    output_path: z.string().optional().describe("If set, save the resulting PNG to this path."),
+  },
+  async (a) => {
+    try {
+      let buf;
+      if (a.image_base64) buf = Buffer.from(stripDataUrl(a.image_base64), "base64");
+      else if (a.image_path) buf = await readFile(a.image_path);
+      else if (a.image_url) buf = Buffer.from(await (await fetch(a.image_url)).arrayBuffer());
+      else return errText("Provide one of image_path, image_base64, or image_url.");
+
+      // Decode locally to raw RGBA (no Worker decode -> no decode CPU on the edge).
+      const { data, info } = await sharp(buf).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+
+      // Start: raw bytes go in the binary body; params in the query string.
+      const q = new URLSearchParams({ action: "start", w: String(info.width), h: String(info.height), auto: (a.auto ?? true) ? "1" : "0" });
+      if (a.colors) q.set("colors", String(a.colors));
+      if (a.seed != null) q.set("seed", String(a.seed));
+      if (a.target_width) q.set("tw", String(a.target_width));
+      if (a.target_height) q.set("th", String(a.target_height));
+
+      let res = await jobReq(q.toString(), data);
+      const jobId = res.job_id;
+      let guard = 0;
+      while (!res.done) {
+        if (++guard > 1000) return errText("pixelate-mcp: job did not converge");
+        res = await jobReq(`action=step&id=${encodeURIComponent(jobId)}`);
+      }
+
+      let summary = `Pixel art ${res.width}x${res.height}.`;
+      if (a.output_path) {
+        await writeFile(a.output_path, Buffer.from(res.image_base64, "base64"));
+        summary += ` Saved to ${a.output_path}.`;
+      }
+      return {
+        content: [
+          { type: "text", text: summary },
+          { type: "image", data: res.image_base64, mimeType: "image/png" },
+        ],
+      };
+    } catch (e) {
+      return errText(`pixelate-mcp error: ${e?.message || e}`);
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "pixelate-mcp",
+  "version": "0.1.0",
+  "description": "MCP server: turn any image into grid-perfect pixel art via the Pixelate Cloud API. Works in Codex, Claude Desktop, Cursor.",
+  "type": "module",
+  "bin": {
+    "pixelate-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pixel-art",
+    "pixelate",
+    "codex",
+    "claude",
+    "cursor",
+    "aseprite"
+  ],
+  "homepage": "https://pixelaoi.pro",
+  "license": "MIT",
+  "author": "PixelAOI",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "sharp": "^0.33.5",
+    "zod": "^3.23.8"
+  }
+}