@pixel-normal-edit/mcp 2.0.10 → 2.2.0

package/clear-firebase.js

@@ -0,0 +1,37 @@
+require('dotenv').config({ path: require('path').join(__dirname, '../../.env') });
+const { initializeApp } = require('firebase/app');
+const { getFirestore, collection, getDocs, deleteDoc, doc } = require('firebase/firestore');
+
+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);
+
+async function clearAll() {
+  console.log('Fetching mcp_sessions...');
+  const sessionsSnap = await getDocs(collection(db, 'mcp_sessions'));
+  console.log(`Found ${sessionsSnap.size} sessions.`);
+
+  for (const sessionDoc of sessionsSnap.docs) {
+    const sessionId = sessionDoc.id;
+    console.log(`Clearing commands for session: ${sessionId}`);
+    const cmdsRef = collection(db, 'mcp_sessions', sessionId, 'commands');
+    const cmdsSnap = await getDocs(cmdsRef);
+    let count = 0;
+    for (const cmdDoc of cmdsSnap.docs) {
+      await deleteDoc(doc(db, 'mcp_sessions', sessionId, 'commands', cmdDoc.id));
+      count++;
+    }
+    console.log(`Deleted ${count} commands.`);
+  }
+  console.log('Done!');
+  process.exit(0);
+}
+
+clearAll().catch(console.error);

package/core/command-bus.js

@@ -15,11 +15,14 @@ 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
+ * @param {number} timeoutOverride - Optional timeout in milliseconds
  * @returns {Promise<Object>} MCP-compatible response object
  */
-async function sendCommand(payload) {
+async function sendCommand(payload, timeoutOverride = null) {
   const id = crypto.randomUUID();
   const ref = doc(db, 'mcp_sessions', SESSION, 'commands', id);
+  const actualTimeout = timeoutOverride || TIMEOUT;
+
   await setDoc(ref, { ...payload, status: 'pending', timestamp: Date.now() });
 
   return new Promise((resolve) => {
@@ -27,9 +30,9 @@ async function sendCommand(payload) {
       unsub();
       resolve({
         isError: true,
-        content: [{ type: 'text', text: `⏱ Timeout (${TIMEOUT}ms). Is the browser tab open with session: ${SESSION}?` }]
+        content: [{ type: 'text', text: `⏱ Timeout (${actualTimeout}ms). Is the browser tab open with session: ${SESSION}?` }]
       });
-    }, TIMEOUT);
+    }, actualTimeout);
 
     const unsub = onSnapshot(ref, (snap) => {
       const d = snap.data();

package/core/server.js

@@ -6,7 +6,9 @@
  * Provides a tool registration factory for consistent tool definitions.
  */
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
-const { sendCommand } = require('./command-bus');
+const { sendCommand, SESSION } = require('./command-bus');
+const workflow = require('../rules/workflow');
+const { DRAWING_STEPS } = require('../rules/rules');
 
 /**
  * Create a new MCP server instance
@@ -16,16 +18,109 @@ function createServer() {
   return new McpServer({ name: 'PixelNormalEdit', version: '2.0.0' });
 }
 
+/**
+ * Read-only tools that do not modify the canvas and should bypass strict workflow checks
+ */
+const READ_ONLY_TOOLS = [
+  'ping', 
+  'layer_get_info', 
+  'workspace_list_tabs', 
+  'workspace_get_active_tab', 
+  'animation_get_info', 
+  'anchor_list', 
+  'query_snapshot', 
+  'query_bounding_box', 
+  'query_palette', 
+  'query_pixel', 
+  'query_export_image', 
+  'query_document_state',
+  'workflow_status',
+  'workflow_get_progress'
+];
+
+/**
+ * Identify if a tool is a drawing tool that should only be allowed in drawing steps
+ */
+function isDrawingTool(name) {
+  return name.startsWith('draw_') || 
+         name.startsWith('bulk_') || 
+         name.startsWith('filter_') || 
+         name.startsWith('sprite_') || 
+         name.startsWith('region_') || 
+         name.startsWith('layer_') ||
+         name.startsWith('animation_') ||
+         name.startsWith('art_tree_');
+}
+
 /**
  * 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
+ * @param {Function} mapToCmd - Function mapping params to command payload or returning MCP response
  */
 function registerTool(server, name, desc, schema, mapToCmd) {
-  server.tool(name, desc, schema, async (params) => sendCommand(mapToCmd(params)));
+  server.tool(name, desc, schema, async (params) => {
+    // 1. Strict Middleware Enforcement (Run BEFORE tool execution)
+    if (!READ_ONLY_TOOLS.includes(name)) {
+      const state = workflow.getState(SESSION);
+      
+      // Allow workflow_start to run even if state is null
+      if (!state && name !== 'workflow_start') {
+        return { 
+          isError: true, 
+          content: [{ type: 'text', text: "⛔ Middleware Block: Workflow not started! Call workflow_start first." }] 
+        };
+      }
+      
+      if (state) {
+        if (state.step_status === 'WAITING_FOR_USER') {
+          return { 
+            isError: true, 
+            content: [{ type: 'text', text: "⛔ Middleware Block: Workflow is paused! Waiting for user approval. You cannot execute this tool." }] 
+          };
+        }
+        
+        if (state.step_status === 'COMPLETED') {
+          return { 
+            isError: true, 
+            content: [{ type: 'text', text: "⛔ Middleware Block: Workflow is completed! Please start a new workflow." }] 
+          };
+        }
+
+        // Block creating new tabs in EDIT_IMAGE mode
+        if (name === 'workspace_create_tab' && state.current_mode === 'EDIT_IMAGE') {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: "⛔ Middleware Block: You cannot create new images in EDIT_IMAGE mode. Please only edit the existing image." }]
+          };
+        }
+
+        // Check Drawing Steps Enforcement
+        if (isDrawingTool(name)) {
+          const currentStep = state.steps[state.currentStepIndex];
+          if (!currentStep || !DRAWING_STEPS.includes(currentStep.id)) {
+            return {
+              isError: true,
+              content: [{ type: 'text', text: `⛔ Middleware Block: You cannot use drawing/layer tools in the current step ("${currentStep ? currentStep.label : 'None'}"). You must advance to a drawing step (e.g. EXECUTE_PHASES) first.` }]
+            };
+          }
+        }
+      }
+    }
+
+    // 2. Execute the tool implementation
+    const res = mapToCmd(params);
+    
+    // 3. If the tool implementation returns an MCP response directly (local tool like workflow_*)
+    if (res && res.content) {
+      return res;
+    }
+
+    // 4. Forward the command payload to the browser
+    return sendCommand(res);
+  });
 }
 
 module.exports = { createServer, registerTool, sendCommand };

