@pixel-normal-edit/mcp 2.0.4 → 2.0.5

package/tools/animation.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * animation.js — Animation Frame tools
+ *
+ * Tools: animation_enable, animation_add_frame, animation_go_to_frame,
+ *        animation_ensure_frame, animation_get_info, animation_remove_frame,
+ *        animation_reorder_frame, animation_compare_frames
+ */
+const { z } = require('zod');
+const { registerTool, sendCommand } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'animation_enable',
+    'Enable or disable animation mode. When enabled, the canvas has multiple frames.',
+    { enabled: z.boolean().describe('true to enable, false to disable') },
+    (p) => ({ action: 'setAnimationMode', enabled: p.enabled }));
+
+  registerTool(server, 'animation_add_frame',
+    'Append a new blank frame to the animation',
+    {},
+    () => ({ action: 'addFrame' }));
+
+  registerTool(server, 'animation_go_to_frame',
+    'Switch to editing a specific frame by index (0-based)',
+    { index: z.number().int().min(0).describe('Frame index') },
+    (p) => ({ action: 'goToFrame', index: p.index }));
+
+  registerTool(server, 'animation_ensure_frame',
+    'Make sure the animation has at least (index+1) frames, then switch to that frame',
+    { index: z.number().int().min(0).describe('Target frame index') },
+    (p) => ({ action: 'ensureFrame', index: p.index }));
+
+  registerTool(server, 'animation_get_info',
+    'Get current frame count and active frame index',
+    {},
+    async () => {
+      const [count, idx] = await Promise.all([
+        sendCommand({ action: 'getFrameCount' }),
+        sendCommand({ action: 'getActiveFrameIndex' }),
+      ]);
+      return { content: [{ type: 'text', text: JSON.stringify({ frameCount: count, activeIndex: idx }) }] };
+    });
+
+  registerTool(server, 'animation_remove_frame',
+    'Remove frame at the given index',
+    { index: z.number().int().min(0) },
+    (p) => ({ action: 'removeFrame', index: p.index }));
+
+  registerTool(server, 'animation_reorder_frame',
+    'Move a frame from one position to another',
+    { from: z.number().int().min(0), to: z.number().int().min(0) },
+    (p) => ({ action: 'reorderFrame', from: p.from, to: p.to }));
+
+  registerTool(server, 'animation_compare_frames',
+    'Get list of pixel differences between two frames',
+    { frameIndex1: z.number().int().min(0), frameIndex2: z.number().int().min(0) },
+    (p) => ({ action: 'getFrameDifferences', ...p }));
+}
+
+module.exports = { register };

package/tools/canvas.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * canvas.js — Canvas & Setup tools
+ *
+ * Tools: canvas_get_size, canvas_resize, canvas_clear, canvas_trim
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'canvas_get_size',
+    'Get current canvas dimensions {width, height}',
+    {},
+    () => ({ action: 'getSize' }));
+
+  registerTool(server, 'canvas_resize',
+    'Resize canvas to new dimensions. mode=clear resets pixels, extend keeps them.',
+    {
+      width: z.number().int().min(1).max(1024).describe('New width in pixels'),
+      height: z.number().int().min(1).max(1024).describe('New height in pixels'),
+      mode: z.enum(['clear', 'extend', 'fit']).default('clear').describe('How to handle existing content'),
+      dx: z.number().int().default(0).describe('X offset for content when extending'),
+      dy: z.number().int().default(0).describe('Y offset for content when extending')
+    },
+    (p) => ({ action: 'resize', ...p }));
+
+  registerTool(server, 'canvas_clear',
+    'Erase all pixels on the current canvas frame',
+    {},
+    () => ({ action: 'clear' }));
+
+  registerTool(server, 'canvas_trim',
+    'Auto-trim transparent borders from canvas',
+    {},
+    () => ({ action: 'trim' }));
+}
+
+module.exports = { register };

package/tools/colors.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * colors.js — Color tools
+ *
+ * Tools: color_set, color_get
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/).describe('Hex color e.g. #ff0000');
+
+function register(server) {
+  registerTool(server, 'color_set',
+    'Set the primary and/or secondary color',
+    { primary: hexColor.optional(), secondary: hexColor.optional() },
+    (p) => ({ action: 'setColor', ...p }));
+
+  registerTool(server, 'color_get',
+    'Get current primary and secondary colors',
+    {},
+    () => ({ action: 'getColor' }));
+}
+
+module.exports = { register };

