Funplay Cocos MCP

Funplay MCP for Cocos

适用于 Cocos Creator 编辑器的内嵌式 MCP 服务

中文 | English

如果这个项目对你的 Cocos 工作流有所帮助，请考虑点个 Star。这能让更多开发者发现该项目，并支持项目持续开发。

Funplay MCP for Cocos 是一个采用 MIT 许可证的 Cocos Creator 扩展，可将 HTTP MCP 服务直接嵌入编辑器。它让 Claude Code、Cursor、Codex、VS Code Copilot、Trae、Kiro、Qoder、Kimi Code、OpenCode、CodeBuddy 和 DeepSeek Harness (DSH) 等 AI 助手能够检查并操作正在运行的 Cocos 项目。

该软件包遵循 Funplay MCP for Unity 的相同产品方向：保持默认工具集精简，提供一键式客户端配置窗口，并将一个灵活度极高的执行工具作为主要工作流。

对于 Cocos，主要工具是 execute_javascript：

• context: "scene" 会在当前 Cocos 场景/运行时上下文中执行 JavaScript
• context: "editor" 会在 Cocos 编辑器/浏览器上下文中执行 JavaScript

“创建一个登录页面 UI，包含账号/密码输入框和一个主登录按钮。”

AI 助手可以调用 execute_javascript，在当前 Canvas 下构建 UI 层级、附加 Cocos 组件、检查结果，并截取屏幕截图以供验证。

快速开始

如果你只想快速连接，请完成以下三项操作：

• 将此仓库安装为 Cocos Creator 扩展
• 打开 Funplay > MCP Server
• 使用内置的一键式 MCP 客户端配置

1. 安装为 Cocos Creator 扩展

推荐的安装方式：使用官方 Cocos Store 页面，将扩展安装到目标 Cocos Creator 项目中。

对于本地开发或尚未发布的版本，请将此仓库克隆或复制到 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，或在编辑器中重新加载扩展。

若不使用 Git 安装，请从 GitHub Releases 页面下载 Funplay.CocosMcp.v<version>.zip，解压后将解压出的 funplay-cocos-mcp 文件夹移入项目的 extensions/ 目录。

为所有项目安装（推荐）

先在任意项目中安装并打开扩展。然后打开 Funplay > MCP Settings，并在 All Projects 部分中点击 Install for All Projects。扩展会下载最新的 GitHub Release，验证 SHA256SUMS.txt，并将其安装到当前 Cocos Creator 版本的托管全局扩展目录中：

• macOS / Linux：~/.CocosCreator/builtin-extensions/<Creator version>/funplay-cocos-mcp
• Windows：%USERPROFILE%\.CocosCreator\builtin-extensions\<Creator version>\funplay-cocos-mcp

Cocos Creator 会立即扫描并注册已安装的副本。之后，使用该 Creator 版本打开或创建的项目会自动加载此扩展，MCP 服务也会保持默认的自动启动行为。如果已运行的项目优先使用项目级副本，请重新打开该项目。不会将扩展文件复制到各个项目的 extensions/ 目录中。

全局扩展按 Cocos Creator 版本隔离。如果使用多个 Creator 版本，请在每个版本中分别运行一次 Install for All Projects。

安装程序不会删除当前项目中的副本，以保护开发工作区。如果两个副本都存在，MCP Settings 会显示重复安装警告。确认全局副本正常运行后，请移除或禁用项目级副本，以避免扩展冲突。

2. 启动 MCP 服务

打开编辑器菜单：

Funplay > MCP Server

新项目会获得一个根据项目生成的稳定端口，范围为 20000–29999。已保存的配置会保留其固定端口（包括 8765）。请使用 MCP Server 中显示的准确 URL；如果当前正在使用临时备用端口，请在配置客户端之前点击 Pin Current Port 或 Use Per-Project Port。

如果配置的端口已被占用，扩展会先检查现有监听器是否属于同一个 Cocos 项目。同一项目的监听器会安全地复用；无关的监听器则会触发自动回退，切换到下一个可用的本地端口。

面板有意保持精简：

• 启用或禁用 MCP 服务
• 打开专注于工具暴露、MCP 设置和项目技能的窗口
• 自动将已安装版本与 GitHub 上的最新版本进行检查
• 从面板打开发布页面，或安装经过验证的发布包
• 只需安装一次到 Cocos Creator 全局扩展目录，现有和新建项目即可自动使用
• 一键配置 AI 客户端并预览所选客户端配置
• 将高级工具配置文件编辑、传输设置和安装管理留在主服务窗口之外
• 自动跟随 Cocos Creator 界面语言，或在 MCP Settings 中为每个项目选择中文/英文
• 在 Settings 中切换 Print MCP logs，静默 MCP 控制台消息，同时保留 Recent Activity 和内部诊断信息

