@pixel-normal-edit/mcp 2.0.8 → 2.0.10

package/index.js

@@ -28,6 +28,7 @@ require('dotenv').config({ path: require('path').join(__dirname, '..', '.env') }
 const { createServer } = require('./core/server');
 const { registerAll: registerCoreTools } = require('./tools/index');
 const { registerAll: registerArtTree } = require('./domains/art-tree/index');
+const { registerAll: registerRules } = require('./rules/index');
 
 // ── Initialize ────────────────────────────────────────────────────────────
 const server = createServer();
@@ -35,6 +36,9 @@ const server = createServer();
 // ── Register Core Tools ───────────────────────────────────────────────────
 registerCoreTools(server);
 
+// ── Register Rules / Workflow Tools (BẮT BUỘC: chạy trước khi vẽ) ────────
+registerRules(server);
+
 // ── Register Domain Modules ───────────────────────────────────────────────
 registerArtTree(server);
 // Future domains: registerPixelArt(server), registerCharacterDrawing(server), etc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-normal-edit/mcp",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "MCP server for Pixel Normal Edit canvas - enables AI agents to draw pixel art",
   "main": "index.js",
   "bin": {

package/rules/README.md

@@ -0,0 +1,403 @@
+# Rules Module — Báo cáo hoạt động
+
+## Tổng quan
+
+Module `rules/` là **bộ não điều khiển** của MCP Firebase Bridge. Nó đảm bảo agent AI **không thể làm bậy** — mọi thao tác vẽ đều phải tuân theo quy trình đã định sẵn.
+
+---
+
+## Cấu trúc thư mục
+
+```
+rules/
+├── index.js           # Module aggregator — import tất cả và export registerAll()
+├── rules.js           # Định nghĩa rules: naming, workflow steps, constraints
+├── workflow.js        # Workflow engine — quản lý trạng thái từng bước
+└── prerequisites.js   # 7 MCP Tools để agent tương tác với workflow
+```
+
+---
+
+## Luồng hoạt động (Workflow)
+
+### 1. Agent bắt đầu bằng `workflow_start`
+
+```
+Agent → workflow_start()
+       ↓
+Workflow Engine khởi tạo 9 bước:
+  [create_canvas → name_canvas → resize_canvas → enable_animation → 
+   setup_layers → prepare_colors → draw → review → finalize]
+       ↓
+Trả về: "Bước hiện tại: Tạo canvas"
+```
+
+### 2. Agent thực hiện từng bước
+
+Mỗi bước có **3 tool** liên quan:
+
+| Tool | Mục đích | Khi nào dùng |
+|------|----------|--------------|
+| `workflow_validate` | Kiểm tra có được phép làm bước này không | **TRƯỚC** mỗi thao tác |
+| `*_tools` (vd: `canvas_resize`) | Thực hiện thao tác thật | Sau khi validate OK |
+| `workflow_advance` | Đánh dấu hoàn thành, chuyển bước tiếp theo | **SAU** khi thao tác thành công |
+
+**Ví dụ thực tế — Bước "Đặt tên canvas":**
+
+```
+Agent → workflow_validate(stepId: "name_canvas")
+       ↓
+Workflow Engine kiểm tra:
+  - Đang ở bước 2? ✓
+  - Bước 1 đã hoàn thành? ✓
+       ↓
+Trả về: "✅ Bạn có thể thực hiện name_canvas"
+       ↓
+Agent → validate_canvas_name(name: "Bức tranh 1")
+       ↓
+Trả về: "✅ Tên hợp lệ!"
+       ↓
+Agent → workspace_rename_tab(tabId: "...", name: "Bức tranh 1")
+       ↓
+Thực hiện đổi tên thành công
+       ↓
+Agent → workflow_advance()
+       ↓
+Workflow Engine:
+  - Đánh dấu "name_canvas" = completed
+  - Chuyển sang bước 3: "Resize canvas"
+       ↓
+Trả về: "✅ Hoàn thành: Đặt tên canvas. Bước tiếp theo: Resize canvas"
+```
+
+### 3. Nếu agent làm sai thứ tự → BỊ CHẶN
+
+```
+Agent → draw_pixel(x: 10, y: 10, color: "#ff0000")  # ❌ Vẽ trước khi tạo canvas!
+       ↓
+(Nếu có middleware kiểm tra workflow)
+       ↓
+Trả về: "⛔ Bạn chưa thể thực hiện 'draw'. 
+         Trước hết hãy hoàn thành: Tạo canvas"
+```
+
+---
+
+## 7 Workflow Tools (trong `prerequisites.js`)
+
+### 1. `workflow_start`
+**Mục đích:** Khởi tạo workflow mới  
+**Tham số:** Không có  
+**Trả về:** Trạng thái workflow ban đầu + bước đầu tiên cần làm
+
+```json
+{
+  "content": [{
+    "type": "text",
+    "text": "🚀 Workflow đã bắt đầu!\n📋 Tiến trình vẽ:\n⬜ Tạo canvas\n🔄 Đặt tên canvas ← ĐANG LÀM\n..."
+  }]
+}
+```
+
+### 2. `workflow_status`
+**Mục đích:** Xem tiến trình hiện tại  
+**Tham số:** Không có  
+**Trả về:** Danh sách các bước với trạng thái (✅/🔄/⬜)
+
+### 3. `workflow_advance`
+**Mục đích:** Đánh dấu hoàn thành bước hiện tại, chuyển sang bước tiếp theo  
+**Tham số:** Không có  
+**Trả về:** Thông báo bước vừa hoàn thành + bước tiếp theo
+
+### 4. `workflow_validate`
+**Mục đích:** Kiểm tra agent có được phép thực hiện hành động không  
+**Tham số:**
+- `stepId` (string): ID bước muốn kiểm tra (vd: "draw", "resize_canvas")
+
+**Trả về:**
+- Nếu OK: `"✅ Bạn có thể thực hiện 'draw'. Hãy tiếp tục!"`
+- Nếu sai thứ tự: `"⛔ Bạn chưa thể thực hiện 'draw'. Trước hết hãy hoàn thành: Tạo canvas"`
+
+### 5. `workflow_reset`
+**Mục đích:** Reset workflow về đầu (xóa toàn bộ tiến trình)  
+**Tham số:** Không có  
+**Trả về:** `"🔄 Workflow đã được reset. Hãy bắt đầu lại từ đầu."`
+
+### 6. `validate_canvas_name`
+**Mục đích:** Kiểm tra tên canvas có hợp lệ không  
+**Tham số:**
+- `name` (string): Tên canvas muốn kiểm tra
+
+**Quy tắc:**
+- 3-64 ký tự
+- Chỉ gồm chữ, số, `_`, `-`, khoảng trắng
+- Ví dụ hợp lệ: "Bức_tranh_1", "My Canvas 2024"
+
+### 7. `validate_canvas_size`
+**Mục đích:** Kiểm tra kích thước canvas có nằm trong giới hạn không  
+**Tham số:**
+- `width` (int): Chiều rộng
+- `height` (int): Chiều cao
+
+**Giới hạn:** 8x8 đến 1024x1024 pixels
+
+---
+
+## 9 Workflow Steps (định nghĩa trong `rules.js`)
+
+| # | Step ID | Label | Description |
+|---|---------|-------|-------------|
+| 1 | `create_canvas` | Tạo canvas | Tạo tab mới với kích thước phù hợp |
+| 2 | `name_canvas` | Đặt tên canvas | Đặt tên cho canvas (3-64 ký tự) |
+| 3 | `resize_canvas` | Resize canvas | Điều chỉnh kích thước canvas nếu cần |
+| 4 | `enable_animation` | Bật animation | Bật chế độ animation nếu cần nhiều frame |
+| 5 | `setup_layers` | Thiết lập layers | Tạo/sắp xếp layers trước khi vẽ |
+| 6 | `prepare_colors` | Chuẩn bị màu sắc | Chọn màu chính/phụ trước khi vẽ |
+| 7 | `draw` | Vẽ | Thực hiện vẽ theo đúng kỹ thuật |
+| 8 | `review` | Kiểm tra | Xem lại kết quả sau khi vẽ |
+| 9 | `finalize` | Hoàn tất | Lưu và hoàn tất tác phẩm |
+
+---
+
+## Các loại Rules (trong `rules.js`)
+
+### 1. Naming Rules (`NAMING_RULES`)
+
+Quy tắc đặt tên cho các đối tượng:
+
+| Object | Pattern | Example |
+|--------|---------|---------|
+| Canvas/Tab | `^[A-Za-z0-9_\-\sÀ-ỹ]{3,64}$` | "Bức_tranh_1" |
+| Stamp | `^[a-z][a-z0-9_]{2,32}$` | "my_tree_01" |
+| Anchor | `^[a-z][a-z0-9_]{2,32}$` | "head_top" |
+
+### 2. Workflow Steps (`WORKFLOW_STEPS`)
+
+Danh sách 9 bước bắt buộc (xem bảng ở mục trên).
+
+### 3. Drawing Constraints (`DRAWING_CONSTRAINTS`)
+
+| Constraint | Value |
+|------------|-------|
+| Max canvas size | 1024x1024 |
+| Min canvas size | 8x8 |
+| Allowed colors | Tất cả hex colors |
+| Max stamp name length | 32 ký tự |
+| Max anchor name length | 32 ký tự |
+
+---
+
+## Workflow Engine (`workflow.js`)
+
+### State Management
+
+Workflow engine lưu trạng thái **in-memory** theo session:
+
+```javascript
+sessions = new Map([
+  "session-id-1": {
+    currentStepIndex: 2,
+    steps: [
+      { id: "create_canvas", label: "Tạo canvas", status: "completed" },
+      { id: "name_canvas", label: "Đặt tên canvas", status: "completed" },
+      { id: "resize_canvas", label: "Resize canvas", status: "in_progress" },
+      // ...
+    ],
+    completedSteps: ["create_canvas", "name_canvas"],
+    startedAt: 1234567890
+  }
+])
+```
+
+### Các hàm chính
+
+| Hàm | Mục đích |
+|------|----------|
+| `start(sessionId)` | Khởi tạo workflow mới |
+| `getState(sessionId)` | Lấy toàn bộ trạng thái |
+| `getCurrentStep(sessionId)` | Lấy bước hiện tại |
+| `validateStep(sessionId, stepId)` | Kiểm tra có được phép làm bước này không |
+| `advance(sessionId)` | Hoàn thành bước hiện tại, chuyển sang bước tiếp |
+| `reset(sessionId)` | Reset workflow về đầu |
+| `getProgressReport(sessionId)` | Lấy báo cáo tiến trình dạng text |
+
+### Logic Validation
+
+```
+validateStep(sessionId, stepId):
+  1. Nếu chưa start workflow → TỪ CHỐI
+  2. Nếu workflow đã hoàn thành → TỪ CHỐI
+  3. Nếu stepId đã hoàn thành → CHO PHÉP (với warning)
+  4. Nếu stepId đúng là bước hiện tại → CHO PHÉP
+  5. Nếu stepId nằm ở tương lai → TỪ CHỐI (với hướng dẫn bước hiện tại)
+```
+
+---
+
+## Cách sử dụng cho Agent
+
+### Scenario 1: Vẽ một hình tròn đơn giản
+
+```
+1. workflow_start()
+   → "Bước 1: Tạo canvas"
+
+2. validate_canvas_size(width: 32, height: 32)
+   → "✅ Kích thước 32x32 hợp lệ!"
+
+3. workspace_create_tab(width: 32, height: 32)
+   → Tạo canvas thành công
+
+4. workflow_validate(stepId: "name_canvas")
+   → "✅ Bạn có thể thực hiện name_canvas"
+
+5. validate_canvas_name(name: "Hình tròn")
+   → "✅ Tên hợp lệ!"
+
+6. workspace_rename_tab(tabId: "...", name: "Hình tròn")
+   → Đổi tên thành công
+
+7. workflow_advance()
+   → "✅ Hoàn thành: Đặt tên canvas. Bước tiếp theo: Resize canvas"
+
+8. workflow_validate(stepId: "resize_canvas")
+   → "✅ Bạn có thể thực hiện resize_canvas"
+
+9. canvas_resize(width: 64, height: 64)
+   → Resize thành công
+
+10. workflow_advance()
+    → Chuyển sang bước "Bật animation"
+
+11. workflow_validate(stepId: "enable_animation")
+    → "✅ Bạn có thể thực hiện enable_animation"
+
+12. animation_enable(enabled: false)  # Không cần animation
+    → OK
+
+13. workflow_advance()
+    → Chuyển sang bước "Thiết lập layers"
+
+14. workflow_validate(stepId: "setup_layers")
+    → "✅ Bạn có thể thực hiện setup_layers"
+
+15. layer_add()
+    → Thêm layer mới
+
+16. workflow_advance()
+    → Chuyển sang bước "Chuẩn bị màu sắc"
+
+17. workflow_validate(stepId: "prepare_colors")
+    → "✅ Bạn có thể thực hiện prepare_colors"
+
+18. color_set(primary: "#ff0000")
+    → Đặt màu đỏ
+
+19. workflow_advance()
+    → Chuyển sang bước "Vẽ" ← ĐÂY LÀ BƯỚC QUAN TRỌNG
+
+20. workflow_validate(stepId: "draw")
+    → "✅ Bạn có thể thực hiện draw"
+
+21. draw_circle(cx: 32, cy: 32, r: 20, color: "#ff0000")
+    → Vẽ hình tròn thành công
+
+22. workflow_advance()
+    → Chuyển sang bước "Kiểm tra"
+
+23. workflow_validate(stepId: "review")
+    → "✅ Bạn có thể thực hiện review"
+
+24. query_snapshot()
+    → Xem kết quả vẽ
+
+25. workflow_advance()
+    → Chuyển sang bước "Hoàn tất"
+
+26. workflow_validate(stepId: "finalize")
+    → "✅ Bạn có thể thực hiện finalize"
+
+27. workspace_save()
+    → Lưu tác phẩm
+
+28. workflow_advance()
+    → "🎉 Hoàn tất tất cả các bước!"
+```
+
+### Scenario 2: Agent cố gắng vẽ trước khi tạo canvas
+
+```
+1. workflow_start()
+   → "Bước 1: Tạo canvas"
+
+2. draw_pixel(x: 10, y: 10, color: "#ff0000")  # ❌ Sai thứ tự!
+   → (Nếu có middleware kiểm tra)
+   → "⛔ Bạn chưa thể thực hiện 'draw'. 
+      Trước hết hãy hoàn thành: Tạo canvas"
+```
+
+---
+
+## Lưu ý quan trọng
+
+1. **Workflow là per-session:** Mỗi session có workflow riêng, không ảnh hưởng lẫn nhau.
+2. **Có thể quay lại bước cũ:** Nếu agent đã hoàn thành bước 3 và muốn làm lại, `validateStep` sẽ cho phép nhưng có cảnh báo.
+3. **Workflow không tự động chặn tool:** Tool `draw_pixel` vẫn chạy được nếu agent gọi trực tiếp. Tuy nhiên, agent được hướng dẫn **PHẢI** gọi `workflow_validate` trước mỗi thao tác.
+4. **Có thể reset:** Dùng `workflow_reset` để bắt đầu lại từ đầu nếu cần.
+
+---
+
+## Cách thêm Rule mới
+
+### Thêm Naming Rule mới
+
+```javascript
+// rules.js
+const NAMING_RULES = {
+  // ... existing rules
+  newObject: {
+    pattern: /^[a-z]{3,16}$/,
+    message: 'Tên phải 3-16 ký tự, chỉ chữ thường',
+    example: 'myobject',
+  },
+};
+
+// Thêm validator
+function validateNewObjectName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Tên không được để trống' };
+  }
+  if (!NAMING_RULES.newObject.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.newObject.message };
+  }
+  return { valid: true };
+}
+```
+
+### Thêm Workflow Step mới
+
+```javascript
+// rules.js
+const WORKFLOW_STEPS = [
+  // ... existing steps
+  { id: 'new_step', label: 'Bước mới', description: 'Mô tả bước mới' },
+];
+
+// prerequisites.js — Thêm tool validate nếu cần
+registerTool(server, 'validate_new_step', 'Kiểm tra...', {...}, (p) => {...});
+```
+
+---
+
+## Tóm tắt
+
+Module `rules/` đảm bảo:
+
+✅ Agent **bắt buộc** tuân theo thứ tự 9 bước  
+✅ Tất cả tên đều **hợp lệ** theo quy tắc  
+✅ Kích thước canvas **nằm trong giới hạn**  
+✅ Agent **không thể bỏ qua** bước nào  
+✅ Có thể **kiểm tra tiến trình** bất cứ lúc nào  
+✅ Có thể **reset** nếu cần làm lại  
+
+**Mục tiêu:** Không còn tình trạng "agent muốn gì làm nấy" — mọi thao tác đều có **rule engine** giám sát.

package/rules/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * rules/index.js — Rules Module Aggregator
+ *
+ * Aggregates và export tất cả các rules, workflow engine, và prerequisite tools.
+ *
+ * Module này cung cấp:
+ *   1. rules.js         — Định nghĩa rules (naming, constraints, validators)
+ *   2. workflow.js      — Workflow engine (quản lý thứ tự bước)
+ *   3. prerequisites.js — MCP Tools cho workflow (start, status, advance, validate)
+ *
+ * Cách thêm rule mới:
+ *   - Thêm vào rules.js (NAMING_RULES, WORKFLOW_STEPS, DRAWING_CONSTRAINTS)
+ *   - Nếu cần logic phức tạp, tạo file mới trong rules/ và import vào đây
+ */
+
+const rules = require('./rules');
+const workflow = require('./workflow');
+const prerequisites = require('./prerequisites');
+
+/**
+ * Register tất cả workflow/prerequisite tools lên MCP server
+ * @param {McpServer} server
+ */
+function registerAll(server) {
+  prerequisites.register(server);
+}
+
+module.exports = {
+  rules,
+  workflow,
+  prerequisites,
+  registerAll,
+};

package/rules/prerequisites.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * prerequisites.js — Prerequisites Check (Điều kiện để chạy)
+ *
+ * Đây là MCP Tool để agent gọi trước khi bắt đầu vẽ.
+ * Nó sẽ kiểm tra mọi điều kiện tiên quyết và trả về hướng dẫn chi tiết.
+ *
+ * QUAN TRỌNG: Agent BẮT BUỘC phải gọi tool này TRƯỚC TIÊN
+ * trước khi làm bất kỳ thao tác vẽ nào.
+ */
+
+const { z } = require('zod');
+const { validateCanvasName, validateCanvasSize, DRAWING_CONSTRAINTS, WORKFLOW_STEPS } = 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) {
+  // ── Tool 1: workflow_start — Bắt đầu workflow ─────────────────────────
+  registerTool(server, 'workflow_start',
+    `🚀 BẮT BUỘC: Gọi tool này ĐẦU TIÊN trước khi vẽ bất cứ thứ gì.
+Tool này khởi tạo một workflow vẽ với các bước tuần tự.
+Agent PHẢI làm theo đúng thứ tự các bước.
+
+Các bước workflow:
+1. create_canvas  — Tạo canvas mới
+2. name_canvas    — Đặt tên cho canvas
+3. resize_canvas  — Resize nếu cần
+4. enable_animation — Bật animation nếu cần
+5. setup_layers   — Thiết lập layers
+6. prepare_colors — Chuẩn bị màu sắc
+7. draw           — Vẽ (chỉ được vẽ sau các bước trên)
+8. review         — Kiểm tra kết quả
+9. finalize       — Lưu và hoàn tất`,
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const state = workflow.start(session);
+      return {
+        content: [{ type: 'text', text: `🚀 **Workflow đã bắt đầu!**\n\n${workflow.getProgressReport(session)}\n\n---\nBắt đầu với bước: **${state.steps[0].label}** → ${state.steps[0].description}` }]
+      };
+    });
+
+  // ── Tool 2: workflow_status — Xem trạng thái hiện tại ─────────────────
+  registerTool(server, 'workflow_status',
+    'Xem tiến trình workflow hiện tại: đang ở bước nào, đã làm gì, cần làm gì tiếp theo.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      const report = workflow.getProgressReport(session);
+      const current = workflow.getCurrentStep(session);
+      if (!current) {
+        return { content: [{ type: 'text', text: '⚠️ Chưa bắt đầu workflow. Gọi **workflow_start** trước.' }] };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: `${report}\n\n👉 **Đang cần:** ${current.label} — ${current.description}`
+        }]
+      };
+    });
+
+  // ── Tool 3: workflow_advance — Hoàn thành bước hiện tại ───────────────
+  registerTool(server, 'workflow_advance',
+    '✅ Đánh dấu bước hiện tại là hoàn thành và chuyển sang bước tiếp theo. Chỉ gọi SAU KHI đã làm xong bước hiện tại.',
+    {},
+    () => {
+      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 }] };
+    });
+
+  // ── Tool 4: workflow_validate — Kiểm tra trước khi gọi tool ──────────
+  registerTool(server, 'workflow_validate',
+    `🔍 Kiểm tra xem agent có được phép thực hiện một hành động nào đó không.
+  Gọi tool này TRƯỚC khi làm bất kỳ thao tác vẽ nào để đảm bảo đúng thứ tự workflow.
+  
+  Các stepId hợp lệ:
+  - create_canvas
+  - name_canvas
+  - resize_canvas
+  - enable_animation
+  - setup_layers
+  - prepare_colors
+  - draw
+  - review
+  - finalize`,
+    { stepId: z.string().describe('ID của bước muốn kiểm tra (vd: "draw", "resize_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 || `✅ Bạn có thể thực hiện "${p.stepId}". Hãy tiếp tục!` }] };
+    });
+
+  // ── Tool 5: workflow_reset — Làm lại từ đầu ──────────────────────────
+  registerTool(server, 'workflow_reset',
+    '🔄 Reset workflow về trạng thái ban đầu. Xoá toàn bộ tiến trình đã làm.',
+    {},
+    () => {
+      const session = require('../core/command-bus').SESSION;
+      workflow.reset(session);
+      return { content: [{ type: 'text', text: '🔄 Workflow đã được reset. Hãy bắt đầu lại từ đầu.' }] };
+    });
+
+  // ── Tool 6: validate_canvas_name — Kiểm tra tên canvas ───────────────
+  registerTool(server, 'validate_canvas_name',
+    `Kiểm tra tên canvas có hợp lệ không trước khi đặt.
+  Quy tắc: 3-64 ký tự, chỉ gồm chữ, số, _, -, khoảng trắng.
+  Ví dụ: "Bức_tranh_1", "My Canvas 2024"`,
+    { name: z.string().describe('Tên canvas muốn kiểm tra') },
+    (p) => {
+      const result = validateCanvasName(p.name);
+      if (!result.valid) {
+        return { isError: true, content: [{ type: 'text', text: `❌ ${result.message}` }] };
+      }
+      return { content: [{ type: 'text', text: `✅ Tên "${p.name}" hợp lệ!` }] };
+    });
+
+  // ── Tool 7: validate_canvas_size — Kiểm tra kích thước canvas ────────
+  registerTool(server, 'validate_canvas_size',
+    `Kiểm tra kích thước canvas có nằm trong giới hạn cho phép không.
+  Giới hạn: ${DRAWING_CONSTRAINTS.minCanvasSize.width}x${DRAWING_CONSTRAINTS.minCanvasSize.height} đến ${DRAWING_CONSTRAINTS.maxCanvasSize.width}x${DRAWING_CONSTRAINTS.maxCanvasSize.height}`,
+    { width: z.number().int().describe('Chiều rộng'), height: z.number().int().describe('Chiều cao') },
+    (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: `✅ Kích thước ${p.width}x${p.height} hợp lệ!` }] };
+    });
+}
+
+module.exports = { register };