package/tools/drawing.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * drawing.js — Drawing Primitives tools
+ *
+ * Tools: draw_pixel, draw_erase, draw_line, draw_rect, draw_circle,
+ *        draw_ellipse, draw_polygon, draw_fill, draw_gradient_rect,
+ *        bulk_replace_color, bulk_flood_fill_all
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/).describe('Hex color e.g. #ff0000');
+
+function register(server) {
+  registerTool(server, 'draw_pixel',
+    'Set a single pixel to a color',
+    { x: z.number().int().describe('X coordinate'), y: z.number().int().describe('Y coordinate'), color: hexColor },
+    (p) => ({ action: 'drawPixel', ...p }));
+
+  registerTool(server, 'draw_erase',
+    'Erase a single pixel (make transparent)',
+    { x: z.number().int(), y: z.number().int() },
+    (p) => ({ action: 'erasePixel', ...p }));
+
+  registerTool(server, 'draw_line',
+    'Draw a straight line using Bresenham algorithm',
+    { x0: z.number().int(), y0: z.number().int(), x1: z.number().int(), y1: z.number().int(), color: hexColor },
+    (p) => ({ action: 'drawLine', ...p }));
+
+  registerTool(server, 'draw_rect',
+    'Draw a rectangle (outline or filled)',
+    {
+      x: z.number().int().describe('Top-left X'), y: z.number().int().describe('Top-left Y'),
+      w: z.number().int().min(1).describe('Width'), h: z.number().int().min(1).describe('Height'),
+      color: hexColor, filled: z.boolean().default(false).describe('Fill interior?')
+    },
+    (p) => ({ action: 'drawRect', ...p }));
+
+  registerTool(server, 'draw_circle',
+    'Draw a circle (outline or filled)',
+    { cx: z.number().int().describe('Center X'), cy: z.number().int().describe('Center Y'),
+      r: z.number().int().min(1).describe('Radius'), color: hexColor, filled: z.boolean().default(false) },
+    (p) => ({ action: 'drawCircle', ...p }));
+
+  registerTool(server, 'draw_ellipse',
+    'Draw an ellipse (outline or filled)',
+    { cx: z.number().int(), cy: z.number().int(), rx: z.number().int().min(1).describe('Horizontal radius'),
+      ry: z.number().int().min(1).describe('Vertical radius'), color: hexColor, filled: z.boolean().default(false) },
+    (p) => ({ action: 'drawEllipse', ...p }));
+
+  registerTool(server, 'draw_polygon',
+    'Draw a polygon from a list of points (outline or filled)',
+    { points: z.array(z.object({ x: z.number().int(), y: z.number().int() })).min(3).describe('Array of {x,y} vertices'),
+      color: hexColor, filled: z.boolean().default(false) },
+    (p) => ({ action: 'drawPolygon', ...p }));
+
+  registerTool(server, 'draw_fill',
+    'Flood-fill starting from (x,y) with a color',
+    { x: z.number().int(), y: z.number().int(), color: hexColor },
+    (p) => ({ action: 'fill', ...p }));
+
+  registerTool(server, 'draw_gradient_rect',
+    'Draw a rectangle filled with a smooth gradient',
+    { x: z.number().int(), y: z.number().int(), w: z.number().int().min(1), h: z.number().int().min(1),
+      colorFrom: hexColor.describe('Start color'), colorTo: hexColor.describe('End color'),
+      direction: z.enum(['h', 'v']).default('h').describe('h=horizontal, v=vertical') },
+    (p) => ({ action: 'drawGradientRect', ...p }));
+
+  registerTool(server, 'bulk_replace_color',
+    'Replace ALL pixels of one color with another across the entire canvas',
+    { from: hexColor.describe('Color to replace'), to: hexColor.describe('New color') },
+    (p) => ({ action: 'replaceColor', from: p.from, to: p.to }));
+
+  registerTool(server, 'bulk_flood_fill_all',
+    'Flood-fill every disconnected region of a given color',
+    { color: hexColor.describe('Color to replace'), to: hexColor.describe('Replacement color') },
+    (p) => ({ action: 'floodFillAll', color: p.color, to: p.to }));
+}
+
+module.exports = { register };

