funplay-cocos-mcp/CONTRIBUTING.md

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:

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

2. 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.

3. Restart Cocos Creator or reload extensions.

4. 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:

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.

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.