CocosPlugin/mcp-bridge

Fork 0

Files

火焰库拉 a851493966 feat: Implement VFX management, Undo/Redo, Find in File; docs: Update README and plans

2026-02-01 13:30:11 +08:00

21 KiB

Raw Blame History

Cocos-MCP 开发计划文档

1. 项目概述

1.1 项目背景

Cocos-MCP (Model Context Protocol) 插件是一个为 Cocos Creator 编辑器提供外部 AI 工具交互能力的桥梁。通过 HTTP 服务和 MCP 协议，插件允许外部 AI 工具（如 Cursor、VS Code 等）直接与 Cocos Creator 编辑器进行交互，实现场景操作、资源管理、脚本编辑等功能。

1.2 项目目标

提供与 Unity-MCP 对等的功能集，使 Cocos Creator 开发者获得同样强大的 AI 辅助开发体验
实现编辑器管理、游戏对象查找、材质/纹理管理等高级功能
优化现有功能，提高插件稳定性和性能
建立完善的测试和部署流程

1.3 技术栈

开发语言：JavaScript/TypeScript
运行环境：Node.js (Cocos Creator 内置)
通信协议：HTTP + JSON (MCP 协议)
编辑器 API：Cocos Creator 2.4.x Editor API
界面技术：HTML/CSS + Cocos Creator 面板 API

2. 功能分析

2.1 Unity-MCP 功能参考

Unity-MCP 提供了以下核心功能：

功能类别	具体功能	描述
编辑器管理	manage_editor	控制 Unity 编辑器状态和操作
游戏对象管理	find_gameobjects	根据条件查找游戏对象
材质管理	manage_material	创建和管理材质资源
着色器管理	manage_shader	管理着色器资源
纹理管理	manage_texture	管理纹理资源
代码编辑增强	apply_text_edits	应用文本编辑操作到文件
测试功能	run_tests	运行测试用例
控制台读取	read_console	读取编辑器控制台输出
菜单项执行	execute_menu_item	执行编辑器菜单项
脚本验证	validate_script	验证脚本语法
VFX 管理	manage_vfx	管理视觉效果资源

2.2 Cocos-MCP 现状分析

已实现功能

场景节点操作：获取选中节点、设置节点名称、获取场景层级、更新节点变换、创建节点
组件管理：添加、移除、获取组件
资源管理：创建、删除、移动资源
脚本管理：创建、删除、读取、写入脚本（默认创建 TypeScript 脚本）
批处理执行：批量执行多个操作
资产管理：管理各种资源文件
场景管理：创建、删除、复制、获取场景信息
预制体管理：创建、更新、实例化、获取预制体信息
面板界面：提供主面板和工具测试面板
编辑器管理：控制编辑器状态、执行编辑器操作
游戏对象查找：根据条件查找场景中的节点
材质管理：创建和管理材质资源
着色器管理：管理着色器资源
纹理管理：管理纹理资源
代码编辑增强：应用文本编辑操作到文件
测试功能：运行自动化测试用例 (run_tests.js)
控制台读取：读取编辑器控制台输出
菜单项执行：执行编辑器菜单项
脚本验证：验证脚本语法

缺失功能

VFX 管理：管理视觉效果资源（暂未排期）

2.3 功能优先级排序

所有高/中优先级功能均已完成。

2.4 Unity-MCP 差异分析 (Gap Analysis)

通过对比 Unity-MCP，发现以下缺失或可增强的功能：

全局搜索 (find_in_file): ✅ 已实现。支持在整个项目中搜索文本内容。
ScriptableObject 管理 (manage_scriptable_object): 虽然 AssetDB 可以创建资源，但缺乏专门针对 ScriptableObject (cc.Asset) 的简便创建工具。
Undo/Redo 支持: ✅ 已实现。通过 manage_undo 提供了 undo/redo 及事务组支持。
VFX 管理 (manage_vfx): ✅ 已实现。支持粒子系统的创建、修改和信息获取。
Git 集成 (get_sha): 获取当前版本库信息。

find_in_file、Undo/Redo 和 manage_vfx 已在最新迭代中完成。

3. 开发路线图

3.1 第三阶段开发计划（已完成）