package/tools/filters.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * filters.js — Visual Filter tools
+ *
+ * Tools: filter_apply
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'filter_apply',
+    `Apply a visual filter to the canvas (or a region).
+Types: brightness (value: -255 to 255), invert, grayscale, hue-rotate (value: degrees 0-360)`,
+    { type: z.enum(['brightness', 'invert', 'grayscale', 'hue-rotate']),
+      value: z.number().optional().describe('Parameter: brightness=-255..255, hue-rotate=0..360'),
+      x: z.number().int().optional(), y: z.number().int().optional(),
+      w: z.number().int().optional(), h: z.number().int().optional() },
+    (p) => ({ action: 'applyFilter', ...p }));
+}
+
+module.exports = { register };

package/tools/health.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * health.js — Health Check / Ping tools
+ *
+ * Tools: ping
+ */
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'ping',
+    'Check if the browser editor is connected and responding',
+    {},
+    () => ({ action: 'ping' }));
+}
+
+module.exports = { register };

package/tools/history.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * history.js — History (Undo/Redo) tools
+ *
+ * Tools: history_undo, history_redo
+ */
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'history_undo',
+    'Undo the last drawing action',
+    {},
+    () => ({ action: 'undo' }));
+
+  registerTool(server, 'history_redo',
+    'Redo the last undone action',
+    {},
+    () => ({ action: 'redo' }));
+}
+
+module.exports = { register };

package/tools/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * tools/index.js — Tool registry aggregator
+ *
+ * Imports and registers all core drawing/utility tools on an MCP server instance.
+ * To add a new tool category, create a new file in this folder and add it here.
+ */
+const canvas = require('./canvas');
+const workspace = require('./workspace');
+const animation = require('./animation');
+const drawing = require('./drawing');
+const sprite = require('./sprite');
+const region = require('./region');
+const filters = require('./filters');
+const anchors = require('./anchors');
+const query = require('./query');
+const history = require('./history');
+const modes = require('./modes');
+const colors = require('./colors');
+const health = require('./health');
+
+/**
+ * Register all core tools on the given MCP server instance.
+ * @param {McpServer} server
+ */
+function registerAll(server) {
+  canvas.register(server);
+  workspace.register(server);
+  animation.register(server);
+  drawing.register(server);
+  sprite.register(server);
+  region.register(server);
+  filters.register(server);
+  anchors.register(server);
+  query.register(server);
+  history.register(server);
+  modes.register(server);
+  colors.register(server);
+  health.register(server);
+}
+
+module.exports = { registerAll };

package/tools/modes.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * modes.js — Mode settings tools
+ *
+ * Tools: mode_set_mirror, mode_set_onion_skin, mode_set_grid
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'mode_set_mirror',
+    'Enable/disable mirror drawing mode (symmetric left-right)',
+    { enabled: z.boolean() },
+    (p) => ({ action: 'setMirror', enabled: p.enabled }));
+
+  registerTool(server, 'mode_set_onion_skin',
+    'Enable/disable onion skin (shows previous frame as ghost)',
+    { enabled: z.boolean() },
+    (p) => ({ action: 'setOnionSkin', enabled: p.enabled }));
+
+  registerTool(server, 'mode_set_grid',
+    'Show/hide the pixel grid overlay',
+    { enabled: z.boolean() },
+    (p) => ({ action: 'setGrid', enabled: p.enabled }));
+}
+
+module.exports = { register };

