funplay-cocos-mcp/README.md

Funplay Cocos MCP

一个嵌入在 Cocos Creator 3.x 扩展里的 MCP Server，对齐了你现有 unity-mcp 的核心思路：

• 编辑器内嵌 HTTP MCP 服务
• execute_javascript 作为统一主工具
• tools / resources / prompts 三层能力
• 场景树、节点、文件系统、项目上下文的统一访问

当前实现更偏向 Unity MCP 的 core 能力集，而不是一次性把全部 Unity 工具逐个照搬。

已实现能力

• MCP 协议：
  • initialize
  • tools/list
  • tools/call
  • resources/list
  • resources/read
  • resources/templates/list
  • prompts/list
  • prompts/get
• 核心工具：
  • execute_javascript
  • execute_scene_script
  • execute_editor_script
  • get_scene_info
  • get_hierarchy
  • find_nodes
  • inspect_node
  • list_components
  • inspect_component
  • list_cameras
  • list_animations
  • play_animation
  • stop_animation
  • get_project_info
  • list_scenes
  • open_scene
  • list_prefabs
  • list_assets
  • inspect_asset
  • open_asset
  • select_asset
  • get_editor_selection
  • read_file
  • get_file_snippet
  • write_file
  • replace_in_file
  • search_files
  • list_directory
  • exists
  • refresh_assets
  • run_script_diagnostics
  • get_script_diagnostic_context
  • capture_desktop_screenshot
  • capture_editor_screenshot
  • capture_scene_screenshot
  • capture_game_screenshot
  • capture_preview_screenshot
  • list_editor_windows
  • get_runtime_state
  • pause_runtime
  • resume_runtime
  • set_time_scale
  • emit_node_event
  • simulate_button_click
  • invoke_component_method
  • simulate_mouse_click
  • simulate_mouse_drag
  • simulate_key_press
  • simulate_key_combo
  • simulate_preview_input
• full 模式附加工具：
  • create_node
  • delete_node
  • set_node_transform
  • add_component
  • remove_component
  • set_component_property
  • reset_component_property
  • create_canvas
  • create_label
  • create_button
  • create_sprite
  • create_camera
  • set_camera_properties
  • add_animation_clip
  • instantiate_prefab
  • run_scene_asset
  • delete_asset
• 资源：
  • cocos://project/context
  • cocos://project/summary
  • cocos://scene/active
  • cocos://scene/current
  • cocos://selection/current
  • cocos://selection/asset
  • cocos://errors/scripts
  • cocos://mcp/interactions

安装方式

把当前目录作为 Cocos Creator 扩展放到：

• 项目级：<你的项目>/extensions/funplay-cocos-mcp
• 全局级：<Cocos Creator 用户扩展目录>/funplay-cocos-mcp

然后重启 Cocos Creator，扩展会默认自动启动 MCP 服务。

默认地址：

• http://127.0.0.1:8765/

图形化面板

扩展启用后，可以在 Cocos Creator 顶部菜单打开：

• Funplay -> MCP Server

面板里可以直接完成：

• 启动 / 停止 / 重启 MCP Server
• 查看当前 URL、端口、Profile、项目名
• 保存 host / port / toolProfile / autostart 配置
• 一键写入 MCP Client 配置
• 复制 Codex TOML 或 JSON MCP Client 配置
• 查看工具列表、资源列表、最近交互日志
• 直接从 Cocos 里调用工具并填写 JSON 参数
• Quick Actions 优先给出 execute_javascript
• 一键测试 execute_javascript、get_project_info、get_scene_info、get_hierarchy、截图、诊断等常用工具

一键配置当前支持：

• Claude Code / Claude Desktop：~/.claude.json
• Cursor：~/.cursor/mcp.json
• VS Code：~/.vscode/mcp.json
• Trae：~/.trae/mcp.json
• Kiro：~/.kiro/settings/mcp.json
• Codex：~/.codex/config.toml

面板会使用当前端口写入 funplay_cocos MCP server。写入后请重启对应客户端。

可选配置

在 Cocos 项目根目录放一个 funplay-cocos-mcp.config.json：