任务	状态	描述
编辑器管理工具实现	✅ 完成	实现 manage_editor 工具，支持编辑器状态控制和操作执行
游戏对象查找工具实现	✅ 完成	实现 find_gameobjects 工具，支持根据条件查找场景节点
材质和纹理管理工具实现	✅ 完成	实现 manage_material 和 manage_texture 工具，支持材质和纹理资源管理
菜单项执行工具实现	✅ 完成	实现 execute_menu_item 工具，支持执行 Cocos Creator 菜单项
代码编辑增强工具实现	✅ 完成	实现 apply_text_edits 工具，支持文本编辑操作应用
控制台读取工具实现	✅ 完成	实现 read_console 工具，支持读取编辑器控制台输出
脚本验证工具实现	✅ 完成	实现 validate_script 工具，支持脚本语法验证

3.2 第四阶段开发计划（已完成）

任务	状态	描述
测试功能实现	✅ 完成	实现 run_tests.js 脚本，支持运行自动化测试用例
错误处理增强	✅ 完成	完善 HTTP 服务和工具调用的错误日志记录

3.3 差异填补阶段（Gap Filling）- 已完成

任务	状态	描述
全局文件搜索	✅ 完成	实现 find_in_file 工具
撤销/重做支持	✅ 完成	实现 manage_undo 工具，并重构核心操作支持撤销
特效管理	✅ 完成	实现 manage_vfx 工具，支持粒子系统管理

3.3 第五阶段开发计划（远期）

任务	优先级	预计时间	描述
工具扩展	低	3 天	添加更多高级工具和功能
界面美化	低	2 天	进一步优化面板界面，提升用户体验
国际化支持	低	2 天	添加多语言支持
文档完善	中	2 天	完善 API 文档和使用示例
插件发布	高	1 天	准备插件发布，提交到 Cocos 插件商店

4. 技术架构

4.1 系统架构

┌────────────────────┐     HTTP     ┌────────────────────┐     IPC     ┌────────────────────┐
│  外部 AI 工具       │  ──────────> │  main.js (HTTP服务) │  ─────────> │  scene-script.js   │
│  (Cursor/VS Code)  │     <──────── │  (MCP 协议处理)     │     <──────── │  (场景操作执行)     │
└────────────────────┘     JSON     └────────────────────┘     JSON     └────────────────────┘

4.2 核心模块

HTTP 服务模块：处理外部请求，解析 MCP 协议，返回操作结果
MCP 工具模块：实现各种操作工具，包括新增的编辑器管理、游戏对象查找等功能
场景操作模块：执行场景相关操作，如节点查找、组件管理等
资源管理模块：处理脚本、材质、纹理等资源文件的创建和管理
面板界面模块：提供用户交互界面，包括主面板和工具测试面板

4.3 技术实现要点

编辑器 API 调用：使用 Editor.Ipc 与编辑器核心进行通信
资源操作：使用 Editor.assetdb API 进行资源文件的创建、读取、更新和删除
场景操作：通过场景脚本执行节点和组件操作
异步处理：使用回调函数处理异步操作，避免阻塞主线程
错误处理：完善的错误捕获和处理机制，提高插件稳定性
性能优化：使用批处理执行减少 HTTP 请求次数，优化资源操作效率

5. 功能实现方案

5.1 编辑器管理工具 (`manage_editor`)

功能描述

提供对 Cocos Creator 编辑器状态的控制和操作执行能力。

实现方案

// 在 main.js 中添加
manageEditor(args, callback) {
    const { action, target, properties } = args;
    
    switch (action) {
        case "get_selection":
            // 获取当前选中的资源或节点
            const nodeSelection = Editor.Selection.curSelection('node');
            const assetSelection = Editor.Selection.curSelection('asset');
            callback(null, {
                nodes: nodeSelection,
                assets: assetSelection
            });
            break;
        case "set_selection":
            // 设置选中状态
            if (target === 'node' && properties.nodes) {
                Editor.Selection.select('node', properties.nodes);
            } else if (target === 'asset' && properties.assets) {
                Editor.Selection.select('asset', properties.assets);
            }
            callback(null, "Selection updated");
            break;
        case "refresh_editor":
            // 刷新编辑器
            Editor.assetdb.refresh();
            callback(null, "Editor refreshed");
            break;
        default:
            callback("Unknown action");
    }
}

5.2 游戏对象查找工具 (`find_gameobjects`)

功能描述

根据条件查找场景中的节点对象。

实现方案

// 在 scene-script.js 中添加
findGameObjects(params, callback) {
    const { conditions, recursive } = params;
    const result = [];
    
    // 遍历场景根节点
    cc.director.getScene().children.forEach(child => {
        searchNode(child, conditions, recursive, result);
    });
    
    callback(null, result);
}

