Cocos

Бесплатно

A headless MCP server that enables AI to create complete 2D/3D games in Cocos Creator without opening the editor or writing TypeScript code, featuring 184 tools

автор: chenShengBiao

GitHub

Описание

A headless MCP server that enables AI to create complete 2D/3D games in Cocos Creator without opening the editor or writing TypeScript code, featuring 184 tools for scene building, physics, UI, and automated testing.

README

无头 Cocos Creator 3.8 MCP 服务器 —— 让 AI 不打开编辑器、不写一行 .ts 代码，30 分钟内交付一个能跑能玩的完整 2D / 基础 3D 小游戏。

🇺🇸 English

🔐 商业授权项目 · 源码闭源 需要试用 / 合作 / 定制：📧 [email protected] 旧版本（≤v1.1.0）以 MIT 开源，现版本起转闭源。

✨ 核心能力

🎮 完全 Headless —— 直接读写 .scene / .prefab / .meta JSON，不依赖编辑器 GUI；业界唯一
⚡ 一句话交付游戏 —— "做一个 Flappy Bird" / "做 2048" / "做一个带物理的平台跳跃"，AI 自动调 184 工具完成全流程
🔁 Playwright 闭环反馈 —— AI 能点击 / 按键 / 读状态 / 视觉 diff，"自己玩自己做的游戏"
🎯 9 个游戏逻辑脚手架 —— player / enemy / spawner / game_loop / input / score / audio / camera_follow / ui_screen，canonical TypeScript 模板直接挂节点
🎨 5 内置 UI 主题 + 6 UI 模式预设 —— dark_game / neon_arcade / pastel_cozy / ...；add_dialog_modal / add_main_menu / add_hud_bar 一次搭完整 UI 块
🏭 一键多端发布 —— iOS / Android 原生包 + Asset Bundle + 微信小游戏分包 + 构建后补丁

📋 Requirements

Cocos Creator 3.8+（测试过 3.8.6）
Python 3.11 或 3.12
任意 MCP 客户端：Claude Desktop · Claude Code · Cursor · Windsurf · VS Code

🚀 Quick Start

仓库为私有仓库。先联系作者获取访问权限（邮箱：[email protected]）。

# 1. 克隆（用你的访问凭证）
git clone https://gitee.com/csbcsb/cocos-mcp.git ~/.claude/mcp-servers/cocos-mcp

# 2. 装依赖
cd ~/.claude/mcp-servers/cocos-mcp
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install .

# 3. 注册到你的 MCP 客户端（见下方 Client Configuration）

然后重启客户端，直接说：

"做一个贪吃蛇游戏" "做一个带物理碰撞的平台跳跃" "把这个角色 prefab 在场景里实例化 10 个" "打包成微信小游戏，levels/ 走分包"

⚙️ Client Configuration

Claude Code（推荐）

一行命令注册：

claude mcp add -s user cocos-mcp -- bash ~/.claude/mcp-servers/cocos-mcp/run.sh

重启 Claude Code 生效。

Claude Desktop

编辑配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "cocos-mcp": {
      "command": "bash",
      "args": ["/Users/YOU/.claude/mcp-servers/cocos-mcp/run.sh"]
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "cocos-mcp": {
      "command": "bash",
      "args": ["/Users/YOU/.claude/mcp-servers/cocos-mcp/run.sh"]
    }
  }
}

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "cocos-mcp": {
      "command": "bash",
      "args": ["/Users/YOU/.claude/mcp-servers/cocos-mcp/run.sh"]
    }
  }
}

VS Code（含 GitHub Copilot Chat）

在项目根或 ~/.vscode/settings.json 里：

{
  "mcp": {
    "servers": {
      "cocos-mcp": {
        "type": "stdio",
        "command": "bash",
        "args": ["/Users/YOU/.claude/mcp-servers/cocos-mcp/run.sh"]
      }
    }
  }
}

Windows 用户：把 bash /path/to/run.sh 换成 cmd /c /path/to/run.bat，或直接用 python server.py 启动（需先激活 venv）。

🔄 升级

已经装过的用户拉新版本（以默认安装路径 ~/.claude/mcp-servers/cocos-mcp 为例）：

cd ~/.claude/mcp-servers/cocos-mcp
git pull
uv pip install --python .venv/bin/python .   # 同步依赖（pyproject 可能新增包）

