# Cocos4 MCP Server AI

An AI-native scaffold and enhanced [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for building games with [Cocos4](https://github.com/cocos/cocos4) using AI coding agents such as **Codex**, **Claude Code**, and other MCP-compatible clients.

Cocos4 is a fully open-source (MIT), headless-first game engine — a rare fit for AI agents, since the entire editing pipeline can run from a CLI without a GUI. Its CLI (`cocos-cli`) already ships a built-in MCP server exposing ~50 low-level tools for scene, node, component, prefab, asset, and build operations. **This project builds on top of that**, rather than duplicating it:

- **Proxies** all native Cocos4 MCP tools transparently, so this project stays in sync as `cocos-cli` evolves — no hand-maintained tool schemas to drift out of date.
- **Adds** high-level scaffolding tools that the native server doesn't provide: project bootstrapping, TypeScript component/manager code generation, and ready-to-use gameplay templates (platformer, top-down shooter, match-3, endless runner, turn-based RPG, UI app).
- **Ships** a CLI (`cocos4-ai`) to bootstrap AI-ready projects with MCP client config already wired up.

## Why this exists

Cocos4 went fully open source in January 2026 (MIT license, all commercial clauses removed). Its CLI is still in early alpha, and the native MCP server is powerful but low-level — an AI agent has to know exact tool names, path conventions (`Canvas/Node1/cc.Sprite` vs `Canvas/Node1`), and multi-step sequences (create scene → open scene → create node → add component → set property → save scene) to get anything done.

This project is the missing layer between "raw engine primitives" and "an AI agent that can build a whole game from a prompt": project templates, codegen, and a single unified MCP endpoint that Codex (or any MCP client) can point at.

## Architecture

```
┌─────────────────────┐
│   Codex / Claude /   │
│   any MCP client     │
└──────────┬───────────┘
           │ stdio (MCP)
┌──────────▼───────────┐
│   cocos4-ai server    │  ← this project
│  ┌─────────────────┐  │
│  │ High-level tools │  │  project init, codegen, templates
│  └─────────────────┘  │
│  ┌─────────────────┐  │
│  │  Native proxy    │──┼──► streamable-HTTP (MCP) ──► cocos start-mcp-server
│  └─────────────────┘  │                                (50 native tools:
└───────────────────────┘                                 scene-*, assets-*,
                                                            builder-*, file-*,
                                                            system-*)
```

The server uses the MCP SDK's low-level `Server` class (not the high-level `McpServer` helper) so it can merge `tools/list` responses from two sources — the native Cocos4 CLI MCP server and this project's own tools — and route `tools/call` requests to whichever one owns the tool name.

## Requirements

- Node.js ≥ 22
- [Cocos4 CLI](https://github.com/cocos/cocos-cli) installed and available on `PATH` as `cocos`

## Installation

```bash
git clone git@github.com:usernema/cocos4-mcp-server-AI.git
cd cocos4-mcp-server-AI
npm install
npm run build
npm link   # makes `cocos4-ai` available globally
```

## Usage

### 1. Bootstrap a new project

```bash
cocos4-ai init my-game --type 3d
```

This creates the Cocos4 project via `cocos create` and writes an MCP client config (`.mcp/config.json`) so any MCP-compatible agent can connect immediately.

### 2. Point your AI agent at the server

For Codex, Claude Code, or any MCP client, add to its MCP config:

```json
{
  "mcpServers": {
    "cocos4-ai": {
      "command": "cocos4-ai",
      "args": ["serve", "--project", "./my-game"]
    }
  }
}
```

### 3. Let the agent build the game

Once connected, the agent has access to:

- **`cocos4_verify_installation`**, **`cocos4_create_project`**, **`cocos4_connect`**, **`cocos4_run_cli_command`** — environment and project lifecycle
- **`cocos4_list_templates`**, **`cocos4_apply_template`** — bootstrap common gameplay patterns
- **`cocos4_generate_component`**, **`cocos4_generate_manager`** — generate typed TypeScript scripts
- **~50 native tools** proxied from `cocos start-mcp-server`, once `cocos4_connect` is called:
  - `scene-*` — create/open/save/close scenes, query and mutate the node tree
  - `scene-create-node-by-type`, `scene-update-node`, `scene-delete-node`
  - `scene-add-component`, `scene-set-component-property`, `scene-query-component`
  - `create-prefab-from-node`, `apply-prefab-changes`, `revert-prefab`
  - `assets-*` — asset CRUD, metadata, import/reimport
  - `builder-build`, `builder-run`, `builder-make` — compile and launch builds
  - `file-insert-text`, `file-replace-text`, `file-query-text` — precise script editing
  - `system-query-logs` — read CLI logs for debugging

The agent should always call a `*-query-*` tool before mutating anything, to fetch exact node paths/UUIDs rather than guessing them (the native server enforces this — see `scene-query-node` vs `scene-query-component` distinctions in each tool's description).

## CLI reference

```bash
cocos4-ai check                          # verify cocos-cli is installed
cocos4-ai init <name> [--type 2d|3d]     # bootstrap a new AI-ready project
cocos4-ai serve --project <path>         # start the MCP server (stdio transport)
  [--native-port <port>]                 # port for the native Cocos MCP server (default 9527)
  [--no-auto-start]                      # don't auto-connect to a native server on boot
  [--debug]                              # verbose logging to stderr
```

## Available templates

| ID | Description |
|---|---|
| `platformer-2d` | Side-scrolling platformer: movement, jumping, `GameManager` |
| `shooter-topdown` | Top-down shooter: WASD movement, aiming, firing |
| `puzzle-match3` | Grid-based match-3: swap logic, match detection |
| `runner-endless` | Auto-runner: jump physics, obstacle avoidance |
| `rpg-turnbased` | Turn-based combat: turn order, attack resolution |
| `ui-app` | Multi-screen UI navigation with history stack |

## Development

```bash
npm run dev     # tsc --watch
npm run build   # compile TypeScript
npm test        # run tests (vitest)
```

## Project status

This is an early-stage project built to accompany an application to [OpenAI's Codex for Open Source](https://developers.openai.com/codex/codex-for-oss-terms) program. Cocos4 itself is in active development (CLI at `0.0.1-alpha.x` as of writing) — expect native tool names/schemas to evolve, which is exactly why this project proxies rather than duplicates them.

Contributions and issue reports welcome.

## License

MIT