@pixel-normal-edit/mcp 2.0.3 → 2.0.5

package/README.md

@@ -16,6 +16,14 @@ This bridge solves that by using Firebase Firestore as a real-time message bus:
 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.
 
+## Security Information
+
+You might notice that the Firebase API keys (`VITE_FIREBASE_API_KEY`, etc.) are included directly in the source code of this package. This is completely safe and by design:
+
+* **API Keys are Routing Identifiers:** In the context of Firebase Web SDK, these keys are NOT secret passwords. They merely act as a "public address" to tell the bridge which Firebase project to connect to.
+* **Firestore Security Rules:** Real security is enforced on the server-side via `firestore.rules`. The rules ensure that connections can only be established using a valid, unguessable UUID (the Session ID). 
+* **Zero User Data Access:** The bridge only has access to its designated `mcp_sessions` sandbox. It is explicitly blocked from reading or writing any user accounts, passwords, or other collections.
+
 ## Usage (For Users)
 
 You do not need to download or clone this repository manually to use it! 
@@ -24,7 +32,7 @@ To connect your AI, simply open Pixel Normal Edit, go to **Settings > Account >
 
 For example, to run it via `npx`:
 ```bash
-npx -y @pixel-normal-edit/mcp YOUR_SESSION_ID
+npx -y @pixel-normal-edit/mcp@latest YOUR_SESSION_ID
 ```
 *(Replace `YOUR_SESSION_ID` with the ID provided in your app).*
 
@@ -37,9 +45,12 @@ Add this to your `claude_desktop_config.json`:
       "command": "npx",
       "args": [
         "-y",
-        "@pixel-normal-edit/mcp",
+        "@pixel-normal-edit/mcp@latest",
         "YOUR_SESSION_ID"
-      ]
+      ],
+      "env": {
+        "DOTENV_CONFIG_QUIET": "true"
+      }
     }
   }
 }

package/core/command-bus.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * command-bus.js — Firebase-backed command bus for MCP
+ *
+ * Sends a JSON command payload to Firestore under the current session,
+ * then waits for the browser editor to respond with success/error.
+ */
+const crypto = require('crypto');
+const { doc, setDoc, onSnapshot } = require('firebase/firestore');
+const { db } = require('./firebase');
+
+const SESSION = process.argv[2] || process.env.MCP_SESSION || 'default-session';
+const TIMEOUT = parseInt(process.env.MCP_TIMEOUT || '20000');
+
+/**
+ * Send a command payload to the browser via Firestore and wait for response.
+ * @param {Object} payload - The command action and parameters
+ * @returns {Promise<Object>} MCP-compatible response object
+ */
+async function sendCommand(payload) {
+  const id = crypto.randomUUID();
+  const ref = doc(db, 'mcp_sessions', SESSION, 'commands', id);
+  await setDoc(ref, { ...payload, status: 'pending', timestamp: Date.now() });
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      unsub();
+      resolve({
+        isError: true,
+        content: [{ type: 'text', text: `⏱ Timeout (${TIMEOUT}ms). Is the browser tab open with session: ${SESSION}?` }]
+      });
+    }, TIMEOUT);
+
+    const unsub = onSnapshot(ref, (snap) => {
+      const d = snap.data();
+      if (!d) return;
+      if (d.status === 'success') {
+        clearTimeout(timer); unsub();
+        const out = d.result !== undefined ? JSON.stringify(d.result, null, 2) : '✓ Done';
+        resolve({ content: [{ type: 'text', text: out }] });
+      } else if (d.status === 'error') {
+        clearTimeout(timer); unsub();
+        resolve({ isError: true, content: [{ type: 'text', text: `❌ ${d.error}` }] });
+      }
+    });
+  });
+}
+
+module.exports = { sendCommand, SESSION };

package/core/firebase.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * firebase.js — Firebase initialization for MCP Firebase Bridge
+ *
+ * Initializes and exports the Firestore database instance.
+ * All Firebase config is hardcoded (safe as these are public API keys).
+ */
+const { initializeApp } = require('firebase/app');
+const { getFirestore } = require('firebase/firestore');
+const path = require('path');
+const dotenv = require('dotenv');
+
+dotenv.config({ path: path.join(__dirname, '..', '..', '.env') });
+
+const app = initializeApp({
+  apiKey: 'AIzaSyBSrvCt58Jhsh14wbC2bD2KLFUUVbAVim0',
+  authDomain: 'pixel-normal-edit.firebaseapp.com',
+  projectId: 'pixel-normal-edit',
+  storageBucket: 'pixel-normal-edit.firebasestorage.app',
+  messagingSenderId: '397075334229',
+  appId: '1:397075334229:web:b02eede3fc7b41d02f80dc',
+});
+
+const db = getFirestore(app);
+
+module.exports = { db };