然后 完整重启 MCP 客户端（Claude Code / Desktop / Cursor / ...）。理由：MCP server 是常驻子进程，Python 代码已加载进内存；不重启客户端就还在跑旧版本。

快速校验本地安装没坏：

~/.claude/mcp-servers/cocos-mcp/.venv/bin/python -c "import cocos, server; print('import OK')"

Windows 用户：把 .venv/bin/python 换成 .\.venv\Scripts\python.exe。

🧰 Tools (184 total)

启动时 stderr 会打印实际注册数量：cocos-mcp: N tools registered…

UUID / 项目 / 资源（15 工具）

UUID：new_uuid / compress_uuid（生成 23 字符短形式）/ decompress_uuid
项目：list_creator_installs / init_project / get_project_info / list_assets
资源：add_script / add_image / add_audio_file / add_resource_file / upgrade_image_meta / set_sprite_frame_border（9-slice）/ get_sprite_frame_uuid / constants

场景节点 + 基础组件（16 工具）

节点：create_scene / create_node / move_node / delete_node / duplicate_node / set_node_position/scale/rotation/active/layer / find_node_by_name / list_scene_nodes
基础组件：add_uitransform / add_sprite / add_label / add_graphics / add_widget / add_component（通用）

2D 物理（12 工具）

add_rigidbody2d + 3 种 Collider（Box / Circle / Polygon）
全套 8 种 Joint2D：Distance / Fixed / Hinge / Spring / Mouse / Slider / Wheel / Relative
set_physics_2d_config（重力 / 睡眠阈值 / 子步数）

3D 物理 + 渲染（18 工具）

3D 物理：add_rigidbody_3d + 8 种 Collider（Box / Sphere / Capsule / Cylinder / Cone / Plane / Mesh / Terrain）+ 2 种 CharacterController + set_physics_3d_config + create_physics_material
3D 渲染：add_directional_light / add_sphere_light / add_spot_light / add_mesh_renderer / add_skinned_mesh_renderer
所有字段默认值逐一对齐 cocos-engine v3.8.6 源码，ERigidBodyType.DYNAMIC=1 / STATIC=2 / KINEMATIC=4 这类 bitmask 都有 regression test

UI 组件 + 模式预设 + 响应式（29 工具）

经典组件（13）：Button / Layout / ProgressBar / ScrollView / Toggle / EditBox / Slider / PageView / ToggleContainer / MotionStreak / ScrollBar / PageViewIndicator / WebView
UI 模式预设（6）：add_dialog_modal / add_main_menu / add_hud_bar / add_card_grid / add_toast / add_loading_spinner —— AI 一次搭完整 UI 块
响应式助手（5）：make_fullscreen / anchor_to_edge / center_in_parent / stack_vertically / stack_horizontally —— 告别 Widget bitmask
文本合成（1）：add_styled_text_block —— 标题 + 副标题 + 分割线 + 正文
渲染扩展（4）：Camera / Mask / RichText / 9-slice Sprite / Tiled Sprite / Filled Sprite

动画 + 主题 + UI Lint（11 工具）

入场动画（6）：add_fade_in / add_slide_in / add_scale_in / add_bounce_in / add_pulse / add_shake
UI 主题（4）：set_ui_theme（5 内置：dark_game / light_minimal / neon_arcade / pastel_cozy / corporate）/ get_ui_tokens / list_builtin_themes / hex_to_rgba
UI 质量 lint（1）：cocos_lint_ui —— 8 条规则（touch target / 长文本剪字 / UI layer / WCAG 对比度 / 按钮重叠 / 字号框 / 按钮多无 Layout / 嵌套 Mask）

🔁 Playwright 闭环反馈（8 工具）

让 AI 真正能"玩"自己做的游戏：

cocos_click_preview / cocos_press_key_preview / cocos_drag_preview
cocos_fill_preview（文字输入）
cocos_read_state_preview（读任意 JS 表达式，如 window.game.score）
cocos_wait_preview / cocos_run_preview_sequence（序列批执行）
cocos_screenshot_preview_diff（纯 Pillow 视觉回归，不依赖 Playwright）

Playwright 是可选依赖（~200 MB chromium），没装时工具返回明确的 install hint。

