wangjunxiao/funplay-cocos-mcp

Fork 0

Files

T

winlifes c57cf140a8 Release v0.3.0

2026-05-20 18:52:25 -07:00

15 KiB

Raw Permalink Blame History

Funplay MCP for Cocos

嵌入 Cocos Creator 编辑器的 MCP Server

中文 | English

如果这个项目对你有帮助，欢迎顺手点一个 Star。它能帮助更多 Cocos 开发者发现项目，也能支持后续持续维护。

Funplay MCP for Cocos 是一个采用 MIT 协议的 Cocos Creator 扩展，它把 HTTP MCP Server 直接嵌入编辑器，让 Claude Code、Cursor、Codex、VS Code Copilot、Trae、Kiro 等 AI 助手可以直接检查和操作正在运行的 Cocos 项目。

这个项目延续 Funplay MCP for Unity 的产品方向：默认工具面保持聚焦，提供一键客户端配置，并围绕一个高灵活度主执行工具组织工作流。

在 Cocos 里，主工具是 execute_javascript：

context: "scene" 在当前 Cocos 场景/运行态上下文执行 JavaScript
context: "editor" 在 Cocos 编辑器/browser 上下文执行 JavaScript

“在当前场景里创建一个登录页 UI，包含账号/密码输入框和登录按钮。”

AI 助手可以调用 execute_javascript，在当前 Canvas 下生成 UI 层级，挂载 Cocos 组件，检查层级，并截图验证效果。

快速开始

如果你只想尽快连上，先做这三步：

把这个仓库安装为 Cocos Creator 扩展
打开 Funplay > MCP Server
使用内置的一键 MCP 客户端配置

1. 安装为 Cocos Creator 扩展

把仓库 clone 或复制到 Cocos 项目的扩展目录：

cd /path/to/your-cocos-project
mkdir -p extensions
git clone https://github.com/FunplayAI/funplay-cocos-mcp.git extensions/funplay-cocos-mcp

然后重启 Cocos Creator，或在编辑器里重新加载扩展。

你也可以把目录复制到 Cocos Creator 的全局用户扩展目录中。

2. 启动 MCP Server

打开编辑器菜单：

Funplay > MCP Server

服务默认运行在 http://127.0.0.1:8765/。

如果配置端口已被占用，扩展会自动回退到下一个可用本地端口，并在一键客户端配置时使用实际运行端口。

面板刻意保持精简：

启用或停用 MCP Server
修改服务端口
在 core / full / custom 工具暴露模式之间切换
检查当前安装版本是否落后于 GitHub 最新 Release
按工具分类或单个工具调整暴露范围
一键配置 AI 客户端
需要时再展开 Debug Output

3. 配置 AI 客户端

优先使用 Funplay > MCP Server 面板里的 MCP Client Config 区域。

选择目标客户端，点击 One-Click Configure，扩展会直接写入推荐的 MCP 配置项。

写入客户端的 MCP server 名称是：

funplay_cocos

如果你更想手动编辑配置文件，再参考下面这些示例。

Claude Code / Claude Desktop

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

Cursor

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

VS Code

