🎮 Servidor MCP definitivo para Roblox Studio

Inglés | 日本語

El servidor MCP (Model Context Protocol) más completo para Roblox Studio. 41 herramientas para un control total de Studio desde Claude Code o cualquier asistente de IA compatible con MCP.

✨ Por qué existe esto

El MCP predeterminado de Roblox Studio solo proporciona run_code, lo que te obliga a manipular las fuentes de los scripts mediante operaciones de cadena (gsub). Esto conduce a:

❌ Fallos en la coincidencia de patrones
❌ Sentencias end) rotas
❌ Reversiones silenciosas cuando los scripts se revierten
❌ Sin verificación de sintaxis antes de escribir
❌ Horas desperdiciadas en ediciones simples

Este MCP resuelve todo eso.

🚀 Características

Operaciones de script (El punto de inflexión)

Herramienta	Descripción
`getScript`	Obtener el código fuente completo
`setScript`	Reemplazar la fuente completa (con verificación de sintaxis + copia de seguridad automática)
`editScript`	Editar un rango de líneas específico (¡edición parcial!)
`insertCode`	Insertar código después de una línea específica
`removeLines`	Eliminar líneas específicas
`replaceInScript`	Buscar y reemplazar texto (texto plano, seguro)
`getLines`	Obtener solo un rango de líneas específico (ligero)
`getFunctionList`	Listar todas las funciones con números de línea
`getScriptSummary`	Resumen: funciones, requires, globales
`listScripts`	Listar todos los scripts en el juego
`getAllScripts`	Obtener todas las fuentes de scripts a la vez
`searchInScripts`	Buscar palabra clave en todos los scripts
`getReferences`	Encontrar todos los usos de una variable/función
`getModuleDependencies`	Listar dependencias de require()

Mecanismos de seguridad

Característica	Descripción
🔒 Verificación de sintaxis	Valida automáticamente antes de escribir. Rechaza código incorrecto.
💾 Copia de seguridad automática	Guarda la versión anterior antes de cada edición (10 generaciones)
🛑 Protección de modo de juego	Bloquea escrituras durante el modo de juego (evita reversiones silenciosas)
📝 UpdateSourceAsync	Utiliza ScriptEditorService para escrituras sin conflictos

Copia de seguridad y restauración

Herramienta	Descripción
`restoreBackup`	Restaurar desde una copia de seguridad guardada automáticamente
`listBackups`	Listar copias de seguridad disponibles

Validación

Herramienta	Descripción
`checkSyntax`	Verificar sintaxis sin escribir
`verifyScript`	Verificar recuento de líneas / longitud de fuente
`validateAllScripts`	Verificación de sintaxis por lotes de todos los scripts

Operaciones de instancia

Herramienta	Descripción
`getTree`	Obtener jerarquía de instancias
`getChildren`	Listar hijos (ligero)
`getProperty` / `setProperty`	Obtener/establecer propiedades
`createInstance`	Crear nueva instancia
`deleteInstance`	Eliminar instancia
`cloneInstance`	Clonar instancia
`renameInstance`	Renombrar instancia
`moveInstance`	Mover a un padre diferente
`findInstances`	Buscar instancias por nombre/clase

Otros

Herramienta	Descripción
`runCode`	Ejecutar código Luau (con captura de salida)
`batch`	Ejecutar múltiples comandos a la vez
`getAttribute` / `setAttribute`	Operaciones de atributos
`getErrors` / `clearErrors`	Gestión de registro de errores
`undo` / `redo`	Operaciones de deshacer/rehacer
`getSelection`	Obtener selección actual
`getStudioInfo`	Obtener información de Studio

📦 Instalación

1. Clonar y construir

git clone https://github.com/YOUR_USERNAME/roblox-studio-ultimate-mcp.git
cd roblox-studio-ultimate-mcp
npm install
npm run build

2. Instalar plugin de Studio

Copia el archivo del plugin a tu carpeta de Plugins de Roblox:

Mac:

cp plugin/UltimateMCP.rbxmx ~/Documents/Roblox/Plugins/

Windows:

copy plugin\UltimateMCP.rbxmx %LOCALAPPDATA%\Roblox\Plugins\

O genéralo desde la fuente:

bash generate-plugin.sh

3. Habilitar HTTP en Studio

Abre Roblox Studio, luego en la barra de comandos (View → Command Bar):

game:GetService("HttpService").HttpEnabled = true

4. Registrar con Claude Code

Añade a tu ~/.claude.json bajo el proyecto apropiado:

{
  "mcpServers": {
    "roblox_ultimate": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/roblox-studio-ultimate-mcp/dist/index.js"],
      "env": {}
    }
  }
}

5. Reiniciar

Reinicia Roblox Studio (para cargar el plugin)
Reinicia Claude Code (para conectar al MCP)

🏗️ Arquitectura

Claude Code ←(stdio)→ MCP Server (Node.js) ←(HTTP)→ Studio Plugin (Luau)
                         Port 3002

Servidor MCP (src/index.ts): Traduce llamadas de herramientas MCP a comandos HTTP
Plugin de Studio (plugin/RobloxMCP.lua): Sondea el servidor, ejecuta comandos dentro de Studio
Comunicación: Sondeo HTTP (intervalo de 300ms)

🔧 Uso con otros servidores MCP

Este servidor está diseñado para funcionar junto al MCP oficial de Roblox Studio:

Caso de uso	Qué MCP
Lectura/escritura de scripts	Ultimate (getScript/setScript)
Pruebas de juego	Official (start_stop_play)
Salida de consola	Official (get_console_output)
Manipulación de instancias	Ultimate
Cambios de propiedad	Ultimate

📝 Impacto en el mundo real

Antes de este MCP, una simple corrección de una línea en un script de 260 líneas requería:

run_code para obtener la fuente
Coincidencia de patrones gsub (a menudo falla)
run_code para volver a escribir
Rezar para que funcionara
Repetir 3-5 veces

Ahora: editScript(path, 103, 103, "nuevo código") → Listo. Al primer intento.

🤝 Contribuyendo

¡Las PR son bienvenidas! Especialmente para:

Nuevas herramientas
Mejor manejo de errores
Mejoras de rendimiento
Documentación

📄 Licencia

MIT

Roblox Studio Ultimate MCP Server