Docs: add changelog and contributing guide
This commit is contained in:
winlifes
@@ -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.
|
||||||
+112
@@ -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.
|
||||||
Reference in New Issue
Block a user