Vibe Blocks MCP

Vibe Blocks MCP für Roblox Studio

Verbindet Roblox Studio über das Model Context Protocol (MCP) mit KI-Codierungseditoren (wie Cursor, Windsurf, Claude usw.) und ermöglicht so die KI-gestützte Spieleentwicklung in Ihrer Roblox Studio-Umgebung.

Überblick

Dieses Projekt besteht aus zwei Hauptteilen:

1. Python MCP-Server: Ein lokal laufender FastAPI-Server. Er stellt Roblox Studio-Aktionen als Tools über MCP bereit (mithilfe von Server-Sent Events – SSE). Optional kann er mit Roblox Open Cloud APIs interagieren, sofern konfiguriert.
2. Lua Companion Plugin: Ein Roblox Studio-Plugin ( roblox_mcp_plugin/src/Plugin.server.lua ), das innerhalb von Studio ausgeführt wird. Es fragt den lokalen Python-Server nach Befehlen ab, führt diese im Studio-Kontext aus (manipuliert Instanzen, liest Eigenschaften, führt Lua aus) und sendet Ergebnisse und Studio-Protokolle an den Server zurück.

Dadurch kann ein über MCP verbundener KI-Agent Ihre Live-Roblox-Studio-Sitzung verstehen und mit ihr interagieren.

Merkmale

• Live-Studio-Interaktion:
  • Szenenmanipulation: Erstellen, löschen, klonen, verschieben, skalieren und legen Sie Eigenschaften (einschließlich PrimaryPart) von Objekten (Teilen, Modellen, Skripten usw.) direkt in der Studioszene fest.
  • Szeneninspektion: Rufen Sie Objekteigenschaften ab, listen Sie untergeordnete Objekte auf, suchen Sie Instanzen nach Klasse oder Name im Studio.
  • Skripting: Erstellen, Bearbeiten und Löschen von Skripten/LocalScripts. Führen Sie beliebigen Luau-Code direkt in der Studio-Umgebung aus und erfassen Sie Ausgaben/Fehler.
  • Umgebung: Legen Sie Eigenschaften für Beleuchtungs- oder Geländedienste fest.
  • Animation: Spielen Sie Animationen auf Humanoiden/AnimationControllern ab.
  • NPCs: Erstellen Sie NPCs, indem Sie vorhandene Vorlagen klonen oder aus Asset-IDs einfügen.
  • Untergeordnete Objekte ändern: Wenden Sie Eigenschaftsänderungen basierend auf Filtern auf mehrere untergeordnete Objekte eines Objekts an.
  • Studio-Protokolle: Rufen Sie aktuelle Protokolle aus dem Studio-Ausgabefenster ab.
• Roblox Open Cloud-Integration (optional – erfordert API-Schlüssel):
  • Luau-Ausführung (Cloud): Führen Sie Luau-Code in einer separaten Cloud-Umgebung aus (nützlich für Aufgaben, die keinen Live-Studio-Zugriff erfordern).
  • DataStores: Speicher auflisten, Schlüssel-Wert-Einträge in Standard-DataStores abrufen, festlegen und löschen.
  • Assets: Laden Sie neue Assets (Modelle, Bilder, Audio) aus lokalen Dateien hoch.
  • Veröffentlichen: Veröffentlichen Sie die aktuell gespeicherte oder veröffentlichte Version eines Ortes.
  • (Geplant): Asset-Details abrufen, Benutzer-Assets auflisten.

Aufstellen

1. Voraussetzungen:

• Python >= 3.10
• uv -Paketmanager ( UV installieren ). Dies wird für eine schnellere Abhängigkeitsverwaltung dringend empfohlen.
• Roblox Studio
• (Optional) Ein Roblox-API-Schlüssel für Open Cloud-Funktionen. Sie erhalten ihn im Roblox Creator Dashboard unter „Anmeldeinformationen“ . Sie benötigen Berechtigungen für die APIs, die Sie verwenden möchten (DataStore, Asset-Upload, Veröffentlichung, Luau-Ausführung usw.).
• (Optional) Ihre Roblox Universe-ID und die Ziel-Orts-ID (erforderlich für Open Cloud-Funktionen).

2. Klonen Sie das Repository:

3. Abhängigkeiten installieren:

Verwendung von uv (empfohlen):

Alternativ können Sie pip verwenden:

4. Umgebung konfigurieren (optional – für Cloud-Funktionen):

• Wenn Sie die Open Cloud-Tools (DataStores, Asset Upload, Publishing, Cloud Luau) verwenden möchten, kopieren Sie die Beispielumgebungsdatei:
  cp .env.example .env
• Bearbeiten Sie die .env Datei:
  • Ersetzen Sie "YOUR_API_KEY_HERE" durch Ihren Roblox-API-Schlüssel.
  • Ersetzen Sie 0 für ROBLOX_UNIVERSE_ID durch Ihre Universe-ID.
  • Ersetzen Sie 0 für ROBLOX_PLACE_ID durch die Ziel-Orts-ID.
• Wenn Sie keine Cloud-Funktionen benötigen, können Sie die Erstellung der .env Datei überspringen. Der Server wird zwar weiterhin ausgeführt, aber Cloud-bezogene Tools geben einen Fehler zurück.

5. Installieren Sie das Companion-Plugin in Roblox Studio:

• Installieren Sie Rojo: Wenn Sie Rojo nicht installiert haben, folgen Sie den Anweisungen auf der Rojo-Website .
• Erstellen Sie das Plugin (optional): Navigieren Sie in Ihrem Terminal zum Verzeichnis roblox_mcp_plugin und führen Sie Folgendes aus:
  rojo build default.project.json --output VibeBlocksMCP_Companion.rbxm
  Dadurch wird eine VibeBlocksMCP_Companion.rbxm -Datei erstellt. Sie können aber auch die im Repository bereitgestellte Datei verwenden.
• In Studio installieren:
  • Suchen Sie Ihren Roblox Studio-Plugin-Ordner:
    • Windows: %LOCALAPPDATA%\Roblox\Plugins
    • macOS: ~/Documents/Roblox/Plugins (Sie müssen möglicherweise im Finder Cmd+Shift+G verwenden und den Pfad einfügen, um dorthin zu navigieren, oder in Roblox Studio auf „Plugin-Ordner“ klicken).
  • Verschieben oder kopieren Sie die generierte Datei VibeBlocksMCP_Companion.rbxm in diesen Plugin-Ordner.
• Starten Sie Roblox Studio neu: Das Plugin sollte jetzt automatisch geladen werden, wenn Sie Studio öffnen.
  • Hinweis: Das Plugin fragt http://localhost:8000/plugin_command ab. Wenn Sie den Server-Port ändern, müssen Sie die Variable SERVER_URL oben im Lua-Skript ( roblox_mcp_plugin/src/Plugin.server.lua ) aktualisieren und das Plugin neu erstellen.

6. Führen Sie den Python-Server aus:

• Öffnen Sie Ihr Terminal im Stammverzeichnis des Projekts.
• Machen Sie das Serverskript ausführbar (falls Sie dies noch nicht getan haben):
  chmod +x server.sh
• Führen Sie den Server aus:
  ./server.sh
• Der Server wird gestartet, überprüft/installiert uvicorn bei Bedarf und protokolliert, dass es auf http://localhost:8000 ausgeführt wird.
• Lassen Sie dieses Terminalfenster geöffnet, während Sie den Dienst verwenden.

7. Verbindung vom MCP-Client (z. B. Cursor) herstellen:

• Dieser Dienst funktioniert mit jedem KI-Client, der das Model Context Protocol (MCP) über Server-Sent Events (SSE) unterstützt, wie z. B. Cursor, Windsurf oder möglicherweise zukünftige Versionen von Claude Desktop.
• Beispiel mit Cursor:
  • Gehen Sie zu File > Settings > MCP (oder Code > Settings > MCP auf dem Mac).
  • Klicken Sie auf „Neuen globalen MCP-Server hinzufügen“.
  • Geben Sie die SSE-URL ein: http://localhost:8000/sse (achten Sie darauf, das abschließende /sse einzuschließen).
  • Möglicherweise müssen Sie die Datei mcp.json bearbeiten GXP8
• Der Client sollte jetzt die Toolquelle „Vibe Blocks MCP“ und die darin verfügbaren Tools erkennen.