所有管理页面均采用一致的标题、对齐的控件和轻量级分区。工具暴露页面按类别分组显示各个工具的开关；项目技能页面突出显示可用操作，并折叠文件路径和备份信息。Recent Activity 会将每次调用的摘要和实际结果显示为可展开的对象/数组树；对于脚本，执行日志和返回值会分别显示在不同分区中。输出分区和独立的日志查看面板已移除。简短的操作提示会保留成功/失败反馈，同时 MCP 工具和资源仍可获取诊断日志。

脚本工具会捕获每次调用的 console.log/info/warn/error/debug 输出，包括发生故障前的日志，不受 Print MCP logs 影响。捕获过程在并发和嵌套调用之间相互隔离，并在脚本执行完成后停止；不会收集全局/项目日志以及单独 require 的模块所产生的日志。请使用注入的 console（在 run/模块导出中也可通过 env.console 使用）。MCP 响应会保留现有的 data 结构，并添加可选的 execution 元数据，其中包含上下文、耗时、有界/脱敏后的日志以及省略条目数。Recent Activity 会保留结果层级和标量值；大型结果以及文件/脚本正文仍会受到限制或被省略，并显示截断提示。

扩展菜单和原生面板标题会跟随 Cocos Creator 界面语言。面板控件、工具说明、状态消息、提示词和空状态均支持英文和中文；打开 Funplay > MCP Settings，即可跟随 Creator 的语言，或设置项目专属的内容语言覆盖项。MCP 工具 ID 和架构保持英文，以确保客户端集成稳定。

3. 配置 AI 客户端

请先使用 Funplay > MCP Server 面板内置的 MCP Client Config 分区。

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

写入客户端的 MCP 服务名称为：

cocos-<project>-<hash>

如果你更愿意手动编辑配置文件，请将以下示例用作备用参考。请将示例中的旧版名称 funplay_cocos 和端口 8765 替换为面板中显示的名称和 URL。一键配置 Claude Code 时，会使用 ~/.claude.json 中的项目 Git 根目录作用域，而非下方的全局示例。请参阅项目设置和迁移。

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

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

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

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

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

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

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

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

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

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

dsh web --patch '/absolute/path/to/cocos-project/.dsh/funplay-cocos-mcp.patch.json'

如果你的 MCP 客户端更倾向于使用本地 stdio 命令，请先启动 Cocos 编辑器服务，再安装 npm 包装器：

npm install -g funplay-cocos-mcp

MCP 客户端配置示例：

{
  "mcpServers": {
    "funplay_cocos": {
      "command": "funplay-cocos-mcp",
      "env": {
        "FUNPLAY_COCOS_MCP_URL": "http://127.0.0.1:8765/"
      }
    }
  }
}

该包装器会将 stdio MCP 流量桥接到内嵌的 Cocos HTTP 端点。你也可以通过 npx funplay-cocos-mcp --url http://127.0.0.1:8765/ 运行它。

stdio 传输支持标准的、以换行符分隔的 UTF-8 JSON-RPC 消息（NDJSON）。包装器也接受现有的 Content-Length 分帧格式，并使用与传入消息相同的分帧格式写入响应。

4. 验证连接

打开你的 AI 客户端，先尝试一些安全的请求：

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

如果这些请求都能正常工作，说明 MCP 服务、资源、提示词和主要执行工具已正确连接。

如需调试本地传输，面板可以复制这些命令，你也可以直接运行：

curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/tools

5. 开始构建

尝试在 AI 客户端中输入更高级的提示词：

在当前 Cocos 场景中创建一个登录页面 UI，包含账号／密码输入框、登录按钮和游客登录按钮。先使用 execute_javascript 检查层级结构，然后截取屏幕截图。

开始之前

