@pixel-normal-edit/mcp 2.0.7 → 2.0.10

package/rules/workflow.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * workflow.js — Workflow Engine (Bắt buộc tuân thủ thứ tự)
+ *
+ * Engine này quản lý trạng thái workflow của agent.
+ * Mỗi lần agent gọi 1 tool, workflow engine sẽ kiểm tra:
+ *   - Agent đang ở bước nào?
+ *   - Bước tiếp theo phải là gì?
+ *   - Nếu sai thứ tự → từ chối và yêu cầu làm đúng bước
+ *
+ * Cách dùng:
+ *   const workflow = require('./rules/workflow');
+ *   workflow.start('my_project');        // Bắt đầu workflow mới
+ *   workflow.getCurrentStep();           // Xem đang ở bước nào
+ *   workflow.advance();                  // Chuyển sang bước tiếp theo
+ *   workflow.validateStep('draw');       // Kiểm tra có được phép vẽ chưa
+ */
+
+const { WORKFLOW_STEPS } = require('./rules');
+
+// ── In-memory workflow state ────────────────────────────────────────────────
+// Key: sessionId, Value: { currentStepIndex, steps, completedSteps, startedAt }
+const sessions = new Map();
+
+/**
+ * Bắt đầu một workflow mới cho session
+ * @param {string} sessionId - Mã session (thường là MCP_SESSION)
+ * @returns {Object} Trạng thái workflow ban đầu
+ */
+function start(sessionId) {
+  const state = {
+    currentStepIndex: 0,
+    steps: WORKFLOW_STEPS.map(s => ({ ...s, status: 'pending' })),
+    completedSteps: [],
+    startedAt: Date.now(),
+  };
+  sessions.set(sessionId, state);
+  return getState(sessionId);
+}
+
+/**
+ * Lấy trạng thái workflow hiện tại
+ * @param {string} sessionId
+ * @returns {Object|null}
+ */
+function getState(sessionId) {
+  return sessions.get(sessionId) || null;
+}
+
+/**
+ * Lấy bước hiện tại
+ * @param {string} sessionId
+ * @returns {{ id: string, label: string, description: string, status: string }|null}
+ */
+function getCurrentStep(sessionId) {
+  const state = sessions.get(sessionId);
+  if (!state) return null;
+  return state.steps[state.currentStepIndex] || null;
+}
+
+/**
+ * Kiểm tra xem agent có được phép thực hiện hành động này không
+ * @param {string} sessionId
+ * @param {string} stepId - ID của bước muốn thực hiện
+ * @returns {{ allowed: boolean, message?: string, currentStep?: Object }}
+ */
+function validateStep(sessionId, stepId) {
+  const state = sessions.get(sessionId);
+  if (!state) {
+    return {
+      allowed: false,
+      message: '⚠️ Chưa bắt đầu workflow. Hãy gọi workflow_start trước!',
+    };
+  }
+
+  const current = state.steps[state.currentStepIndex];
+  if (!current) {
+    return {
+      allowed: false,
+      message: '✅ Workflow đã hoàn tất! Không còn bước nào cần làm.',
+    };
+  }
+
+  // Tìm index của stepId trong workflow
+  const targetIndex = state.steps.findIndex(s => s.id === stepId);
+  if (targetIndex === -1) {
+    return {
+      allowed: false,
+      message: `❌ Không tìm thấy bước "${stepId}" trong workflow.`,
+    };
+  }
+
+  // Nếu stepId nằm trước bước hiện tại (đã hoàn thành) → cho phép (có thể cần quay lại)
+  if (targetIndex < state.currentStepIndex) {
+    return {
+      allowed: true,
+      message: `⚠️ Bước "${stepId}" đã hoàn thành trước đó. Bạn có chắc muốn làm lại?`,
+      currentStep: current,
+    };
+  }
+
+  // Nếu stepId đúng là bước hiện tại → cho phép
+  if (targetIndex === state.currentStepIndex) {
+    return {
+      allowed: true,
+      currentStep: current,
+    };
+  }
+
+  // Nếu stepId nằm ở tương lai → CHẶN
+  return {
+    allowed: false,
+    message: `⛔ Bạn chưa thể thực hiện "${stepId}". Trước hết hãy hoàn thành: "${current.label}" (${current.description})`,
+    currentStep: current,
+  };
+}
+
+/**
+ * Đánh dấu bước hiện tại là hoàn thành và chuyển sang bước tiếp theo
+ * @param {string} sessionId
+ * @returns {Object} Kết quả chuyển bước
+ */
+function advance(sessionId) {
+  const state = sessions.get(sessionId);
+  if (!state) {
+    return { success: false, message: 'Chưa bắt đầu workflow' };
+  }
+
+  const current = state.steps[state.currentStepIndex];
+  if (!current) {
+    return { success: false, message: 'Workflow đã hoàn tất' };
+  }
+
+  // Đánh dấu bước hiện tại là completed
+  current.status = 'completed';
+  state.completedSteps.push(current.id);
+
+  // Chuyển sang bước tiếp theo
+  state.currentStepIndex++;
+
+  const next = state.steps[state.currentStepIndex] || null;
+  if (next) {
+    next.status = 'in_progress';
+    return {
+      success: true,
+      completedStep: current,
+      nextStep: next,
+      message: `✅ Hoàn thành: "${current.label}". Bước tiếp theo: "${next.label}" — ${next.description}`,
+    };
+  }
+
+  return {
+    success: true,
+    completedStep: current,
+    nextStep: null,
+    message: `🎉 Hoàn tất tất cả các bước! Tác phẩm đã sẵn sàng.`,
+  };
+}
+
+/**
+ * Reset workflow về đầu
+ * @param {string} sessionId
+ */
+function reset(sessionId) {
+  sessions.delete(sessionId);
+  return start(sessionId);
+}
+
+/**
+ * Lấy toàn bộ tiến trình dạng text để trả về cho agent
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function getProgressReport(sessionId) {
+  const state = sessions.get(sessionId);
+  if (!state) return 'Chưa bắt đầu workflow.';
+
+  const lines = ['📋 **Tiến trình vẽ:**\n'];
+  state.steps.forEach((step, i) => {
+    const icon = step.status === 'completed' ? '✅' :
+                 step.status === 'in_progress' ? '🔄' : '⬜';
+    const marker = i === state.currentStepIndex ? ' ← **ĐANG LÀM**' : '';
+    lines.push(`${icon} **${step.label}**${marker}`);
+    if (step.status === 'in_progress' || i === state.currentStepIndex) {
+      lines.push(`   → ${step.description}`);
+    }
+  });
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  start,
+  getState,
+  getCurrentStep,
+  validateStep,
+  advance,
+  reset,
+  getProgressReport,
+};

package/tools/{anchors.js → anchor-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * anchors.js — Coordinate Anchor tools
+ * anchor-tools.js — Coordinate Anchor tools
  *
  * Tools: anchor_set, anchor_get, anchor_list
  */

