@pixel-normal-edit/mcp 2.0.8 → 2.1.0

package/rules/prerequisites.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * prerequisites.js — Prerequisites Check
+ *
+ * This is an MCP Tool for the agent to call before starting to draw.
+ * It will check all prerequisites and return detailed instructions.
+ *
+ * IMPORTANT: The Agent MUST call this tool FIRST
+ * before performing any drawing operations.
+ */
+
+const { z } = require('zod');
+const { validateCanvasName, validateCanvasSize, DRAWING_CONSTRAINTS, MODES, DRAWING_PHASES } = require('./rules');
+const workflow = require('./workflow');
+const { registerTool } = require('../core/server');
+
+/**
+ * Register workflow/prerequisite tools on the MCP server
+ * @param {McpServer} server
+ */
+function register(server) {
+  registerTool(server, 'workflow_start',
+    `🚀 REQUIRED: Call this tool FIRST before drawing anything.
+This tool initializes a drawing workflow with sequential steps for a specific mode.
+Modes: CREATE_IMAGE, EDIT_IMAGE, CREATE_ANIMATION`,
+    { mode: z.enum([MODES.CREATE_IMAGE, MODES.EDIT_IMAGE, MODES.CREATE_ANIMATION]).describe('Workflow mode to start') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const state = workflow.start(session, p.mode);
+      return {
+        content: [{ type: 'text', text: `🚀 **Workflow started in mode: ${p.mode}!**\n\n${workflow.getProgressReport(session)}\n\n---\nStart with step: **${state.steps[0].label}** → ${state.steps[0].description}` }]
+      };
+    });
+
+  registerTool(server, 'workflow_status',
+    'View current workflow progress: current mode, layer, frame, steps and statuses.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const report = workflow.getProgressReport(session);
+      const current = workflow.getCurrentStep(session);
+      if (!current) {
+        return { content: [{ type: 'text', text: '⚠️ Workflow has not started. Call **workflow_start** first.' }] };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: `${report}\n\n👉 **Pending:** ${current.label} — ${current.description}`
+        }]
+      };
+    });
+
+  registerTool(server, 'workflow_advance',
+    '✅ Mark current step as complete and move to the next step. Only call AFTER successfully finishing the current step.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const result = workflow.advance(session);
+      if (!result.success) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      if (!result.nextStep) {
+        return { content: [{ type: 'text', text: `🎉 ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: result.message }] };
+    });
+
+  registerTool(server, 'workflow_validate',
+    `🔍 Check if the agent is allowed to perform a certain action.
+  Call this tool BEFORE performing operations to ensure correct workflow order.`,
+    { stepId: z.string().describe('ID of the step to validate (e.g., "INITIALIZE_CANVAS")') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const result = workflow.validateStep(session, p.stepId);
+      if (!result.allowed) {
+        return { isError: true, content: [{ type: 'text', text: result.message }] };
+      }
+      return { content: [{ type: 'text', text: result.message || `✅ You can perform "${p.stepId}". Please proceed!` }] };
+    });
+
+  registerTool(server, 'workflow_set_layer',
+    'Set the active layer for the workflow tracking.',
+    { layer: z.number().int().describe('The layer index') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const success = workflow.setLayerAndFrame(session, p.layer, undefined);
+      if (!success) {
+        return { isError: true, content: [{ type: 'text', text: '❌ Workflow not started' }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Active layer set to ${p.layer}` }] };
+    });
+
+  registerTool(server, 'workflow_set_frame',
+    'Set the active frame for the workflow tracking (useful for animation mode).',
+    { frame: z.number().int().describe('The frame index') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const success = workflow.setLayerAndFrame(session, undefined, p.frame);
+      if (!success) {
+        return { isError: true, content: [{ type: 'text', text: '❌ Workflow not started' }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Active frame set to ${p.frame}` }] };
+    });
+
+  registerTool(server, 'workflow_set_phase',
+    'Set the active drawing phase (e.g. PHASE_0_SKETCH_BLOCKING, PHASE_1_BACKGROUND, etc.).',
+    { phase: z.enum(DRAWING_PHASES).describe('The drawing phase') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const success = workflow.setPhase(session, p.phase);
+      if (!success) {
+        return { isError: true, content: [{ type: 'text', text: '❌ Workflow not started' }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Active phase set to ${p.phase}` }] };
+    });
+
+  registerTool(server, 'workflow_setup_animation',
+    'Declare animation metadata for tracking (fps, total_frames, loop).',
+    { 
+      fps: z.number().int().optional().describe('Frames per second'),
+      total_frames: z.number().int().optional().describe('Total frames in the animation'),
+      loop: z.boolean().optional().describe('Whether the animation loops')
+    },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const success = workflow.setAnimationMeta(session, p.fps, p.total_frames, p.loop);
+      if (!success) {
+        return { isError: true, content: [{ type: 'text', text: '❌ Workflow not started' }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Animation meta updated: FPS=${p.fps}, Frames=${p.total_frames}, Loop=${p.loop}` }] };
+    });
+
+  registerTool(server, 'workflow_create_input_request',
+    'Pause the workflow and ask the user for specific input via the UI (e.g. CANVAS_SIZE, APPROVE_PLAN, SELECT_EDIT_REGION).',
+    { 
+      type: z.enum(['CANVAS_SIZE', 'APPROVE_PLAN', 'REVIEW_RESULT', 'SELECT_EDIT_REGION', 'ANIMATION_SETUP']).describe('The type of request'),
+      fields: z.record(z.any()).optional().describe('Context or fields for the request')
+    },
+    async (p) => {
+      const { sendCommand, SESSION } = require('../core/command-bus');
+      const reqId = workflow.createInputRequest(SESSION, p.type, p.fields || {});
+      if (!reqId) {
+        return { isError: true, content: [{ type: 'text', text: '❌ Workflow not started' }] };
+      }
+      
+      const res = await sendCommand({ action: 'showUserInputRequest', type: p.type, fields: p.fields || {}, reqId }, 35000);
+      
+      if (!res.isError) {
+        workflow.completeInputRequest(SESSION, reqId, res.content[0].text);
+      }
+      
+      return res;
+    });
+
+  registerTool(server, 'workflow_require_approval',
+    'Pause the workflow and require user approval before continuing.',
+    { required: z.boolean().describe('True to pause and wait for user, False to resume') },
+    (p) => {
+      const session = require('../core/command-bus').SESSION;
+      const success = workflow.setApprovalRequired(session, p.required);
+      if (!success) {
+        return { isError: true, content: [{ type: 'text', text: '❌ Workflow not started' }] };
+      }
+      return { content: [{ type: 'text', text: p.required ? '✅ Workflow paused, waiting for user approval.' : '✅ Workflow resumed.' }] };
+    });
+
+  registerTool(server, 'workflow_reset',
+    '🔄 Reset workflow to initial state. Clears all progress.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      workflow.reset(session);
+      return { content: [{ type: 'text', text: '🔄 Workflow reset. Please start from the beginning.' }] };
+    });
+
+  registerTool(server, 'validate_canvas_name',
+    `Validate canvas name before setting it.
+  Rules: 3-64 characters, letters, numbers, _, -, and spaces only.
+  Example: "Painting_1", "My Canvas 2024"`,
+    { name: z.string().describe('Canvas name to validate') },
+    (p) => {
+      const result = validateCanvasName(p.name);
+      if (!result.valid) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Name "${p.name}" is valid!` }] };
+    });
+
+  registerTool(server, 'validate_canvas_size',
+    `Validate if canvas size is within allowed limits.
+  Limits: ${DRAWING_CONSTRAINTS.minCanvasSize.width}x${DRAWING_CONSTRAINTS.minCanvasSize.height} to ${DRAWING_CONSTRAINTS.maxCanvasSize.width}x${DRAWING_CONSTRAINTS.maxCanvasSize.height}`,
+    { width: z.number().int().describe('Width'), height: z.number().int().describe('Height') },
+    (p) => {
+      const result = validateCanvasSize(p.width, p.height);
+      if (!result.valid) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Size ${p.width}x${p.height} is valid!` }] };
+    });
+}
+
+module.exports = { register };

package/rules/rules.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * rules.js — Core Drawing Rules & Constraints
+ *
+ * IMPORTANT: Every function in here is a STRICT rule.
+ * The Agent MUST NOT skip or execute them out of order.
+ */
+
+const NAMING_RULES = {
+  canvasTab: {
+    pattern: /^[A-Za-z0-9_\-\sÀ-ỹ]{3,64}$/,
+    message: 'Canvas name must be 3-64 characters long, containing only letters, numbers, _, -, and spaces',
+    example: 'Painting_1',
+  },
+  stamp: {
+    pattern: /^[a-z][a-z0-9_]{2,32}$/,
+    message: 'Stamp name must start with a lowercase letter, 3-32 characters long, containing only a-z, 0-9, _',
+    example: 'my_tree_01',
+  },
+  anchor: {
+    pattern: /^[a-z][a-z0-9_]{2,32}$/,
+    message: 'Anchor name must start with a lowercase letter, 3-32 characters long',
+    example: 'head_top',
+  },
+};
+
+const MODES = {
+  CREATE_IMAGE: 'CREATE_IMAGE',
+  EDIT_IMAGE: 'EDIT_IMAGE',
+  CREATE_ANIMATION: 'CREATE_ANIMATION'
+};
+
+const STATUSES = {
+  PENDING: 'PENDING',
+  IN_PROGRESS: 'IN_PROGRESS',
+  WAITING_FOR_USER: 'WAITING_FOR_USER',
+  COMPLETED: 'COMPLETED',
+  FAILED: 'FAILED',
+  CANCELLED: 'CANCELLED'
+};
+
+const DRAWING_PHASES = [
+  'PHASE_0_SKETCH_BLOCKING',
+  'PHASE_1_BACKGROUND',
+  'PHASE_2_MAIN_SHAPES',
+  'PHASE_3_LINE_SILHOUETTE',
+  'PHASE_4_BASE_COLORS',
+  'PHASE_5_SHADING',
+  'PHASE_6_LIGHTING',
+  'PHASE_7_DETAILS',
+  'PHASE_8_FINAL_REVIEW'
+];
+
+// Workflow Steps are now categorized by MODE
+const WORKFLOW_STEPS = {
+  CREATE_IMAGE: [
+    { id: 'INITIALIZE_CANVAS', label: 'Khởi tạo Canvas', description: 'Kiểm tra và khởi tạo kích thước canvas' },
+    { id: 'ANALYZE_REQUEST', label: 'Phân tích yêu cầu', description: 'Phân tích yêu cầu của người dùng thành các thành phần có cấu trúc' },
+    { id: 'PLAN_DRAWING', label: 'Lập kế hoạch vẽ', description: 'Tạo kế hoạch vẽ theo thứ tự từ tổng thể đến chi tiết (cần user xác nhận)' },
+    { id: 'EXECUTE_PHASES', label: 'Thực hiện vẽ theo giai đoạn', description: 'Vẽ theo từng giai đoạn (PHASE_0 -> PHASE_8)' },
+    { id: 'FINALIZE', label: 'Hoàn thiện', description: 'Lưu và hoàn tất ảnh' }
+  ],
+  EDIT_IMAGE: [
+    { id: 'ANALYZE_REQUEST', label: 'Nhận yêu cầu sửa', description: 'Phân tích chính xác nội dung cần sửa' },
+    { id: 'GET_CURRENT_IMAGE', label: 'Lấy ảnh hiện tại', description: 'Lấy ảnh hiện tại làm nguồn gốc' },
+    { id: 'COMPARE_AND_LOCATE', label: 'So sánh và xác định', description: 'Xác định vùng hoặc layer cần chỉnh sửa' },
+    { id: 'EDIT_TARGET_AREA', label: 'Thực hiện chỉnh sửa', description: 'Chỉ sửa phần được yêu cầu trong phạm vi khoanh vùng' },
+    { id: 'CHECK_HARMONY', label: 'Kiểm tra sự tương thích', description: 'Kiểm tra sự hòa hợp với các vùng xung quanh và điều chỉnh phần chuyển tiếp' },
+    { id: 'FINALIZE', label: 'Cập nhật thay đổi', description: 'Cập nhật thay đổi vào ảnh hiện tại và kiểm tra kết quả' }
+  ],
+  CREATE_ANIMATION: [
+    { id: 'INITIALIZE_CANVAS_AND_ANIMATION', label: 'Khởi tạo Canvas và Animation', description: 'Xác định kích thước, fps, total_frames, loop' },
+    { id: 'ANALYZE_ANIMATION', label: 'Phân tích animation', description: 'Phân tích đối tượng, chuyển động, keyframe, layer...' },
+    { id: 'PROCESS_FRAMES', label: 'Tạo và xử lý từng frame', description: 'Xử lý từng frame theo đúng thứ tự (0 -> n)' },
+    { id: 'CHECK_CONTINUITY', label: 'Kiểm tra tính liên tục', description: 'Kiểm tra tính liên tục của animation giữa các frame' },
+    { id: 'FINALIZE', label: 'Hoàn thiện', description: 'Lưu và hoàn tất animation' }
+  ]
+};
+
+const DRAWING_STEPS = [
+  'EXECUTE_PHASES',
+  'EDIT_TARGET_AREA',
+  'PROCESS_FRAMES'
+];
+
+const DRAWING_CONSTRAINTS = {
+  maxCanvasSize: { width: 1024, height: 1024 },
+  minCanvasSize: { width: 8, height: 8 },
+  allowedColors: null,
+  maxStampNameLength: 32,
+  maxAnchorNameLength: 32,
+};
+
+/**
+ * Validate if the canvas name is valid
+ * @param {string} name
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateCanvasName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Canvas name cannot be empty' };
+  }
+  if (!NAMING_RULES.canvasTab.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.canvasTab.message };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate if the stamp name is valid
+ * @param {string} name
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateStampName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Stamp name cannot be empty' };
+  }
+  if (!NAMING_RULES.stamp.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.stamp.message };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate if the canvas size is within limits
+ * @param {number} w
+ * @param {number} h
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateCanvasSize(w, h) {
+  const { minCanvasSize, maxCanvasSize } = DRAWING_CONSTRAINTS;
+  if (w < minCanvasSize.width || h < minCanvasSize.height) {
+    return { valid: false, message: `Minimum canvas size is ${minCanvasSize.width}x${minCanvasSize.height}` };
+  }
+  if (w > maxCanvasSize.width || h > maxCanvasSize.height) {
+    return { valid: false, message: `Maximum canvas size is ${maxCanvasSize.width}x${maxCanvasSize.height}` };
+  }
+  return { valid: true };
+}
+
+module.exports = {
+  NAMING_RULES,
+  MODES,
+  STATUSES,
+  DRAWING_PHASES,
+  DRAWING_STEPS,
+  WORKFLOW_STEPS,
+  DRAWING_CONSTRAINTS,
+  validateCanvasName,
+  validateStampName,
+  validateCanvasSize,
+};