# Reported issues for Funplay Cocos MCP

Pod holds 17 of 17 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Funplay Cocos MCP](/mcp/funplay-cocos-mcp).

## Most discussed

### create_prefab_from_node 生成的 prefab 无法在编辑器打开：缺少 cc.PrefabInfo，报 Cannot read properties of null (reading 'instance')

## 环境
- Cocos Creator 3.8.8
- funplay-cocos-mcp 0.4.7
- 平台：macOS

## 现象
用 `create_prefab_from_node` 创建的 prefab 资源能正常生成，但在编辑器中双击打开时失败，报错：
[Scene] open prefab failed <uuid> TypeError: Cannot read properties of null (reading 'instance')
at PrefabSceneProxy._loadPrefabById
at PrefabSceneProxy.open
at PrefabSceneFacade.openScene
at SceneFacadeManager.openScene

## 复现步骤
1. 打开任意场景，建一个带 UI 组件的节点（如 UITransform + 脚本组件）。
2. 调用 MCP `create_prefab_from_node`，target 指向 `assets/xxx.prefab`。
3. 在资源管理器中双击该 pref

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/17) · 2026-08-12 · closed · external user · 2 comments

### Phase 3: Multi-agent scheduler locks and deadlock prevention

Parent: #7
Depends on Phase 2 child issue.

## Objective
Implement agent sessions, tool policy metadata, request contexts, scheduler queues, resource locks, atomic acquisition/order, lease/watchdog, timeout, cancellation, fairness, and structured concurrency errors.

## Ownership
Current workspace, sequential writer. Treat arbitrary Editor scripts as exclusive. Preserve tool schemas and keep tool execution in the extension. Add deterministic concurrency/deadlock tests.

## Verify
`npm run check`

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/14) · 2026-07-31 · closed · external user · 1 comment

### Phase 5: Final integration review and acceptance verification

Parent: #7
Depends on Phases 0-4 child issues.

## Objective
Review and integrate the complete implementation against every requirement in `docs/COCOS_CLI_GATEWAY_PLAN.md`, resolve regressions, update docs, and run the full verification suite.

## Ownership
Current workspace, sequential integrator. Inspect all diffs and tests. Do not claim Cocos Editor E2E unless the runtime is actually available; clearly record any external runtime blocker.

## Verify
`npm run check`, `npm test`, package/dry-ru

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/13) · 2026-07-31 · closed · external user · 1 comment

### Phase 3: Multi-agent scheduler locks and deadlock prevention

Parent: #7
Depends on Phase 2 child issue.

## Objective
Implement agent sessions, tool policy metadata, request contexts, scheduler queues, resource locks, atomic acquisition/order, lease/watchdog, timeout, cancellation, fairness, and structured concurrency errors.

## Ownership
Current workspace, sequential writer. Treat arbitrary Editor scripts as exclusive. Preserve tool schemas and keep tool execution in the extension. Add deterministic concurrency/deadlock tests.

## Verify
`npm run check`

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/11) · 2026-07-31 · closed · external user · 1 comment

### Phase 1: Central Gateway MCP front door and client-only CLI

Parent: #7
Depends on Phase 0 child issue.

## Objective
Implement the central MCP Gateway front door and `cocos-cli mcp` forwarding client. Agent requests must reach the Gateway, then an extension control channel; `cocos-cli` must not expose or execute Gateway start/stop/ensure.

## Ownership
Current workspace, sequential writer. Reuse Phase 0 interfaces and existing MCP/tool registry where safe. Add unit/protocol tests and structured unavailable/error responses.