{
  "servers": {
    "funplay_cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

Trae

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

Kiro

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

Codex

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

4. 验证连接

先在 AI 客户端里试几个安全请求：

“调用 get_project_info，总结当前 Cocos 项目。”
“读取 cocos://project/context，告诉我当前编辑器状态。”
“用 execute_javascript 的 context: \"scene\" 返回当前场景名。”
“用 execute_javascript 的 context: \"editor\" 返回项目路径。”

如果这些都正常返回，说明 MCP server、resources、prompts 和主执行工具已经连通。

5. 开始构建

可以在 AI 客户端里尝试：

在当前 Cocos 场景里创建一个登录页 UI，包含账号/密码输入框、登录按钮和游客登录按钮。优先使用 execute_javascript，创建后检查层级并截图验证。

开始前说明

这是一个 仅限 Editor 的扩展，用于自动化 Cocos Creator，不会给最终游戏包添加运行时依赖。
MCP Server 默认监听 http://127.0.0.1:8765/。
如果配置端口被占用，服务会自动回退到下一个可用端口，面板与一键客户端配置会使用实际运行端口。
默认 core profile 暴露 34 个高频工具；如果需要完整工具集，可在面板切到 full，暴露全部 89 个工具；也可以用 custom 按分类或工具名增删。
面板提供手动更新检查，会对比当前安装版本和 GitHub 最新 Release。
Streamable HTTP 响应已补齐 MCP 传输层要求，包括 Accept、MCP-Protocol-Version、JSON-RPC notification/response，以及可选 Mcp-Session-Id session。
工具列表会包含 MCP outputSchema 和 annotations；结构化工具结果统一使用包含 ok、tool、callId、summary、data、refs 的标准 envelope。
所有已暴露的 MCP 工具都会直接执行，Cocos 扩展里没有额外 approval 开关。
文件工具和 cocos://asset/path/... 资源默认只能访问当前 Cocos 项目根目录内的路径。
推荐工作流是优先使用 execute_javascript，再配合截图、诊断、资产、检查类工具。
如果在面板里修改端口或工具暴露模式，扩展会自动保存配置，并在需要时重启服务。

为什么做这个项目

execute_javascript 主工具优先 — 一个高灵活度 JavaScript 工具就能编排场景/运行态和编辑器自动化，避免 AI 客户端被大量细碎工具干扰
嵌入式 Cocos 扩展 — Cocos 侧不需要单独 Python 守护进程或外部 bridge
一键客户端配置 — 在 Cocos Creator 内直接配置 Claude Code、Cursor、VS Code、Trae、Kiro、Codex
内建项目上下文 — 直接暴露项目、场景、选择、脚本诊断、日志和交互历史资源
默认聚焦，必要时全量 — core 降低工具列表噪音，需要时切到 full 暴露全部工具；custom 可按分类或工具名调整
可视化验证 — 截图和输入模拟让 AI 能验证 UI 与玩法改动

核心特性

89 个内置工具 — 覆盖场景层级、编辑器状态、选择工作流、Prefab、资产、项目指令、UI 创建、组件、文件、日志、脚本诊断、截图、运行态控制和输入模拟
统一主工具 — execute_javascript 同时支持 scene 和 editor 两种上下文
Resources 与 Prompts — 实时项目/日志资源，以及脚本修复、场景验证、可玩原型等可复用工作流
Cocos 图形面板 — Funplay > MCP Server 提供服务管理、更新检查、工具暴露和 MCP 客户端配置
截图与输入支持 — 支持编辑器/场景/Game/Preview 截图，以及 Electron 级鼠标键盘事件
厂商无关 — 兼容任意支持 HTTP JSON-RPC MCP 的 AI 客户端

与 Funplay MCP for Unity 的关系

Funplay MCP for Cocos 延续 Funplay MCP for Unity 的设计原则，并针对 Cocos Creator 的 JavaScript/TypeScript 编辑器环境做了适配。

维度	Funplay MCP for Cocos	Funplay MCP for Unity
编辑器集成	Cocos Creator 扩展	Unity Editor 包
内置服务	内嵌 HTTP MCP Server	内嵌 HTTP MCP Server
主执行工具	`execute_javascript`	`execute_code`
主语言	场景/编辑器上下文中的 JavaScript	Unity 编辑器/运行态中的 C#
默认工具集	`core`，34 个工具	聚焦版 `core` 工具集
完整工具集	89 个工具，并支持 `custom` 暴露	79 个工具
客户端配置	一键配置面板	一键配置窗口

MCP 能力结构

当前包提供四层能力：

Tools — core 下 34 个工具，full 下 89 个工具，并支持 custom include/exclude 规则
Primary execution — execute_javascript 用于场景/运行态和编辑器/browser 自动化
Prompts — fix_script_errors、create_playable_prototype、scene_validation、auto_wire_scene
Resources — 项目上下文、场景摘要、当前选择、脚本诊断、资产选择、日志和 MCP 交互历史

当前默认 core 工具集刻意保持精简，只包含：execute_javascript、execute_scene_script、execute_editor_script、get_editor_state、get_tool_catalog、check_for_updates、get_selection、list_project_instructions、read_project_instruction、set_selection、get_project_info、get_scene_info、get_hierarchy、list_scenes、open_scene、inspect_prefab、validate_prefab_references、inspect_prefab_instance、list_assets、inspect_asset、open_asset、select_asset、run_script_diagnostics、get_recent_logs、search_project_logs、clear_logs、validate_scene、get_performance_snapshot、get_script_diagnostic_context、get_runtime_state、capture_editor_screenshot、capture_scene_screenshot、capture_preview_screenshot、list_editor_windows。

内置 Resources

Resource	说明
`cocos://project/context`	完整项目与编辑器上下文
`cocos://project/summary`	项目摘要
`cocos://scene/active`	当前场景快照
`cocos://scene/current`	当前场景别名
`cocos://selection/current`	当前编辑器选择
`cocos://selection/asset`	当前选中资产
`cocos://errors/scripts`	脚本诊断信息
`cocos://logs/editor`	最近 MCP 运行日志和工具交互
`cocos://logs/project`	常见项目日志文件的尾部内容
`cocos://mcp/interactions`	最近 MCP 交互历史

内置工具

Funplay MCP for Cocos 当前在 full profile 下提供 89 个工具函数：

分类	工具
脚本执行	`execute_javascript`, `execute_scene_script`, `execute_editor_script`
编辑器状态	`get_editor_state`, `get_tool_catalog`, `check_for_updates`, `get_selection`, `set_selection`, `get_editor_selection`
项目指令	`list_project_instructions`, `read_project_instruction`, `write_project_instruction`, `create_project_skill`
项目与场景	`get_project_info`, `get_scene_info`, `get_hierarchy`, `find_nodes`, `inspect_node`, `list_scenes`, `open_scene`, `run_scene_asset`
节点编辑	`create_node`, `delete_node`, `set_node_transform`
资产与 Prefab	`list_assets`, `inspect_asset`, `open_asset`, `select_asset`, `delete_asset`, `list_prefabs`, `inspect_prefab`, `validate_prefab_references`, `duplicate_prefab`, `edit_prefab_json`, `create_prefab_instance`, `inspect_prefab_instance`, `apply_prefab_instance`, `revert_prefab_instance`, `instantiate_prefab`
组件	`list_components`, `inspect_component`, `add_component`, `remove_component`, `set_component_property`, `reset_component_property`
UI	`create_canvas`, `create_label`, `create_button`, `create_sprite`
相机	`list_cameras`, `create_camera`, `set_camera_properties`
动画	`list_animations`, `add_animation_clip`, `play_animation`, `stop_animation`
文件	`read_file`, `get_file_snippet`, `write_file`, `replace_in_file`, `search_files`, `list_directory`, `exists`, `refresh_assets`
诊断与日志	`run_script_diagnostics`, `get_script_diagnostic_context`, `get_recent_logs`, `search_project_logs`, `clear_logs`, `validate_scene`, `get_performance_snapshot`
运行态	`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`
截图与窗口	`capture_desktop_screenshot`, `capture_editor_screenshot`, `capture_scene_screenshot`, `capture_game_screenshot`, `capture_preview_screenshot`, `list_editor_windows`

主工具示例

Scene 上下文

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

Editor 上下文

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

Editor 上下文脚本可以访问 Editor、fs、path、os、require、context、args，以及 helpers.getStatus()、helpers.listTools()、helpers.readResource(uri)、helpers.callTool(name, args)、helpers.configureClient(targetId) 等辅助函数。

可选配置

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

{
  "host": "127.0.0.1",
  "port": 8765,
  "toolProfile": "core",
  "enabledToolCategories": [],
  "disabledToolCategories": [],
  "enabledTools": [],
  "disabledTools": [],
  "enableSessions": false,
  "autostart": true,
  "maxInteractionLogEntries": 50
}

也支持环境变量：

COCOS_MCP_HOST
COCOS_MCP_PORT
COCOS_MCP_PROFILE

toolProfile: "custom" 会从 core 集合开始，再加入 enabledToolCategories / enabledTools，并移除 disabledToolCategories / disabledTools。enableSessions 默认关闭，因为常规编辑器自动化不需要跨请求客户端状态。

架构

Cocos Creator Extension
    ├─ browser.js
    │   ├─ Embedded HTTP MCP Server
    │   ├─ Tool Registry
    │   ├─ Resource Provider
    │   ├─ Prompt Provider
    │   └─ One-Click Client Configuration
    ├─ scene.js
    │   └─ Scene/runtime execution bridge
    ├─ panel/index.js
    │   └─ Minimal MCP Server panel
    └─ lib/
        ├─ assets, diagnostics, screenshots, input
        └─ server, resources, prompts, tool registry

服务使用 MCP 风格的 HTTP JSON-RPC 2.0，支持 tools、resources、resource templates、prompts 和 health check。

开发

发布改动前可以跑语法检查：

npm run check

协议

MIT License。详见 LICENSE。

15 KiB Raw Permalink Blame History Unescape Escape