package/domains/art-tree/README.md

@@ -0,0 +1,134 @@
+# Art Tree Domain Module
+
+Art education domain providing interactive drawing lessons through MCP tools.
+
+## Architecture
+
+```
+domains/art-tree/
+├── index.js                      # Entry point - registers all tools
+├── lib/                          # Shared utilities
+│   ├── validators.js             # Common Zod schemas
+│   └── tool-register.js          # Tool registration helpers
+├── shapes/                       # Shape primitives (building blocks)
+│   ├── index.js                  # Exports all shapes
+│   ├── basic.js                  # Line, square, rect, circle, ellipse, triangle, polygon
+│   ├── grid.js                   # Grid drawing
+│   └── polyline.js               # Polyline drawing
+├── lessons/                      # Lesson implementations
+│   ├── index.js                  # Exports all lessons
+│   ├── basic/                    # Basic shape lessons (13 lessons)
+│   ├── advanced/                 # Advanced properties (5 lessons)
+│   ├── curves/                   # Curve lessons (3 lessons)
+│   ├── ellipses/                 # Ellipse lessons
+│   ├── 3d/                       # 3D form lessons (4 lessons)
+│   ├── structure/                # Structure lessons (3 lessons)
+│   ├── cross-sections/           # Cross-section lessons (3 lessons)
+│   ├── transforms/               # Transform lessons (8 lessons)
+│   ├── surfaces/                 # Surface lessons (4 lessons)
+│   ├── perspective/              # Perspective lessons (4 lessons)
+│   ├── hidden/                   # Hidden shapes lessons (3 lessons)
+│   ├── lighting/                 # Lighting lessons (3 lessons)
+│   ├── materials/                # Material lessons (3 lessons)
+│   ├── analysis/                 # Analysis capstone (10 steps)
+│   ├── layers/                   # Layer structure lessons (7 steps)
+│   └── sky/                      # Sky & sun lessons (3 lessons)
+└── tools/                        # MCP tool registration
+    ├── index.js                  # Registers all tool categories
+    ├── basic.js                  # Basic shape tools
+    ├── lessons.js                # Lesson tools
+    ├── advanced.js               # Advanced tools
+    ├── curves.js                 # Curve tools
+    ├── ellipses.js               # Ellipse tools
+    ├── 3d.js                     # 3D tools
+    ├── structure.js              # Structure tools
+    ├── cross-sections.js         # Cross-section tools
+    ├── transforms.js             # Transform tools
+    ├── surfaces.js               # Surface tools
+    ├── perspective.js            # Perspective tools
+    ├── hidden.js                 # Hidden tools
+    ├── lighting.js               # Lighting tools
+    ├── materials.js              # Material tools
+    ├── analysis.js               # Analysis tools
+    ├── layers.js                 # Layer tools
+    └── sky.js                    # Sky tools
+```
+
+## Layer Separation
+
+### 1. Shapes Layer (Primitives)
+- **Purpose**: Low-level drawing primitives that map 1:1 to core drawing actions
+- **Location**: `shapes/`
+- **Returns**: Command payloads (not executed)
+- **Example**: `drawLine()`, `drawCircle()`, `drawGrid()`
+
+### 2. Lessons Layer (Educational Content)
+- **Purpose**: Educational sequences that teach art concepts
+- **Location**: `lessons/`
+- **Returns**: Array of command payloads
+- **Example**: `lessonLines()`, `lessonCircles()`, `lesson3DBox()`
+
+### 3. Tools Layer (MCP API)
+- **Purpose**: MCP tool definitions that expose shapes/lessons to AI agents
+- **Location**: `tools/`
+- **Returns**: MCP responses
+- **Example**: `art_tree_draw_line`, `art_tree_lesson_lines`
+
+## Design Principles
+
+1. **Separation of Concerns**: Each layer has a single responsibility
+2. **Composition over Inheritance**: Lessons compose shapes, tools compose lessons
+3. **No Duplication**: Shared validators and registration helpers in `lib/`
+4. **Consistent Naming**: Clear patterns for all files and functions
+5. **Easy Navigation**: Related functionality grouped together
+
+## Usage
+
+### Registering Tools
+
+```javascript
+const { registerAll } = require('./domains/art-tree');
+registerAll(server);
+```
+
+### Using Shapes
+
+```javascript
+const shapes = require('./domains/art-tree/shapes');
+const cmd = shapes.drawCircle(10, 10, 5, '#ff0000');
+// Returns: { action: 'drawCircle', cx: 10, cy: 10, r: 5, color: '#ff0000' }
+```
+
+### Using Lessons
+
+```javascript
+const lessons = require('./domains/art-tree/lessons');
+const commands = lessons.lessonLines(32, '#ff0000');
+// Returns: Array of command payloads
+```
+
+## Adding New Features
+
+### New Shape
+1. Add function to `shapes/basic.js` (or create new file in `shapes/`)
+2. Export from `shapes/index.js`
+
+### New Lesson
+1. Create lesson function in appropriate `lessons/[category]/` folder
+2. Export from `lessons/[category]/index.js`
+3. Export from `lessons/index.js`
+
+### New Tool
+1. Create tool file in `tools/[category].js`
+2. Use helpers from `lib/tool-register.js`
+3. Import and call `register()` in `tools/index.js`
+
+## Migration Notes
+
+This is a refactored version of the original art-tree module. The old flat structure with 17+ `*_tools.js` files has been reorganized into:
+- Clear layer separation (shapes → lessons → tools)
+- Category-based organization
+- Shared utilities to reduce duplication
+- Consistent naming conventions
+
+All original functionality is preserved, just better organized.

