Cocos MCP Server 0.0.1-dev.0 (versión de desarrollo)

Rama actual: develop · Estado actual: en desarrollo · Actualmente no hay una versión oficial publicada

La versión del paquete es 0.0.1-dev.0; la versión del protocolo y del contrato de Tools sigue siendo 0.0.1.

Extensión MCP local multiproyecto para Cocos Creator 3.8.8. Cocos Dashboard se encarga de la creación e importación de proyectos, de la selección de la versión de Creator y de su arranque; los Workers de la extensión se registran en el Manager local, el Agent se conecta únicamente al Manager y proporciona projectId explícitamente en cada llamada a nivel de proyecto.

Estado de desarrollo

• El trabajo de código y verificación se rige por la rama develop; main no se utiliza como rama de desarrollo activa.

• El paquete actual es una versión de desarrollo y no debe distribuirse directamente como un paquete de publicación oficial.

• La versión de paquete 0.0.1-dev.0 indica el estado de prepublicación de desarrollo actual; el protocolo, el Schema y el contrato de Tools siguen usando 0.0.1.

• Comandos como verify:release y build:release son puertas de lanzamiento y herramientas de verificación de paquetes candidatos en la fase de desarrollo; superarlas no equivale a haber publicado una versión oficial.

• Antes de la publicación oficial aún deben completarse el candidato limpio, las pruebas Direct Creator Live, Dashboard Creator Live y el cierre del ciclo de evidencias de publicación.

Related MCP server: mcp-bridge

Límites principales

• Versión: paquete 0.0.1-dev.0; protocolo/contrato 0.0.1; estado de distribución development

• Conexión: http://127.0.0.1:38488/mcp

• Transporte: MCP Streamable HTTP

• Conexión del Agent: sin autenticación; solo se permiten direcciones de bucle local y Host/Origin válidos

• Arranque de proyectos: los proyectos de usuario solo pueden iniciarse a través de Cocos Dashboard; únicamente Direct Creator Live inicia y termina los Fixtures temporales propios del Runner y nunca manipula proyectos de usuario

• Multiproyecto: un Manager enruta varios Workers ya iniciados; cuando el último Worker se desconecta y no hay arranques pendientes, el Manager sale automáticamente

• Operaciones de escritura: verificación previa, comparación de revision, ejecución, validación de lectura de retorno e informe de cambios parciales

• No se ofrece: transacciones, retroceso automático, copias de seguridad de archivos, historial de operaciones MCP ni registros de auditoría

Instalación de desarrollo

npm install
npm run build

Coloque el directorio de la extensión en el proyecto de destino:

<project>/extensions/cocos-mcp-server

A continuación, mediante Cocos Dashboard:

1. Importe o seleccione el proyecto;

2. Seleccione Cocos Creator 3.8.8;

3. Inicie el proyecto;

4. Espere a que el Worker de la extensión se registre en el Manager.

No inicie proyectos de usuario ejecutando directamente el ejecutable de CocosCreator; esto eludiría el contexto de versión e inicio de sesión de Dashboard. Direct Creator Live solo se aplica a los Fixtures temporales descartables propios del Runner.

Conexión del Agent

Conexión del cliente MCP:

http://127.0.0.1:38488/mcp

Configuración de ejemplo:

{
  "mcpServers": {
    "cocos": {
      "url": "http://127.0.0.1:38488/mcp"
    }
  }
}

Flujo recomendado tras la conexión:

1. MCP initialize;

2. MCP tools/list, para descubrir las Tools y el Schema registrados por el Manager;

3. Llame a system_control.list_projects;

4. Seleccione el projectId de destino;

5. Antes de generar el plan de ejecución, el Agent señala, según los metadatos de Action, el alcance y el impacto que requieren confirmación del usuario;

6. Ejecute en serie las operaciones de escritura, proyecto por proyecto, y revise la revision, la verification y el ChangeManifest devueltos.

El panel de Cocos no gestiona las aprobaciones y MCP tampoco emite tokens de aprobación. Los avisos de aprobación permanecen de forma unificada en el contexto del Agent.

Escenario Dirty

Solo se admite:

reject
save

Por defecto: reject. No se admite discard; no se descartan sin aviso las modificaciones no guardadas.

Comandos habituales

