pixelorama-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,29 @@
 # Pixelorama MCP (Node.js client)
 
+**Versión:** 0.1.1
+
+
 This package provides a **Node.js client** for the **Pixelorama Model Communication Protocol (MCP)** that is implemented inside Pixelorama as a GDScript WebSocket server (see `addons/mcp`).
 
-## Installation
+## Instalación
+
+### Desde npm (recomendado)
+```bash
+# Instalar globalmente para usar el comando en cualquier terminal
+npm i -g pixelorama-mcp
+
+# O bien, usar directamente sin instalar con npx
+npx pixelorama-mcp --help
+```
+
+### Instalación local (para desarrollo)
 ```bash
-npm install --save path/to/Pixelorama/mcp
-# or, from the repository root:
-npm install ./mcp
+# Desde la raíz del repositorio (en tu máquina)
+npm install ./mcp   # instala como dependencia del proyecto
+npm link ./mcp          # crea el enlace global `pixelorama-mcp`
 ```
 
+
 ## Usage
 ```js
 const { PixeloramaMCP } = require('pixelorama-mcp');

package/bridge.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+const net = require('net');
+const readline = require('readline');
+
+const PIXELORAMA_HOST = process.env.PIXELORAMA_HOST || '127.0.0.1';
+const PIXELORAMA_PORT = parseInt(process.env.PIXELORAMA_PORT || '8080', 10);
+
+let tcpClient = null;
+let tcpBuffer = '';
+let tcpPending = new Map();
+let tcpNextId = 1;
+
+const TOOLS = [
+	{
+		name: 'new_project',
+		description: 'Create a new empty project in Pixelorama.',
+		inputSchema: { type: 'object', properties: {}, required: [] }
+	},
+	{
+		name: 'load_project',
+		description: 'Load a Pixelorama project from a file path.',
+		inputSchema: {
+			type: 'object',
+			properties: { path: { type: 'string', description: 'Absolute path to .pxo file' } },
+			required: ['path']
+		}
+	},
+	{
+		name: 'save_project',
+		description: 'Save the current project to a .pxo file.',
+		inputSchema: {
+			type: 'object',
+			properties: { path: { type: 'string', description: 'Absolute path to save .pxo file' } },
+			required: ['path']
+		}
+	},
+	{
+		name: 'add_frame',
+		description: 'Add a new frame to the current project.',
+		inputSchema: { type: 'object', properties: {}, required: [] }
+	},
+	{
+		name: 'remove_frame',
+		description: 'Remove a frame by index from the current project.',
+		inputSchema: {
+			type: 'object',
+			properties: { index: { type: 'integer', description: 'Frame index (0-based)' } },
+			required: ['index']
+		}
+	},
+	{
+		name: 'set_frame_duration',
+		description: 'Set the duration of a specific frame in seconds.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				index: { type: 'integer', description: 'Frame index (0-based)' },
+				seconds: { type: 'number', description: 'Duration in seconds' }
+			},
+			required: ['index', 'seconds']
+		}
+	},
+	{
+		name: 'set_fps',
+		description: 'Set the frames per second of the current project.',
+		inputSchema: {
+			type: 'object',
+			properties: { value: { type: 'number', description: 'FPS value (must be > 0)' } },
+			required: ['value']
+		}
+	},
+	{
+		name: 'toggle_onion',
+		description: 'Enable or disable onion skinning.',
+		inputSchema: {
+			type: 'object',
+			properties: { enabled: { type: 'boolean', description: 'true to enable, false to disable' } },
+			required: ['enabled']
+		}
+	},
+	{
+		name: 'set_onion_past_rate',
+		description: 'Set how many past frames are shown in onion skinning.',
+		inputSchema: {
+			type: 'object',
+			properties: { rate: { type: 'integer', description: 'Number of past frames' } },
+			required: ['rate']
+		}
+	},
+	{
+		name: 'set_onion_future_rate',
+		description: 'Set how many future frames are shown in onion skinning.',
+		inputSchema: {
+			type: 'object',
+			properties: { rate: { type: 'integer', description: 'Number of future frames' } },
+			required: ['rate']
+		}
+	},
+	{
+		name: 'set_onion_opacity',
+		description: 'Set onion skinning opacity (0.0 to 1.0).',
+		inputSchema: {
+			type: 'object',
+			properties: { value: { type: 'number', description: 'Opacity value (0.0-1.0)' } },
+			required: ['value']
+		}
+	},
+	{
+		name: 'set_onion_blue_red',
+		description: 'Toggle blue/red onion skinning mode.',
+		inputSchema: {
+			type: 'object',
+			properties: { enabled: { type: 'boolean', description: 'true for blue/red mode' } },
+			required: ['enabled']
+		}
+	},
+	{
+		name: 'export_project',
+		description: 'Export the current project as an image or animation.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				format: { type: 'string', description: 'Export format: PNG, WEBP, JPEG, GIF, APNG, MP4, etc.' },
+				output: { type: 'string', description: 'Output file path' }
+			},
+			required: ['format', 'output']
+		}
+	},
+	{
+		name: 'query_status',
+		description: 'Get the current project status (frames, fps, onion settings).',
+		inputSchema: { type: 'object', properties: {}, required: [] }
+	}
+];
+
+const TOOL_TO_COMMAND = {
+	new_project: 'new_project',
+	load_project: 'load_project',
+	save_project: 'save_project',
+	add_frame: 'add_frame',
+	remove_frame: 'remove_frame',
+	set_frame_duration: 'set_frame_duration',
+	set_fps: 'set_fps',
+	toggle_onion: 'toggle_onion',
+	set_onion_past_rate: 'set_onion_past_rate',
+	set_onion_future_rate: 'set_onion_future_rate',
+	set_onion_opacity: 'set_onion_opacity',
+	set_onion_blue_red: 'set_onion_blue_red',
+	export_project: 'export',
+	query_status: 'query_status'
+};
+
+const TOOL_PARAMS_MAP = {
+	load_project: (p) => ({ path: p.path }),
+	save_project: (p) => ({ path: p.path }),
+	remove_frame: (p) => ({ index: p.index }),
+	set_frame_duration: (p) => ({ index: p.index, seconds: p.seconds }),
+	set_fps: (p) => ({ value: p.value }),
+	toggle_onion: (p) => ({ enabled: p.enabled }),
+	set_onion_past_rate: (p) => ({ rate: p.rate }),
+	set_onion_future_rate: (p) => ({ rate: p.rate }),
+	set_onion_opacity: (p) => ({ value: p.value }),
+	set_onion_blue_red: (p) => ({ enabled: p.enabled }),
+	export_project: (p) => ({ format: p.format, output: p.output })
+};
+
+function ensureConnection() {
+	return new Promise((resolve, reject) => {
+		if (tcpClient && !tcpClient.destroyed && tcpClient.readyState === 'open') {
+			return resolve();
+		}
+		tcpClient = new net.Socket();
+		tcpBuffer = '';
+		tcpClient.connect(PIXELORAMA_PORT, PIXELORAMA_HOST, () => resolve());
+		tcpClient.on('error', (err) => {
+			tcpClient = null;
+			reject(err);
+		});
+		tcpClient.on('data', (data) => {
+			tcpBuffer += data.toString();
+			let idx;
+			while ((idx = tcpBuffer.indexOf('\n')) >= 0) {
+				const line = tcpBuffer.slice(0, idx);
+				tcpBuffer = tcpBuffer.slice(idx + 1);
+				if (!line) continue;
+				try {
+					const msg = JSON.parse(line);
+					if (msg.id && tcpPending.has(msg.id)) {
+						const { resolve: res, reject: rej } = tcpPending.get(msg.id);
+						tcpPending.delete(msg.id);
+						if (msg.status === 'ok') res(msg);
+						else rej(new Error(msg.message || msg.code || 'Pixelorama error'));
+					}
+				} catch (_) {}
+			}
+		});
+		tcpClient.on('close', () => { tcpClient = null; });
+	});
+}
+
+function sendToPixelorama(command, params = {}) {
+	return new Promise(async (resolve, reject) => {
+		try {
+			await ensureConnection();
+		} catch (e) {
+			return reject(new Error('Cannot connect to Pixelorama on ' + PIXELORAMA_HOST + ':' + PIXELORAMA_PORT + '. Is Pixelorama running with MCP server enabled?'));
+		}
+		const id = tcpNextId++;
+		const payload = Object.assign({ command, id }, params);
+		tcpPending.set(id, { resolve, reject });
+		try {
+			tcpClient.write(JSON.stringify(payload) + '\n');
+		} catch (e) {
+			tcpPending.delete(id);
+			reject(e);
+		}
+	});
+}
+
+function sendJsonRpc(msg) {
+	process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+async function handleRequest(msg) {
+	if (!msg || !msg.method) {
+		sendJsonRpc({ jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: msg?.id ?? null });
+		return;
+	}
+
+	const { method, params, id } = msg;
+
+	if (method === 'initialize') {
+		sendJsonRpc({
+			jsonrpc: '2.0',
+			result: {
+				protocolVersion: '2024-11-05',
+				capabilities: { tools: { listChanged: false } },
+				serverInfo: { name: 'pixelorama-mcp', version: '0.2.0' }
+			},
+			id
+		});
+		return;
+	}
+
+	if (method === 'notifications/initialized') {
+		return;
+	}
+
+	if (method === 'ping') {
+		sendJsonRpc({ jsonrpc: '2.0', result: {}, id });
+		return;
+	}
+
+	if (method === 'tools/list') {
+		sendJsonRpc({ jsonrpc: '2.0', result: { tools: TOOLS }, id });
+		return;
+	}
+
+	if (method === 'tools/call') {
+		const toolName = params?.name;
+		const toolArgs = params?.arguments || {};
+		const cmd = TOOL_TO_COMMAND[toolName];
+		if (!cmd) {
+			sendJsonRpc({
+				jsonrpc: '2.0',
+				error: { code: -32601, message: 'Unknown tool: ' + toolName },
+				id
+			});
+			return;
+		}
+		try {
+			const mappedParams = TOOL_PARAMS_MAP[toolName] ? TOOL_PARAMS_MAP[toolName](toolArgs) : {};
+			const result = await sendToPixelorama(cmd, mappedParams);
+			sendJsonRpc({
+				jsonrpc: '2.0',
+				result: {
+					content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+				},
+				id
+			});
+		} catch (err) {
+			sendJsonRpc({
+				jsonrpc: '2.0',
+				result: {
+					content: [{ type: 'text', text: 'Error: ' + err.message }],
+					isError: true
+				},
+				id
+			});
+		}
+		return;
+	}
+
+	sendJsonRpc({
+		jsonrpc: '2.0',
+		error: { code: -32601, message: 'Method not found: ' + method },
+		id
+	});
+}
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on('line', (line) => {
+	const trimmed = line.trim();
+	if (!trimmed) return;
+	let msg;
+	try { msg = JSON.parse(trimmed); } catch (_) { return; }
+	handleRequest(msg);
+});
+rl.on('close', () => {
+	if (tcpClient) tcpClient.destroy();
+	process.exit(0);
+});

package/package.json

@@ -1,17 +1,32 @@
 {
   "name": "pixelorama-mcp",
-  "version": "0.1.0",
-  "description": "Node.js client for Pixelorama Model Communication Protocol (MCP). Allows external scripts to control Pixelorama via WebSocket.",
+  "version": "0.2.0",
+  "description": "MCP server bridge for Pixelorama – exposes Pixelorama tools via the Model Context Protocol (stdio JSON-RPC).",
   "main": "index.js",
   "bin": {
-    "pixelorama-mcp": "cli.js"
+    "pixelorama-mcp": "bridge.js",
+    "pixelorama-mcp-cli": "cli.js"
   },
+  "files": [
+    "bridge.js",
+    "cli.js",
+    "index.js"
+  ],
   "scripts": {
-    "test": "node index.js"
+    "test": "node test.js",
+    "bridge": "node bridge.js"
   },
-  "author": "OpenAI",
+  "keywords": [
+    "mcp",
+    "pixelorama",
+    "pixel-art",
+    "model-context-protocol",
+    "stdio"
+  ],
+  "author": "escobarq",
   "license": "MIT",
-  "dependencies": {
-    "ws": "^8.13.0"
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/test.js

@@ -1,9 +0,0 @@
-const { PixeloramaMCP } = require('./index');
-(async () => {
-  const mcp = new PixeloramaMCP();
-  await mcp.connect();
-  console.log('Connected');
-  const status = await mcp.queryStatus();
-  console.log('Status:', status);
-  process.exit(0);
-})();