Files

root 8781bbf0f5 初次提交

2025-07-17 18:12:56 +08:00

7.9 KiB

Executable File

Raw Blame History

Cocos Creator MCP 服务器插件

一个适用于 Cocos Creator 3.8+ 的综合性 MCP（模型上下文协议）服务器插件，使 AI 助手能够通过标准化协议与 Cocos Creator 编辑器进行交互。一键安装和使用，省去所有繁琐环境和配置。已经测试过Claude客户端Claude CLI和Cursor，其他的编辑器理论上也完美支持。

🚀 现在提供 9 个类别的 80 个工具，实现95%的编辑器控制！（暂时无法操控预制体）

快速使用

Claude cli配置：

claude mcp add --transport http http://localhost:3000/mcp（使用你自己配置的端口号）

Claude客户端配置：

{

  "mcpServers": {

		"cocos-creator": {

 		"type": "http",

		"url": "http://localhost:3000/mcp"

		 }

	  }

}

Cursor或VS类MCP配置

{

  "mcpServers": { 

   "cocos-creator": {
      "url": "http://localhost:3000/mcp"
   }
  }

}

效果：

功能特性

🎯 场景操作

获取当前场景信息和完整场景列表
通过路径打开场景并保存当前场景
创建自定义名称的新场景
获取完整场景层级结构及组件信息

🎮 节点操作

创建不同类型的节点（Node、2DNode、3DNode）
通过 UUID 获取节点信息，按名称模式查找节点
设置节点属性（位置、旋转、缩放、激活状态）
删除、移动和复制节点，完整支持层级结构

🔧 组件操作

向节点添加/删除组件
获取节点的所有组件及属性
动态设置组件属性
从资源路径挂载脚本组件
按类别列出可用的组件类型

📦 预制体操作

列出项目中的所有预制体，支持文件夹组织
加载、实例化和创建预制体
更新现有预制体并还原预制体实例
获取详细的预制体信息，包括依赖关系

🚀 项目控制

在预览模式下运行项目（浏览器/模拟器）
为不同平台构建项目（Web、移动端、桌面端）
获取项目信息和设置
刷新资源数据库并导入新资源
获取详细的资源信息

🔍 调试工具

获取编辑器控制台日志，支持过滤
清空控制台并在场景上下文中执行 JavaScript
获取详细的节点树用于调试
性能统计和场景验证
获取编辑器和环境信息

⚙️ 其他功能

偏好设置管理: 获取/设置编辑器偏好和全局设置
服务器控制: 服务器信息、项目详情和编辑器控制
消息广播: 监听和广播自定义消息
资源管理: 创建、复制、移动、删除和查询资源
构建系统: 项目构建和预览服务器控制

安装说明

1. 复制插件文件

将整个 cocos-mcp-server 文件夹复制到您的 Cocos Creator 项目的 extensions 目录中：

您的项目/
├── assets/
├── extensions/
│   └── cocos-mcp-server/          <- 将插件放在这里
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

2. 安装依赖

cd extensions/cocos-mcp-server
npm install

3. 构建插件

npm run build

4. 启用插件

重启 Cocos Creator 或刷新扩展
插件将出现在扩展菜单中
点击 扩展 > Cocos MCP Server 打开控制面板

使用方法

启动服务器

从 扩展 > Cocos MCP Server 打开 MCP 服务器面板
配置设置：
- 端口: http 服务器端口（默认：3000）
- 自动启动: 编辑器启动时自动启动服务器
- 调试日志: 启用详细日志以便开发调试
- 最大连接数: 允许的最大并发连接数
点击"启动服务器"开始接受连接

连接 AI 助手

服务器在 http://localhost:3000/mcp（或您配置的端口）上提供 http 端点。

AI 助手可以使用 MCP 协议连接并访问所有可用工具。

工具分类

工具按类别组织，命名约定为：category_toolname