{
  "host": "127.0.0.1",
  "port": 8765,
  "toolProfile": "core",
  "autostart": true,
  "maxInteractionLogEntries": 50
}

也支持环境变量：

• COCOS_MCP_HOST
• COCOS_MCP_PORT
• COCOS_MCP_PROFILE

MCP Client 示例

Codex

[mcp_servers.funplay_cocos]
url = "http://127.0.0.1:8765/"

Claude / Cursor

{
  "mcpServers": {
    "funplay_cocos": {
      "url": "http://127.0.0.1:8765/"
    }
  }
}

推荐首测

先在 MCP Client 里调用：

1. get_project_info
2. get_scene_info
3. get_hierarchy
4. resources/read with cocos://project/context
5. execute_javascript（context: "scene"）
6. execute_javascript（context: "editor"）
7. run_script_diagnostics
8. capture_desktop_screenshot
9. list_components
10. get_script_diagnostic_context
11. get_runtime_state
12. capture_editor_screenshot
13. list_editor_windows
14. capture_scene_screenshot
15. simulate_mouse_click

其中 execute_javascript 是统一主工具，execute_scene_script / execute_editor_script 主要保留给兼容调用。

execute_javascript 示例，场景上下文：

{
  "context": "scene",
  "code": "return { sceneName: scene.name, rootCount: scene.children.length };"
}

execute_javascript 示例，编辑器上下文：

{
  "context": "editor",
  "code": "return { projectPath: context.projectPath, toolCount: helpers.listTools().length };"
}

execute_scene_script.code 兼容示例：

return {
  sceneName: scene.name,
  rootChildren: scene.children.map((node) => node.name),
};

和 Unity MCP 的对应关系

• Unity execute_code → Cocos execute_javascript
• Unity execute_code 的场景/编辑器兼容拆分入口 → execute_scene_script / execute_editor_script
• Unity get_scene_info → Cocos get_scene_info
• Unity get_hierarchy → Cocos get_hierarchy
• Unity read_file/write_file/search_files → 同名 Cocos 文件工具
• Unity resources/prompts → 同结构的 Cocos 资源与提示词
• Unity core/full → Cocos toolProfile=core|full

当前边界

这版已经进入第二阶段，补上了：

• 资产查询 / 打开 / 删除 / 选中
• TypeScript 脚本诊断
• 本机桌面截图回传 MCP image

现在第三段也补上了：

• 组件增删查改
• Scene / Prefab 资产工具
• 脚本修复辅助链路：get_script_diagnostic_context + replace_in_file

第四段继续补上了：

• UI 专用工具：Canvas / Label / Button / Sprite 创建
• Camera 专用工具：列出、创建、属性设置
• Animation 专用工具：列出、添加 Clip、播放、停止
• 运行态控制：暂停、恢复、时间缩放、状态查询
• 输入/交互模拟：按钮点击、节点事件、组件方法调用
• 截图增强：桌面截图、Editor 窗口截图、场景截图别名

这次把之前两块缺口也补了：

• capture_scene_screenshot 现在优先按 Editor 内部面板区域裁剪，不再只是整窗截图别名
• 新增 capture_game_screenshot / capture_preview_screenshot
• 新增 list_editor_windows 方便先看 Cocos/Electron 当前有哪些窗口
• 新增基于 Electron webContents.sendInputEvent 的底层输入注入：
  • simulate_mouse_click
  • simulate_mouse_drag
  • simulate_key_press
  • simulate_key_combo
  • simulate_preview_input

暂时还没有直接补齐 Unity MCP 里的这些能力：

• 对 Scene/Game 面板做“语义级”识别仍然是 best-effort，依赖当前 Cocos 面板 DOM 结构
• Preview/Simulator 底层输入已经支持，但不同窗口标题和焦点状态可能需要先用 list_editor_windows 确认目标
• 动画曲线/状态机深度编辑

如果你要，我下一步可以继续补下一阶段，专门给你做：

1. SceneView/GameView 精确截图裁剪
2. Preview/Simulator 键鼠事件注入
3. 动画曲线和状态机编辑
4. 更像 unity-mcp 的完整工具分层