Cocos MCP Community

English | 简体中文

Una extensión del Model Context Protocol (MCP) construida por la comunidad para Cocos Creator 3.8+. Conecta un cliente de IA compatible para inspeccionar y operar el proyecto actualmente abierto en Cocos Creator.

La extensión se ejecuta localmente, escucha en 127.0.0.1 y requiere confirmación explícita para cambios persistentes o estructurales.

Versión actual: 0.2.3. La suite automatizada supera las verificaciones, y los flujos principais de lectura y de escritura aislada se han verificado con Cocos Creator 3.8.8.

Características

El servidor expone 23 herramientas MCP orientadas a intenciones. Cada herramienta agrupa acciones related to que clientes reciban un listado de herramientas en focalizado y, a la vez, mantienen amplia cobertura de editor.

Otras funcciones availables: Streamable HTTP compatible con sesión, notifación de changes in la "lista de herramientas", entradas extracted by esquema, pasos de confirmación, operaciones en lotes con reversión y presets de herramientas locales del proyecto.

Related MCP server: Cocos Creator MCP Server

Requisitos

• Cocos Creator 3.8 o posterior.

• Node.js 18 o posterior.

• npm.

• Un clien MCP compatible Con Streamable HTTP.

Instalación y uso

1. Instalar la extensión

Clona el repositorio en el directorio extensions del project Cocos, instala deps and compila:

cd /path/to/YourCocosProject/extensions
git clone <repository-url> cocos-mcp-community
cd cocos-mcp-community
npm ci
npm run build

Abra el proyecto in Cocos Creator. Si el editor ya estaba abierto, recarga las extensiones or reinicia el editor.

2. Iniciar el servidor MCP

Abra Extensión → Cocos MCP Community y selecciona Start server. El endpunto predeterminado es:

http://127.0.0.1:3100/mcp

El panel muestra el punto de conexión activo y el estado del servidor. También puedes cambiar el puerto local del proyecto o activar el inicio automático.

3. Connect an MCP client

Añada un servidor Streamable HTTP a la configuración MCP de tu cliente. La entrada genérica del servidor es:

{
  "type": "http",
  "url": "http://127.0.0.1:3100/mcp"
}

The rest of the configuration parameters differ by client. After the first connection, the client_config tool can generate complete entries for Claude Desktop, Cursor, VS Code, and Windsurf.

Restart or reconnect the MCP client after making configuration changes. If the server port changes in the Cocos panel, update the client URL as well.

4. Verify the connection

Keep the target project and scene open in Cocos Creator, then ask the AI client for a read-only action, for example:

Summarize the current Cocos scene hierarchy.

List the assets under db://assets and report any missing references.

Check the current editor and Preview errors without changing the project.

If the client can return project or scene information, the connection is ready.

5. Use editing workflows

You can describe editor tasks in natural language. For example:

Create a Canvas with a centered panel, a title, and a button in the current scene.

Set the selected Label font size to 32 and change its text to "Play".

Create an AnimationClip that moves the selected node from x=0 to x=300 in one second.

Persistent and structural changes require confirmation. A recommended workflow is:

1. Ask the client to inspect the current state and explain the planned change.

2. Review the target scene, nodes, assets, and paths.

3. Confirm the operation when the client requests permission.

4. Check the result in Cocos Creator and save the scene as appropriate.

Commit or back up important work before using tools that mutate. Use a disposable scene and temporary assets for your first attempt.

Tool management

The extension panel has two tabs:

• Server controls the port, autوسtart, and server state.

• Tool management provides individual tool toggles and the All, Core workflow, UI workflow, and Minimal presets.

Diminishing the set of exposed tools reduces the MCP tool definitions sent to the client. The preferences recovery tool always remains available. Clients that support tool-list change notifications refresh automatically; reconnect older clients when their tool list shows stale.

Settings are stored per project in library/cocos-mcp-community.settings.json.

Troubleshooting

• The client cannot connect: verify that Cocos Creator is open, extensions are enabled, and the panel shows the server as running. Check that the client URL uses the same port.

• Stale tool list: reconnect the MCP client after saving Tool management changes.

• A scene action fails: open the target scene and try a read-only summary of that scene first.

• A write edit is rejected: verify the target UUID or asset path and explicitly approve the requested write operation.

• Port already in use: choose another port between 1024 and 65535 in the Server panel, then update the client configuration.

開發

npm install
npm run check
npm run build
npm run test:ci

La suite smoke no moddo something modify project Cocos. Las pruebas de integración de escritura deben usar escenas desechables and temporary assets.

Estructura del obyecto

src/main.ts                 Extension lifecycle and panel messages
src/server/                 MCP transport, sessions, and tool registration
src/cocos/editor-bridge.ts  Cocos Editor integration
src/scene.ts                Scene-process operations
src/tools/                  Schema-validated MCP tools
src/panels/default/         Dockable extension panel
scripts/                    Regression and smoke tests

Contribución

Las ies and pull requests son bienvenid. Lea CONTRIBUTING.md, preserlos pasos de confirmación and verifications for persistent edits, and include tests and documentation for user-facing changes.

Contribuir

Agradecimientos

Gracias a los siguientes proyectos open source por referencia and inspiración:

• caravanglory/cocos-mcp-server

• DaxianLee/cocos-mcp-server

Licencia

Publicado bajo la licencia MIT.

Este es un proyecto comunitario independiente y no es un producto oficial de Cocos. Cocos and Cocos Creator son marcas comerciales de sus respectivos responsables.