package/tools/query.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * query.js — Query & Visual Feedback tools
+ *
+ * Tools: query_snapshot, query_bounding_box, query_palette, query_pixel,
+ *        query_export_image, query_document_state
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'query_snapshot',
+    `Get an ASCII art representation of the current canvas frame. Use this to "see" what you've drawn before continuing.
+Returns: { ascii, legend, width, height } where each symbol in ascii maps to a hex color via legend.
+Increase scale to get a smaller grid (scale=2 means 1 char = 2×2 pixels).`,
+    { scale: z.number().int().min(1).max(8).default(1).describe('Downscale factor (1=full resolution)'),
+      maxColors: z.number().int().min(2).max(32).default(12).describe('Max distinct colors in legend') },
+    (p) => ({ action: 'querySnapshot', ...p }));
+
+  registerTool(server, 'query_bounding_box',
+    'Get the bounding box of all non-transparent pixels {minX, minY, maxX, maxY, width, height}',
+    {},
+    () => ({ action: 'query', type: 'getBoundingBox' }));
+
+  registerTool(server, 'query_palette',
+    'Get list of all distinct colors used on the canvas',
+    {},
+    () => ({ action: 'query', type: 'getPalette' }));
+
+  registerTool(server, 'query_pixel',
+    'Get the color of a specific pixel. Returns hex string or null if transparent.',
+    { x: z.number().int(), y: z.number().int() },
+    (p) => ({ action: 'getPixel', x: p.x, y: p.y }));
+
+  registerTool(server, 'query_export_image',
+    `Export the current frame as a base64 PNG data URL.
+Use this to visually verify your work — paste the dataUrl into an image viewer.
+The dataUrl starts with "data:image/png;base64,..."`,
+    { format: z.enum(['png', 'webp', 'jpeg']).default('png') },
+    (p) => ({ action: 'exportBase64', format: p.format }));
+
+  registerTool(server, 'query_document_state',
+    'Get full document state: tab name, canvas size, animation info, undo availability',
+    {},
+    () => ({ action: 'query', type: 'getDocumentState' }));
+}
+
+module.exports = { register };

package/tools/region.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * region.js — Region Clipboard tools
+ *
+ * Tools: region_copy, region_paste
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'region_copy',
+    'Copy a rectangular region of pixels to an internal clipboard',
+    { x: z.number().int().default(0), y: z.number().int().default(0),
+      w: z.number().int().min(1).describe('Width of region'), h: z.number().int().min(1).describe('Height of region') },
+    (p) => ({ action: 'copyRegion', ...p }));
+
+  registerTool(server, 'region_paste',
+    'Paste the clipboard region at (x,y). Defaults to original position.',
+    { x: z.number().int().optional().describe('X destination (default: original X)'),
+      y: z.number().int().optional().describe('Y destination (default: original Y)') },
+    (p) => ({ action: 'pasteRegion', ...p }));
+}
+
+module.exports = { register };

package/tools/sprite.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * sprite.js — Sprite / Stamp System tools
+ *
+ * Tools: sprite_draw, sprite_save_stamp, sprite_use_stamp, sprite_list_stamps
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'sprite_draw',
+    `Draw a sprite using ASCII art + color palette. Each character in the data array maps to a color.
+EXAMPLE:
+  palette: { "H": "#ffcc99", "B": "#1565c0", ".": null }
+  data:    [ "..H..", ".BBB.", "..H.." ]
+This is the most efficient way to draw complex shapes — replaces dozens of drawPixel calls.`,
+    {
+      x: z.number().int().default(0).describe('Top-left X offset'),
+      y: z.number().int().default(0).describe('Top-left Y offset'),
+      palette: z.record(z.string().length(1), z.string().nullable()).describe('Char→hex map. null = transparent/skip'),
+      data: z.array(z.string()).min(1).describe('Rows of ASCII art characters')
+    },
+    (p) => ({ action: 'drawSprite', ...p }));
+
+  registerTool(server, 'sprite_save_stamp',
+    'Save a named sprite for reuse across frames. Use sprite_use_stamp to place it.',
+    { name: z.string().describe('Unique stamp name'), palette: z.record(z.string().length(1), z.string().nullable()),
+      data: z.array(z.string()).min(1) },
+    (p) => ({ action: 'saveStamp', ...p }));
+
+  registerTool(server, 'sprite_use_stamp',
+    'Place a previously saved stamp at a position. Optionally override palette colors.',
+    { name: z.string().describe('Stamp name (from sprite_save_stamp)'), x: z.number().int().default(0),
+      y: z.number().int().default(0), palette: z.record(z.string().length(1), z.string().nullable()).optional().describe('Override specific palette colors') },
+    (p) => ({ action: 'useStamp', ...p }));
+
+  registerTool(server, 'sprite_list_stamps',
+    'List all saved stamp names',
+    {},
+    () => ({ action: 'listStamps' }));
+}
+
+module.exports = { register };

