pixelorama-mcp 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# Pixelorama MCP (Node.js client)
+
+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
+```bash
+npm install --save path/to/Pixelorama/mcp
+# or, from the repository root:
+npm install ./mcp
+```
+
+## Usage
+```js
+const { PixeloramaMCP } = require('pixelorama-mcp');
+
+(async () => {
+  const mcp = new PixeloramaMCP(); // defaults to ws://127.0.0.1:8080
+  await mcp.connect();
+
+  // Create a fresh project
+  await mcp.newProject();
+
+  // Add five frames
+  for (let i = 0; i < 5; i++) await mcp.addFrame();
+
+  // Set playback speed to 24 FPS
+  await mcp.setFPS(24);
+
+  // Enable onion‑skinning and configure it
+  await mcp.toggleOnion(true);
+  await mcp.setOnionPastRate(2);
+  await mcp.setOnionFutureRate(2);
+  await mcp.setOnionOpacity(0.7);
+
+  // Export as an animated GIF
+  await mcp.export('GIF', 'user://exports/animation.gif');
+
+  // Query the current project state
+  const status = await mcp.queryStatus();
+  console.log('Project status:', status.project_status);
+})();
+```
+
+All methods return **Promises** that resolve with the JSON reply from the MCP server. Errors are thrown as exceptions.
+
+## API reference
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `loadProject(path)` | `path: string` | Load a `.pxo` project file. |
+| `newProject()` | – | Create an empty project. |
+| `addFrame()` | – | Append a new frame to the timeline. |
+| `removeFrame(index)` | `index: number` | Delete the frame at *index*. |
+| `setFrameDuration(index, seconds)` | `index: number`, `seconds: number` | Set duration of a single frame. |
+| `setFPS(value)` | `value: number` | Change the project's frames‑per‑second. |
+| `toggleOnion(enabled)` | `enabled: boolean` | Turn onion‑skinning on/off. |
+| `setOnionPastRate(rate)` | `rate: number` | Number of past frames shown. |
+| `setOnionFutureRate(rate)` | `rate: number` | Number of future frames shown. |
+| `setOnionOpacity(value)` | `value: number (0‑1)` | Opacity of onion layers. |
+| `setOnionBlueRed(enabled)` | `enabled: boolean` | Enable blue‑red colour mode. |
+| `export(format, output)` | `format: string`, `output: string` | Export the current project. Supported formats: PNG, WEBP, JPEG, EXR, GIF, APNG, MP4, AVI, OGV, MKV, WEBM. |
+| `saveProject(path)` | `path: string` | Save the current project as a `.pxo`. |
+| `queryStatus()` | – | Return a snapshot of the current project (frames, FPS, onion settings, …). |
+
+The client also emits any **event** messages the server pushes (e.g., `project_saved`) via the standard `EventEmitter` interface:
+```js
+mcp.on('project_saved', (msg) => console.log('saved to', msg.path));
+```
+
+---
+
+> **Note**: The MCP server must be active inside Pixelorama (enable the "Pixelorama MCP" plugin under *Project → Project Settings → Plugins*). The server runs on port `8080` by default; you can change it by editing `addons/mcp/MCPServer.gd` (variable `port`).
+
+### Uso desde la línea de comandos
+Una vez que el servidor está corriendo, puedes usar el comando **pixelorama-mcp** que se instala con este paquete:
+```
+pixelorama-mcp new-project                # crea un proyecto nuevo
+pixelorama-mcp add-frame                 # añade un frame
+pixelorama-mcp set-fps 24                 # establece 24 FPS
+pixelorama-mcp export GIF path/to/out.gif # exporta a GIF
+```
+Estos comandos pueden ser invocados desde scripts, CI pipelines o herramientas de IA como Codex/Claude.
+

