cocos-mcp

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

🇺🇸 English

🔐 商业授权项目 · 源码闭源 需要试用 / 合作 / 定制：📧 2282059276@qq.com 旧版本（≤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

仓库为私有仓库。先联系作者获取访问权限（邮箱：2282059276@qq.com）。

# 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

<details> <summary><b>Claude Code（推荐）</b></summary>

一行命令注册：

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

重启 Claude Code 生效。

</details>

<details> <summary><b>Claude Desktop</b></summary>

编辑配置文件（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"]
    }
  }
}

</details>

<details> <summary><b>Cursor</b></summary>

编辑 ~/.cursor/mcp.json：

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

</details>

<details> <summary><b>Windsurf</b></summary>

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

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

</details>

<details> <summary><b>VS Code（含 GitHub Copilot Chat）</b></summary>

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

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

</details>

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…

<details> <summary><b>UUID / 项目 / 资源（15 工具）</b></summary>

• 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 </details>

<details> <summary><b>场景节点 + 基础组件（16 工具）</b></summary>

• 节点：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（通用） </details>

<details> <summary><b>2D 物理（12 工具）</b></summary>

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

<details> <summary><b>3D 物理 + 渲染（18 工具）</b></summary>

• 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 </details>

<details> <summary><b>UI 组件 + 模式预设 + 响应式（29 工具）</b></summary>

• 经典组件（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 </details>

<details> <summary><b>动画 + 主题 + UI Lint（11 工具）</b></summary>

• 入场动画（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） </details>

<details> <summary><b>🔁 Playwright 闭环反馈（8 工具）</b></summary>

让 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。 </details>

<details> <summary><b>🎯 游戏脚手架（9 工具）</b></summary>

生成 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 } 注解。 </details>

<details> <summary><b>媒体 / 骨骼 / 粒子 / 瓦片（14 工具）</b></summary>

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

<details> <summary><b>场景工具 + Prefab + 批量操作（12 工具）</b></summary>

• 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） </details>

<details> <summary><b>🏭 构建 + 发布 + 构建后补丁（11 工具）</b></summary>

• 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 等） </details>

💡 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 即可玩。

<details> <summary><b>3D 滚球 Demo（mini 代码）</b></summary>

# 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)

</details>

🏭 商业化发布

<details> <summary><b>iOS / Android 原生打包</b></summary>

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
)

</details>

<details> <summary><b>Asset Bundle</b></summary>

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

</details>

<details> <summary><b>微信小游戏分包（4 MB 主包分包）</b></summary>

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

</details>

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

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 预检。

</details>

⚡ 性能调优

旋钮	默认	效果
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

<details> <summary><b>找不到 Cocos Creator 安装</b></summary>

默认扫描 /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

</details>

<details> <summary><b>构建超时</b></summary>

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

cocos_build(project, timeout_sec=900)

</details>

<details> <summary><b>场景组件不生效（但构建成功）</b></summary>

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

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

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

</details>

<details> <summary><b>微信小游戏 appid 被重置</b></summary>

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 走，换机器 / 队友不会丢。

</details>

📊 质量保障

• 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

Proprietary · All Rights Reserved · Copyright © heitugongzuoshi

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

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

---

商业授权 / 合作 / 定制

📧 2282059276@qq.com

服务内容：

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