• 此扩展仅适用于编辑器。它旨在自动化操作 Cocos Creator，而不是为最终游戏构建添加运行时依赖项。
• 新项目使用根据项目生成的端口。MCP 服务面板会显示准确的端点，并支持固定端口。
• 如果配置的端口正被占用，服务会自动切换到下一个可用端口，面板和客户端配置会使用实际运行的端口。
• GET /health 和 GET /tools 是只读调试端点，可在 MCP 客户端之外快速进行本地检查。
• 默认的 core 配置集提供 39 个高价值工具。切换到 full 可使用全部 106 个工具，也可以使用 custom 纳入或排除工具类别和单个工具。
• 面板会自动检查 GitHub 版本发布，也支持手动检查。
• 一键更新会下载 GitHub Release zip，验证 SHA256SUMS.txt，备份当前扩展，替换软件包文件，并在 Cocos 软件包 API 支持时重新加载扩展。如果无法重新加载，请在安装后重启 Cocos Creator。Git 工作树和符号链接安装有意保留为手动执行 git pull 或替换软件包。
• 为所有项目安装使用相同的版本发布和 SHA256 验证流程，目标是当前 Creator 版本的受管理全局目录，然后请求 Creator 扫描并注册软件包。它会保留活动项目中的副本，而不会在设置窗口打开时切换其下的软件包；如果当前没有活动的项目副本，全局副本会立即启用，否则会在下次打开项目时启用。
• 项目技能可管理内置的 funplay-cocos-mcp-workflow 和 funplay-cocos-ui-composition 技能，以及适用于 Codex、Claude Code、Cursor、Qoder、Kimi Code、OpenCode、CodeBuddy 和 DSH 的自定义技能。内置的 v3 模板使用精简入口文件和按需加载的参考文件；版本检查、差异比较、备份和恢复都包含这些受管理的参考文件。现有的用户自有参考文件会受到保护。旧版 Codex 内置技能可迁移到 .agents/skills，而不会删除其原始文件。
• Streamable HTTP 响应遵循 MCP 传输要求，涵盖 Accept、MCP-Protocol-Version、JSON-RPC 通知和响应，以及可选的 Mcp-Session-Id 会话。
• 工具列表包含 MCP outputSchema 和 annotations；结构化工具结果使用包含 ok、tool、callId、summary、data 和后续 refs 的标准信封。
• 默认启用 execute_javascript 安全检查。它会阻止明显有风险的文件系统和 Shell 模式，例如删除或截断调用、原始可写流、路径遍历、用户或系统绝对路径，以及 child_process。这只是安全防护措施，并非完整沙箱；如果已评估风险，可在调用中明确传入 safety_checks: false。
• 所有已公开的 MCP 工具都会直接执行。Cocos 扩展中没有额外的审批开关。
• 文件工具和 cocos://asset/path/... 资源仅限访问活动 Cocos 项目根目录。
• 推荐的工作流是先使用 execute_javascript，再使用专门的辅助工具进行截图、诊断、资源和检查。
• 如果在面板中更改服务端口或工具公开范围，扩展会保存配置，并在需要时重启服务。

为什么打造此项目

• 以 execute_javascript 为首选 — 一个高灵活性的 JavaScript 工具即可编排场景／运行时工作和编辑器端自动化，无需让 AI 客户端承受过多细分工具调用
• 内嵌 Cocos 扩展 — Cocos 侧插件无需单独的 Python 守护进程或外部桥接进程
• 一键配置客户端 — 配置 Claude Code、Cursor、VS Code、Trae、Kiro、Qoder、Kimi Code、Codex、OpenCode 和 CodeBuddy（IDE 4.0+），或通过显式的 --patch 启动命令生成 DSH 覆盖层
• 内置项目上下文 — 提供实时项目、场景、选择内容、脚本诊断、日志和交互历史资源
• 默认精简，需要时全面开放 — core 可减少工具列表中的干扰；full 会开放所有可用工具；custom 配合已保存的配置文件，可按类别或工具调整并还原工具开放范围
• 可视化验证 — 场景／编辑器／预览截图和输入模拟可帮助 AI 验证 UI 与游戏玩法的改动

亮点

• 内置 106 个工具 — 场景层级、编辑器状态、选择工作流、预制体、资源、资源依赖、项目说明、UI 创建、组件、文件、日志、脚本诊断、截图、运行时控制、构建／预览辅助、编辑器偏好设置、事件绑定和输入模拟
• 主要统一工具 — execute_javascript 同时支持 scene 和 editor 上下文
• 资源与提示词 — 实时项目／日志资源，以及脚本修复、场景验证和可玩原型创建等可复用工作流
• Cocos 面板 UI — 精简的 Funplay > MCP Server 控制面板，以及用于大型工作流的专用 Tool Exposure、MCP Settings 和 Project Skills 窗口
• 截图与输入支持 — 捕获编辑器／场景／游戏／预览截图，并发送 Electron 级别的鼠标／键盘事件；鼠标点击／拖动可使用精确的 PNG 像素坐标，并配合新鲜截图的 captureId
• 不依赖特定厂商 — 适用于任何支持通过 HTTP JSON-RPC 使用 MCP 的 AI 客户端

与 Funplay MCP for Unity 的关系

Funplay MCP for Cocos 遵循与 Funplay MCP for Unity 相同的设计原则，并针对 Cocos Creator 的 JavaScript／TypeScript 编辑器环境进行了适配。

MCP 能力

当前软件包公开了四层能力：