🎯 游戏脚手架（9 工具）

生成 canonical .ts 模板，返回压缩 UUID 直接挂节点：

scaffold_input_abstraction —— WASD + 方向键 + 触屏统一成 InputManager 单例
scaffold_score_system —— 当前/最高分 + localStorage + Label 自动渲染
scaffold_player_controller —— 4 kinds：platformer / topdown / flappy / click_only
scaffold_enemy_ai —— 3 kinds：patrol / chase / shoot
scaffold_spawner —— 2 kinds：time 定时 / proximity 靠近触发
scaffold_game_loop —— menu / play / over 状态机
scaffold_audio_controller / scaffold_camera_follow / scaffold_ui_screen

所有模板字段都走 @property 让 Inspector 可调；numeric 字段带 { tooltip } 注解。

媒体 / 骨骼 / 粒子 / 瓦片（14 工具）

媒体：AudioSource / Animation / ParticleSystem2D / VideoPlayer
骨骼动画：Spine + 资源导入 / DragonBones + 资源导入
TiledMap：TiledMap / TiledLayer / TMX 资源导入
AI 素材生成：generate_asset（CogView-3-Flash / Pollinations，SHA-256 缓存）/ create_sprite_atlas
AnimationClip 关键帧生成器

场景工具 + Prefab + 批量操作（12 工具）

Prefab：create_prefab / instantiate_prefab（带 fileId 唯一化）/ save_subtree_as_prefab
场景：validate_scene / audit_scene_modules（组件 vs 引擎模块一致性）/ get_object / get_object_count / list_scene_nodes
batch_scene_ops：一次 read/write 跑多个 op；27 种 op 类型；实测 200 工具调用 4293ms → 33ms（130x）
场景全局：set_ambient / set_skybox / set_shadows / set_fog（LINEAR / EXP / EXP² / LAYERED）

🏭 构建 + 发布 + 构建后补丁（11 工具）

cocos_build：headless 构建 web-mobile / wechatgame / ios / android，带 source_maps / md5_cache / skip_compress_texture / inline_enum / mangle_properties
cocos_start_preview / stop_preview / preview_status
构建后补丁（4）：register_post_build_patch / list / remove / apply —— 声明式 json_set / regex_sub / copy_from，cocos_build 成功后自动应用，跟着 git 走
项目设置：set_native_build_config（iOS/Android 包名/签名/朝向/icon）/ set_bundle_config / set_wechat_subpackages（4 MB 主包分包）
引擎模块：get_engine_modules / set_engine_module（开关 physics-2d-box2d / spine / video 等）

💡 Examples

仓库自带 3 个一键运行的演示项目：

.venv/bin/python examples/flappy-bird/build_flappy.py /tmp/flappy --port 8080
.venv/bin/python examples/click-counter/build_click_counter.py /tmp/click --port 8081
.venv/bin/python examples/breakout/build_breakout.py

运行后打开 http://localhost:8080 即可玩。

3D 滚球 Demo（mini 代码）

# 1. 初始化 + 开启 3D 物理（默认 gravity = -10 m/s² 不是 -320 像素）
cocos_init_project("/tmp/roll3d")
cocos_set_physics_3d_config("/tmp/roll3d", gravity_y=-9.8)

# 2. 造个有摩擦系数的物理材质
ice = cocos_create_physics_material("/tmp/roll3d", "ice", friction=0.02, restitution=0.3)

# 3. 场景：Ball + Ground + 方向光
scene = cocos_create_scene("/tmp/roll3d/assets/scenes/game.scene")
canvas = scene["canvas_node_id"]

sun = cocos_create_node(scene_path, canvas, "Sun")
cocos_add_directional_light(scene_path, sun, illuminance=65000, shadow_enabled=True)

ball = cocos_create_node(scene_path, canvas, "Ball", lpos=[0, 5, 0])
cocos_add_rigidbody_3d(scene_path, ball, body_type=1)      # DYNAMIC=1（bitmask）
col = cocos_add_sphere_collider_3d(scene_path, ball, radius=0.5)
cocos_set_uuid_property(scene_path, col, "_material", ice["uuid"])

# 4. 雾 + release 构建
cocos_set_fog(scene_path, enabled=True, fog_type=1, density=0.05)  # EXP
cocos_build("/tmp/roll3d", debug=False, md5_cache=True)