function searchNode(node, conditions, recursive, result) {
    // 检查节点是否满足条件
    let match = true;
    
    if (conditions.name && !node.name.includes(conditions.name)) {
        match = false;
    }
    
    if (conditions.tag && node.tag !== conditions.tag) {
        match = false;
    }
    
    if (conditions.component && !node.getComponent(conditions.component)) {
        match = false;
    }
    
    if (match) {
        result.push({
            id: node.uuid,
            name: node.name,
            tag: node.tag,
            position: node.position,
            rotation: node.rotation,
            scale: node.scale
        });
    }
    
    // 递归搜索子节点
    if (recursive) {
        node.children.forEach(child => {
            searchNode(child, conditions, recursive, result);
        });
    }
}

5.3 材质和纹理管理工具 (`manage_material`, `manage_texture`)

功能描述

管理材质和纹理资源，支持创建、修改、删除等操作。

实现方案

// 在 main.js 中添加
manageMaterial(args, callback) {
    const { action, path, properties } = args;
    
    switch (action) {
        case "create":
            // 创建材质资源
            const materialContent = JSON.stringify({
                __type__: "cc.Material",
                _name: "",
                _objFlags: 0,
                _native: "",
                effects: [{
                    technique: 0,
                    defines: {},
                    uniforms: properties.uniforms || {}
                }]
            });
            
            // 确保目录存在
            const fs = require('fs');
            const pathModule = require('path');
            const absolutePath = Editor.assetdb.urlToFspath(path);
            const dirPath = pathModule.dirname(absolutePath);
            if (!fs.existsSync(dirPath)) {
                fs.mkdirSync(dirPath, { recursive: true });
            }
            
            Editor.assetdb.create(path, materialContent, (err) => {
                callback(err, err ? null : `Material created at ${path}`);
            });
            break;
        // 其他操作...
    }
}

manageTexture(args, callback) {
    const { action, path, properties } = args;
    
    switch (action) {
        case "create":
            // 创建纹理资源（简化版，实际需要处理纹理文件）
            const textureContent = JSON.stringify({
                __type__: "cc.Texture2D",
                _name: "",
                _objFlags: 0,
                _native: properties.native || "",
                width: properties.width || 128,
                height: properties.height || 128
            });
            
            // 确保目录存在
            const fs = require('fs');
            const pathModule = require('path');
            const absolutePath = Editor.assetdb.urlToFspath(path);
            const dirPath = pathModule.dirname(absolutePath);
            if (!fs.existsSync(dirPath)) {
                fs.mkdirSync(dirPath, { recursive: true });
            }
            
            Editor.assetdb.create(path, textureContent, (err) => {
                callback(err, err ? null : `Texture created at ${path}`);
            });
            break;
        // 其他操作...
    }
}

5.4 菜单项执行工具 (`execute_menu_item`)

功能描述

执行 Cocos Creator 编辑器的菜单项命令。

实现方案

// 在 main.js 中添加
executeMenuItem(args, callback) {
    const { menuPath } = args;
    
    try {
        // 执行菜单项
        Editor.Ipc.sendToMain('menu:click', menuPath);
        callback(null, `Menu item executed: ${menuPath}`);
    } catch (err) {
        callback(`Failed to execute menu item: ${err.message}`);
    }
}

5.5 代码编辑增强工具 (`apply_text_edits`)

功能描述

应用文本编辑操作到文件，支持插入、删除、替换等操作。

实现方案

// 在 main.js 中添加
applyTextEdits(args, callback) {
    const { filePath, edits } = args;
    
    // 读取文件内容
    Editor.assetdb.queryInfoByUrl(filePath, (err, info) => {
        if (err) {
            callback(`Failed to get file info: ${err.message}`);
            return;
        }
        
        Editor.assetdb.loadMeta(info.uuid, (err, content) => {
            if (err) {
                callback(`Failed to load file: ${err.message}`);
                return;
            }
            
            // 应用编辑操作
            let updatedContent = content;
            edits.forEach(edit => {
                switch (edit.type) {
                    case "insert":
                        updatedContent = updatedContent.slice(0, edit.position) + edit.text + updatedContent.slice(edit.position);
                        break;
                    case "delete":
                        updatedContent = updatedContent.slice(0, edit.start) + updatedContent.slice(edit.end);
                        break;
                    case "replace":
                        updatedContent = updatedContent.slice(0, edit.start) + edit.text + updatedContent.slice(edit.end);
                        break;
                }
            });
            
            // 写回文件
            Editor.assetdb.save(info.uuid, updatedContent, (err) => {
                callback(err, err ? null : `Text edits applied to ${filePath}`);
            });
        });
    });
}