package/tools/{animation.js → animation-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * animation.js — Animation Frame tools
+ * animation-tools.js — Animation Frame tools
  *
  * Tools: animation_enable, animation_add_frame, animation_go_to_frame,
  *        animation_ensure_frame, animation_get_info, animation_remove_frame,

package/tools/{canvas.js → canvas-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * canvas.js — Canvas & Setup tools
+ * canvas-tools.js — Canvas & Setup tools
  *
  * Tools: canvas_get_size, canvas_resize, canvas_clear, canvas_trim
  */

package/tools/{colors.js → color-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * colors.js — Color tools
+ * color-tools.js — Color tools
  *
  * Tools: color_set, color_get
  */

package/tools/{drawing.js → drawing-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * drawing.js — Drawing Primitives tools
+ * drawing-tools.js — Drawing Primitives tools
  *
  * Tools: draw_pixel, draw_erase, draw_line, draw_rect, draw_circle,
  *        draw_ellipse, draw_polygon, draw_fill, draw_gradient_rect,

package/tools/{filters.js → filter-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * filters.js — Visual Filter tools
+ * filter-tools.js — Visual Filter tools
  *
  * Tools: filter_apply
  */

package/tools/{health.js → health-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * health.js — Health Check / Ping tools
+ * health-tools.js — Health Check / Ping tools
  *
  * Tools: ping
  */

package/tools/{history.js → history-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * history.js — History (Undo/Redo) tools
+ * history-tools.js — History (Undo/Redo) tools
  *
  * Tools: history_undo, history_redo
  */

package/tools/index.js

@@ -4,20 +4,37 @@
  *
  * Imports and registers all core drawing/utility tools on an MCP server instance.
  * To add a new tool category, create a new file in this folder and add it here.
+ *
+ * File naming convention: {category}-tools.js
+ *   - canvas-tools.js     → Canvas operations
+ *   - workspace-tools.js  → Tab/workspace management
+ *   - animation-tools.js  → Animation frames
+ *   - drawing-tools.js    → Drawing primitives
+ *   - sprite-tools.js     → Sprite/stamp system
+ *   - region-tools.js     → Region clipboard
+ *   - filter-tools.js     → Visual filters
+ *   - anchor-tools.js     → Coordinate anchors
+ *   - query-tools.js      → Query & visual feedback
+ *   - history-tools.js    → Undo/redo
+ *   - mode-tools.js       → Mode settings
+ *   - color-tools.js      → Color management
+ *   - health-tools.js     → Health check
+ *   - layer-tools.js      → Layer management
  */
-const canvas = require('./canvas');
-const workspace = require('./workspace');
-const animation = require('./animation');
-const drawing = require('./drawing');
-const sprite = require('./sprite');
-const region = require('./region');
-const filters = require('./filters');
-const anchors = require('./anchors');
-const query = require('./query');
-const history = require('./history');
-const modes = require('./modes');
-const colors = require('./colors');
-const health = require('./health');
+const canvas = require('./canvas-tools');
+const workspace = require('./workspace-tools');
+const animation = require('./animation-tools');
+const drawing = require('./drawing-tools');
+const sprite = require('./sprite-tools');
+const region = require('./region-tools');
+const filters = require('./filter-tools');
+const anchors = require('./anchor-tools');
+const query = require('./query-tools');
+const history = require('./history-tools');
+const modes = require('./mode-tools');
+const colors = require('./color-tools');
+const health = require('./health-tools');
+const layer = require('./layer-tools');
 
 /**
  * Register all core tools on the given MCP server instance.
@@ -37,6 +54,7 @@ function registerAll(server) {
   modes.register(server);
   colors.register(server);
   health.register(server);
+  layer.register(server);
 }
 
 module.exports = { registerAll };

package/tools/layer-tools.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * layer-tools.js — MCP Tool Registration for Layers
+ *
+ * Exposes the layer management functionality to MCP clients.
+ */
+const { z } = require('zod');
+const { registerTool, sendCommand } = require('../core/server');
+
+/**
+ * Register all layer tools on the MCP server.
+ * @param {McpServer} server
+ */
+function register(server) {
+  registerTool(server, 'layer_get_info',
+    'Get information about all current layers and the active layer index.',
+    {},
+    async () => {
+      const activeRes = await sendCommand({ action: 'layer.getActiveLayerIndex' });
+      const layersRes = await sendCommand({ action: 'layer.getLayers' });
+      return { 
+        content: [{ 
+          type: 'text', 
+          text: JSON.stringify({ 
+            activeLayerIndex: activeRes.result, 
+            layers: layersRes.result 
+          }, null, 2)
+        }] 
+      };
+    });
+
+  registerTool(server, 'layer_add',
+    'Add a new layer on top of existing layers.',
+    {},
+    async () => {
+      await sendCommand({ action: 'layer.add' });
+      return { content: [{ type: 'text', text: '✓ New layer added.' }] };
+    });
+
+  registerTool(server, 'layer_remove',
+    'Remove a layer by its index.',
+    { index: z.number().int().describe('The index of the layer to remove (0 is the bottom-most)') },
+    async (p) => {
+      await sendCommand({ action: 'layer.remove', index: p.index });
+      return { content: [{ type: 'text', text: `✓ Layer ${p.index} removed.` }] };
+    });
+
+  registerTool(server, 'layer_move',
+    'Move a layer up or down in the stack.',
+    { 
+      index: z.number().int().describe('The index of the layer to move'),
+      direction: z.enum(['up', 'down']).describe('Direction to move the layer')
+    },
+    async (p) => {
+      if (p.direction === 'up') {
+        await sendCommand({ action: 'layer.moveUp', index: p.index });
+      } else {
+        await sendCommand({ action: 'layer.moveDown', index: p.index });
+      }
+      return { content: [{ type: 'text', text: `✓ Layer ${p.index} moved ${p.direction}.` }] };
+    });
+
+  registerTool(server, 'layer_toggle_visibility',
+    'Toggle the visibility of a layer by its index.',
+    { index: z.number().int().describe('The index of the layer to toggle') },
+    async (p) => {
+      await sendCommand({ action: 'layer.toggle', index: p.index });
+      return { content: [{ type: 'text', text: `✓ Toggled visibility of layer ${p.index}.` }] };
+    });
+
+  registerTool(server, 'layer_select',
+    'Select an active layer for drawing operations.',
+    { index: z.number().int().describe('The index of the layer to select') },
+    async (p) => {
+      await sendCommand({ action: 'layer.select', index: p.index });
+      return { content: [{ type: 'text', text: `✓ Selected layer ${p.index}.` }] };
+    });
+}
+
+module.exports = { register };

package/tools/{modes.js → mode-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * modes.js — Mode settings tools
+ * mode-tools.js — Mode settings tools
  *
  * Tools: mode_set_mirror, mode_set_onion_skin, mode_set_grid
  */

package/tools/{query.js → query-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * query.js — Query & Visual Feedback tools
+ * query-tools.js — Query & Visual Feedback tools
  *
  * Tools: query_snapshot, query_bounding_box, query_palette, query_pixel,
  *        query_export_image, query_document_state

package/tools/{region.js → region-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * region.js — Region Clipboard tools
+ * region-tools.js — Region Clipboard tools
  *
  * Tools: region_copy, region_paste
  */

package/tools/{sprite.js → sprite-tools.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * sprite.js — Sprite / Stamp System tools
+ * sprite-tools.js — Sprite / Stamp System tools
  *
  * Tools: sprite_draw, sprite_save_stamp, sprite_use_stamp, sprite_list_stamps
  */

package/tools/{workspace.js → workspace-tools.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 /**
- * workspace.js — Workspace / Tabs tools
+ * workspace-tools.js — Workspace / Tabs tools
  *
  * Tools: workspace_list_tabs, workspace_get_active_tab, workspace_create_tab,
  *        workspace_switch_tab, workspace_rename_tab, workspace_save
  */
 const { z } = require('zod');
-const { registerTool } = require('../core/server');
+const { registerTool, sendCommand } = require('../core/server');
 
 function register(server) {
   registerTool(server, 'workspace_list_tabs',
@@ -19,7 +19,6 @@ function register(server) {
     {},
     () => ({ action: 'getActiveTabId' }));
 
-  const { sendCommand } = require('../core/server');
   server.tool('workspace_create_tab',
     'Create a new blank canvas tab',
     {