Verwendung

Sobald der Server läuft, das Plug-In in Studio installiert ist und Ihr MCP-Client verbunden ist, können Sie über die KI mit Ihrer Studio-Sitzung interagieren.

Sprechen Sie den Agenten an (unter Angabe der Tools per @, wenn Ihr Client diese benötigt, z. B. list_children ) und bitten Sie ihn, Aktionen auszuführen.

Beispiel-Eingabeaufforderungen:

• „Erstellen Sie im Arbeitsbereich ein leuchtend rotes Teil mit dem Namen ‚Boden‘. Stellen Sie seine Größe auf (100, 2, 100) und seine Position auf (0, -1, 0) ein. Verankern Sie es.“
• „Löschen Sie das Objekt mit dem Namen ‚Workspace.OldPlatform‘“
• „Was ist die Position-Eigenschaft von ‚Workspace.SpawnLocation‘?“
• „Listet die untergeordneten Elemente von ServerScriptService auf.“
• „Suchen Sie alle Instanzen mit dem Klassennamen ‚Script‘ unter ServerScriptService.“
• „Führen Sie dieses Skript in Studio aus: print(game:GetService('Lighting').ClockTime) “
• „Setzen Sie die ClockTime Eigenschaft von Lighting auf 14.“
• „Klonen Sie ‚ReplicatedStorage.Templates.EnemyNPC‘ und nennen Sie den Klon ‚Guard1‘. Ordnen Sie ihn Workspace als übergeordnetes Element zu.“
• „Lassen Sie das Modell mit dem Namen ‚Workspace.Guard1‘ das Animations-Asset 123456789 abspielen.“
• „Ändern Sie alle untergeordneten Elemente von ‚Workspace.DecorationFolder‘ mit dem Klassennamen ‚Part‘, sodass ihr Material auf ‚Neon‘ eingestellt ist.“
• (Cloud-Beispiel) „Laden Sie ‚./assets/MyCoolModel.fbx‘ als Modell mit dem Namen ‚Cool Character Model‘ hoch.“
• (Cloud-Beispiel) „Holen Sie den Wert für den Schlüssel ‚player_123_score‘ aus dem Datenspeicher ‚PlayerData‘.“
• (Cloud-Beispiel) „Veröffentlichen Sie den aktuellen Ort.“
• „Zeigen Sie mir die neuesten Protokolle der Studio-Ausgabe.“

Verfügbare Tools

(Tools interagieren entweder direkt mit dem Studio-Plugin oder mit Roblox Open Cloud-APIs)

Studio-Plugin-Tools (Live-Interaktion):

• get_property : Ruft den Wert einer bestimmten Eigenschaft von einem Objekt in Studio ab.
• list_children : Ruft direkte untergeordnete Objekte eines Objekts in Studio ab.
• find_instances : Sucht Instanzen innerhalb einer angegebenen Wurzel basierend auf dem Klassennamen oder einem Namen, der Text in Studio enthält.
• create_instance : Erstellt eine neue Instanz (Teil, Modell, Skript usw.) in Studio.
• delete_instance : Löscht ein Objekt aus der Studioszene.
• set_property : Legt eine bestimmte Eigenschaft für ein Objekt in Studio fest (verwendet JSON-String für den Wert).
• set_primary_part : Legt die PrimaryPart-Eigenschaft eines Modells fest.
• move_instance : Verschiebt ein Objekt (Modell oder Basisteil) an eine neue Position in Studio.
• clone_instance : Klont ein vorhandenes Objekt in Studio.
• create_script : Erstellt eine neue Script- oder LocalScript-Instanz mit bereitgestelltem Code in Studio.
• edit_script : Bearbeitet den Quellcode eines vorhandenen Skripts oder LocalScript in Studio.
• delete_script : Löscht eine vorhandene Script- oder LocalScript-Instanz in Studio.
• set_environment : Legt Eigenschaften für Umgebungsdienste (Beleuchtung oder Gelände) in Studio fest.
• spawn_npc : Erzeugt einen NPC in Studio, entweder durch Einfügen eines Modells aus der Asset-ID oder durch Klonen eines vorhandenen Vorlagenmodells.
• play_animation : Lädt und spielt eine Animation auf dem Humanoid oder AnimationController eines Zielobjekts in Studio ab.
• execute_luau_in_studio : Führt über das Plug-In ein beliebiges Luau-Skript in der LIVE Studio-Sitzung aus und erfasst Ausgabe-/Rückgabewerte/Fehler.
• modify_children : Sucht direkte Kinder unter einem Elternteil, die optionalen Filtern (Name/Klasse) entsprechen, und legt für sie eine angegebene Eigenschaft fest.
• get_studio_logs : Ruft die aktuellsten Protokolle ab, die über das Plug-In aus dem Roblox Studio-Ausgabefenster erfasst wurden.