package/core/server.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * server.js — MCP Server instance factory
+ *
+ * Creates and configures the McpServer instance.
+ * Provides a tool registration factory for consistent tool definitions.
+ */
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { sendCommand } = require('./command-bus');
+
+/**
+ * Create a new MCP server instance
+ * @returns {McpServer}
+ */
+function createServer() {
+  return new McpServer({ name: 'PixelNormalEdit', version: '2.0.0' });
+}
+
+/**
+ * Register a single-command tool on the server
+ * @param {McpServer} server - The MCP server instance
+ * @param {string} name - Tool name
+ * @param {string} desc - Tool description
+ * @param {Object} schema - Zod schema for parameters
+ * @param {Function} mapToCmd - Function mapping params to command payload
+ */
+function registerTool(server, name, desc, schema, mapToCmd) {
+  server.tool(name, desc, schema, async (params) => sendCommand(mapToCmd(params)));
+}
+
+module.exports = { createServer, registerTool, sendCommand };

package/domains/art-tree/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * domains/art-tree/index.js — Art Tree Module Aggregator
+ *
+ * Aggregates and exports all Art Tree module components.
+ * To add new features to this module, create a new file and add it here.
+ *
+ * Module namespace: art_tree_* (all tools prefixed with art_tree_)
+ */
+const shapes = require('./shapes');
+const lessons = require('./lessons');
+const tools = require('./tools');
+
+/**
+ * Register all Art Tree MCP tools on the server
+ * @param {McpServer} server
+ */
+function registerAll(server) {
+  tools.register(server);
+}
+
+module.exports = {
+  shapes,
+  lessons,
+  tools,
+  registerAll,
+};