package/domains/art-tree/REORGANIZATION_PLAN.md

@@ -0,0 +1,168 @@
+# Art Tree Module Reorganization Plan
+
+## Current Issues
+
+1. **Too many files**: 17+ separate `*_tools.js` files in one directory
+2. **Inconsistent naming**: Mix of `_tools.js`, `_lessons.js`, `_shapes.js` suffixes
+3. **Code duplication**: Every tool file repeats the same boilerplate (zod imports, hexColor schema, register function pattern)
+4. **Hard to navigate**: Difficult to find related functionality
+5. **Mixed concerns**: Tools, lessons, and shapes all mixed together
+
+## Proposed Structure
+
+```
+domains/art-tree/
+├── index.js                      # Main entry point - register all tools
+├── README.md                     # Domain documentation
+├── lib/                          # Shared utilities
+│   ├── validators.js             # Common Zod schemas (hexColor, canvasSize, etc.)
+│   └── tool-register.js          # Tool registration helper with common patterns
+├── shapes/                       # Shape primitives (currently shapes.js)
+│   ├── index.js                  # Export all shapes
+│   ├── basic.js                  # Line, square, rect, circle, ellipse, triangle, polygon
+│   ├── grid.js                   # Grid drawing
+│   └── polyline.js               # Polyline drawing
+├── lessons/                      # Lesson implementations
+│   ├── index.js                  # Export all lessons + catalog functions
+│   ├── basic/                    # Basic shape lessons
+│   │   ├── lines.js
+│   │   ├── squares.js
+│   │   ├── circles.js
+│   │   ├── ellipses.js
+│   │   ├── triangles.js
+│   │   ├── polygons.js
+│   │   ├── composition.js
+│   │   ├── freehand.js
+│   │   ├── proportions.js
+│   │   ├── curves.js
+│   │   ├── spiral.js
+│   │   ├── strokes.js
+│   │   └── parallel-intersecting.js
+│   ├── advanced/                 # Advanced property lessons
+│   │   ├── ratios.js
+│   │   ├── symmetry.js
+│   │   ├── angles.js
+│   │   ├── distances.js
+│   │   └── relationships.js
+│   ├── curves/                   # Curve-specific lessons
+│   │   ├── types.js
+│   │   ├── topology.js
+│   │   └── properties.js
+│   ├── 3d/                       # 3D form lessons
+│   │   ├── box.js
+│   │   ├── sphere.js
+│   │   ├── cylinder.js
+│   │   └── cone.js
+│   ├── structure/                # Structure lessons
+│   │   ├── xyz-axes.js
+│   │   ├── bottle.js
+│   │   └── orientation.js
+│   ├── cross-sections/           # Cross-section lessons
+│   │   ├── bottle.js
+│   │   ├── glass.js
+│   │   └── head.js
+│   ├── transforms/               # Transform lessons
+│   │   ├── stretch.js
+│   │   ├── squash.js
+│   │   ├── taper.js
+│   │   ├── bend.js
+│   │   ├── rotate.js
+│   │   ├── cut.js
+│   │   ├── hollow.js
+│   │   └── combine.js
+│   ├── surfaces/                 # Surface lessons
+│   │   ├── types.js
+│   │   ├── edges.js
+│   │   ├── cup.js
+│   │   └── chair.js
+│   ├── perspective/              # Perspective lessons
+│   │   ├── 1point.js
+│   │   ├── 2point.js
+│   │   ├── 3point.js
+│   │   └── foreshorten.js
+│   ├── hidden/                   # Hidden shapes lessons
+│   │   ├── box.js
+│   │   ├── head.js
+│   │   └── cup.js
+│   ├── lighting/                 # Lighting lessons
+│   │   ├── zones.js
+│   │   ├── direction.js
+│   │   └── contact.js
+│   ├── materials/                # Material lessons
+│   │   ├── shiny.js
+│   │   ├── glass.js
+│   │   └── texture.js
+│   ├── analysis/                 # Analysis lessons (capstone)
+│   │   ├── step-1.js
+│   │   ├── step-2.js
+│   │   ├── ... (up to step-10)
+│   │   └── index.js
+│   ├── layers/                   # Layer structure lessons
+│   │   ├── step-1.js
+│   │   ├── ... (up to step-7)
+│   │   └── index.js
+│   └── sky/                      # Sky & sun lessons
+│       ├── sun-shapes.js
+│       ├── sunset-colors.js
+│       └── sunset-sky.js
+└── tools/                         # MCP tool registration
+    ├── index.js                   # Main tool registration entry
+    ├── basic.js                   # Basic shape tools
+    ├── lessons.js                 # Lesson tools (catalog + individual)
+    ├── advanced.js                # Advanced property tools
+    ├── curves.js                  # Curve tools
+    ├── ellipses.js                # Ellipse tools
+    ├── 3d.js                      # 3D form tools
+    ├── structure.js               # Structure tools
+    ├── cross-sections.js          # Cross-section tools
+    ├── transforms.js              # Transform tools
+    ├── surfaces.js                # Surface tools
+    ├── perspective.js             # Perspective tools
+    ├── hidden.js                  # Hidden shapes tools
+    ├── lighting.js                # Lighting tools
+    ├── materials.js               # Material tools
+    ├── analysis.js                # Analysis tools
+    ├── layers.js                  # Layer tools
+    └── sky.js                     # Sky tools
+```
+
+## Benefits
+
+1. **Clear separation of concerns**: Shapes, lessons, and tools are separate
+2. **Easier navigation**: Related files grouped together
+3. **Less duplication**: Shared validators and registration helpers
+4. **Scalable**: Easy to add new lessons/tools without cluttering
+5. **Consistent naming**: Clear pattern for all files
+6. **Better documentation**: Each subfolder can have its own README
+
+## Migration Strategy
+
+1. Create new directory structure
+2. Move and refactor files in batches:
+   - First: lib/ (shared utilities)
+   - Second: shapes/ (no dependencies)
+   - Third: lessons/ (depends on shapes)
+   - Fourth: tools/ (depends on lessons)
+3. Update index.js to use new structure
+4. Test each batch before moving to next
+5. Delete old files after verification
+
+## Implementation Priority
+
+**Phase 1 - Foundation (No breaking changes)**
+- Create lib/ with validators and helpers
+- Create shapes/ and move shapes.js
+
+**Phase 2 - Lessons (Depends on Phase 1)**
+- Create lessons/ structure
+- Move all lesson files
+
+**Phase 3 - Tools (Depends on Phase 2)**
+- Create tools/ structure
+- Move all tool files
+- Update index.js
+
+**Phase 4 - Cleanup**
+- Remove old files
+- Update documentation
+- Verify all tests pass