Vibe Blocks MCP

Vibe Blocks MCP para Roblox Studio

Conecta Roblox Studio con editores de codificación de IA (como Cursor, Windsurf, Claude, etc.) a través del Protocolo de contexto de modelo (MCP), lo que permite el desarrollo de juegos asistido por IA dentro de su entorno de Roblox Studio.

Descripción general

Este proyecto consta de dos partes principales:

1. Servidor MCP de Python: Un servidor FastAPI que se ejecuta localmente. Expone las acciones de Roblox Studio como herramientas a través de MCP (mediante eventos enviados por el servidor - SSE). Opcionalmente, puede interactuar con las API de Roblox Open Cloud si se configura.
2. Plugin complementario de Lua: Un plugin de Roblox Studio ( roblox_mcp_plugin/src/Plugin.server.lua ) que se ejecuta dentro de Studio. Sondea el servidor local de Python en busca de comandos, los ejecuta en el contexto de Studio (manipulación de instancias, lectura de propiedades, ejecución de Luau) y envía los resultados y los registros de Studio al servidor.

Esto permite que un agente de IA conectado a través de MCP comprenda e interactúe con su sesión en vivo de Roblox Studio.

Características

• Interacción en estudio en vivo:
  • Manipulación de escenas: cree, elimine, clone, mueva, escale y establezca propiedades (incluida PrimaryPart) de objetos (partes, modelos, scripts, etc.) directamente en la escena de Studio.
  • Inspección de escena: obtenga propiedades de objetos, enumere elementos secundarios, busque instancias por clase o nombre dentro de Studio.
  • Scripting: Crea, edita y elimina scripts/localscripts. Ejecuta código Luau arbitrario directamente en el entorno de Studio y captura resultados y errores.
  • Entorno: establezca propiedades en los servicios de Iluminación o Terreno.
  • Animación: Reproduce animaciones en Humanoids/AnimationControllers.
  • PNJ: genere PNJ clonando plantillas existentes o insertando ID de activos.
  • Modificar hijos: aplicar cambios de propiedad a varios hijos de un objeto según filtros.
  • Registros de estudio: recupera registros recientes de la ventana de Salida de estudio.
• Integración de Roblox Open Cloud (opcional: requiere clave API):
  • Ejecución de Luau (nube): ejecute el código de Luau en un entorno de nube separado (útil para tareas que no requieren acceso a Studio en vivo).
  • Almacenes de datos: enumera almacenes, obtiene, establece y elimina entradas de clave-valor en almacenes de datos estándar.
  • Activos: cargue nuevos activos (modelos, imágenes, audio) desde archivos locales.
  • Publicación: publica la versión actualmente guardada o publicada de un lugar.
  • (Planificado): Obtener detalles de los activos, enumerar los activos del usuario.

Configuración

1. Requisitos previos:

• Python >= 3.10
• Gestor de paquetes uv ( Instalar uv ). Esto es muy recomendable para una gestión más rápida de las dependencias.
• Estudio Roblox
• (Opcional) Una clave de API de Roblox para las funciones de Open Cloud. Obtén una en el Panel de Creador de Roblox > Credenciales . Necesitarás permisos para las API que quieras usar (Almacén de datos, Subida de recursos, Publicación, Ejecución de Luau, etc.).
• (Opcional) Tu ID de Roblox Universe y la ID del lugar de destino (necesaria para las funciones de Open Cloud).

2. Clonar el repositorio:

3. Instalar dependencias:

Uso de uv (recomendado):

Alternativamente, usando pip :

4. Configurar el entorno (opcional - para funciones en la nube):

• Si planea utilizar las herramientas de Open Cloud (DataStores, Asset Upload, Publishing, Cloud Luau), copie el archivo de entorno de ejemplo:
  cp .env.example .env
• Edite el archivo .env :
  • Reemplaza "YOUR_API_KEY_HERE" con tu clave API de Roblox.
  • Reemplace 0 para ROBLOX_UNIVERSE_ID con su ID de universo.
  • Reemplace 0 para ROBLOX_PLACE_ID con el ID del lugar de destino.
• Si no necesita las funciones de la nube, puede omitir la creación del archivo .env . El servidor seguirá funcionando, pero las herramientas relacionadas con la nube generarán un error.

5. Instale el complemento complementario en Roblox Studio:

• Instalar Rojo: Si no tienes Rojo instalado, sigue las instrucciones en el sitio web de Rojo .
• Construye el complemento (opcional): navega al directorio roblox_mcp_plugin en tu terminal y ejecuta:
  rojo build default.project.json --output VibeBlocksMCP_Companion.rbxm
  Esto creará un archivo VibeBlocksMCP_Companion.rbxm o puede usar el proporcionado en el repositorio.
• Instalar en Studio:
  • Encuentra tu carpeta de complementos de Roblox Studio:
    • Windows: %LOCALAPPDATA%\Roblox\Plugins
    • macOS: ~/Documents/Roblox/Plugins (Es posible que tengas que usar Cmd+Shift+G en el Finder y pegar la ruta para navegar allí, o hacer clic en Carpeta de complementos en Roblox Studio).
  • Mueva o copie el archivo VibeBlocksMCP_Companion.rbxm generado en esta carpeta de complementos.
• Reiniciar Roblox Studio: el complemento ahora debería cargarse automáticamente cuando abras Studio.
  • Nota: El complemento sondea http://localhost:8000/plugin_command . Si cambia el puerto del servidor, deberá actualizar la variable SERVER_URL en la parte superior del script de Lua ( roblox_mcp_plugin/src/Plugin.server.lua ) y reconstruir el complemento.

6. Ejecute el servidor Python:

• Abra su terminal en el directorio raíz del proyecto.
• Haga que el script del servidor sea ejecutable (si aún no lo ha hecho):
  chmod +x server.sh
• Ejecutar el servidor:
  ./server.sh
• El servidor se iniciará, verificará/instalará uvicorn si es necesario y registrará que se está ejecutando en http://localhost:8000 .
• Mantenga esta ventana de terminal abierta mientras utiliza el servicio.

7. Conectarse desde el cliente MCP (por ejemplo, Cursor):

• Este servicio funciona con cualquier cliente de IA que admita el Protocolo de contexto de modelo (MCP) a través de eventos enviados por el servidor (SSE), como Cursor, Windsurf o posibles versiones futuras de Claude Desktop.
• Ejemplo usando Cursor:
  • Vaya a File > Settings > MCP (o Code > Settings > MCP en Mac).
  • Haga clic en "Agregar nuevo servidor MCP global".
  • Ingrese la URL de SSE: http://localhost:8000/sse (asegúrese de incluir el /sse final).
  • Es posible que necesites editar el archivo mcp.json GXP8
• El cliente ahora debería detectar la fuente de la herramienta "Vibe Blocks MCP" y sus herramientas disponibles.

Uso

Una vez que el servidor esté en ejecución, el complemento esté instalado en Studio y su cliente MCP esté conectado, podrá interactuar con su sesión de Studio a través de la IA.

Dirígete al agente (@-mencionando las herramientas si tu cliente las requiere, por ejemplo, list_children ) y pídele que realice acciones.

Ejemplos de indicaciones:

• Cree una pieza roja brillante llamada "Piso" en el espacio de trabajo. Establezca su tamaño en (100, 2, 100) y su posición en (0, -1, 0). Anclela.
• Eliminar el objeto llamado 'Workspace.OldPlatform'
• "¿Qué es la propiedad Posición de 'Workspace.SpawnLocation'?"
• "Enumere los hijos de ServerScriptService".
• "Buscar todas las instancias con el nombre de clase 'Script' en ServerScriptService".
• Ejecute este script en Studio: print(game:GetService('Lighting').ClockTime)
• "Establezca la propiedad ClockTime de Iluminación en 14."
• Clona 'ReplicatedStorage.Templates.EnemyNPC' y nómbralo 'Guard1'. Asocialo a Workspace.
• "Hacer que el modelo llamado 'Workspace.Guard1' reproduzca el recurso de animación 123456789".
• "Modifique todos los elementos secundarios de 'Workspace.DecorationFolder' con el nombre de clase 'Part' para que su material se configure en 'Neón'."
• (Ejemplo en la nube) "Cargue './assets/MyCoolModel.fbx' como un modelo llamado 'Cool Character Model'".
• (Ejemplo en la nube) "Obtener el valor de la clave 'player_123_score' del almacén de datos 'PlayerData'".
• (Ejemplo de nube) "Publicar el lugar actual".
• "Muéstrame los últimos registros de la salida del estudio".

Herramientas disponibles

(Las herramientas interactúan directamente con el complemento Studio o con las API de Roblox Open Cloud)

Herramientas de complemento de estudio (interacción en vivo):