5.6 控制台读取工具 (`read_console`)

功能描述

读取编辑器控制台的输出信息。

实现方案

// 在 main.js 中添加
// 首先在模块顶部添加控制台输出捕获
let consoleOutput = [];
const originalLog = console.log;
const originalError = console.error;
const originalWarn = console.warn;

console.log = function(...args) {
    consoleOutput.push({ type: 'log', message: args.join(' ') });
    originalLog.apply(console, args);
};

console.error = function(...args) {
    consoleOutput.push({ type: 'error', message: args.join(' ') });
    originalError.apply(console, args);
};

console.warn = function(...args) {
    consoleOutput.push({ type: 'warn', message: args.join(' ') });
    originalWarn.apply(console, args);
};

// 然后添加 read_console 工具
readConsole(args, callback) {
    const { limit, type } = args;
    let filteredOutput = consoleOutput;
    
    if (type) {
        filteredOutput = filteredOutput.filter(item => item.type === type);
    }
    
    if (limit) {
        filteredOutput = filteredOutput.slice(-limit);
    }
    
    callback(null, filteredOutput);
}

5.7 脚本验证工具 (`validate_script`)

功能描述

验证脚本文件的语法正确性。

实现方案

// 在 main.js 中添加
validateScript(args, callback) {
    const { filePath } = args;
    
    // 读取脚本内容
    Editor.assetdb.queryInfoByUrl(filePath, (err, info) => {
        if (err) {
            callback(`Failed to get file info: ${err.message}`);
            return;
        }
        
        Editor.assetdb.loadMeta(info.uuid, (err, content) => {
            if (err) {
                callback(`Failed to load file: ${err.message}`);
                return;
            }
            
            try {
                // 对于 JavaScript 脚本，使用 eval 进行简单验证
                if (filePath.endsWith('.js')) {
                    // 包装在函数中以避免变量污染
                    const wrapper = `(function() { ${content} })`;
                    eval(wrapper);
                }
                // 对于 TypeScript 脚本，这里可以添加更复杂的验证逻辑
                
                callback(null, { valid: true, message: 'Script syntax is valid' });
            } catch (err) {
                callback(null, { valid: false, message: err.message });
            }
        });
    });
}
    });
}

5.8 常用 IPC 消息参考 (Cocos Creator 2.4.x)

基于社区资料整理，以下 IPC 消息可用于扩展功能：

场景操作 (`scene:`)

创建/实例化:
- scene:create-node-by-classid (参数: name, parentUuid)
- scene:create-nodes-by-uuids (实例化预制体, 参数: [prefabUuid], parentUuid)
修改:
- scene:set-property (参数: {id, path, type, value})
- scene:copy-nodes / scene:paste-nodes
安全机制:
- scene:undo / scene:redo (建议集成到 manage_editor)

资源操作 (`assets:`)

assets:hint (高亮资源)
assets:open-text-file (打开外部编辑器)

6. 测试策略

6.1 测试目标

验证所有新增功能的正确性和稳定性
确保现有功能不受影响
测试插件在不同场景下的性能表现
验证错误处理机制的有效性

6.2 测试方法

单元测试

为每个工具函数编写独立的测试用例
测试各种输入参数和边界情况
验证函数返回值的正确性

集成测试

测试工具之间的协作能力
验证批处理执行的正确性
测试插件与编辑器的集成稳定性

性能测试

测试工具执行速度
验证批处理执行的性能优势
测试插件在处理大量操作时的表现

回归测试

确保新增功能不破坏现有功能
验证修复的 bug 不会再次出现
测试插件在不同版本 Cocos Creator 中的兼容性

6.3 测试工具

手动测试：通过面板界面测试工具功能
脚本测试：编写测试脚本自动执行测试用例
性能分析：使用浏览器开发者工具分析性能瓶颈

7. 部署与维护

7.1 部署方案

本地部署

将插件复制到 Cocos Creator 项目的 packages 目录
重启 Cocos Creator 编辑器
在编辑器中打开 MCP Bridge 面板
启动 HTTP 服务

远程部署