scene_*: 场景相关操作 (8个工具)
node_*: 节点操作 (9个工具)
component_*: 组件管理 (7个工具)
prefab_*: 预制体操作 (8个工具)
project_*: 项目控制 (22个工具)
debug_*: 调试工具 (7个工具)
preferences_*: 编辑器偏好设置 (6个工具)
server_*: 服务器信息 (8个工具)
broadcast_*: 消息广播 (5个工具)

总计: 80个工具 实现全面的编辑器控制。

📖 查看完整工具文档 了解详细的使用示例和参数。

工具使用示例

创建新的精灵节点

{
  "tool": "node_create_node",
  "arguments": {
    "name": "MySprite",
    "nodeType": "2DNode",
    "parentUuid": "parent-node-uuid"
  }
}

添加 Sprite 组件

{
  "tool": "component_add_component",
  "arguments": {
    "nodeUuid": "node-uuid",
    "componentType": "cc.Sprite"
  }
}

实例化预制体

{
  "tool": "prefab_instantiate_prefab",
  "arguments": {
    "prefabPath": "db://assets/prefabs/Enemy.prefab",
    "position": { "x": 100, "y": 200, "z": 0 }
  }
}

在浏览器中运行项目

{
  "tool": "project_run_project",
  "arguments": {
    "platform": "browser"
  }
}

配置

设置存储在 您的项目/settings/mcp-server.json 中：

{
  "port": 3000,
  "autoStart": false,
  "enableDebugLog": true,
  "allowedOrigins": ["*"],
  "maxConnections": 10
}

图标设置

为插件面板添加图标：

创建 PNG 图标文件（推荐尺寸：32x32 或 64x64）
将其放在 static/ 目录中：static/icon.png
图标路径已在 package.json 中配置

开发

项目结构

cocos-mcp-server/
├── source/                    # TypeScript 源文件
│   ├── main.ts               # 插件入口点
│   ├── mcp-server.ts         # MCP 服务器实现
│   ├── settings.ts           # 设置管理
│   ├── types/                # TypeScript 类型定义
│   ├── tools/                # 工具实现
│   └── panels/               # UI 面板实现
├── dist/                     # 编译后的 JavaScript 输出
├── static/                   # 静态资源（图标等）
├── i18n/                     # 国际化文件
├── package.json              # 插件配置
└── tsconfig.json             # TypeScript 配置

从源码构建

# 安装依赖
npm install

# 开发构建（监视模式）
npm run watch

# 生产构建
npm run build

添加新工具

在 source/tools/ 中创建新的工具类
实现 ToolExecutor 接口
将工具添加到 mcp-server.ts 初始化中
工具会自动通过 MCP 协议暴露

TypeScript 支持

插件完全使用 TypeScript 编写，具备：

启用严格类型检查
为所有 API 提供全面的类型定义
开发时的 IntelliSense 支持
自动编译为 JavaScript

故障排除

常见问题

服务器无法启动: 检查端口可用性和防火墙设置
工具不工作: 确保场景已加载且 UUID 有效
构建错误: 运行 npm run build 检查 TypeScript 错误
连接问题: 验证 HTTP URL 和服务器状态

调试模式

在插件面板中启用调试日志以获取详细的操作日志。

使用调试工具

{
  "tool": "debug_get_console_logs",
  "arguments": {"limit": 50, "filter": "error"}
}

{
  "tool": "debug_validate_scene",
  "arguments": {"checkMissingAssets": true}
}

系统要求

Cocos Creator 3.8.0 或更高版本
Node.js（Cocos Creator 自带）
TypeScript（作为开发依赖安装）

许可证

本插件供 Cocos Creator 项目使用,并且源代码一并打包，可以用于学习和交流。没有加密。可以支持你自己二次开发优化，任何本项目代码或者衍生代码均不能用于任何商用、转售，如果需要商用，请联系本人。

7.9 KiB Executable File Raw Blame History Unescape Escape