From 05446c973d2aea5c5a8f6e1649c94fe05d7ee17e Mon Sep 17 00:00:00 2001 From: winlifes <110321103+Winlifes@users.noreply.github.com> Date: Wed, 15 Apr 2026 17:55:30 +0800 Subject: [PATCH] Docs: add changelog and contributing guide --- CHANGELOG.md | 56 ++++++++++++++++++++++++ CONTRIBUTING.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ab2e0ec --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,56 @@ +# Changelog + +All notable changes to Funplay MCP for Cocos will be documented in this file. + +This project follows a simple changelog format inspired by [Keep a Changelog](https://keepachangelog.com/), and uses semantic versioning when releases are tagged. + +## [0.1.0] - 2026-04-15 + +### Added + +- Embedded HTTP MCP server inside a Cocos Creator extension. +- `Funplay > MCP Server` editor panel for service management and one-click MCP client configuration. +- One-click configuration support for Claude Code / Claude Desktop, Cursor, VS Code, Trae, Kiro, and Codex. +- Primary unified tool: `execute_javascript`. + - `context: "scene"` for active scene/runtime automation. + - `context: "editor"` for Cocos editor/browser automation. +- Compatibility execution tools: + - `execute_scene_script` + - `execute_editor_script` +- MCP protocol capabilities: + - `initialize` + - `tools/list` + - `tools/call` + - `resources/list` + - `resources/read` + - `resources/templates/list` + - `prompts/list` + - `prompts/get` +- `core` tool profile with 50 high-signal tools. +- `full` tool profile with 67 tools. +- Scene and hierarchy inspection tools. +- Node, component, UI, camera, animation, prefab, and asset tools. +- File read/write/search tools and asset refresh helpers. +- TypeScript diagnostic tools for Cocos projects. +- Runtime state and time-scale control tools. +- Button, node event, component method, mouse, keyboard, and preview input simulation tools. +- Desktop, editor, scene, game, and preview screenshot tools. +- MCP resources for project context, scene state, selection, script errors, and interaction history. +- MCP prompts for script repair, playable prototype creation, scene validation, and scene auto-wiring. +- Debug logs for server lifecycle events. +- English and Chinese README files. +- MIT license file. + +### Changed + +- Promoted `execute_javascript` as the recommended primary tool across tool descriptions, prompts, and documentation. +- Simplified the Cocos panel to focus on service management and MCP client configuration. +- Changed the menu entry to `Funplay > MCP Server`. + +### Fixed + +- Fixed panel initialization issues caused by unsafe DOM querying. +- Fixed relative-path handling for asset open/select workflows. +- Fixed bundled Cocos TypeScript diagnostic lookup. +- Improved scene/game screenshot targeting with panel-level cropping when available. +- Improved low-level mouse drag coordinates for panel-relative input injection. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a8f94ad --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,112 @@ +# 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.