使用 Git 进行版本控制
提供插件的 GitHub 仓库地址
发布插件到 Cocos 插件商店（未来）

7.2 维护计划

版本管理

遵循语义化版本规范（MAJOR.MINOR.PATCH）
定期发布更新版本
维护详细的版本变更日志

错误处理

建立错误报告机制
定期分析错误日志
及时修复发现的问题

性能优化

定期分析插件性能
优化资源操作和网络请求
提高插件响应速度

文档维护

保持 README.md 和开发文档的更新
提供详细的 API 文档
编写使用教程和示例

8. 风险评估

8.1 潜在风险

风险	影响	缓解措施
编辑器 API 变更	插件功能失效	定期检查 Cocos Creator 更新，适配新 API
性能问题	插件响应缓慢	优化代码结构，使用批处理执行，避免阻塞操作
安全漏洞	未授权访问	添加 IP 白名单，实现认证机制，限制服务访问范围
兼容性问题	不同版本 Cocos Creator 不兼容	测试多个版本，提供版本兼容层
错误处理不完善	插件崩溃	完善错误捕获和处理机制，提高插件稳定性

8.2 应对策略

持续集成：建立自动化测试流程，及时发现问题
监控机制：添加性能监控和错误监控
用户反馈：建立用户反馈渠道，收集使用问题
文档完善：提供详细的安装和使用文档
社区支持：建立社区支持渠道，解答用户问题

9. 结论

Cocos-MCP 插件的开发计划基于与 Unity-MCP 的功能对比，旨在为 Cocos Creator 开发者提供同样强大的 AI 辅助开发体验。通过分阶段实现编辑器管理、游戏对象查找、材质/纹理管理等高级功能，插件将逐步完善其功能集，成为 Cocos Creator 编辑器的重要扩展工具。

本开发计划文档为后续的开发工作提供了详细的指导，包括功能实现方案、技术架构设计、测试策略和部署维护计划。通过严格按照计划执行开发工作，我们可以确保插件的质量和稳定性，为 Cocos Creator 生态系统做出贡献。

21 KiB Raw Blame History Unescape Escape

Cocos-MCP 开发计划文档

1. 项目概述

1.1 项目背景

1.2 项目目标

1.3 技术栈

2. 功能分析

2.1 Unity-MCP 功能参考

2.2 Cocos-MCP 现状分析

已实现功能

缺失功能

2.3 功能优先级排序

2.4 Unity-MCP 差异分析 (Gap Analysis)

3. 开发路线图

3.1 第三阶段开发计划（已完成）

3.2 第四阶段开发计划（已完成）

3.3 差异填补阶段（Gap Filling）- 已完成

3.3 第五阶段开发计划（远期）

4. 技术架构

4.1 系统架构

4.2 核心模块

4.3 技术实现要点

5. 功能实现方案

5.1 编辑器管理工具 (manage_editor)

功能描述

实现方案

5.2 游戏对象查找工具 (find_gameobjects)

功能描述

实现方案

5.3 材质和纹理管理工具 (manage_material, manage_texture)

功能描述

实现方案

5.4 菜单项执行工具 (execute_menu_item)

功能描述

实现方案

5.5 代码编辑增强工具 (apply_text_edits)

功能描述

实现方案

5.6 控制台读取工具 (read_console)

功能描述

实现方案

5.7 脚本验证工具 (validate_script)

功能描述

实现方案

5.8 常用 IPC 消息参考 (Cocos Creator 2.4.x)

场景操作 (scene:)

资源操作 (assets:)

6. 测试策略

6.1 测试目标

6.2 测试方法

单元测试

集成测试

性能测试

回归测试

6.3 测试工具

7. 部署与维护

7.1 部署方案

本地部署

远程部署

7.2 维护计划

版本管理

错误处理

性能优化

文档维护

8. 风险评估

8.1 潜在风险

8.2 应对策略

9. 结论

21 KiB

Raw Blame History

5.1 编辑器管理工具 (`manage_editor`)

5.2 游戏对象查找工具 (`find_gameobjects`)

5.3 材质和纹理管理工具 (`manage_material`, `manage_texture`)

5.4 菜单项执行工具 (`execute_menu_item`)

5.5 代码编辑增强工具 (`apply_text_edits`)

5.6 控制台读取工具 (`read_console`)

5.7 脚本验证工具 (`validate_script`)

场景操作 (`scene:`)

资源操作 (`assets:`)