package/domains/art-tree/lessons.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * lessons.js — Art Tree: Basic Shapes Lessons
+ *
+ * Layer: Lesson API (built on top of Shape API)
+ *
+ * Provides structured lessons that guide learners through
+ * drawing basic geometric shapes step by step.
+ * Each lesson returns a sequence of command payloads.
+ */
+const shapes = require('./shapes');
+
+/**
+ * Lesson 1: Lines — Introduction to drawing straight lines.
+ * Teaches horizontal, vertical, and diagonal lines.
+ * @param {number} canvasSize - Canvas dimension (assumes square)
+ * @param {string} color - Primary color for the lesson
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonLines(canvasSize = 32, color = '#ff0000') {
+  const mid = Math.floor(canvasSize / 2);
+  const margin = Math.floor(canvasSize * 0.15);
+  return [
+    // Horizontal line
+    shapes.drawLine(margin, mid, canvasSize - margin, mid, color),
+    // Vertical line
+    shapes.drawLine(mid, margin, mid, canvasSize - margin, '#0000ff'),
+    // Diagonal (top-left to bottom-right)
+    shapes.drawLine(margin, margin, canvasSize - margin, canvasSize - margin, '#00aa00'),
+    // Diagonal (top-right to bottom-left)
+    shapes.drawLine(canvasSize - margin, margin, margin, canvasSize - margin, '#ff8800'),
+  ];
+}
+
+/**
+ * Lesson 2: Squares & Rectangles — Understanding right angles and proportions.
+ * @param {number} canvasSize - Canvas dimension
+ * @param {string} color - Primary color
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonSquares(canvasSize = 32, color = '#1565c0') {
+  const margin = Math.floor(canvasSize * 0.1);
+  const small = Math.floor(canvasSize * 0.2);
+  const large = Math.floor(canvasSize * 0.35);
+  return [
+    // Small square (outline)
+    shapes.drawSquare(margin, margin, small, color, false),
+    // Large square (filled)
+    shapes.drawSquare(canvasSize - margin - large, margin, large, '#ff7043', true),
+    // Rectangle (horizontal)
+    shapes.drawRectangle(margin, canvasSize - margin - small, large + small, small, '#4caf50', false),
+    // Rectangle (vertical, filled)
+    shapes.drawRectangle(canvasSize - margin - small, canvasSize - margin - large, small, large, '#9c27b0', true),
+  ];
+}
+
+/**
+ * Lesson 3: Circles — Learning curves and symmetry.
+ * @param {number} canvasSize - Canvas dimension
+ * @param {string} color - Primary color
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonCircles(canvasSize = 32, color = '#e91e63') {
+  const mid = Math.floor(canvasSize / 2);
+  const r1 = Math.floor(canvasSize * 0.15);
+  const r2 = Math.floor(canvasSize * 0.3);
+  return [
+    // Small circle (outline)
+    shapes.drawCircle(mid, mid, r1, color, false),
+    // Large circle (filled)
+    shapes.drawCircle(mid, mid, r2, '#2196f3', true),
+    // Small filled circle offset
+    shapes.drawCircle(mid + r1, mid - r1, Math.floor(r1 / 2), '#ff9800', true),
+  ];
+}
+
+/**
+ * Lesson 4: Ellipses — Understanding oval shapes and proportions.
+ * @param {number} canvasSize - Canvas dimension
+ * @param {string} color - Primary color
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonEllipses(canvasSize = 32, color = '#9c27b0') {
+  const mid = Math.floor(canvasSize / 2);
+  const rx = Math.floor(canvasSize * 0.3);
+  const ry = Math.floor(canvasSize * 0.15);
+  return [
+    // Horizontal ellipse (outline)
+    shapes.drawEllipse(mid, mid, rx, ry, color, false),
+    // Vertical ellipse (filled)
+    shapes.drawEllipse(mid, mid, ry, rx, '#4caf50', true),
+    // Small circle-like ellipse
+    shapes.drawEllipse(mid + rx, mid - ry, Math.floor(rx / 3), Math.floor(ry / 2), '#ff5722', true),
+  ];
+}
+
+/**
+ * Lesson 5: Triangles — Three-point shapes and stability.
+ * @param {number} canvasSize - Canvas dimension
+ * @param {string} color - Primary color
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonTriangles(canvasSize = 32, color = '#ff5722') {
+  const mid = Math.floor(canvasSize / 2);
+  const size = Math.floor(canvasSize * 0.4);
+  const margin = Math.floor(canvasSize * 0.1);
+  return [
+    // Equilateral triangle (outline)
+    shapes.drawEquilateralTriangle(mid, mid, size, color, false),
+    // Right triangle (filled)
+    shapes.drawTriangle([
+      { x: margin, y: canvasSize - margin },
+      { x: margin, y: margin },
+      { x: Math.floor(canvasSize * 0.35), y: canvasSize - margin },
+    ], '#3f51b5', true),
+    // Inverted triangle
+    shapes.drawEquilateralTriangle(mid, mid, Math.floor(size * 0.6), '#009688', true),
+  ];
+}
+
+/**
+ * Lesson 6: Polygons — Multi-sided shapes.
+ * @param {number} canvasSize - Canvas dimension
+ * @param {string} color - Primary color
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonPolygons(canvasSize = 32, color = '#607d8b') {
+  const mid = Math.floor(canvasSize / 2);
+  const r = Math.floor(canvasSize * 0.35);
+  return [
+    // Pentagon
+    shapes.drawRegularPolygon(mid, mid, 5, r, '#4caf50', false),
+    // Hexagon (filled)
+    shapes.drawRegularPolygon(mid, mid, 6, Math.floor(r * 0.7), '#ff9800', true),
+    // Octagon
+    shapes.drawRegularPolygon(mid, mid, 8, Math.floor(r * 0.5), '#9c27b0', false),
+  ];
+}
+
+/**
+ * Lesson 7: Composition — Combining basic shapes to create simple objects.
+ * @param {number} canvasSize - Canvas dimension
+ * @returns {Array<Object>} Array of command payloads
+ */
+function lessonComposition(canvasSize = 32) {
+  const mid = Math.floor(canvasSize / 2);
+  const q1 = Math.floor(canvasSize * 0.25);
+  const q3 = Math.floor(canvasSize * 0.75);
+  const small = Math.floor(canvasSize * 0.1);
+  return [
+    // House: square body
+    shapes.drawSquare(q1, mid, q3 - q1, '#8d6e63', true),
+    // House: triangle roof
+    shapes.drawTriangle([
+      { x: q1 - 1, y: mid },
+      { x: mid, y: q1 },
+      { x: q3 + 1, y: mid },
+    ], '#d32f2f', true),
+    // Sun: circle
+    shapes.drawCircle(canvasSize - small - 2, small + 2, small, '#ffc107', true),
+    // Tree: rectangle trunk
+    shapes.drawRectangle(q1 + small, canvasSize - small - 2, Math.floor(small / 2), small, '#5d4037', true),
+    // Tree: circle top
+    shapes.drawCircle(q1 + Math.floor(small / 4), canvasSize - small - 4, Math.floor(small / 2), '#388e3c', true),
+  ];
+}
+
+/**
+ * Get all available lessons with metadata.
+ * @returns {Array<{id: string, name: string, description: string, fn: Function}>}
+ */
+function getLessonCatalog() {
+  return [
+    { id: 'lines', name: 'Đường thẳng', description: 'Vẽ đường thẳng ngang, dọc và chéo', fn: lessonLines },
+    { id: 'squares', name: 'Hình vuông & Hình chữ nhật', description: 'Hiểu về góc vuông và tỷ lệ', fn: lessonSquares },
+    { id: 'circles', name: 'Hình tròn', description: 'Làm quen với đường cong và đối xứng', fn: lessonCircles },
+    { id: 'ellipses', name: 'Hình elip', description: 'Hiểu về hình bầu dục và tỷ lệ', fn: lessonEllipses },
+    { id: 'triangles', name: 'Hình tam giác', description: 'Hình ba cạnh và sự ổn định', fn: lessonTriangles },
+    { id: 'polygons', name: 'Đa giác', description: 'Hình nhiều cạnh', fn: lessonPolygons },
+    { id: 'composition', name: 'Tổng hợp', description: 'Kết hợp các hình cơ bản tạo vật thể đơn giản', fn: lessonComposition },
+  ];
+}
+
+module.exports = {
+  lessonLines,
+  lessonSquares,
+  lessonCircles,
+  lessonEllipses,
+  lessonTriangles,
+  lessonPolygons,
+  lessonComposition,
+  getLessonCatalog,
+};

