@pixel-normal-edit/mcp 2.0.0 → 2.0.2

package/README.md

@@ -0,0 +1,79 @@
+# @pixel-normal-edit/mcp
+
+**Model Context Protocol (MCP) Bridge for Pixel Normal Edit**
+
+This package is a standalone MCP server that allows AI agents (like Claude Desktop, Cursor, or Windsurf) to connect directly to your live [Pixel Normal Edit](https://github.com/TinhSsc/Pixel-Normal-Edit.git) canvas through Firebase. 
+
+By connecting your AI agent to this server, the AI can read your canvas state and draw pixel art in real time via structured tools.
+
+## How it works
+
+Since Pixel Normal Edit runs entirely in the browser (client-side), AI agents running on your desktop cannot manipulate its DOM directly. 
+This bridge solves that by using Firebase Firestore as a real-time message bus:
+
+1. **AI Agent** calls an MCP tool (e.g. `draw_rect`) via this Node.js bridge.
+2. **Bridge** writes the command to Firestore under your specific Session ID.
+3. **Browser** listens to that Firestore document, executes the command on the canvas, and writes the result back.
+4. **Bridge** reads the result and returns it to the AI Agent.
+
+## Usage (For Users)
+
+You do not need to download or clone this repository manually to use it! 
+
+To connect your AI, simply open Pixel Normal Edit, go to **Settings > Account > AI Connection (MCP)** and copy the provided command or configuration. 
+
+For example, to run it via `npx`:
+```bash
+npx -y @pixel-normal-edit/mcp YOUR_SESSION_ID
+```
+*(Replace `YOUR_SESSION_ID` with the ID provided in your app).*
+
+### Claude Desktop Configuration
+Add this to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "pixel-normal-edit": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@pixel-normal-edit/mcp",
+        "YOUR_SESSION_ID"
+      ]
+    }
+  }
+}
+```
+
+## Available AI Tools
+
+This bridge exposes dozens of native tools to the AI, categorized into:
+* **Drawing Primitives:** `draw_pixel`, `draw_rect`, `draw_circle`, `draw_line`, `draw_fill`, etc.
+* **Canvas Info & Vision:** `query_snapshot` (gets an ASCII representation of the canvas), `query_palette`, `query_bounding_box`, `canvas_get_size`.
+* **Sprite System:** `sprite_draw`, `sprite_save_stamp`, `sprite_use_stamp` for bulk drawing optimization.
+* **Animation Frames:** `animation_add_frame`, `animation_go_to_frame`, `animation_compare_frames`.
+* **Region & Bulk:** `region_copy`, `region_paste`, `bulk_replace_color`.
+
+## Development (For Contributors)
+
+If you want to modify this bridge or run it locally from source:
+
+1. Clone the project.
+2. Navigate to `mcp-firebase-bridge/`.
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+4. Copy the environment variables:
+   Ensure there is a `.env` file in the root of the project with your Firebase configuration.
+5. Run the bridge:
+   ```bash
+   npm start YOUR_SESSION_ID
+   ```
+
+### HTTP Mode
+By default, the server runs in `stdio` mode (standard for Claude Desktop). You can also run it as an HTTP server:
+```bash
+npm run mcp:http
+```
+(Or set `HTTP_PORT=3456`).

package/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * MCP Firebase Bridge v2
  * ─────────────────────────────────────────────────────────────────────────
@@ -11,26 +12,26 @@
  *  - Visual feedback via querySnapshot / exportBase64
  */
 
-const { McpServer }              = require('@modelcontextprotocol/sdk/server/mcp.js');
-const { StdioServerTransport }   = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
-const { z }                      = require('zod');
-const { initializeApp }          = require('firebase/app');
+const { z } = require('zod');
+const { initializeApp } = require('firebase/app');
 const { getFirestore, doc, setDoc, onSnapshot } = require('firebase/firestore');
-const dotenv                     = require('dotenv');
-const path                       = require('path');
-const crypto                     = require('crypto');
-const http                       = require('http');
+const dotenv = require('dotenv');
+const path = require('path');
+const crypto = require('crypto');
+const http = require('http');
 
 dotenv.config({ path: path.join(__dirname, '..', '.env') });
 
 const db = getFirestore(initializeApp({
-  apiKey: process.env.VITE_FIREBASE_API_KEY || 'AIzaSyBSrvCt58Jhsh14wbC2bD2KLFUUVbAVim0',
-  authDomain: process.env.VITE_FIREBASE_AUTH_DOMAIN || 'pixel-normal-edit.firebaseapp.com',
-  projectId: process.env.VITE_FIREBASE_PROJECT_ID || 'pixel-normal-edit',
-  storageBucket: process.env.VITE_FIREBASE_STORAGE_BUCKET || 'pixel-normal-edit.firebasestorage.app',
-  messagingSenderId: process.env.VITE_FIREBASE_MESSAGING_SENDER_ID || '397075334229',
-  appId: process.env.VITE_FIREBASE_APP_ID || '1:397075334229:web:b02eede3fc7b41d02f80dc',
+  apiKey: process.env.VITE_FIREBASE_API_KEY,
+  authDomain: process.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.VITE_FIREBASE_PROJECT_ID,
+  storageBucket: process.env.VITE_FIREBASE_STORAGE_BUCKET,
+  messagingSenderId: process.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
+  appId: process.env.VITE_FIREBASE_APP_ID,
 }));
 
 const SESSION = process.argv[2] || process.env.MCP_SESSION || 'default-session';
@@ -528,7 +529,7 @@ async function startHttp(port) {
   });
 
   app.listen(port, () => {
-    console.log(`\n🚀 Pixel Normal Edit MCP HTTP Server`);
+    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}`);

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@pixel-normal-edit/mcp",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "MCP server for Pixel Normal Edit canvas - enables AI agents to draw pixel art",
   "main": "index.js",
   "bin": {
     "pixel-normal-edit-mcp": "index.js"
   },
   "scripts": {
-    "start":     "node index.js",
-    "mcp":       "node index.js",
-    "mcp:http":  "node index.js --http",
+    "start": "node index.js",
+    "mcp": "node index.js",
+    "mcp:http": "node index.js --http",
     "mcp:setup": "node setup.js"
   },
-  "keywords": ["mcp", "pixel-art", "ai", "canvas"],
+  "keywords": [
+    "mcp",
+    "pixel-art",
+    "ai",
+    "canvas"
+  ],
   "author": "",
   "license": "ISC",
   "type": "commonjs",
@@ -20,7 +25,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "firebase": "^12.16.0",
+    "jimp": "^1.6.1",
     "zod": "^4.4.3"
   }
 }
-