🏭 商业化发布

iOS / Android 原生打包

cocos_set_native_build_config(
    project, "android",
    package_name="com.foo.game",
    orientation="landscape",
    android_min_api=21, android_target_api=33,
    android_use_debug_keystore=False,
    android_keystore_path="/keys/release.jks",
    android_keystore_password="…",
    android_keystore_alias="prod",
    android_keystore_alias_password="…",
    android_app_bundle=True,   # 出 .aab
)

Asset Bundle

# 把 assets/levels/ 标记成 Bundle，运行时 cc.assetManager.loadBundle('levels')
cocos_set_bundle_config(project, "assets/levels",
    compression_type={"web-mobile": "merge_dep", "wechatgame": "subpackage"})

微信小游戏分包（4 MB 主包分包）

cocos_set_wechat_subpackages(project, [
    {"name": "level1", "root": "assets/levels/world1"},
    {"name": "audio", "root": "assets/audio"},
])

构建后补丁 —— 解决 build/ 每次重生成被刷掉的问题

Cocos 每次构建都会重新生成 build/<platform>/，手动改的 style.css / project.config.json 全被刷掉。通过声明式补丁登记一次，之后每次构建自动应用：

cocos_register_post_build_patch(project, patches=[
    # ① JSON 精准 key 覆盖（解决 WeChat appid 被重置）
    {"platform": "wechatgame", "file": "project.config.json",
     "kind": "json_set", "path": "appid", "value": "wx000000000000demo"},

    # ② 正则替换
    {"platform": "web-mobile", "file": "style.css",
     "kind": "regex_sub",
     "find": r"background:\s*#[0-9a-fA-F]{3,6}",
     "replace": "background: #1c2833"},

    # ③ 整文件覆盖
    {"platform": "web-mobile", "file": "index.html",
     "kind": "copy_from", "source": "custom/index.html"},
])

安全阀：regex 编译预检 + 路径注入防御（拒绝 .. / 绝对路径）+ drift 保护（正则不匹配报错而非静默跳过）+ dry_run=True 预检。

⚡ 性能调优

旋钮	默认	效果
`cocos_batch_scene_ops`	—	一次 read/write 跑多个 op；200 工具调用 4293ms → 33ms（130x）
场景读缓存	on	按绝对路径 + `st_mtime_ns` LRU(8) 缓存；外部写盘自动失效
Creator 安装缓存	on	`list_creator_installs` 走 `functools.lru_cache`，session 内不重复扫
`COCOS_CREATOR_PATH`	—	指定 Creator 版本目录，优先级最高（CI / Docker）
`COCOS_CREATOR_EXTRA_ROOTS`	—	追加扫描路径（POSIX `:` / Windows `;` 分隔）
`COCOS_MCP_SCENE_COMPACT=1`	off	scene 写盘 compact JSON（500 对象 -41% 大小）
Pillow lazy-import	—	不触发图片操作的工具不需要 Pillow

🎯 AI 友好度 / 可靠性护栏

结构化错误 —— cocos_build 失败返回 {error_code, hint}，9 种类型（BUILD_TYPESCRIPT_ERROR / BUILD_MISSING_MODULE / BUILD_ASSET_NOT_FOUND / BUILD_TIMEOUT / ...）
TS 错误结构化 —— BuildResult 带 ts_errors: [{file, line, col, code, message}]，AI 直接 Read+Edit
场景预检 —— audit_scene_modules 扫组件 vs engine.json，返回可复制的 cocos_set_engine_module 命令链
引擎模块映射表 —— 内置 COMPONENT_REQUIRES_MODULE（30+ 条）
脚本 UUID 幂等 —— add_script 接受 23 / 36 字符 UUID，re-add 保持 UUID 不变
构建后补丁 —— drift 保护 + 首个失败止损
TypedDict 契约 —— BuildResult / ValidationResult / BatchOpsResult 8 个 TypedDict，改字段忘同步自动失败

🐛 Troubleshooting

找不到 Cocos Creator 安装

默认扫描 /Applications/Cocos/Creator (macOS) 或 %LOCALAPPDATA%\Programs\CocosDashboard\resources\.editors (Windows)。如果路径非标：