• 工具 — core 中有 39 个工具，full 中有 106 个工具，另外还支持 custom 包含／排除规则和已保存的工具配置
• 主要执行能力 — execute_javascript，用于场景／运行时以及编辑器／浏览器自动化
• 提示词 — fix_script_errors、create_playable_prototype、scene_validation 和 auto_wire_scene，以及从 mcp-prompts/*.md 加载的参数化项目工作流。请参阅项目隔离、Skills 和工作流设置。
• 资源 — 项目上下文、场景摘要、当前选择、脚本诊断、资源选择、日志和 MCP 交互历史

生成的工具参考文档包含类别、配置和读／修改提示，请参阅 docs/TOOLS.md。

默认的 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_build_status、get_preview_mode、create_scene、get_scene_info、get_hierarchy、list_scenes、open_scene、inspect_prefab、validate_prefab_references、inspect_prefab_instance、list_assets、inspect_asset、inspect_asset_dependencies、validate_asset_dependencies、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。

预览模式

Creator 3.8.x 预览自动化使用与内置预览工具栏相同的模式和编辑器 API：

使用 get_preview_mode 检查当前活动模式，使用 set_preview_mode 切换模式，并使用 run_project_preview 启动预览。run_project_preview 仍接受 platform 作为已弃用的 mode 别名。

Game View 通过原生预览工具栏启动，因此手动暂停／恢复按钮仍可使用。重复启动时，已有预览会继续运行（包括其暂停状态）。pause_runtime 和 resume_runtime 控制同一个 Game View 预览，且具有幂等性；它们要求 Game View 正在运行，不控制浏览器／模拟器预览或编辑场景导演。切换离开 Game View 时，会先通过工具栏停止预览；如果操作被拒绝，则会报告错误，而不会声称操作成功。

请在 full 或自定义工具配置中启用这些控制工具。编写脚本时，优先使用这些工具，而不要直接调用 scene.editor-preview-set-play，因为直接调用会绕过工具栏同步。

get_runtime_state（validate_scene 也会使用）会报告 scope: "gameView"、实际的 running／paused 值、busy 和 toolbarSynchronized。它不再将编辑场景的帧数／时间缩放计数器作为预览状态呈现；这些数据仍保留在 get_performance_snapshot.runtime 中，其 scope 为 "editScene"。set_time_scale 仍只影响编辑场景。预览控制要求 Creator 主窗口工具栏兼容且就绪；如果工具栏不可用，会明确报告错误。

浏览器预览结果会区分同主机自动化与局域网访问：

内置资源

内置工具

Funplay MCP for Cocos 在 full 配置中目前提供 106 个工具函数：

主要工具示例

场景上下文

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

编辑器上下文

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

编辑器上下文脚本会接收 Editor、fs、path、os、require、context、args，以及 helpers.getStatus()、helpers.listTools()、helpers.readResource(uri)、helpers.callTool(name, args) 和 helpers.configureClient(targetId) 等辅助函数。

可选配置

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

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

也支持使用环境变量：

• COCOS_MCP_HOST
• COCOS_MCP_PORT
• COCOS_MCP_PROFILE

toolProfile: "custom" 会从 core 集合开始，然后添加 enabledToolCategories / enabledTools，并移除 disabledToolCategories / disabledTools。面板可以将这些暴露设置保存为命名的 savedToolProfiles，以便快速恢复或分享。默认情况下，enableSessions 处于关闭状态，因为此服务在常规编辑器自动化中不需要跨请求的客户端状态。

enableConsoleLogging 默认为 true。在 MCP Settings > Console Logs > Print MCP logs 中将其关闭，即可阻止扩展和 HTTP 服务向 Cocos 控制台输出 MCP 信息、警告和错误。此设置会立即生效，按项目保存，且不会重启 MCP、清除历史记录、屏蔽项目脚本日志或更改 stdio 协议输出。

架构

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 dashboard
    ├─ panel/tool-exposure.js, panel/settings.js, panel/project-skills.js
    │   └─ Focused maintenance windows
    └─ lib/
        ├─ assets, diagnostics, screenshots, input
        ├─ tool-profiles, javascript-safety
        ├─ tools/
        │   ├─ files
        │   ├─ assets-advanced
        │   ├─ cocos-project
        │   └─ scene-events
        └─ server, resources, prompts, tool registry

此服务使用 MCP 风格的 HTTP JSON-RPC 2.0，并支持工具、资源、资源模板、提示词、健康检查以及只读的 /tools 调试端点。

开发

发布更改前运行检查：

npm run check
npm test
npm run docs:check
npm run release:check
npm run pack:dry-run

更改 lib/tool-registry.js 后，重新生成工具参考文档：

npm run docs:generate

生成可用于 GitHub Release 的扩展包：

npm run release:package

软件包会写入 releases/<version>/，其中包含 zip、清单、生成的发行说明、校验和文件以及发行版 README。请上传全部五个文件，以便验证公开校验和。完整流程请参阅 RELEASE_WORKFLOW.md 和 RELEASE_CHECKLIST.md。

发布前验证 MCP Registry 元数据：

npm run registry:validate

许可证

MIT 许可证。请参阅 LICENSE。