Files

T

mingyuansi b65a4f22c3 fix: Windows spawn, prefab path, preview API, asset deps, error messages; add execute-context resource, tool descriptions, scene/script/asset tools

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

2026-06-30 21:53:06 +08:00

4.9 KiB

Raw Blame History

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

Clone the repository:

git clone https://github.com/FunplayAI/funplay-cocos-mcp.git
cd funplay-cocos-mcp

Install it into a Cocos project as an extension:

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.

Restart Cocos Creator or reload extensions.
Open the panel:

Funplay > MCP Server

Validation

Before opening a pull request, run:

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:

curl -sS http://127.0.0.1:8765/health

If you use a custom port, replace 8765 with your configured port.

Project Structure

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:

Add the tool definition in lib/tool-registry.js.
Use profile: "core" only for high-signal tools.
Put scene/runtime work behind sceneBridge.call(...) when it must run in the active Cocos scene.
Use editor-side helpers for asset-db, filesystem, and panel/client configuration workflows.
Return JSON-serializable data where possible.
Add clear input schema descriptions so AI clients can choose the tool correctly.
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:

Create the template file at resources/template.<ext> (e.g. resources/template.scene).
Add "resources/" to the files array in package.json so it ships in the npm package.
In the tool handler, read the template with fs.readFileSync, optionally replace _name fields, then call create-asset with the content string.
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.

4.9 KiB Raw Blame History