package/tools/workspace.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * workspace.js — Workspace / Tabs tools
+ *
+ * Tools: workspace_list_tabs, workspace_get_active_tab, workspace_create_tab,
+ *        workspace_switch_tab, workspace_rename_tab, workspace_save
+ */
+const { z } = require('zod');
+const { registerTool } = require('../core/server');
+
+function register(server) {
+  registerTool(server, 'workspace_list_tabs',
+    'List all open document tabs with their IDs and names',
+    {},
+    () => ({ action: 'listTabs' }));
+
+  registerTool(server, 'workspace_get_active_tab',
+    'Get the currently active tab ID',
+    {},
+    () => ({ action: 'getActiveTabId' }));
+
+  registerTool(server, 'workspace_create_tab',
+    'Create a new blank canvas tab',
+    {
+      name: z.string().optional().describe('Tab name'),
+      width: z.number().int().default(32).describe('Canvas width'),
+      height: z.number().int().default(32).describe('Canvas height')
+    },
+    (p) => ({ action: 'createTab', ...p }));
+
+  registerTool(server, 'workspace_switch_tab',
+    'Switch to a different tab by ID (get IDs from workspace_list_tabs)',
+    { tabId: z.string().describe('Tab ID to switch to') },
+    (p) => ({ action: 'switchTab', tabId: p.tabId }));
+
+  registerTool(server, 'workspace_rename_tab',
+    'Rename a tab',
+    { tabId: z.string(), name: z.string() },
+    (p) => ({ action: 'renameTab', ...p }));
+
+  registerTool(server, 'workspace_save',
+    'Quick-save the current workspace',
+    {},
+    () => ({ action: 'quickSave' }));
+}
+
+module.exports = { register };

package/transport/http.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * transport/http.js — HTTP transport for MCP server
+ *
+ * Starts an HTTP server that accepts MCP requests at /mcp.
+ * Supports CORS for browser tools, health checks at /health.
+ * Each HTTP request gets its own transport instance (stateless).
+ */
+const http = require('http');
+const crypto = require('crypto');
+const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { registerAll } = require('../tools/index');
+const { SESSION } = require('../core/command-bus');
+
+/**
+ * Build a fresh MCP server instance (used per HTTP request)
+ * @returns {McpServer}
+ */
+function buildServer() {
+  const { createServer } = require('../core/server');
+  const s = createServer();
+  registerAll(s);
+  return s;
+}
+
+/**
+ * Start the MCP server as an HTTP server on the given port
+ * @param {number} port - HTTP port to listen on
+ */
+async function start(port) {
+  const app = http.createServer(async (req, res) => {
+    // CORS for browser tools
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, DELETE');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, mcp-session-id');
+    if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
+
+    if (req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, session: SESSION, ts: Date.now() }));
+      return;
+    }
+
+    if (req.url !== '/mcp') {
+      res.writeHead(404); res.end('Use /mcp'); return;
+    }
+
+    // Read body
+    let body = '';
+    req.on('data', chunk => body += chunk);
+    req.on('end', async () => {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+        enableJsonResponse: true,
+      });
+      const freshServer = buildServer();
+      await freshServer.connect(transport);
+      await transport.handleRequest(
+        { method: req.method, headers: req.headers, body: JSON.parse(body || '{}') },
+        res,
+        JSON.parse(body || '{}')
+      );
+    });
+  });
+
+  app.listen(port, () => {
+    console.log(`\nPixel Normal Edit MCP HTTP Server`);
+    console.log(`   Endpoint : http://localhost:${port}/mcp`);
+    console.log(`   Health   : http://localhost:${port}/health`);
+    console.log(`   Session  : ${SESSION}`);
+    console.log(`   Editor   : http://localhost:5173?mcp_session=${SESSION}`);
+    console.log(`\n── AI config (paste into mcp_config.json) ──`);
+    console.log(JSON.stringify({
+      mcpServers: {
+        'pixel-normal-edit': {
+          command: 'npx',
+          args: ['mcp-remote', `http://localhost:${port}/mcp`]
+        }
+      }
+    }, null, 2));
+    console.log('────────────────────────────────────────────\n');
+  });
+}
+
+module.exports = { start };

package/transport/stdio.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * transport/stdio.js — Stdio transport for MCP server
+ *
+ * Connects the server to standard input/output for use with
+ * Claude Desktop, Cursor, Windsurf, and other stdio-based MCP clients.
+ */
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+
+/**
+ * Start the MCP server using the stdio transport
+ * @param {McpServer} server - The configured MCP server instance
+ */
+async function start(server) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Console.error output is suppressed to avoid JSON parsing issues
+  // with MCP clients that merge stdout and stderr.
+}
+
+module.exports = { start };