• get_property : recupera el valor de una propiedad específica de un objeto en Studio.
• list_children : recupera los hijos directos de un objeto en Studio.
• find_instances : busca instancias dentro de una raíz especificada según el nombre de clase o un nombre que contenga texto en Studio.
• create_instance : crea una nueva instancia (pieza, modelo, script, etc.) en Studio.
• delete_instance : elimina un objeto de la escena de Studio.
• set_property : establece una propiedad específica en un objeto en Studio (utiliza una cadena JSON para el valor).
• set_primary_part : establece la propiedad PrimaryPart de un modelo.
• move_instance : mueve un objeto (modelo o basepart) a una nueva posición en Studio.
• clone_instance : clona un objeto existente en Studio.
• create_script : crea una nueva instancia de Script o LocalScript con el código proporcionado en Studio.
• edit_script : edita el código fuente de un Script o LocalScript existente en Studio.
• delete_script : elimina una instancia de Script o LocalScript existente en Studio.
• set_environment : establece propiedades en los servicios de entorno (iluminación o terreno) en Studio.
• spawn_npc : genera un NPC en Studio, ya sea insertando un modelo desde el ID del activo o clonando un modelo de plantilla existente.
• play_animation : carga y reproduce una animación en el Humanoid o AnimationController de un objeto de destino en Studio.
• execute_luau_in_studio : ejecuta un script Luau arbitrario en la sesión LIVE Studio a través del complemento y captura valores de salida/retorno/errores.
• modify_children : busca hijos directos bajo un padre que coincida con filtros opcionales (nombre/clase) y establece una propiedad específica en ellos.
• get_studio_logs : recupera los registros más recientes capturados de la ventana de salida de Roblox Studio a través del complemento.

Herramientas de API de Open Cloud (opcional: requiere configuración .env ):

• execute_luau_in_cloud : ejecuta un script Luau arbitrario a través de la API de Roblox Cloud (se ejecuta en un entorno de nube separado, no en Live Studio).
• list_datastores_in_cloud : enumera los almacenes de datos estándar a través de la API de Cloud.
• get_datastore_value_in_cloud : obtiene el valor de una entrada de un almacén de datos estándar a través de la API de Cloud.
• set_datastore_value_in_cloud : establece el valor de una entrada en un almacén de datos estándar a través de la API de Cloud.
• delete_datastore_value_in_cloud : elimina una entrada de un almacén de datos estándar a través de la API de Cloud.
• upload_asset_via_cloud : carga un archivo desde el sistema local como un nuevo activo de Roblox a través de la API de la nube.
• publish_place_via_cloud : publica el lugar especificado a través de la API de Cloud.
• get_asset_details_via_cloud : (no implementado) obtiene detalles sobre un activo específico a través de la API de Cloud.
• list_user_assets_via_cloud : (no implementado) enumera los activos que posee el usuario autenticado a través de la API de Cloud.
• send_chat_via_cloud : envía un mensaje al chat del juego a través de la API de la nube (execute_luau).
• teleport_player_via_cloud : teletransporta a un jugador a través de la API de la nube (execute_luau).

Herramientas internas/de cola:

• queue_studio_command : (nivel inferior) Pone en cola un único diccionario de comandos sin procesar para el complemento Studio.
• queue_studio_command_batch : (nivel inferior) Pone en cola un lote de diccionarios de comandos sin procesar para el complemento Studio.

Solución de problemas

• El servidor no se inicia: Asegúrese de que Python y uv estén instalados correctamente. Revise la terminal para ver si hay mensajes de error. Asegúrese de que las dependencias estén instaladas ( uv pip sync pyproject.toml ).
• Plugin no conectado: Verifique que el servidor Python esté en ejecución. Verifique que SERVER_URL en el script del plugin de Lua coincida con la dirección y el puerto del servidor (predeterminado http://localhost:8000/plugin_command ). Revise la ventana de salida de Studio para ver si hay errores del script del plugin.
• El cliente MCP no se conecta: Asegúrese de que el servidor esté en ejecución. Verifique que la URL de SSE ( http://localhost:8000/sse ) esté correctamente ingresada en la configuración del cliente MCP.
• Fallo en las herramientas de la nube: Asegúrate de haber creado un archivo .env con una clave de API, un ID de universo y un ID de lugar válidos. Asegúrate de que tu clave de API tenga los permisos necesarios para las API de la nube que intentas usar.
• Permisos: El complemento complementario requiere permisos de inyección de script para funcionar correctamente si lo carga desde un archivo local en lugar de instalarlo correctamente.