export COCOS_CREATOR_PATH=/custom/path/to/CocosCreator.app
# 或追加扫描目录
export COCOS_CREATOR_EXTRA_ROOTS=/opt/cocos:/shared/editors

构建超时

首次构建 Creator 要 import 所有资源，可能超过默认 5 分钟。显式传 timeout：

cocos_build(project, timeout_sec=900)

场景组件不生效（但构建成功）

多半是组件需要的引擎模块没启用。跑：

cocos_audit_scene_modules(scene_path)
# → { ok: false, disabled: ["physics-2d"], actions: [...] }

把 actions 里的命令复制粘贴跑一遍即可。

微信小游戏 appid 被重置

Creator 每次重写 project.config.json。用构建后补丁：

cocos_register_post_build_patch(project, patches=[
    {"platform": "wechatgame", "file": "project.config.json",
     "kind": "json_set", "path": "appid", "value": "wx000000000000demo"},
])

跟着 git 走，换机器 / 队友不会丢。

📊 质量保障

741 pytest 单元测试，本地 < 15s 跑完
GitHub Actions CI 矩阵：Ubuntu / macOS / Windows × Python 3.11 / 3.12
mypy cocos/ 0 errors
ruff check 0 errors
所有 3D 组件字段默认值逐一对齐 cocos-engine v3.8.6 源码（含 regression 测试锁定）
跨平台：所有外部进程调用走 sys.executable / socket / tempfile.gettempdir()

🔐 Security & Privacy

所有操作本地文件 I/O，不上传项目代码
generate_asset 默认走 CogView-3-Flash 国内免费 API；可切 Pollinations 或本地模型
Playwright 闭环反馈仅访问本地 preview server
无任何遥测 / 埋点

📂 项目结构（简）

cocos-mcp/
├── server.py                 # MCP 入口（60 行 FastMCP + tools.register_all）
├── run.sh / run.bat
├── cocos/
│   ├── tools/                # MCP 工具薄包装，10 模块
│   ├── scene_builder/        # 场景 JSON 构造（physics / ui / ui_patterns / prefab ...）
│   ├── project/              # 资源导入 / UI token / 构建后补丁
│   ├── scaffolds/            # 9 个游戏逻辑 .ts 模板
│   ├── build.py              # CLI 构建 + 跨平台预览
│   ├── interact.py           # Playwright 闭环反馈
│   ├── gen_asset.py          # AI 生图（CogView / Pollinations + 缓存）
│   ├── errors.py / types.py / uuid_util.py / meta_util.py
├── examples/                 # 3 个一键 demo
├── tests/                    # 741 pytest
└── .github/workflows/test.yml

📄 License

未经书面授权，不得复制、修改、分发、二次发布或将本项目用于任何商业用途。仅授权给已被邀请的协作者用于内部评估、试用与开发。

旧版本（≤v1.1.0）以 MIT 协议发布，相关分发已停止。本仓库当前版本（1.2-dev）起转为闭源。

商业授权 / 合作 / 定制

📧 [email protected]

服务内容：

商用授权（团队 / 公司）
定制开发（专属工具 / 特殊平台适配）
技术咨询（Cocos 3.8 AI 工作流 / headless CI 集成）
企业培训（AI + 游戏开发工作流）

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "cocos-mcp": {
      "command": "npx",
      "args": []
    }
  }
}

Cocos

Описание

README

✨ 核心能力

📋 Requirements

🚀 Quick Start

⚙️ Client Configuration

🔄 升级

🧰 Tools (184 total)

💡 Examples

🏭 商业化发布

⚡ 性能调优

🎯 AI 友好度 / 可靠性护栏

🐛 Troubleshooting

📊 质量保障

🔐 Security & Privacy

📂 项目结构（简）

📄 License

商业授权 / 合作 / 定制

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem

Command Palette

Cocos

Описание

README

✨ 核心能力

📋 Requirements

🚀 Quick Start

⚙️ Client Configuration

🔄 升级

🧰 Tools (184 total)

💡 Examples

🏭 商业化发布

⚡ 性能调优

🎯 AI 友好度 / 可靠性护栏

🐛 Troubleshooting

📊 质量保障

🔐 Security & Privacy

📂 项目结构（简）

📄 License

商业授权 / 合作 / 定制

Как установить

Похожие MCP

GitHub

Supabase

Everything

Filesystem