# 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`.

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