## Verify
`npm run check`, `np

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/9) · 2026-07-31 · closed · external user · 9 comments

### Phase 0: Gateway lifecycle and extension control channel

Parent: #7

## Objective
Implement Phase 0 of `docs/COCOS_CLI_GATEWAY_PLAN.md`: only the Cocos extension may start the Gateway detached; add health, ownership, register/heartbeat/unregister, reconnect, stale cleanup, and idle shutdown primitives.

## Dependencies
None. Inspect current `browser.js`, `lib/server.js`, config, package scripts, and existing tests before editing.

## Ownership
Current workspace, sequential writer. Own lifecycle/control-channel modules and their tests; update package e

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/8) · 2026-07-31 · closed · external user · 8 comments

### 连接不上怎么解决

[Funplay Cocos MCP] Update check failed: GitHub returned HTTP 403: {"message":"API rate limit exceeded for 118.166.9.133. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation fo

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/4) · 2026-07-21 · closed · external user · 2 comments

### Run Script Dignoses 返回 spawn EINVAL

{
  "ok": false,
  "tool": "run_script_diagnostics",
  "callId": "fp_53e69ec9f982a23d",
  "timestamp": "2026-07-10T13:34:10.016Z",
  "summary": "spawn EINVAL",
  "data": {
    "message": "spawn EINVAL"
  },
  "refs": []
}

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/1) · 2026-07-10 · closed · external user · 1 comment

## Most recent

### Phase 5: Final integration review and acceptance verification

Parent: #7
Depends on Phases 0-4 child issues.

## Objective
Review and integrate the complete implementation against every requirement in `docs/COCOS_CLI_GATEWAY_PLAN.md`, resolve regressions, update docs, and run the full verification suite.

## Ownership
Current workspace, sequential integrator. Inspect all diffs and tests. Do not claim Cocos Editor E2E unless the runtime is actually available; clearly record any external runtime blocker.

## Verify
`npm run check`, `npm test`, package/dry-ru

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/16) · 2026-07-31 · closed · external user · 1 comment

### Phase 4: Conflict detection reliability jobs and observability

Parent: #7
Depends on Phase 3 child issue.

## Objective
Implement revision/hash conflict detection, idempotency, job tracking, cancellation/recovery, audit logging, metrics/diagnostic state, structured errors, and Gateway/extension restart behavior.

## Ownership
Current workspace, sequential writer. Add tests for conflicts, retries, disconnects, timeouts, stale locks, and recovery. Keep local-only default behavior secure.

## Verify
`npm run check`, `npm test`, and targeted reliability/conflic

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/15) · 2026-07-31 · closed · external user · 1 comment

### Phase 4: Conflict detection reliability jobs and observability

Parent: #7
Depends on Phase 3 child issue.

## Objective
Implement revision/hash conflict detection, idempotency, job tracking, cancellation/recovery, audit logging, metrics/diagnostic state, structured errors, and Gateway/extension restart behavior.

## Ownership
Current workspace, sequential writer. Add tests for conflicts, retries, disconnects, timeouts, stale locks, and recovery. Keep local-only default behavior secure.

## Verify
`npm run check`, `npm test`, and targeted reliability/conflic

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/12) · 2026-07-31 · closed · external user · 1 comment

### Phase 2: Multi-editor target registry and routing

Parent: #7
Depends on Phase 1 child issue.

## Objective
Implement dynamic multi-editor target registration, editorInstanceId/generation identity, health/heartbeat state, sticky target routing, ambiguity handling, capability checks, and primary-writer policy.

## Ownership
Current workspace, sequential writer. Do not bypass the extension control channel. Add tests for multiple projects, multiple Editor instances, same-project ambiguity, offline targets, reconnect, and stale connections.

## Veri

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/10) · 2026-07-31 · closed · external user · 1 comment

### Implement central Cocos CLI Gateway architecture

## Outcome
Implement the Cocos CLI Gateway architecture described in `docs/COCOS_CLI_GATEWAY_PLAN.md`.

## Acceptance checks
- [ ] A central Gateway exposes the MCP surface and coordinates multiple agents and Editor instances.
- [ ] `cocos-cli` is client-only: it forwards requests and cannot start or stop the Gateway.
- [ ] Only the Cocos Creator extension can start the Gateway detached, register/heartbeat/unregister an Editor instance, and trigger idle shutdown ownership.
- [ ] Gateway routing,

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/7) · 2026-07-31 · closed · external user · 1 comment

### run_project_preview 返回 LAN URL，导致同机 Browser Preview 的 socket.io.js 加载失败

## 环境

- Funplay Cocos MCP：v0.4.4
- Cocos Creator：3.8.8
- 操作系统：Windows
- Preview 模式：`browser`
- 调用工具：`run_project_preview({ mode: "browser" })`

## 问题

`run_project_preview` 成功启动 Browser Preview，但返回的 `url` 是本机局域网地址，例如：

```text
http://192.168.16.119:7456
```

在同一台机器的内置浏览器中直接打开该返回 URL 时，Preview 外壳可以加载，但 SystemJS 无法加载 Cocos Preview 所需的 Socket.IO 脚本：

```text
Error loading http://192.168.16.119:7456/socket.io/socket.io.js
(SystemJS Error#3)
```

将主机改成 `localhost`、保持同一端口后：

```text
http://localhost:

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/6) · 2026-07-29 · closed · external user · 1 comment

### create_prefab_instance omits type: 'cc.Prefab' and can report a false linked success

## Environment

- Cocos Creator 3.8.8
- Installed Funplay Cocos MCP: v0.4.2
- Also verified in the current v0.4.4 tag and `main`
- Windows

## Summary

`create_prefab_instance` calls Cocos Creator's `scene:create-node` message without `type: 'cc.Prefab'`.

On Cocos Creator 3.8.8, `assetUuid` plus `unlinkPrefab: false` is not sufficient to guarantee a linked Prefab instance. The request can return a node UUID while the resulting node does not retain the expected Prefab instance linkage. The tool 

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/5) · 2026-07-27 · closed · external user · 1 comment

### Cocos Creator 3.8.8：需要支持浏览器预览与编辑器预览模式的查询和切换

## 环境

- Funplay MCP for Cocos：v0.4.2
- Cocos Creator：3.8.8
- 操作系统：Windows

## 问题

官方 `run_project_preview` 工具提供了可选参数 `platform?: string`，但 README 和工具 schema 没有说明可用值，也没有说明它与 Cocos Creator 的“浏览器预览 / 编辑器预览”模式之间的对应关系。

在 v0.4.2 中，该工具会把整个参数对象直接转交给以下编辑器消息：

- `preview.start`
- `preview.open-preview`
- `builder.preview`

Cocos Creator 3.8.8 中上述三个消息均不存在，因此 MCP 无法启动预览。

另外，浏览器预览和编辑器预览的验证方式不同：浏览器预览没有编辑器内的 Game 面板。目前没有官方 MCP API 可以查询当前预览模式，也不能在浏览器预览和编辑器预览之间切换。

## 复现步骤

1. 将 MCP 工具 profile 切换到 `full`。
2. 

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/3) · 2026-07-15 · closed · external user · 1 comment

### Cannot automatically create scene files

It cannot automatically create scene files; a pop-up will prompt the user to save the file.

[Read the thread](https://github.com/FunplayAI/funplay-cocos-mcp/issues/2) · 2026-07-12 · closed · external user · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/FunplayAI/funplay-cocos-mcp/issues).