Cocos MCP Server 0.0.1-dev.0 (Entwicklungsversion)

Aktueller Branch: develop · Aktueller Status: in Entwicklung · Derzeit keine offizielle Release-Version

Paketversion ist 0.0.1-dev.0; Protokoll- und Tool-Vertragsversion bleibt 0.0.1.

Lokale Multi-Projekt-MCP-Erweiterung für Cocos Creator 3.8.8. Das Cocos Dashboard übernimmt Projekterstellung, -import, Creator-Versionsauswahl und -start; der Worker in der Erweiterung registriert sich beim lokalen Manager, der Agent verbindet sich nur mit dem Manager und gibt bei jedem projektbezogenen Aufruf explizit projectId an.

Entwicklungsstatus

• Code- und Verifizierungsarbeit erfolgt auf dem develop-Branch; main dient nicht als aktueller Entwicklungsbranch.

• Das aktuelle Paket ist eine Entwicklungsversion und darf nicht als offizielles Release-Paket direkt verteilt werden.

• Paketversion 0.0.1-dev.0 kennzeichnet den aktuellen Entwicklungs-Vorabstatus; Protokoll, Schema und Tool-Vertrag verwenden weiterhin 0.0.1.

• verify:release, build:release und ähnliche Befehle sind Release-Gates und Kandidatenpaket-Verifizierungswerkzeuge der Entwicklungsphase; ihr Durchlauf bedeutet keine offizielle Veröffentlichung.

• Vor der offiziellen Veröffentlichung müssen noch saubere Kandidatenversion, Direct Creator Live, Dashboard Creator Live und der geschlossene Kreislauf der Release-Nachweise abgeschlossen werden.

Related MCP server: mcp-bridge

Kern-Grenzen

• Version: Paket 0.0.1-dev.0; Protokoll/Vertrag 0.0.1; Release-Status development

• Verbindung: http://127.0.0.1:38488/mcp

• Transport: MCP Streamable HTTP

• Agent-Verbindung: ohne Authentifizierung; nur Loopback-Adressen, gültiger Host/Origin erlaubt

• Projektstart: Benutzerprojekte können nur über das Cocos Dashboard gestartet werden; nur Direct Creator Live startet und beendet die eigenen temporären Fixtures des Runners, greift niemals in Benutzerprojekte ein

• Multi-Projekt: Ein Manager leitet mehrere gestartete Worker weiter; wenn der letzte Worker offline geht und kein Start aussteht, beendet sich der Manager automatisch

• Schreiboperationen: Vorprüfung, Revisionsvergleich, Ausführung, Rücklese-Verifizierung, Teiländerungsbericht

• Nicht bereitgestellt: Transaktionen, automatisches Rollback, Dateisicherung, MCP-Operationsverlauf oder Audit-Log

Entwicklungsinstallation

npm install
npm run build

Erweiterungsverzeichnis in das Zielprojekt legen:

<project>/extensions/cocos-mcp-server

Dann über Cocos Dashboard:

1. Projekt importieren oder auswählen;

2. Cocos Creator 3.8.8 auswählen;

3. Projekt starten;

4. Warten, bis sich der Erweiterungs-Worker beim Manager registriert.

Die CocosCreator-Ausführbare Datei nicht direkt ausführen, um Benutzerprojekte zu starten; dies umgeht den Versions- und Anmeldekontext des Dashboards. Direct Creator Live ist nur auf verwerfbare temporäre Fixtures des Runners anwendbar.

Agent-Verbindung

MCP-Client-Verbindung:

http://127.0.0.1:38488/mcp

Beispielkonfiguration:

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

Empfohlener Ablauf nach der Verbindung:

1. MCP initialize;

2. MCP tools/list, um die vom Manager registrierten Tools und Schemas zu entdecken;

3. system_control.list_projects aufrufen;

4. Ziel-projectId auswählen;

5. Vor der Erstellung des Ausführungsplans weist der Agent basierend auf den Action-Metadaten auf Umfang und Auswirkungen hin, die der Spieler bestätigen muss;

6. Schreiboperationen projektweise seriell ausführen und die zurückgegebenen Revision, Verifizierung und ChangeManifest prüfen.

Das Cocos-Panel übernimmt keine Genehmigung, und MCP stellt auch keine Genehmigungstoken aus. Genehmigungshinweise bleiben einheitlich im Agent-Kontext.

