# cocos-mcp

**Repository Path**: SimanX/cocos-mcp

## Basic Information

- **Project Name**: cocos-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cocos Creator 3.8.8 MCP Server

一个完全自主操控 Cocos Creator 3.8.8 的 MCP (Model Context Protocol) Server，支持 AI Agent 完整进行游戏开发——编辑→运行→验证的完整闭环。

- [English](README.md) | 中文

---

## 目录

- [Cocos Creator 3.8.8 MCP Server](#cocos-creator-388-mcp-server)
  - [目录](#目录)
  - [特性](#特性)
  - [架构概览](#架构概览)
    - [数据流](#数据流)
  - [目录结构](#目录结构)
  - [前置要求](#前置要求)
  - [快速开始](#快速开始)
    - [1. 安装 MCP Server](#1-安装-mcp-server)
    - [2. 安装 Cocos Creator 扩展](#2-安装-cocos-creator-扩展)
    - [3. 启动 Cocos Creator](#3-启动-cocos-creator)
    - [4. 验证安装](#4-验证安装)
  - [安装详解](#安装详解)
    - [MCP Server 安装](#mcp-server-安装)
    - [Cocos Creator 扩展安装](#cocos-creator-扩展安装)
    - [MCP 客户端配置](#mcp-客户端配置)
      - [Claude Desktop (claude\_desktop\_config.json)](#claude-desktop-claude_desktop_configjson)
      - [Cursor](#cursor)
  - [MCP 工具一览](#mcp-工具一览)
    - [场景管理 (Scene)](#场景管理-scene)
    - [节点操作 (Node)](#节点操作-node)
    - [组件操作 (Component)](#组件操作-component)
    - [预制体 (Prefab)](#预制体-prefab)
    - [资源管理 (Asset)](#资源管理-asset)
    - [构建发布 (Build)](#构建发布-build)
    - [运行时控制 (Runtime)](#运行时控制-runtime)
    - [自动化验证 (Validation)](#自动化验证-validation)
    - [调试 (Debug)](#调试-debug)
  - [通信机制](#通信机制)
    - [HTTP 通道 (Editor 控制)](#http-通道-editor-控制)
    - [WebSocket 通道 (Runtime 控制)](#websocket-通道-runtime-控制)
    - [Game Bridge](#game-bridge)
  - [MCP 状态面板](#mcp-状态面板)
    - [功能区域](#功能区域)
  - [使用示例](#使用示例)
    - [示例 1: 创建游戏 UI](#示例-1-创建游戏-ui)
    - [示例 2: 启动游戏并验证功能](#示例-2-启动游戏并验证功能)
  - [API 参考](#api-参考)
    - [环境变量](#环境变量)
    - [常量](#常量)
  - [开发指南](#开发指南)
    - [编译 MCP Server](#编译-mcp-server)
    - [添加新的 MCP 工具](#添加新的-mcp-工具)
    - [添加新的 Editor 服务](#添加新的-editor-服务)
    - [调试](#调试)
  - [常见问题](#常见问题)
  - [许可证](#许可证)

---

## 特性

- **全链路 AI 游戏开发**: 从场景搭建、节点创建、组件配置，到游戏运行、输入模拟、自动化验证，全部由 AI Agent 通过 MCP 工具驱动
- **Editor + Runtime 双重控制**: 通过 HTTP 与 Cocos Editor 通信，通过 WebSocket 与运行中的游戏通信
- **UI 检测 + 截图对比**: 双重验证策略确保 AI 能准确判断游戏是否符合预期
- **MCP 状态面板**: 在 Cocos Editor 中嵌入可视化面板，实时查看连接状态、运行时信息、日志和工具调用
- **仅支持 Web 平台**: 针对 `web-mobile` 平台优化

---

## 架构概览

```
┌─────────────────────────────────────────────────────────────────┐
│                      AI Agent (MCP Client)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
│  │   Design    │→ │   Build     │→ │    Run      │→ │Validate │ │
│  │ (Scene/     │  │  (Compile)  │  │   (Web)     │  │(UI+Img) │ │
│  │   Node)     │  │             │  │             │  │         │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MCP Server (Node.js)                        │
│  Tools: scene_* | node_* | component_* | runtime_* | validate_* │
│  Transport: HTTP (Editor) + WebSocket (Runtime)                 │
└─────────────────────────────────────────────────────────────────┘
              ┌─────────────────┴─────────────────┐
              ▼                                   ▼
┌──────────────────────────┐        ┌──────────────────────────┐
│   Cocos Creator Editor   │        │    Web Preview (运行中)    │
│   HTTP Server (:3000)    │        │   WebSocket (:3001)      │
│   • 场景/节点/组件/资源操作 │        │   • 输入模拟/状态查询       │
│   • 构建/预览启动          │        │   • 截图/UI检测           │
│   • MCP 状态面板 ★        │        │                          │
└──────────────────────────┘        └──────────────────────────┘
              │                                   │
              │         ┌───────────────────────────┘
              │         │ game-bridge.js 注入到游戏 HTML 中
              └─────────┴─────────────────────────────────────┘
```

### 数据流

1. **AI Agent** 通过 MCP SDK 调用工具
2. **MCP Server** 接收请求，通过 HTTP 向 Cocos Extension 转发
3. **Cocos Extension** 在 Editor 主进程中执行操作
4. **Game Bridge** (注入脚本) 通过 WebSocket 与 Runtime 通信
5. 响应原路返回给 AI Agent

---

## 目录结构

```
cocos-mcp/
├── package.json              # MCP Server 依赖配置
├── tsconfig.json             # TypeScript 配置
├── README.md                 # 本文档
├── src/                      # MCP Server 源码 (TypeScript)
│   ├── index.ts              # 入口点
│   ├── constants.ts          # 常量定义
│   ├── types/                # TypeScript 类型
│   │   └── index.ts
│   ├── schemas/              # Zod 验证 schemas
│   │   ├── scene.ts
│   │   ├── node.ts
│   │   ├── component.ts
│   │   ├── asset.ts
│   │   ├── build.ts
│   │   ├── runtime.ts
│   │   └── validation.ts
│   ├── services/             # 共享服务
│   │   ├── cocos-client.ts   # Cocos HTTP 客户端
│   │   └── error-handler.ts  # 错误处理
│   └── tools/                # MCP Tools 实现
│       ├── scene.ts
│       ├── node.ts
│       ├── component.ts
│       ├── prefab.ts
│       ├── asset.ts
│       ├── build.ts
│       ├── runtime.ts
│       ├── validation.ts
│       └── debug.ts
├── dist/                     # 编译输出 (npm run build)
└── extension/                # Cocos Creator 扩展包
    ├── package.json          # 扩展配置
    ├── main.js               # 扩展主入口 (HTTP/WS 服务)
    ├── panel/                # MCP 状态面板
    │   ├── mcp-panel.js
    │   └── panel.css
    ├── services/             # 扩展服务
    │   ├── scene-service.js
    │   ├── node-service.js
    │   ├── component-service.js
    │   ├── asset-service.js
    │   ├── build-service.js
    │   ├── runtime-service.js
    │   ├── screenshot-service.js
    │   ├── debug-service.js
    │   └── input-service.js
    ├── inject/               # 游戏端注入脚本
    │   └── game-bridge.js    # WebSocket 通信桥接
    └── scenes/               # Scene Scripts (主进程执行)
        └── scene-script.js
```

---

## 前置要求

| 依赖 | 版本要求 |
|------|---------|
| Node.js | >= 18.0.0 |
| npm | >= 9.0.0 |
| Cocos Creator | 3.8.8 |
| MCP 客户端 | Claude Desktop / Cursor 等 |

---

## 快速开始

### 1. 安装 MCP Server

```bash
cd cocos-mcp
npm install
npm run build
```

### 2. 安装 Cocos Creator 扩展

将 `extension` 文件夹复制到 Cocos Creator 的扩展目录：

```bash
# macOS
~/Library/Application Support/Cocos/CocosCreator/3.8.8/extensions/

# Windows
%USERPROFILE%\.CocosCreator\3.8.8\extensions\
```

### 3. 启动 Cocos Creator

打开 Cocos Creator 3.8.8，扩展会自动加载：
- HTTP 服务监听 `127.0.0.1:3000`
- WebSocket 服务监听 `127.0.0.1:3001`

### 4. 验证安装

在 Cocos Creator 菜单栏可以看到 **MCP** 选项，点击 **Open MCP Panel** 打开状态面板。

---

## 安装详解

### MCP Server 安装

```bash
# 进入项目目录
cd cocos-mcp

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# (可选) 开发模式 - 文件变更自动重载
npm run dev

# 类型检查
npm run typecheck
```

### Cocos Creator 扩展安装

**方式一：复制扩展文件夹**

```bash
# 创建扩展目录
mkdir -p ~/Library/Application\ Support/Cocos/CocosCreator/3.8.8/extensions/cocos-mcp

# 复制 extension 目录内容
cp -r extension/* ~/Library/Application\ Support/Cocos/CocosCreator/3.8.8/extensions/cocos-mcp/
```

**方式二：npm link (开发时推荐)**

```bash
cd cocos-mcp/extension
npm link
```

然后在 Cocos Creator 中通过 **扩展 → 本地扩展** 加载。

### MCP 客户端配置

根据不同的 MCP 客户端进行配置。以下是通用配置：

#### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "cocos-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cocos-mcp/dist/index.js"],
      "env": {
        "COCOS_HTTP_URL": "http://127.0.0.1:3000"
      }
    }
  }
}
```

配置文件位置：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Cursor

在 Cursor 设置中添加 MCP Server，或使用 `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cocos-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cocos-mcp/dist/index.js"],
      "env": {
        "COCOS_HTTP_URL": "http://127.0.0.1:3000"
      }
    }
  }
}
```

---

## MCP 工具一览

### 场景管理 (Scene)

| 工具名称 | 说明 |
|---------|------|
| `cocos_scene_list` | 列出项目中所有场景 |
| `cocos_scene_open` | 打开指定场景 |
| `cocos_scene_save` | 保存当前或指定场景 |
| `cocos_scene_create` | 创建新场景 |
| `cocos_scene_hierarchy` | 获取场景层级树结构 |

**示例**:
```json
// cocos_scene_hierarchy - 获取当前场景的完整层级
{}

// cocos_scene_open - 打开场景
{ "uuid": "abc123..." }

// cocos_scene_create - 创建新场景
{ "name": "GameScene" }
```

---

### 节点操作 (Node)

| 工具名称 | 说明 |
|---------|------|
| `cocos_node_create` | 在场景中创建新节点 |
| `cocos_node_find` | 按名称/组件查找节点 |
| `cocos_node_delete` | 删除节点 |
| `cocos_node_get_by_path` | 通过路径获取节点 (如 `Canvas/UI/MainMenu`) |
| `cocos_node_get_by_uuid` | 通过 UUID 获取节点详情 |
| `cocos_node_get_children` | 获取节点的子节点列表 |
| `cocos_node_set_transform` | 设置节点位置/旋转/缩放 |
| `cocos_node_set_active` | 设置节点激活状态 |
| `cocos_node_set_parent` | 重新指定节点父级 |

**示例**:
```json
// 创建节点
{
  "name": "StartButton",
  "parent_uuid": "canvas-uuid..."
}

// 设置 Transform
{
  "node_uuid": "node-uuid...",
  "position": { "x": 100, "y": 200 },
  "rotation": { "x": 0, "y": 0 },
  "scale": { "x": 1, "y": 1 }
}

// 查找节点
{
  "name": "Menu",
  "component_type": "Button"
}
```

---

### 组件操作 (Component)

| 工具名称 | 说明 |
|---------|------|
| `cocos_component_add` | 向节点添加组件 |
| `cocos_component_remove` | 移除组件 |
| `cocos_component_get` | 获取组件信息 |
| `cocos_component_set_property` | 设置组件属性 |
| `cocos_component_get_property` | 获取组件属性 |
| `cocos_sprite_set_sprite_frame` | 设置 Sprite 的图片 |
| `cocos_label_set_text` | 设置 Label 文本 |
| `cocos_button_set_interactable` | 设置按钮可交互状态 |

**示例**:
```json
// 添加 Button 组件
{
  "node_uuid": "node-uuid...",
  "component_type": "Button"
}

// 设置 Label 文本
{
  "node_uuid": "node-uuid...",
  "text": "Hello World"
}

// 设置组件属性
{
  "node_uuid": "node-uuid...",
  "component_type": "Sprite",
  "property": "size",
  "value": { "width": 200, "height": 100 }
}
```

---

### 预制体 (Prefab)

| 工具名称 | 说明 |
|---------|------|
| `cocos_prefab_create` | 从节点创建预制体资源 |
| `cocos_prefab_instantiate` | 在场景中实例化预制体 |
| `cocos_prefab_apply` | 将实例的修改应用回预制体 |
| `cocos_prefab_locate` | 定位预制体资源或实例 |

---

### 资源管理 (Asset)

| 工具名称 | 说明 |
|---------|------|
| `cocos_asset_search` | 搜索项目资源 |
| `cocos_asset_get_info` | 获取资源详细信息 |
| `cocos_asset_import` | 导入外部资源文件 |
| `cocos_asset_delete` | 删除资源 |

**示例**:
```json
// 搜索所有 Sprite 资源
{
  "query": "",
  "type": "sprite"
}

// 搜索包含 "button" 的资源
{
  "query": "button",
  "type": ""
}
```

---

### 构建发布 (Build)

| 工具名称 | 说明 |
|---------|------|
| `cocos_build_get_platforms` | 获取支持的构建平台列表 |
| `cocos_build_project` | 构建项目 |
| `cocos_build_query_progress` | 查询构建进度 |

**示例**:
```json
// 构建 Web Mobile 版本
{
  "platform": "web-mobile",
  "options": {
    "debug": false,
    "sourcemap": true,
    "minify": true,
    "md5_cache": false
  }
}
```

---

### 运行时控制 (Runtime)

这是 AI 自主游戏验证的核心能力。

| 工具名称 | 说明 |
|---------|------|
| `cocos_runtime_start` | 启动游戏预览，建立运行时控制连接 |
| `cocos_runtime_stop` | 停止游戏运行 |
| `cocos_runtime_click` | 模拟鼠标/触摸点击 |
| `cocos_runtime_drag` | 模拟拖拽手势 |
| `cocos_game_call_method` | 调用游戏对象的脚本方法 |
| `cocos_game_get_state` | 评估游戏中的 JavaScript 表达式 |
| `cocos_game_set_variable` | 设置游戏运行时变量 |

**示例**:
```json
// 启动游戏 (不传 scene_uuid 则运行当前场景)
{
  "platform": "web-mobile"
}

// 模拟点击 (屏幕像素坐标)
{
  "x": 400,
  "y": 300
}

// 模拟拖拽
{
  "start_x": 100,
  "start_y": 200,
  "end_x": 300,
  "end_y": 400,
  "duration": 500
}

// 调用游戏脚本方法
{
  "node_path": "Canvas/UI/StartButton",
  "component_name": "Button",
  "method_name": "onClick",
  "args": []
}

// 获取游戏状态
{
  "expression": "cc.director.getScene().name"
}
```

---

### 自动化验证 (Validation)

支持 AI 自我验证游戏是否符合预期。

| 工具名称 | 说明 |
|---------|------|
| `cocos_capture_screenshot` | 截取当前游戏画面 |
| `cocos_ui_find_element` | 在游戏画面中查找 UI 元素 |
| `cocos_validate_game_feature` | 综合验证 (UI检测 + 截图对比) ★ |
| `cocos_assert_game_state` | 批量断言验证 |

**示例**:
```json
// 截取全屏截图
{}

// 截取指定区域
{
  "region": { "x": 0, "y": 0, "width": 800, "height": 600 }
}

// 查找 UI 元素
{
  "selector": {
    "node_path": "Canvas/UI",
    "component": "Button",
    "name": "Start"
  },
  "timeout": 5000
}

// 综合验证 - AI 验证的核心工具 ★
{
  "feature_name": "主菜单显示",
  "ui_selector": {
    "node_path": "Canvas/Menu",
    "expected_text": "Start Game"
  },
  "baseline_screenshot": null,
  "screenshot_threshold": 0.95
}

// 批量断言
{
  "assertions": [
    {
      "type": "element_exists",
      "selector": { "node_path": "Canvas/UI/StartButton" }
    },
    {
      "type": "element_text",
      "selector": { "node_path": "Canvas/UI/Title" },
      "expected_value": "My Game"
    }
  ]
}
```

---

### 调试 (Debug)

| 工具名称 | 说明 |
|---------|------|
| `cocos_debug_get_console_logs` | 获取游戏控制台日志 |
| `cocos_debug_clear_logs` | 清空控制台日志 |
| `cocos_debug_execute_script` | 在游戏上下文中执行 JavaScript |
| `cocos_debug_get_system_info` | 获取系统和编辑器信息 |
| `cocos_debug_health_check` | 检查 MCP 连接健康状态 |

---

## 通信机制

### HTTP 通道 (Editor 控制)

MCP Server 通过 HTTP 与 Cocos Extension 通信，监听 `127.0.0.1:3000`:

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/scene/query` | GET | 获取场景层级 |
| `/api/scene/nodes` | POST | 节点 CRUD 操作 |
| `/api/scene/node` | POST | 查询节点 |
| `/api/scene/create` | POST | 创建节点 |
| `/api/scene/delete` | POST | 删除节点 |
| `/api/scene/transform` | POST | 设置 Transform |
| `/api/scene/children` | POST | 获取子节点 |
| `/api/component/*` | POST | 组件操作 |
| `/api/asset/*` | GET/POST | 资源操作 |
| `/api/build/*` | GET/POST | 构建操作 |
| `/api/runtime/*` | POST | 运行时控制 |
| `/api/console/*` | GET/POST | 日志操作 |

### WebSocket 通道 (Runtime 控制)

游戏运行时通过 WebSocket 连接 `127.0.0.1:3001`:

| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `runtime_connect` | Client→Server | 注册为运行时客户端 |
| `input` | Server→Client | 输入模拟指令 |
| `invoke` | Server→Client | 方法调用 |
| `eval` | Server→Client | 表达式求值 |
| `screenshot` | Server→Client | 截图请求 |
| `ui_find` | Server→Client | UI 查找请求 |
| `invoke_response` | Client→Server | 调用结果 |
| `eval_response` | Client→Server | 求值结果 |
| `screenshot_response` | Client→Server | 截图数据 |
| `runtime_ui_element` | Client→Server | UI 查找结果 |

### Game Bridge

`game-bridge.js` 会被注入到游戏运行时 HTML 中，负责：
- WebSocket 连接管理 (自动重连、心跳)
- 输入事件模拟 (Touch/Mouse/Keyboard)
- 方法调用执行
- 截图采集
- UI 元素查找
- 控制台日志转发

---

## MCP 状态面板

在 Cocos Creator 中通过 **MCP → Open MCP Panel** 打开。

### 功能区域

| 区域 | 内容 |
|------|------|
| **连接状态** | MCP Server 连接状态、HTTP/WS 端口、连接数 |
| **快捷操作** | 一键启动/停止游戏、截图、刷新 |
| **Runtime 控制** | 暂停/恢复、时间缩放、输入模拟 |
| **性能监控** | FPS、内存占用、帧数、运行时间 |
| **日志查看** | 游戏运行时日志，支持按级别过滤 |
| **工具面板** | 快速调用常用工具 |

---

## 使用示例

### 示例 1: 创建游戏 UI

```json
// Step 1: 获取场景层级
{ "tool": "cocos_scene_hierarchy" }

// Step 2: 创建 Canvas 下的 UI 根节点
{
  "tool": "cocos_node_create",
  "params": {
    "name": "GameUI",
    "parent_uuid": "canvas-uuid"
  }
}

// Step 3: 创建按钮
{
  "tool": "cocos_node_create",
  "params": {
    "name": "StartButton",
    "parent_uuid": "gameui-uuid"
  }
}

// Step 4: 添加 Button 组件
{
  "tool": "cocos_component_add",
  "params": {
    "node_uuid": "startbutton-uuid",
    "component_type": "Button"
  }
}

// Step 5: 添加 Label 显示文字
{
  "tool": "cocos_component_add",
  "params": {
    "node_uuid": "startbutton-uuid",
    "component_type": "Label"
  }
}
{
  "tool": "cocos_label_set_text",
  "params": {
    "node_uuid": "startbutton-uuid",
    "text": "Start Game"
  }
}

// Step 6: 设置按钮位置
{
  "tool": "cocos_node_set_transform",
  "params": {
    "node_uuid": "startbutton-uuid",
    "position": { "x": 0, "y": -100 }
  }
}
```

### 示例 2: 启动游戏并验证功能

```json
// Step 1: 启动游戏预览
{
  "tool": "cocos_runtime_start",
  "params": {
    "platform": "web-mobile"
  }
}

// Step 2: 等待游戏加载 (通过健康检查确认)
{
  "tool": "cocos_debug_health_check"
}

// Step 3: 截取主菜单截图
{
  "tool": "cocos_capture_screenshot"
}

// Step 4: 验证 UI 元素存在
{
  "tool": "cocos_ui_find_element",
  "params": {
    "selector": {
      "node_path": "Canvas",
      "component": "Button"
    }
  }
}

// Step 5: 点击开始按钮
{
  "tool": "cocos_runtime_click",
  "params": {
    "x": 400,
    "y": 300
  }
}

// Step 6: 等待切换后截图
{ "tool": "cocos_capture_screenshot" }

// Step 7: 综合验证 - UI + 截图
{
  "tool": "cocos_validate_game_feature",
  "params": {
    "feature_name": "游戏开始界面",
    "ui_selector": {
      "node_path": "Canvas/GameView"
    },
    "screenshot_threshold": 0.9
  }
}

// Step 8: 获取控制台日志检查错误
{
  "tool": "cocos_debug_get_console_logs",
  "params": { "limit": 50 }
}

// Step 9: 停止游戏
{
  "tool": "cocos_runtime_stop"
}
```

---

## API 参考

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `COCOS_HTTP_URL` | `http://127.0.0.1:3000` | Cocos Extension HTTP 服务地址 |

### 常量

```typescript
HTTP_PORT = 3000        // HTTP 服务端口
WS_PORT = 3001          // WebSocket 服务端口
DEFAULT_TIMEOUT = 30000 // 请求超时 (ms)
CHARACTER_LIMIT = 25000 // 响应文本截断限制
MAX_LOGS = 1000         // 日志最大存储条数
SCREENSHOT_THRESHOLD = 0.95 // 截图对比默认阈值
```

---

## 开发指南

### 编译 MCP Server

```bash
npm run build    # 编译 TypeScript
npm run dev      # 开发模式 (热重载)
npm run typecheck # 类型检查
```

### 添加新的 MCP 工具

1. 在 `src/schemas/` 中定义 Zod 输入 schema
2. 在 `src/tools/` 中实现工具逻辑
3. 在 `src/index.ts` 中注册工具
4. 如需 Editor 端支持，在 `extension/services/` 中添加服务
5. 在 `extension/main.js` 的 `_handleHttpRequest` 中添加路由

### 添加新的 Editor 服务

1. 在 `extension/services/` 中创建服务文件
2. 在 `extension/main.js` 中注册消息处理器
3. 在 `_handleHttpRequest` 中添加 HTTP 路由映射

### 调试

```bash
# 查看 MCP Server 日志
npm run dev 2>&1 | tee mcp-debug.log

# 检查 Cocos Extension 是否正常加载
# Cocos Creator 控制台应显示:
# [Cocos-MCP] Extension loaded successfully
# [Cocos-MCP] HTTP Server running on port 3000
# [Cocos-MCP] WebSocket Server running on port 3001
```

---

## 常见问题

**Q: MCP Server 无法连接 Cocos Creator**

确保：
1. Cocos Creator 已启动并加载了扩展
2. `extension/package.json` 放在正确位置
3. HTTP 服务监听在 `127.0.0.1:3000` (不是 `localhost`)
4. 防火墙未阻止 3000/3001 端口

**Q: 游戏运行时无法接收输入模拟**

确保：
1. `game-bridge.js` 已注入到游戏 HTML 中
2. WebSocket 连接 `ws://127.0.0.1:3001` 已建立
3. 在 Cocos Creator 面板中检查 Runtime 连接状态

**Q: 截图返回错误**

游戏必须处于运行状态才能截图。使用 `cocos_runtime_start` 先启动游戏。

**Q: UI 元素查找返回 `found: false`**

检查：
1. 节点路径是否正确 (区分大小写)
2. 元素是否在当前活跃场景中
3. 尝试增加 `timeout` 参数

**Q: 如何查看所有可用工具?**

在支持的 MCP 客户端中，列出所有以 `cocos_` 开头的工具即为所有可用工具。

---

## 许可证

MIT