{"_id":"@chantezy/cocos-bridge","_rev":"2-3daec225d8bc9dbdf823452bf6d91928","name":"@chantezy/cocos-bridge","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@chantezy/cocos-bridge","version":"0.1.0","keywords":["mcp","cocos-creator","game-design","bridge","model-context-protocol"],"author":{"name":"chantezy"},"license":"MIT","_id":"@chantezy/cocos-bridge@0.1.0","maintainers":[{"name":"chantezy","email":"fronter10@foxmail.com"}],"homepage":"https://github.com/chantezy/game-skills#readme","bugs":{"url":"https://github.com/chantezy/game-skills/issues"},"bin":{"cocos-bridge":"bin/cocos-bridge.js"},"dist":{"shasum":"abae002a9dfa7ef9be21da777adf9b216ac039bf","tarball":"https://registry.npmjs.org/@chantezy/cocos-bridge/-/cocos-bridge-0.1.0.tgz","fileCount":23,"integrity":"sha512-yUu07GmmMdhOPFwvNMXOtloAe9VRNePfk9L+FJR9rg/tmhMTkPWQITP44Qj6sD3gsUyHvtdxQfiVmUDOUwY00Q==","signatures":[{"sig":"MEQCICfn1n5W1DYPD71xTSubqbbGZQOpM5Uz9puREpkzTEgkAiB8XG1cpWBaO/p5uZS5NcWzk6j8fMdyIWglrJ3MkOGtvw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":310117},"main":"browser.js","panels":{"default":{"main":"panel/index.html","size":{"width":560,"height":420,"min-width":420,"min-height":360},"type":"dockable","title":"Cocos Bridge MCP"}},"engines":{"node":">=18"},"gitHead":"df8ab005f782a6f1fce07a4a2dc875069f72c50f","mcpName":"io.github.chantezy/cocos-bridge","scripts":{"check":"node --check browser.js && node --check scene.js && node --check bin/cocos-bridge.js && node --check lib/config.js && node --check lib/server.js && node --check lib/tool-registry.js && node --check lib/tool-profiles.js && node --check lib/interaction-log.js && node --check lib/runtime-log.js && node --check lib/javascript-safety.js && node --check lib/path-safety.js && node --check lib/utils.js && node --check lib/generators/index.js && node --check lib/generators/project-scaffold.js && node --check lib/generators/config-generator.js && node --check lib/generators/component-generator.js && node --check lib/generators/state-machine-generator.js"},"_npmUser":{"name":"chantezy","email":"fronter10@foxmail.com"},"repository":{"url":"git+https://github.com/chantezy/game-skills.git","type":"git","directory":"cocos mcp/cocos-bridge/src"},"_npmVersion":"11.11.0","description":"Cocos Bridge MCP — bridges game design documents to Cocos Creator 3.8 engine implementation. 17 intent-level tools + 1 fallback, dual-channel (stdio + HTTP).","directories":{},"_nodeVersion":"24.14.1","contributions":{"menu":[{"path":"Cocos Bridge/MCP Server","message":"open-panel"}],"scene":{"script":"scene.js"},"messages":{"open-url":{"methods":["openUrl"]},"call-tool":{"methods":["callToolFromPanel"]},"get-status":{"methods":["getStatus"]},"list-tools":{"methods":["listToolsForPanel"]},"open-panel":{"methods":["openPanel"]},"save-config":{"methods":["saveConfig"]},"stop-server":{"methods":["stopServer"]},"start-server":{"methods":["startServer"]},"restart-server":{"methods":["restartServer"]},"get-panel-state":{"methods":["getPanelState"]}}},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"package_version":2,"_npmOperationalInternal":{"tmp":"tmp/cocos-bridge_0.1.0_1784601202211_0.8214665044300364","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@chantezy/cocos-bridge","package_version":2,"version":"0.1.1","description":"Cocos Bridge MCP — bridges game design documents to Cocos Creator 3.8 engine implementation. 17 intent-level tools + 1 fallback, dual-channel (stdio + HTTP).","author":{"name":"chantezy"},"license":"MIT","main":"browser.js","bin":{"cocos-bridge":"bin/cocos-bridge.js"},"mcpName":"io.github.chantezy/cocos-bridge","repository":{"type":"git","url":"git+https://github.com/chantezy/cocos-bridge.git"},"keywords":["mcp","cocos-creator","game-design","bridge","model-context-protocol"],"engines":{"node":">=18"},"publishConfig":{"access":"public"},"scripts":{"check":"node --check browser.js && node --check scene.js && node --check bin/cocos-bridge.js && node --check lib/config.js && node --check lib/server.js && node --check lib/tool-registry.js && node --check lib/tool-profiles.js && node --check lib/interaction-log.js && node --check lib/runtime-log.js && node --check lib/javascript-safety.js && node --check lib/path-safety.js && node --check lib/utils.js && node --check lib/generators/index.js && node --check lib/generators/project-scaffold.js && node --check lib/generators/config-generator.js && node --check lib/generators/component-generator.js && node --check lib/generators/state-machine-generator.js"},"panels":{"default":{"title":"Cocos Bridge MCP","type":"dockable","main":"panel/index.html","size":{"min-width":420,"min-height":360,"width":560,"height":420}}},"contributions":{"menu":[{"path":"Cocos Bridge/MCP Server","message":"open-panel"}],"messages":{"open-panel":{"methods":["openPanel"]},"start-server":{"methods":["startServer"]},"stop-server":{"methods":["stopServer"]},"restart-server":{"methods":["restartServer"]},"get-status":{"methods":["getStatus"]},"get-panel-state":{"methods":["getPanelState"]},"save-config":{"methods":["saveConfig"]},"list-tools":{"methods":["listToolsForPanel"]},"call-tool":{"methods":["callToolFromPanel"]},"open-url":{"methods":["openUrl"]}},"scene":{"script":"scene.js"}},"gitHead":"8ccde06c35fb2ef4145a1daa48b22558ef1e71e0","_id":"@chantezy/cocos-bridge@0.1.1","bugs":{"url":"https://github.com/chantezy/cocos-bridge/issues"},"homepage":"https://github.com/chantezy/cocos-bridge#readme","_nodeVersion":"22.23.1","_npmVersion":"12.0.1","dist":{"integrity":"sha512-AkIJkppge8ZZNqcqdvB+ea1YPUYEw2T2eELDBkOUr2vJAFwG4+R3HJ86SSYpbKYgZ/j7X2mkUoMNdLZ7A9C3SQ==","shasum":"b898fb0e626f01f4643d276f3ef189eaa1a03d6e","tarball":"https://registry.npmjs.org/@chantezy/cocos-bridge/-/cocos-bridge-0.1.1.tgz","fileCount":23,"unpackedSize":310071,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@chantezy%2fcocos-bridge@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCnEamWJ2vhcGVkSnNIpzbKThApWk0NU7ndhzIE6u5TSQIgCn1rTBA6Jdkl3yP2uj2+HKIe9/joxdBzddQTB8nZbgw="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:25dc9b15-3562-4685-8234-6bfdc0f17320"}},"directories":{},"maintainers":[{"name":"chantezy","email":"fronter10@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cocos-bridge_0.1.1_1784604914170_0.012264215631000441"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T02:33:22.044Z","modified":"2026-07-21T03:35:14.674Z","0.1.0":"2026-07-21T02:33:22.354Z","0.1.1":"2026-07-21T03:35:14.357Z"},"bugs":{"url":"https://github.com/chantezy/cocos-bridge/issues"},"author":{"name":"chantezy"},"license":"MIT","homepage":"https://github.com/chantezy/cocos-bridge#readme","keywords":["mcp","cocos-creator","game-design","bridge","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/chantezy/cocos-bridge.git"},"description":"Cocos Bridge MCP — bridges game design documents to Cocos Creator 3.8 engine implementation. 17 intent-level tools + 1 fallback, dual-channel (stdio + HTTP).","maintainers":[{"name":"chantezy","email":"fronter10@foxmail.com"}],"readme":"# Cocos Bridge MCP\n\nCocos Creator 3.8 扩展 + MCP Server，将游戏策划案（GDD）直接转化为 Cocos Creator 工程文件、场景和代码。\n\n17 个意图级工具 + 1 个通用回退工具，聚焦「策划案 → 引擎实现」的桥接场景。每个工具封装了多个底层编辑器操作，AI 客户端一次调用即可完成原本需要多步编排的复杂任务。\n\n## 定位\n\nCocos Bridge 是 [game-design MCP](https://github.com/chantezy/game-skills) 的下游执行层：\n\n```\ngame-design MCP (策划案生成)\n    ↓ 输出: 配置表 Schema / 状态机定义 / 关卡配置 / UI 布局\nCocos Bridge MCP (引擎实现)\n    ↓ 输出: .ts 组件 / .json 配置 / 场景节点 / 状态机代码\nCocos Creator 3.8.8 工程\n```\n\n## 双通道架构\n\n| 通道 | 传输 | 依赖 | 工具范围 |\n|------|------|------|----------|\n| **A: stdio** | 本地进程 | 无需编辑器 | 生成器 (4) + 诊断 (3) + 资源 (3) |\n| **B: HTTP** | 编辑器扩展 | Cocos Creator 运行中 | 场景构建 (4) + 编辑器状态 (2) + 回退 (1) |\n\n通道 A 可独立使用——AI 客户端通过 stdio 协议直接调用生成器，无需打开 Cocos Creator。通道 B 需要编辑器扩展运行，提供场景操作和实时检查能力。\n\n## 工具清单\n\n### 生成器 (Generators) — 通道 A\n\n| 工具 | 输入 | 输出 |\n|------|------|------|\n| `generate_project_scaffold` | 游戏类型 + 架构 + 功能标志 | 完整项目目录结构 + tsconfig.json + 基础框架代码 |\n| `generate_config_files` | GDD Schema 定义 | JSON 配置文件 + TypeScript 接口 + ConfigLoader.ts |\n| `generate_component_scripts` | 组件定义 (属性列表) | @ccclass 组件 .ts 文件 + @property 装饰器 |\n| `generate_state_machine` | 状态枚举 + 转移规则 | State enum + StateMachine class + Transitions 模块 |\n\n### 场景构建 (Scene Builders) — 通道 B\n\n| 工具 | 输入 | 输出 |\n|------|------|------|\n| `build_scene_from_config` | 关卡配置 JSON | 场景节点层级 (地形/灯光/相机/出生点) |\n| `build_ui_layout` | UI 布局定义 | Canvas 下的 UI 节点树 + 组件绑定 |\n| `build_combat_setup` | 战斗场景配置 | 角色节点 + 碰撞体 + 相机跟随 + UI 面板 |\n| `populate_level_enemies` | 敌人刷新点列表 | 敌人 Prefab 实例 + 刷新逻辑脚本 |\n\n### 资源管理 (Resources) — 通道 A\n\n| 工具 | 输入 | 输出 |\n|------|------|------|\n| `import_and_organize_assets` | 源目录 + 命名规则 | 自动分类导入 (sprites/audio/prefabs...) |\n| `validate_asset_references` | 项目目录 | 断裂引用 + 孤立资产报告 |\n| `apply_naming_convention` | 目录 + 命名规范 | 批量重命名 + 规范校验报告 |\n\n### 诊断 (Diagnostics) — 通道 A\n\n| 工具 | 输入 | 输出 |\n|------|------|------|\n| `check_config_consistency` | 配置目录 | 字段类型/范围/引用一致性校验 |\n| `audit_project_health` | 项目目录 | 结构/资产/场景/脚本/配置全面体检 |\n| `inspect_scene_graph` | 场景文件路径 | 节点层级 + 组件 + 属性树 |\n\n### 编辑器状态 (Editor State) — 通道 B\n\n| 工具 | 输入 | 输出 |\n|------|------|------|\n| `get_project_context` | 无 | 项目路径/引擎版本/场景列表/脚本统计 |\n| `capture_scene_snapshot` | 无 | 当前场景节点树 + 组件 + 变换信息 |\n\n### 回退 (Fallback) — 通道 B\n\n| 工具 | 输入 | 输出 |\n|------|------|------|\n| `execute_script` | JavaScript 代码 | 在场景或编辑器上下文执行任意 JS |\n\n## 快速开始\n\n### 方式一：stdio 独立使用（无需 Cocos Creator）\n\n适合 AI 客户端直接调用生成器，在任意目录下产出 Cocos 项目文件：\n\n```bash\n# 全局安装\nnpm install -g @chantezy/cocos-bridge\n\n# 或在 MCP 客户端配置中添加\n```\n\nMCP 客户端配置示例：\n\n<details>\n<summary>QoderWork / Claude Desktop</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"cocos_bridge\": {\n      \"command\": \"cocos-bridge\",\n      \"args\": [\"--url\", \"http://127.0.0.1:8765/\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Cursor / VS Code</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"cocos_bridge\": {\n      \"command\": \"cocos-bridge\",\n      \"args\": [\"--url\", \"http://127.0.0.1:8765/\"]\n    }\n  }\n}\n```\n</details>\n\n如果只需使用通道 A（生成器），可以直接指向本地目录，不需要 `--url`：\n\n```json\n{\n  \"mcpServers\": {\n    \"cocos_bridge\": {\n      \"command\": \"cocos-bridge\"\n    }\n  }\n}\n```\n\n### 方式二：Cocos Creator 扩展（完整双通道）\n\n1. 将 `src/` 目录复制到 Cocos 项目的 `extensions/cocos-bridge/`：\n\n```bash\ncd /path/to/your-cocos-project\nmkdir -p extensions\ncp -r /path/to/cocos-bridge/src extensions/cocos-bridge\n```\n\n2. 重启 Cocos Creator，打开菜单 `Cocos Bridge > MCP Server`\n\n3. 在 MCP 客户端中配置 HTTP 连接：\n\n```json\n{\n  \"mcpServers\": {\n    \"cocos_bridge\": {\n      \"url\": \"http://127.0.0.1:8765/\"\n    }\n  }\n}\n```\n\n### 验证连接\n\n```bash\n# HTTP 健康检查\ncurl http://127.0.0.1:8765/health\n\n# 查看可用工具\ncurl http://127.0.0.1:8765/tools\n```\n\n## 与 game-design MCP 集成\n\nCocos Bridge 的每个工具都对应 game-design MCP 的特定技能输出：\n\n| game-design 技能 | 输出格式 | cocos-bridge 工具 |\n|------------------|----------|-------------------|\n| game-system-design | 系统规则 + 数值参数 | `generate_config_files` |\n| game-combat-design | 技能定义 + 伤害公式 | `generate_component_scripts`, `build_combat_setup` |\n| game-level-design | 关卡配置 + 敌人刷新 | `build_scene_from_config`, `populate_level_enemies` |\n| game-narrative-design | 对话系统 + 任务链 | `generate_state_machine` (对话状态机) |\n| game-character-design | 角色属性 + 成长曲线 | `generate_component_scripts`, `generate_config_files` |\n| game-numerical-design | 数值表 + 平衡参数 | `generate_config_files`, `check_config_consistency` |\n| game-tech-implementation | Schema + 状态机 + 映射 | 全部生成器工具 |\n| game-art-workflows | 美术规范 + 资源清单 | `import_and_organize_assets`, `apply_naming_convention` |\n| game-qa-testing | 测试用例 + 检查清单 | `audit_project_health`, `validate_asset_references` |\n| game-creative-discussion | 创意方向 + 核心循环 | `generate_project_scaffold` |\n| game-ui-design | UI 布局 + 交互流程 | `build_ui_layout` |\n\n## 配置\n\n在 Cocos 项目根目录创建 `cocos-bridge.config.json`：\n\n```json\n{\n  \"host\": \"127.0.0.1\",\n  \"port\": 8765,\n  \"toolProfile\": \"core\",\n  \"autostart\": true,\n  \"executeJavascriptSafetyChecks\": true,\n  \"enableSessions\": false\n}\n```\n\n环境变量：`COCOS_BRIDGE_HOST`、`COCOS_BRIDGE_PORT`、`COCOS_BRIDGE_PROFILE`、`COCOS_BRIDGE_URL`。\n\n`toolProfile` 可选值：`core`（默认，全部 17+1 工具）、`full`、`custom`（配合 `enabledTools`/`disabledTools` 精细控制）。\n\n## 项目结构\n\n```\nsrc/\n├── browser.js          # Cocos 扩展入口 (Channel B)\n├── scene.js            # 场景运行时桥接 (1596 行)\n├── bin/\n│   └── cocos-bridge.js # stdio CLI 入口 (Channel A)\n├── lib/\n│   ├── server.js       # HTTP MCP 服务器\n│   ├── tool-registry.js # 18 个工具定义 + handler\n│   ├── config.js       # 配置加载\n│   ├── utils.js        # 工具函数\n│   ├── javascript-safety.js  # JS 安全检查\n│   ├── path-safety.js        # 路径安全检查\n│   ├── interaction-log.js    # 交互日志\n│   ├── runtime-log.js        # 运行日志\n│   ├── tool-profiles.js      # 工具配置模板\n│   └── generators/\n│       ├── index.js\n│       ├── project-scaffold.js    # 项目脚手架 (1317 行)\n│       ├── config-generator.js    # 配置生成器\n│       ├── component-generator.js # 组件生成器\n│       └── state-machine-generator.js # 状态机生成器\n├── package.json\n├── README.md\n└── LICENSE\n```\n\n## 开发\n\n```bash\n# 语法检查\nnpm run check\n\n# 在项目中使用\ncd your-cocos-project\nnpm link @chantezy/cocos-bridge\n```\n\n## 已知限制与后续计划\n\nv0.1 聚焦核心桥接链路，以下功能计划在后续版本补充：\n\n- `manage_prefabs` — Prefab 创建/实例化/变体管理\n- `bind_animation_states` — 动画状态机与 FSM 状态绑定\n- `hot_reload_configs` — 配置热重载（编辑器运行时重新加载 JSON）\n- `generate_dialogue_system` — 对话系统完整实现（节点图 → Cocos 组件）\n- `validate_state_machine` — 状态机可达性/死锁/终止态静态分析\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}