funplay-cocos-mcp

<p align="center">
  <h1 align="center">Funplay MCP for Cocos</h1>
  <p align="center">
    <strong>An Embedded MCP Server for Cocos Creator Editor</strong>
  </p>
  <p align="center">
    <a href="#"><img src="https://img.shields.io/badge/Cocos%20Creator-3.8%2B-blue" alt="Cocos Creator 3.8+"></a>
    <a href="#"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
    <a href="#"><img src="https://img.shields.io/badge/MCP-Compatible-green" alt="MCP Compatible"></a>
    <a href="#"><img src="https://img.shields.io/badge/Platform-Editor%20Only-orange" alt="Editor Only"></a>
    <a href="https://store.cocos.com/app/detail/8913"><img src="https://img.shields.io/badge/Cocos%20Store-Install-brightgreen" alt="Install from Cocos Store"></a>
  </p>
  <p align="center">
    <a href="./README_CN.md">中文</a> | English
  </p>
</p>

> If this project helps your Cocos workflow, please consider giving it a Star. It helps more developers discover the project and supports ongoing development.

---

Funplay MCP for Cocos is an MIT-licensed Cocos Creator extension that embeds an HTTP MCP server directly inside the editor. It lets AI assistants such as Claude Code, Cursor, Codex, VS Code Copilot, Trae, Kiro, Qoder, Kimi Code, and OpenCode inspect and operate your running Cocos project.

The package follows the same product direction as Funplay MCP for Unity: keep the default tool surface focused, provide a one-click client configuration window, and make one high-flexibility execution tool the primary workflow.

For Cocos, the primary tool is `execute_javascript`:

- `context: "scene"` runs JavaScript in the active Cocos scene/runtime context
- `context: "editor"` runs JavaScript in the Cocos editor/browser context

> *"Create a login page UI with account/password fields and a main login button."*
>
> Your AI assistant can call `execute_javascript`, build the UI hierarchy under the active Canvas, attach Cocos components, inspect the result, and capture a screenshot for validation.

## Quick Start

If you just want to connect quickly, do these three things:

- Install this repository as a Cocos Creator extension
- Open `Funplay > MCP Server`
- Use the built-in one-click MCP client configuration

### 1. Install as a Cocos Creator Extension

Recommended install: use the official [Cocos Store page](https://store.cocos.com/app/detail/8913) and install the extension into your target Cocos Creator project.

For local development or unreleased builds, clone or copy this repository into your Cocos project extension directory:

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

Then restart Cocos Creator or reload extensions from the editor.

For a non-git install, download `Funplay.CocosMcp.v<version>.zip` from the GitHub Releases page, unzip it, and move the extracted `funplay-cocos-mcp` folder into your project `extensions/` directory.

#### Install for All Projects (Recommended)

Install and open the extension in any project first. Then open `Funplay > MCP Settings` and click **Install for All Projects** in the All Projects section. The extension downloads the latest GitHub Release, verifies `SHA256SUMS.txt`, and installs it into the active Cocos Creator version's managed global extension directory:

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

Cocos Creator scans and registers the installed copy immediately. Projects opened or created with that Creator version then load it automatically, and the MCP server keeps its default autostart behavior. Reopen an already-running project if its project-level copy has priority. No extension files are copied into each project's `extensions/` directory.

Global extensions are isolated by Cocos Creator version. If you use multiple Creator versions, run **Install for All Projects** once from each version.

The installer does not delete the current project copy, which protects development worktrees. If both copies exist, MCP Settings shows a duplicate-install warning. After confirming that the global copy works, remove or disable the project copy to avoid extension conflicts.

### 2. Start the MCP Server

Open the editor menu:

```text
Funplay > MCP Server
```

New projects get a stable project-derived port in `20000–29999`. Existing saved configurations keep their fixed port (including `8765`). Use the exact URL shown in MCP Server; if a temporary fallback port is active, click **Pin Current Port** or **Use Per-Project Port** before configuring a client.

If the configured port is already occupied, the extension first checks whether the existing listener belongs to the same Cocos project. Same-project listeners are reused safely; unrelated listeners trigger automatic fallback to the next available local port.

The panel is intentionally small:

- Enable or disable the MCP server
- Open focused Tool Exposure, MCP Settings, and Project Skills windows
- Automatically check the installed version against the latest GitHub release
- Open the release page or install verified release packages from the panel
- Install once in the Cocos Creator global extensions directory so existing and new projects can use it automatically
- Configure AI clients with one click and preview the selected client config
- Keep advanced tool profile editing, transport settings, and installation management out of the main server window
- Follow the Cocos Creator interface language automatically, or select Chinese/English per project in MCP Settings
- Toggle **Print MCP logs** in Settings to silence MCP console messages without losing Recent Activity or internal diagnostics

All management pages use consistent headings, aligned controls, and lightweight sections. Tool Exposure groups per-tool toggles by category; Project Skills highlights available actions and folds away file paths and backups. Recent Activity shows each call's summary and actual result as an expandable object/array tree, with execution logs and return values in separate sections for scripts. Output sections and the standalone log-viewing panel are removed. Short action notices preserve success/failure feedback, while diagnostic logs remain available to MCP tools and resources.

Script tools capture per-call `console.log/info/warn/error/debug` output, including logs before a failure, independently of **Print MCP logs**. Capture is isolated across concurrent and nested calls and stops when the script settles; global/project logs and logs from separately required modules are not collected. Use the injected `console` (also available as `env.console` in `run`/module exports). MCP responses retain their existing `data` shape and add optional `execution` metadata with context, duration, bounded/redacted logs, and an omitted-entry count. Recent Activity preserves result hierarchy and scalar values; large results and file/script bodies remain limited or omitted, with truncation notices.

The extension menu and native panel titles follow the Cocos Creator interface language. Panel controls, tool descriptions, status messages, prompts, and empty states support English and Chinese; open `Funplay > MCP Settings` to follow Creator or set a project-specific content-language override. MCP tool IDs and schemas remain in English so client integrations stay stable.

### 3. Configure Your AI Client

Use the built-in **MCP Client Config** section in the `Funplay > MCP Server` panel first.

Select your target client, click **One-Click Configure**, and the extension writes the recommended MCP config entry for you.

The MCP server name written to clients is:

```text
cocos-<project>-<hash>
```

If you prefer to edit config files manually, use the examples below as fallback references. Replace their legacy `funplay_cocos` name and `8765` port with the name and URL shown in your panel. One-click Claude Code configuration uses the project's Git-root scope in `~/.claude.json`, not the global example below. See [project setup and migration](docs/PROJECT_WORKFLOWS.md).

<details>
<summary>Claude Code / Claude Desktop</summary>

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

</details>

<details>
<summary>Cursor</summary>

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

</details>

<details>
<summary>VS Code</summary>

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

</details>

<details>
<summary>Trae</summary>

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

</details>

<details>
<summary>Kiro</summary>

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

</details>

<details>
<summary>Qoder</summary>

The user-level configuration is written to `~/.qoder/settings.json`, or to `$QODER_CONFIG_DIR/settings.json` when that environment variable is set.

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

</details>

<details>
<summary>Kimi Code</summary>

The user-level configuration is written to `~/.kimi-code/mcp.json`, or to `$KIMI_CODE_HOME/mcp.json` when that environment variable is set.

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

</details>

<details>
<summary>Codex</summary>

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

</details>

<details>
<summary>OpenCode</summary>

The global config lives in `$XDG_CONFIG_HOME/opencode/opencode.json` or `~/.config/opencode/opencode.json` on every platform (`opencode.jsonc` also