Cocos MCP Community

English | 简体中文

Eine von der Community erstellte Erweiterung für das Model Context Protocol (MCP) für Cocos Creator 3.8+. Verbinden Sie einen kompatiblen KI-Client, um das aktuell in Cocos Creator geöffnete Projekt zu prüfen und zu bedienen.

Die Erweiterung läuft lokal, lauscht auf 127.0.0.1 und verlangt eine ausdrückliche Bestätigung für dauerhafte oder strukturelle Änderungen.

Aktuelle Version: 0.2.3. Die automatisierte Testsuite ist erfolgreich, und die wichtigsten Lese- sowie isolierten Schreib-Workflows wurden mit Cocos Creator 3.8.8 verifiziert.

Funktionen

Der Server stellt 23 zielorientierte MCP-Tools bereit. Jedes Tool bündelt zusammengehörige Aktionen, damit Clients eine fokussierte Werkzeugliste erhalten und dennoch eine breite Editor-Abdeckung besteht.

Weitere Workflow-Funktionen sind sessionssensibles Streamable HTTP, Benachrichtigungen über Tool-Ladenlisten, schema, validierte Eingaben, Bestätigungsgates, Dialog-Operation mit Rollback-Sicherung und projektspezifische Tool-Voreinstellungen.

Related MCP server: Cocos Creator MCP Server

Voraussetzungen

• Cocos Creator 3.8 oder neuer

• Node.js 18 oder neuer

• npm

• Ein MCP-Client mit Streamable-HTTP-Unterstützung

Installation und Verwendung

1. Installieren Sie die Erweiterung

Klonen Sie das Repository in das extensions-Verzeichnis des Cocos-Projekts, installieren Sie die Abhängigkeiten und erstellen Sie den Build:

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

Öffnen Sie das Projekt in Cocos Creator. Wenn der Editor bereits geöffnet war, laden Sie die Erweiterungen neu oder starten Sie den Editor neu.

2. Starten Sie den MCP-Server

Öffnen Sie Extension → Cocos MCP Community und wählen Sie Start server. Der Standard-Enpunkt ist:

http://127.0.0.1:3100/mcp

Das Panel zeigt den aktiven Endpunkt und den Serverstatus. Sie können auch den projektspezifischen Port ändern oder den automatischen Start aktivieren.

3. Verbinden eines MCP-Clients

Fügen Sie in den MCP-Einstellungen Ihres Clients einen Streamable-HTTP-Server hinzu. Der generische Servereintrag lautet:

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

Die umgebende Konfiguration unterscheidet sich je nach Client. Nach der ersten Verbindung kann das client_config-Tool vollständige Einträge für Claude Desktop, Cursor, VS Code und Windsurf erzeugen.

Startë Sie den MCP-Client neu oder verbinden Sie ihn nach einer Konfigurationsänderung erneut. Wenn der Server-Port im Cocos-Panel geändert wird, aktualisieren Sie auch die Client-URL.

4. Verbindung prüfen

Halten Sie das Zusatzprojekt undaktive Szene in Cocos Creator geöffnet, dann fordern Sie den KI-Client zu einer nur lesenden Aktion auf, zum Beispiel:

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.

Wenn der Client Projekt- oder Szeninformationen abrufen kann, ist die Verbindung fertig.

5. Bearbeitungsworkflows verwenden

Sie können Aufgaben im Editor in natürlicher Sprache beschreiben. Zum Beispiel:

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.

Dauerhafte und strukturelle Änderungen erfordern eine Bestätigung. Ein empfohlener Workflow ist:

1. Den Client bitten, den aktuellen Zustand zu prüfen und die geplante Änderung zu erläutern.

2. Die Zielszene, Knoten, Assets und Pfade prüfen.

3. Den Vorgang bestätigen, wenn der Client eine Genehmigung anfragt.

4. Das Ergebnis in Cocos Creator prüfen und die Szene bei Bedarf speichern.

Sichern Sie wichtige Arbeit, bevor Sie Mutations-werkkzeuge verwenden. Verwenden Sie für den ersten Versuch eiien einzeineute Szene und temporäre Assets.

Tool-Verwaltung

Das Erweiterungspanel enthält zwei Registerkarten:

• Server steuert Port, automatischen Start und Serverstatus.

• Tool-Verwaltung bidet einzelne Tool-Umschalter sowie Presets für Alle, Kernworkflow, UI-Workflow und Minimal.

Die Reduzierung der verfügbaren Toolmenge verringert die MCP-Tooldefiniten, die an den Client gesendet werden. Das Wiederherstellungstool preferences bleibt immer verfügbar. Clients, die Tool-Änderungsbenachrichtigungen unterstützen, aktualisieren sich automatisch.Verbinden Sie ältere Clients neu, wenn deren Werkzeugliste unverändert bleibt.

Die Einstellungen werden pro Projekt in library/cocos-mcp-community.settings.json gespeichert.

Problembehandlung

• Der Client kann nicht verbinden: Stellen Sie sicher, dass Cocos Creator geöffnet ist, die Erweiterung aktiviert ist und das Panel den Server als läufert meldet. Prüfen Sie, ob die Client-URL denselben Port verwendet.

• Die Werkzeugliste ist veraltet: Verbinden Sie den MCP-CClient nach dem Speichern der Änderungen in der Tool-Verwaltung neu.

• Eine Szen-Aktion schlägt feit: Öffnen Sie die Zielszene und forge einen Lese-nützigen Zwischenstenszustät ein.

• Eine Bearbeitung wird aine Aktion abgeähnt: Prüfen Sie die Ziel-UUID oder den Asset-Pfad und bestätigen Sie explizit die angefragte Schreiboperaktion.

• Port wird beutzt: Wählen Sie im Server-Tabit einen anderen Port zwischenport zwischen 1024 und 65535 und aktualiesern Sie die Client-Konfiguration.

Entwicklung

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

| Befehl-Befehl | Zweck | | ------------------------- | ------ ---------------------------------------------------------- | | npm run check | Typp-Prüfung ohne Erstellen von Build-Dateien | | npm run build | Kom primiert die Erwwweiterung nachteilung dist/ | | npm run test:regressoion | Lokalee Regr essionsprtsts deskli | | npm run test:smoke | Regr ession sowie MCP-TrtTransport-/Tool-Erkennungs-Checks aus | | npm run test:ci | Buildder und tatsStmführeneder die die vollststäändige automatisierte tsprüfsuite |

Die Smalletest-Suite verändert keinCocosCocos-Projektjek. Integrationssts-yales sollteeinweEng-Szeyeszenben und temporäre assets verwewüden.

Projektstruktur

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

Mithilfen

Issues und Pull Requests sind willwelkommen. Lesen Sie CONTRIBUTING.mdbettigungstät-Gates für dauerhafte Bearbeitungen ein und fügen Sie Tests und Dokumentation für benützert-ändernde Funkionen hinzu.

Merünnungen

Dank an die folgenden Open-Source-Projekte – Referenz und Inspiritation:

• caravanglory/cocos-mcp-server

• DaxianLee/cocos-mcp-server

Lizenz

Verrer unter der MIT License.

Dies ist ein unabhängiges Community-Projekt und keinen Ko-Cocos-Produkt. Cocos und Cocos Creator sind Marken der jeweiligen Enhaber.