mingyuansi
b65a4f22c3
Bug fixes (verified against Cocos Creator 3.8.8): - diagnostics: shell:true for .cmd/.bat on Windows (T125/T126) - prefabs: duplicatePrefab target resolves under assets/ (T420) - cocos-project: add preview.open candidate for 3.8.8 (T444) - assets-advanced: detect directory assets in inspectAssetDependencies (T110) - scene: improve component-not-found errors with compilation hint (T429) Documentation improvements: - tool-registry: add enum and injected vars to execute_javascript, path format examples, asset ref limitation note - resources: add cocos://mcp/execute-context resource with variables, patterns, pitfalls New tools (core 37->38, full 101->110): - scene-management: create_scene, query_scene_state (core), copy_paste_node, rename_node, reparent_node - scripts: create_script with component/plain templates - prefabs: create_prefab - assets-advanced: batch_asset_ops, find_unused_assets
142 lines
4.9 KiB
Markdown
142 lines
4.9 KiB
Markdown
# Contributing to Funplay MCP for Cocos
|
|
|
|
Thanks for your interest in contributing to Funplay MCP for Cocos.
|
|
|
|
This repository is a Cocos Creator editor extension that embeds an MCP server. Contributions that improve reliability, editor compatibility, documentation, and AI-driven Cocos workflows are welcome.
|
|
|
|
## Development Setup
|
|
|
|
1. Clone the repository:
|
|
|
|
```bash
|
|
git clone https://github.com/FunplayAI/funplay-cocos-mcp.git
|
|
cd funplay-cocos-mcp
|
|
```
|
|
|
|
2. Install it into a Cocos project as an extension:
|
|
|
|
```bash
|
|
mkdir -p /path/to/your-cocos-project/extensions
|
|
ln -s "$PWD" /path/to/your-cocos-project/extensions/funplay-cocos-mcp
|
|
```
|
|
|
|
You can also copy the repository folder instead of using a symlink.
|
|
|
|
3. Restart Cocos Creator or reload extensions.
|
|
|
|
4. Open the panel:
|
|
|
|
```text
|
|
Funplay > MCP Server
|
|
```
|
|
|
|
## Validation
|
|
|
|
Before opening a pull request, run:
|
|
|
|
```bash
|
|
npm run check
|
|
```
|
|
|
|
This validates the JavaScript syntax for the extension entry points and helper modules.
|
|
|
|
If your change affects live MCP behavior, also test against a running Cocos project:
|
|
|
|
```bash
|
|
curl -sS http://127.0.0.1:8765/health
|
|
```
|
|
|
|
If you use a custom port, replace `8765` with your configured port.
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
browser.js Cocos browser/editor extension entry and service lifecycle
|
|
scene.js Scene-side execution bridge and scene tool implementations
|
|
panel/index.js Minimal MCP Server panel UI
|
|
lib/server.js HTTP JSON-RPC MCP server
|
|
lib/tool-registry.js Tool definitions and handlers
|
|
lib/resources.js MCP resources
|
|
lib/prompts.js MCP prompts
|
|
lib/client-config.js One-click MCP client configuration
|
|
lib/assets.js Asset database helpers
|
|
lib/diagnostics.js TypeScript diagnostics
|
|
lib/input.js Electron input simulation
|
|
lib/screenshots.js Screenshot helpers
|
|
```
|
|
|
|
## Contribution Guidelines
|
|
|
|
- Keep the `core` profile focused. Avoid adding noisy tools to `core` unless they are broadly useful for AI clients.
|
|
- Prefer improving `execute_javascript` workflows when one flexible tool is better than many narrow tools.
|
|
- Add tools to `full` when they are useful but not essential for the default AI workflow.
|
|
- Keep the Cocos panel simple. The main panel should focus on service management and MCP client configuration.
|
|
- Avoid adding runtime dependencies to built games; this extension should remain editor-only.
|
|
- Keep changes small and focused.
|
|
- Update `README.md`, `README_CN.md`, or `CHANGELOG.md` when behavior changes.
|
|
- Do not commit generated Cocos folders such as `library/`, `temp/`, or build output.
|
|
|
|
## Tool Design Notes
|
|
|
|
When adding a new tool:
|
|
|
|
1. Add the tool definition in `lib/tool-registry.js`.
|
|
2. Use `profile: "core"` only for high-signal tools.
|
|
3. Put scene/runtime work behind `sceneBridge.call(...)` when it must run in the active Cocos scene.
|
|
4. Use editor-side helpers for asset-db, filesystem, and panel/client configuration workflows.
|
|
5. Return JSON-serializable data where possible.
|
|
6. Add clear input schema descriptions so AI clients can choose the tool correctly.
|
|
7. Test the tool with `tools/list` and `tools/call`.
|
|
|
|
### Asset Creation via Template Files
|
|
|
|
When a tool creates a new Cocos asset with a complex serialized format
|
|
(scene, prefab, animation clip, material, etc.), **store a template file in
|
|
`resources/` and pass its content to `asset-db: create-asset`** rather than
|
|
hard-coding JSON strings in source.
|
|
|
|
Why:
|
|
|
|
- Cocos serialized formats are version-specific and contain many required
|
|
sub-objects (e.g. a scene needs `cc.SceneGlobals` → `cc.AmbientInfo`,
|
|
`cc.ShadowsInfo`, `cc.SkyboxInfo`, `cc.FogInfo`, `cc.OctreeInfo`,
|
|
`cc.SkinInfo`, `cc.LightProbeInfo`, `cc.PostSettingsInfo`). Missing or
|
|
misnamed classes cause silent import failures or runtime errors.
|
|
- A real template file can be created/verified in the Cocos editor and
|
|
updated by simply replacing the file.
|
|
- `asset-db: create-asset(url, content)` handles `.meta` generation and
|
|
import in one step — no need for `fs.writeFileSync` + `refreshAssets`.
|
|
|
|
Pattern:
|
|
|
|
1. Create the template file at `resources/template.<ext>` (e.g.
|
|
`resources/template.scene`).
|
|
2. Add `"resources/"` to the `files` array in `package.json` so it ships
|
|
in the npm package.
|
|
3. In the tool handler, read the template with `fs.readFileSync`, optionally
|
|
replace `_name` fields, then call `create-asset` with the content string.
|
|
4. Export a pure helper (e.g. `buildSceneContent`) for unit testing.
|
|
|
|
## Documentation
|
|
|
|
The documentation is bilingual:
|
|
|
|
- `README.md` for English
|
|
- `README_CN.md` for Chinese
|
|
|
|
When adding user-facing behavior, update both files when possible.
|
|
|
|
## Pull Requests
|
|
|
|
A good pull request should include:
|
|
|
|
- A clear summary of the change
|
|
- What Cocos Creator version was tested
|
|
- Whether the MCP server was tested through an AI client or direct HTTP calls
|
|
- Any screenshots if the change affects the panel or visual scene output
|
|
- Notes about compatibility or limitations
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the MIT License used by this repository.
|