package/domains/art-tree/shapes.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * shapes.js — Art Tree: Basic Shapes API
+ *
+ * Layer: Shape API (built on top of Core Drawing Primitives)
+ *
+ * Provides higher-level shape drawing functions that compose
+ * the primitive drawLine, drawRect, drawCircle, drawEllipse,
+ * drawPolygon calls into more meaningful geometric shapes
+ * suitable for art lessons.
+ *
+ * All functions return command payloads compatible with sendCommand.
+ */
+
+const PRIMITIVE_ACTIONS = {
+  LINE: 'drawLine',
+  RECT: 'drawRect',
+  CIRCLE: 'drawCircle',
+  ELLIPSE: 'drawEllipse',
+  POLYGON: 'drawPolygon',
+  PIXEL: 'drawPixel',
+};
+
+/**
+ * Draw a straight line between two points.
+ * @param {number} x0 - Start X
+ * @param {number} y0 - Start Y
+ * @param {number} x1 - End X
+ * @param {number} y1 - End Y
+ * @param {string} color - Hex color
+ * @returns {Object} Command payload
+ */
+function drawLine(x0, y0, x1, y1, color) {
+  return { action: PRIMITIVE_ACTIONS.LINE, x0, y0, x1, y1, color };
+}
+
+/**
+ * Draw a square (aligned to axes).
+ * @param {number} x - Top-left X
+ * @param {number} y - Top-left Y
+ * @param {number} size - Side length
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawSquare(x, y, size, color, filled = false) {
+  return { action: PRIMITIVE_ACTIONS.RECT, x, y, w: size, h: size, color, filled };
+}
+
+/**
+ * Draw a rectangle (aligned to axes).
+ * @param {number} x - Top-left X
+ * @param {number} y - Top-left Y
+ * @param {number} w - Width
+ * @param {number} h - Height
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawRectangle(x, y, w, h, color, filled = false) {
+  return { action: PRIMITIVE_ACTIONS.RECT, x, y, w, h, color, filled };
+}
+
+/**
+ * Draw a circle.
+ * @param {number} cx - Center X
+ * @param {number} cy - Center Y
+ * @param {number} r - Radius
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawCircle(cx, cy, r, color, filled = false) {
+  return { action: PRIMITIVE_ACTIONS.CIRCLE, cx, cy, r, color, filled };
+}
+
+/**
+ * Draw an ellipse.
+ * @param {number} cx - Center X
+ * @param {number} cy - Center Y
+ * @param {number} rx - Horizontal radius
+ * @param {number} ry - Vertical radius
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawEllipse(cx, cy, rx, ry, color, filled = false) {
+  return { action: PRIMITIVE_ACTIONS.ELLIPSE, cx, cy, rx, ry, color, filled };
+}
+
+/**
+ * Draw a triangle from three vertices.
+ * @param {Array<{x: number, y: number}>} vertices - Three vertices
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawTriangle(vertices, color, filled = false) {
+  if (vertices.length !== 3) {
+    throw new Error('Triangle requires exactly 3 vertices');
+  }
+  return { action: PRIMITIVE_ACTIONS.POLYGON, points: vertices, color, filled };
+}
+
+/**
+ * Draw a regular triangle (equilateral) centered at (cx, cy).
+ * @param {number} cx - Center X
+ * @param {number} cy - Center Y
+ * @param {number} sideLength - Length of each side
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawEquilateralTriangle(cx, cy, sideLength, color, filled = false) {
+  const h = (Math.sqrt(3) / 2) * sideLength;
+  const vertices = [
+    { x: Math.round(cx), y: Math.round(cy - h * 2 / 3) },
+    { x: Math.round(cx - sideLength / 2), y: Math.round(cy + h / 3) },
+    { x: Math.round(cx + sideLength / 2), y: Math.round(cy + h / 3) },
+  ];
+  return drawTriangle(vertices, color, filled);
+}
+
+/**
+ * Draw a polygon from a list of points.
+ * @param {Array<{x: number, y: number}>} points - Array of vertices (min 3)
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawPolygon(points, color, filled = false) {
+  return { action: PRIMITIVE_ACTIONS.POLYGON, points, color, filled };
+}
+
+/**
+ * Draw a regular polygon centered at (cx, cy).
+ * @param {number} cx - Center X
+ * @param {number} cy - Center Y
+ * @param {number} sides - Number of sides (3+)
+ * @param {number} radius - Distance from center to vertices
+ * @param {string} color - Hex color
+ * @param {boolean} [filled=false] - Fill interior
+ * @returns {Object} Command payload
+ */
+function drawRegularPolygon(cx, cy, sides, radius, color, filled = false) {
+  const angleStep = (2 * Math.PI) / sides;
+  const points = [];
+  // Start from top (-PI/2) for natural orientation
+  const startAngle = -Math.PI / 2;
+  for (let i = 0; i < sides; i++) {
+    const angle = startAngle + i * angleStep;
+    points.push({
+      x: Math.round(cx + radius * Math.cos(angle)),
+      y: Math.round(cy + radius * Math.sin(angle)),
+    });
+  }
+  return drawPolygon(points, color, filled);
+}
+
+/**
+ * Draw a grid of squares (useful for pixel art foundation lessons).
+ * @param {number} startX - Top-left X
+ * @param {number} startY - Top-left Y
+ * @param {number} cols - Number of columns
+ * @param {number} rows - Number of rows
+ * @param {number} cellSize - Size of each cell
+ * @param {string} color - Grid line color
+ * @returns {Array<Object>} Array of command payloads
+ */
+function drawGrid(startX, startY, cols, rows, cellSize, color) {
+  const commands = [];
+  // Horizontal lines
+  for (let r = 0; r <= rows; r++) {
+    const y = startY + r * cellSize;
+    commands.push(drawLine(startX, y, startX + cols * cellSize, y, color));
+  }
+  // Vertical lines
+  for (let c = 0; c <= cols; c++) {
+    const x = startX + c * cellSize;
+    commands.push(drawLine(x, startY, x, startY + rows * cellSize, color));
+  }
+  return commands;
+}
+
+module.exports = {
+  PRIMITIVE_ACTIONS,
+  drawLine,
+  drawSquare,
+  drawRectangle,
+  drawCircle,
+  drawEllipse,
+  drawTriangle,
+  drawEquilateralTriangle,
+  drawPolygon,
+  drawRegularPolygon,
+  drawGrid,
+};