Open Cloud API Tools (optional – .env -Setup erforderlich):

• execute_luau_in_cloud : Führt ein beliebiges Luau-Skript über die Roblox Cloud API aus (läuft in einer separaten Cloud-Umgebung, nicht im Live-Studio).
• list_datastores_in_cloud : Listet Standarddatenspeicher über die Cloud-API auf.
• get_datastore_value_in_cloud : Ruft den Wert eines Eintrags aus einem Standarddatenspeicher über die Cloud-API ab.
• set_datastore_value_in_cloud : Legt den Wert für einen Eintrag in einem Standarddatenspeicher über die Cloud-API fest.
• delete_datastore_value_in_cloud : Löscht einen Eintrag aus einem Standarddatenspeicher über die Cloud-API.
• upload_asset_via_cloud : Lädt eine Datei vom lokalen System als neues Roblox-Asset über die Cloud-API hoch.
• publish_place_via_cloud : Veröffentlicht den angegebenen Ort über die Cloud-API.
• get_asset_details_via_cloud : (Nicht implementiert) Ruft Details zu einem bestimmten Asset über die Cloud-API ab.
• list_user_assets_via_cloud : (Nicht implementiert) Listet Assets auf, die dem authentifizierten Benutzer über die Cloud-API gehören.
• send_chat_via_cloud : Sendet eine Nachricht über die Cloud-API (execute_luau) an den In-Game-Chat.
• teleport_player_via_cloud : Teleportiert einen Spieler über die Cloud-API (execute_luau).

Interne/Warteschlangen-Tools:

• queue_studio_command : (Niedrigere Ebene) Stellt ein einzelnes Rohbefehlswörterbuch für das Studio-Plugin in die Warteschlange.
• queue_studio_command_batch : (Niedrigere Ebene) Stellt einen Stapel von Rohbefehlswörterbüchern für das Studio-Plugin in die Warteschlange.

Fehlerbehebung

• Server startet nicht: Stellen Sie sicher, dass Python und uv korrekt installiert sind. Überprüfen Sie das Terminal auf Fehlermeldungen. Stellen Sie sicher, dass die Abhängigkeiten installiert sind ( uv pip sync pyproject.toml ).
• Plugin stellt keine Verbindung her: Stellen Sie sicher, dass der Python-Server läuft. Überprüfen Sie, ob die SERVER_URL im Lua-Plugin-Skript mit der Serveradresse und dem Port übereinstimmt (Standard http://localhost:8000/plugin_command ). Überprüfen Sie das Ausgabefenster von Studio auf Fehler im Plugin-Skript.
• MCP-Client stellt keine Verbindung her: Stellen Sie sicher, dass der Server läuft. Überprüfen Sie, ob die SSE-URL ( http://localhost:8000/sse ) in Ihren MCP-Client-Einstellungen korrekt eingegeben wurde.
• Fehler bei Cloud-Tools: Stellen Sie sicher, dass Sie eine .env Datei mit einem gültigen API-Schlüssel, einer gültigen Universe-ID und einer gültigen Place-ID erstellt haben. Stellen Sie sicher, dass Ihr API-Schlüssel über die erforderlichen Berechtigungen für die spezifischen Cloud-APIs verfügt, die Sie verwenden möchten.
• Berechtigungen: Das Begleit-Plugin benötigt Script Injection-Berechtigungen, um ordnungsgemäß zu funktionieren, wenn Sie es aus einer lokalen Datei laden, anstatt es ordnungsgemäß zu installieren.