package/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+const { PixeloramaMCP } = require('./index');
+
+// Simple argument parser (no external deps)
+const args = process.argv.slice(2);
+
+function usage() {
+  console.log(`Pixelorama MCP CLI
+
+Usage: pixelorama-mcp [options] <command> [params]
+
+Options:
+  --host <host>      MCP server host (default: 127.0.0.1)
+  --port <port>      MCP server port (default: 8080)
+
+Commands:
+  new-project                     Create a new project
+  load-project <path>             Load a project from path
+  add-frame                       Add a new frame
+  remove-frame <index>            Remove frame at index (0‑based)
+  set-fps <value>                 Set frames‑per‑second
+  toggle-onion <true|false>      Enable/disable onion‑skin
+  export <format> <output>        Export (e.g., GIF, PNG) to output path
+  save-project <path>            Save current project
+  query-status                    Get server status (debug)
+
+Examples:
+  pixelorama-mcp new-project
+  pixelorama-mcp set-fps 24
+  pixelorama-mcp export GIF user://exports/anim.gif
+`);
+  process.exit(1);
+}
+
+// Parse options
+let host = '127.0.0.1';
+let port = 8080;
+let i = 0;
+while (i < args.length && args[i].startsWith('--')) {
+  const opt = args[i];
+  if (opt === '--host') {
+    host = args[i + 1];
+    i += 2;
+  } else if (opt === '--port') {
+    port = parseInt(args[i + 1], 10);
+    i += 2;
+  } else {
+    console.error('Unknown option:', opt);
+    usage();
+  }
+}
+
+if (i >= args.length) usage();
+
+const command = args[i];
+const params = args.slice(i + 1);
+
+(async () => {
+  const mcp = new PixeloramaMCP(`tcp://${host}:${port}`);
+  try {
+    await mcp.connect();
+  } catch (e) {
+    console.error('Connection error:', e.message);
+    process.exit(1);
+  }
+
+  try {
+    switch (command) {
+      case 'new-project':
+        await mcp.newProject();
+        console.log('Created new project');
+        break;
+      case 'load-project':
+        if (!params[0]) throw new Error('Missing path');
+        await mcp.loadProject(params[0]);
+        console.log('Project loaded');
+        break;
+      case 'add-frame':
+        await mcp.addFrame();
+        console.log('Frame added');
+        break;
+      case 'remove-frame':
+        if (params[0] === undefined) throw new Error('Missing index');
+        await mcp.removeFrame(parseInt(params[0], 10));
+        console.log('Frame removed');
+        break;
+      case 'set-fps':
+        if (!params[0]) throw new Error('Missing FPS value');
+        await mcp.setFPS(parseInt(params[0], 10));
+        console.log('FPS set');
+        break;
+      case 'toggle-onion':
+        if (!params[0]) throw new Error('Missing true/false');
+        await mcp.toggleOnion(params[0] === 'true');
+        console.log('Onion‑skin toggled');
+        break;
+      case 'export':
+        if (!params[0] || !params[1]) throw new Error('Missing format or output');
+        await mcp.export(params[0], params[1]);
+        console.log('Exported');
+        break;
+      case 'save-project':
+        if (!params[0]) throw new Error('Missing path');
+        await mcp.saveProject(params[0]);
+        console.log('Project saved');
+        break;
+      case 'query-status':
+        const status = await mcp.queryStatus();
+        console.log('Status:', JSON.stringify(status, null, 2));
+        break;
+      default:
+        console.error('Unknown command:', command);
+        usage();
+    }
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+})();

package/index.js

@@ -0,0 +1,125 @@
+const net = require('net');
+const EventEmitter = require('events');
+
+/**
+ * PixeloramaMCP – simple client for the Pixelorama Model Communication Protocol.
+ *
+ * Usage example (async/await):
+ *   const { PixeloramaMCP } = require('pixelorama-mcp');
+ *   const mcp = new PixeloramaMCP();
+ *   await mcp.connect();
+ *   await mcp.newProject();
+ *   await mcp.addFrame();
+ *   await mcp.setFPS(24);
+ *   await mcp.toggleOnion(true);
+ *   await mcp.export('GIF', 'user://exports/anim.gif');
+ */
+
+class PixeloramaMCP extends EventEmitter {
+  /**
+   * @param {string} url WebSocket URL of the MCP server inside Pixelorama.
+   */
+  constructor(url = 'tcp://127.0.0.1:8080') {
+    super();
+    this.url = url;
+    this.ws = null;
+    this._pending = new Map(); // id -> {resolve, reject}
+    this._nextId = 1;
+  }
+
+  /** Connect to the MCP server. */
+  async connect() {
+    // Support only TCP connections for the built-in server.
+    if (this.ws && !this.ws.destroyed) return;
+    // Parse tcp://host:port
+    const addr = this.url.replace(/^tcp:\/\//, '');
+    const [host, portStr] = addr.split(':');
+    const port = parseInt(portStr, 10);
+    this.ws = new net.Socket();
+    // Buffer for incomplete lines.
+    this._buffer = '';
+    await new Promise((resolve, reject) => {
+      this.ws.connect(port, host, resolve);
+      this.ws.on('error', reject);
+    });
+    this.ws.on('data', (data) => {
+      this._buffer += data.toString();
+      let index;
+      while ((index = this._buffer.indexOf('\n')) >= 0) {
+        const line = this._buffer.slice(0, index);
+        this._buffer = this._buffer.slice(index + 1);
+        if (line) this._handleMessage(line);
+      }
+    });
+    this.ws.on('close', () => {
+      // Reject any pending promises when the connection drops.
+      for (const { reject } of this._pending.values()) {
+        reject(new Error('TCP connection closed'));
+      }
+      this._pending.clear();
+      this.emit('close');
+    });
+  }
+
+  _handleMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch (e) {
+      // Ignore malformed messages.
+      return;
+    }
+    // Resolve pending request if it contains an id.
+    if (msg.id && this._pending.has(msg.id)) {
+      const { resolve, reject } = this._pending.get(msg.id);
+      this._pending.delete(msg.id);
+      if (msg.status === 'ok') {
+        resolve(msg);
+      } else {
+        reject(new Error(msg.message || 'MCP error'));
+      }
+      return;
+    }
+    // Emit unsolicited events so the user can listen.
+    if (msg.event) {
+      this.emit(msg.event, msg);
+    }
+  }
+
+  /** Send a command and return a promise that resolves with the reply. */
+  _send(command, params = {}) {
+    const id = this._nextId++;
+    const payload = Object.assign({ command, id }, params);
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      try {
+        this.ws.write(JSON.stringify(payload) + "\n");
+      } catch (e) {
+        this._pending.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  // -----------------------------------------------------------------
+  // API methods – each returns a Promise that resolves to the server reply.
+  // -----------------------------------------------------------------
+  loadProject(path) { return this._send('load_project', { path }); }
+  newProject() { return this._send('new_project'); }
+  addFrame() { return this._send('add_frame'); }
+  removeFrame(index) { return this._send('remove_frame', { index }); }
+  setFrameDuration(index, seconds) {
+    return this._send('set_frame_duration', { index, seconds });
+  }
+  setFPS(value) { return this._send('set_fps', { value }); }
+  toggleOnion(enabled) { return this._send('toggle_onion', { enabled }); }
+  setOnionPastRate(rate) { return this._send('set_onion_past_rate', { rate }); }
+  setOnionFutureRate(rate) { return this._send('set_onion_future_rate', { rate }); }
+  setOnionOpacity(value) { return this._send('set_onion_opacity', { value }); }
+  setOnionBlueRed(enabled) { return this._send('set_onion_blue_red', { enabled }); }
+  export(format, output) { return this._send('export', { format, output }); }
+  saveProject(path) { return this._send('save_project', { path }); }
+  queryStatus() { return this._send('query_status'); }
+}
+
+module.exports = { PixeloramaMCP };

package/package.json

@@ -0,0 +1,17 @@
+{
+  "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.",
+  "main": "index.js",
+  "bin": {
+    "pixelorama-mcp": "cli.js"
+  },
+  "scripts": {
+    "test": "node index.js"
+  },
+  "author": "OpenAI",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.13.0"
+  }
+}

package/test.js

@@ -0,0 +1,9 @@
+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);
+})();