package/rules/rules.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * rules.js — Core Drawing Rules & Constraints
+ *
+ * QUAN TRỌNG: Mọi function trong đây là luật BẮT BUỘC.
+ * Agent KHÔNG được tự ý bỏ qua hay làm sai thứ tự.
+ *
+ * Các rules được chia làm 3 loại:
+ *   1. naming    — Quy tắc đặt tên tab/canvas
+ *   2. workflow  — Quy tắc thứ tự các bước
+ *   3. drawing   — Quy tắc về vẽ (kích thước, màu sắc, v.v.)
+ */
+
+// ── Loại 1: Naming Rules ────────────────────────────────────────────────────
+const NAMING_RULES = {
+  canvasTab: {
+    pattern: /^[A-Za-z0-9_\-\sÀ-ỹ]{3,64}$/,
+    message: 'Tên canvas phải từ 3-64 ký tự, chỉ gồm chữ, số, _, -, và khoảng trắng',
+    example: 'Bức_tranh_1',
+  },
+  stamp: {
+    pattern: /^[a-z][a-z0-9_]{2,32}$/,
+    message: 'Tên stamp phải bắt đầu bằng chữ thường, 3-32 ký tự, chỉ gồm a-z, 0-9, _',
+    example: 'my_tree_01',
+  },
+  anchor: {
+    pattern: /^[a-z][a-z0-9_]{2,32}$/,
+    message: 'Tên anchor phải bắt đầu bằng chữ thường, 3-32 ký tự',
+    example: 'head_top',
+  },
+};
+
+// ── Loại 2: Workflow Steps (thứ tự bắt buộc) ──────────────────────────────
+const WORKFLOW_STEPS = [
+  { id: 'create_canvas',  label: 'Tạo canvas',          description: 'Tạo tab mới với kích thước phù hợp' },
+  { id: 'name_canvas',    label: 'Đặt tên canvas',      description: 'Đặt tên cho canvas (3-64 ký tự)' },
+  { id: 'resize_canvas',  label: 'Resize canvas',       description: 'Điều chỉnh kích thước canvas nếu cần' },
+  { id: 'enable_animation', label: 'Bật animation',     description: 'Bật chế độ animation nếu cần nhiều frame' },
+  { id: 'setup_layers',   label: 'Thiết lập layers',    description: 'Tạo/sắp xếp layers trước khi vẽ' },
+  { id: 'prepare_colors', label: 'Chuẩn bị màu sắc',    description: 'Chọn màu chính/phụ trước khi vẽ' },
+  { id: 'draw',           label: 'Vẽ',                  description: 'Thực hiện vẽ theo đúng kỹ thuật' },
+  { id: 'review',         label: 'Kiểm tra',            description: 'Xem lại kết quả sau khi vẽ' },
+  { id: 'finalize',       label: 'Hoàn tất',            description: 'Lưu và hoàn tất tác phẩm' },
+];
+
+// ── Loại 3: Drawing Constraints ─────────────────────────────────────────────
+const DRAWING_CONSTRAINTS = {
+  maxCanvasSize: { width: 1024, height: 1024 },
+  minCanvasSize: { width: 8, height: 8 },
+  allowedColors: null, // null = all hex colors allowed
+  maxStampNameLength: 32,
+  maxAnchorNameLength: 32,
+};
+
+// ── Validator Functions ──────────────────────────────────────────────────────
+
+/**
+ * Kiểm tra tên canvas có hợp lệ không
+ * @param {string} name
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateCanvasName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Tên canvas không được để trống' };
+  }
+  if (!NAMING_RULES.canvasTab.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.canvasTab.message };
+  }
+  return { valid: true };
+}
+
+/**
+ * Kiểm tra tên stamp có hợp lệ không
+ * @param {string} name
+ * @returns {{ valid: boolean, message?: string }}
+ */
+function validateStampName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, message: 'Tên stamp không được để trống' };
+  }
+  if (!NAMING_RULES.stamp.pattern.test(name)) {
+    return { valid: false, message: NAMING_RULES.stamp.message };
+  }
+  return { valid: true };
+}
+
+/**
+ * Kiểm tra kích thước canvas có nằm trong giới hạn không
+ * @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: `Canvas tối thiểu ${minCanvasSize.width}x${minCanvasSize.height}` };
+  }
+  if (w > maxCanvasSize.width || h > maxCanvasSize.height) {
+    return { valid: false, message: `Canvas tối đa ${maxCanvasSize.width}x${maxCanvasSize.height}` };
+  }
+  return { valid: true };
+}
+
+module.exports = {
+  NAMING_RULES,
+  WORKFLOW_STEPS,
+  DRAWING_CONSTRAINTS,
+  validateCanvasName,
+  validateStampName,
+  validateCanvasSize,
+};

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,21 +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 layer = require('./layer');
+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.

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * layer.js — MCP Tool Registration for Layers
+ * layer-tools.js — MCP Tool Registration for Layers
  *
  * Exposes the layer management functionality to MCP clients.
  */
@@ -77,4 +77,4 @@ function register(server) {
     });
 }
 
-module.exports = { register };
+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',
     {