Dirty-Szenarien

Nur unterstützt:

reject
save

Standard: reject. discard wird nicht unterstützt; ungespeicherte Änderungen werden nicht ohne Hinweis verworfen.

Häufige Befehle

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 dient der Verifizierung in der Entwicklungsphase und ersetzt nicht die vollständigen Nachweise, die für eine offizielle Veröffentlichung erforderlich sind.

Direct-Modus mit temporärem Fixture (Standard)

Der Standardmodus von npm run test:live ist Direct: Der Runner kopiert das schreibgeschützte Fixture und führt Creator -nologin direkt nur auf der erstellten Kopie aus, wobei SIGTERM ausschließlich an die von ihm selbst verfolgten temporären Creator-Unterprozesse gesendet wird. Er startet, speichert, schließt oder beendet keine Benutzerprojekte.

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

Dashboard-Modus mit temporärem Fixture

Der Dashboard-Modus bereitet ebenfalls nur die eigenen temporären Fixtures des Runners vor, startet oder schließt Creator jedoch nicht direkt; der Runner gibt Manifest und absoluten Projektpfad aus, und der Bediener importiert, startet und beendet diese temporären Projekte im Cocos Dashboard.

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

Attach-Modus

Attach verbindet nur temporäre Fixtures, die bereits über das Dashboard gestartet und explizit im Runner-Manifest registriert wurden; es ist ein schreibgeschützter Abnahmemodus.

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

Um eine aktuelle Dashboard-Ausführung anzuhängen, muss das von dieser Ausführung erzeugte Manifest explizit angegeben werden; der Runner scannt keine Verzeichnisse und wählt nicht stillschweigend das „neueste" Manifest aus:

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

Repository-Dokumentation

• Aktuelle Vertragszusammenfassung

• Entwicklungsstatus und Branch-Konventionen

• Änderungsprotokoll

• Sicherheitshinweise

Vertragssnapshots, Test-Fixtures und Implementierungscode sind im Repository gespeichert; es wird nicht auf Dokumentation mit relativen Pfaden im übergeordneten Cocos-Projekt zurückgegriffen.

Fehlerbehebung

Manager nicht verfügbar

Bestätigen, dass mindestens ein über das Cocos Dashboard gestartetes Projekt noch online ist. Der Manager läuft nicht als dauerhafter Projektmanager; ohne Worker und ohne ausstehenden Start beendet er sich automatisch.

Projekt erscheint nicht

• Creator-Version 3.8.8 bestätigen;

• Bestätigen, dass das Projekt die erstellte Erweiterung enthält;

• In settings/cocos-mcp.json prüfen, ob projectId mit der aktuellen Projektidentität übereinstimmt;

• Nicht zwei Projekte mit derselben projectId, aber unterschiedlichen Pfaden gleichzeitig öffnen.

Portänderung wird nicht sofort wirksam

Während der Laufzeit des Managers wird nur der gewünschte Port aktualisiert, kein Online-Neustart durchgeführt. Alle Projekte über die sichtbare Cocos-GUI beenden, auf die Abmeldung des letzten Workers und den automatischen Exit des Managers warten; erst nach erneutem Start des Projekts über das Dashboard verwendet der neue Manager den neuen Port.

Schreiboperation fehlgeschlagen

Zuerst prüfen:

• Ob projectId korrekt ist;

• Ob die Berechtigungskategorie erlaubt;

• Ob der Pfad im Projektbereich liegt;

• Ob expectedRevisions abgelaufen ist;

• Ob die aktuelle Scene/Prefab dirty ist;

• Ob Creator AssetDB, Scene oder Kompilierungsstatus bereit sind.

Die Wiederherstellung übernehmen Agent-Session und Git; MCP implementiert keine Transaktionen oder automatisches Rollback.

Release-Verifizierung in der Entwicklungsphase

Die folgenden Befehle dienen zur Verifizierung des Entwicklungskandidatenpakets und stellen keine offizielle Veröffentlichung dar:

# 普通 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

Vor der offiziellen Veröffentlichung müssen Direct Creator Live, Dashboard Creator Live, SBOM, Prüfsummen und Provenienz auf einer sauberen und committeten Kandidatenversion abgeschlossen und vom Maintainer ausdrücklich freigegeben werden. dist/release/ und dist/release/release/ sind generierte Artefakte und werden nicht in Git aufgenommen.