npm run build
npm test
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:live:matrix
npm run build:release
npm run scan:release

Creator Live

Creator Live se utiliza para la validación en la fase de desarrollo; no sustituye las evidencias completas necesarias para la publicación oficial.

Modo Direct con Fixture temporal (predeterminado)

El modo predeterminado de npm run test:live es Direct: tras copiar el Fixture de solo lectura, el Runner ejecuta directamente Creator -nologin únicamente sobre la copia creada en esa ejecución y solo envía SIGTERM a los procesos hijo temporales de Creator que él mismo rastrea. No inicia, guarda, cierra ni termina ningún proyecto de usuario.

npm run test:live
npm run test:live:direct
npm run test:live:action -- LIVE-SYS-001
npm run test:live:action:direct -- LIVE-SYS-001

Modo Dashboard con Fixture temporal

El modo Dashboard también prepara únicamente Fixtures temporales propios del Runner, pero no inicia ni cierra Creator directamente; el Runner genera un manifest y rutas absolutas de proyecto, y el operador importa, inicia y cierra estos proyectos temporales en Cocos Dashboard.

npm run test:live:dashboard
npm run test:live:action:dashboard -- LIVE-SYS-001

Modo Attach

Attach solo se conecta a los Fixtures temporales que se hayan iniciado mediante Dashboard y que el manifest del Runner haya registrado explícitamente; es un modo de aceptación de solo lectura.

npm run test:live:attach
npm run test:live:action:attach -- LIVE-SYS-001

Para hacer attach a una ejecución concreta de Dashboard, debe especificarse explícitamente el manifest generado por esa ejecución; el Runner no escanea directorios ni selecciona silenciosamente el manifest "más reciente":

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:attach

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:action:attach -- LIVE-SYS-001

Documentación del repositorio

• Resumen del contrato actual

• Estado de desarrollo y convenciones de ramas

• Registro de cambios

• Notas de seguridad

Las instantáneas de contrato, los Fixtures de prueba y el código de implementación se conservan en este repositorio; no se depende de documentación con rutas relativas en el proyecto padre de Cocos.

Solución de problemas

Manager no disponible

Confirme que al menos un proyecto iniciado mediante Cocos Dashboard sigue en línea. El Manager no se ejecuta como gestor de proyectos residente; sale automáticamente cuando no hay Workers y no hay arranques pendientes.

El proyecto no aparece

• Confirme que la versión de Creator es 3.8.8;

• Confirme que el proyecto incluye la extensión compilada;

• Compruebe que el projectId en settings/cocos-mcp.json coincide con la identidad del proyecto actual;

• No abra simultáneamente dos proyectos con el mismo projectId pero con rutas diferentes.

El cambio de puerto no surte efecto de inmediato

Mientras el Manager está en ejecución, solo se actualiza el puerto deseado; no se reinicia en caliente. Salga de todos los proyectos mediante la GUI visible de Cocos, espere a que el último Worker se dé de baja y a que el Manager salga automáticamente; cuando vuelva a iniciar proyectos desde Dashboard, el nuevo Manager usará el nuevo puerto.

Fallo en las operaciones de escritura

Compruebe en primer lugar:

• Si projectId es correcto;

• Si la categoría de permisos lo permite;

• Si la ruta está dentro del alcance del proyecto;

• Si expectedRevisions ha expirado;

• Si la Scene/Prefab actual está Dirty;

• Si el estado de AssetDB, Scene o compilación de Creator está listo.

La recuperación recae en la sesión del Agent y en Git; MCP no implementa transacciones ni retroceso automático.

Verificación de publicación en la fase de desarrollo

Los siguientes comandos se utilizan para verificar los paquetes candidatos de desarrollo; no representan una publicación oficial:

# 普通 CI：干净安装、构建、测试、契约、扫描和高危依赖审计
npm run verify:release:ci

# 开发候选包的完整验证步骤
npm run test:live:release
npm run test:live:dashboard:release
npm run release:evidence
npm run verify:release

Antes de la publicación oficial deben completarse las pruebas Direct Creator Live, Dashboard Creator Live, el SBOM, las sumas de verificación y la provenance sobre un candidato limpio y ya confirmado, con la aprobación explícita del mantenedor para publicar. Tanto dist/release/ como dist/release/release/ son artefactos generados y no se incluyen en Git.