@weppy/roblox-mcp 0.1.8 → 0.1.10

package/docs/en/tools/overview.md

@@ -1,238 +1,95 @@
-# Roblox MCP Tools
+# Roblox MCP Features
 
-For detailed parameters, refer to the MCP tool definitions directly.
+Connect AI to Roblox Studio and automate various tasks. Here's what you can do by category.
 
 ---
 
-## Basic Tools (68)
-
-### Instance - 13
-
-| Tool | Description |
-|------|-------------|
-| `create_instance` | Create a new instance |
-| `create_instance_with_properties` | Create instance with properties |
-| `clone_instance` | Clone an existing instance |
-| `delete_instance` | Delete an instance |
-| `move_instance` | Move instance to new parent |
-| `rename_instance` | Rename an instance |
-| `get_instance` | Get instance information |
-| `get_instance_children` | Get children of an instance |
-| `find_first_child` | Find first child by name |
-| `find_first_descendant` | Find first descendant by name |
-| `get_class_info` | Get class information |
-| `wait_for_child` | Wait for child to exist |
-| `pivot_to` | Set Pivot CFrame |
-
-### Property - 10
-
-| Tool | Description |
-|------|-------------|
-| `get_property` | Get property value |
-| `set_property` | Set property value |
-| `get_all_properties` | Get all properties |
-| `set_multiple_properties` | Set multiple properties at once |
-| `set_calculated_property` | Set property with calculated value |
-| `set_relative_property` | Set property with relative value |
-| `get_attribute` | Get attribute value |
-| `set_attribute` | Set attribute value |
-| `get_all_attributes` | Get all attributes |
-| `delete_attribute` | Delete an attribute |
-
-### Script - 9
-
-| Tool | Description |
-|------|-------------|
-| `create_script` | Create a new script |
-| `get_script_source` | Get script source code |
-| `set_script_source` | Update script source code |
-| `delete_script` | Delete a script |
-| `edit_script_lines` | Edit specific lines |
-| `insert_script_lines` | Insert lines |
-| `delete_script_lines` | Delete lines |
-| `search_in_scripts` | Search within scripts |
-| `get_script_dependencies` | Get dependencies |
-
-### Selection - 12
-
-| Tool | Description |
-|------|-------------|
-| `get_selection` | Get currently selected instances |
-| `get_selection_context` | Get selection with context |
-| `get_selection_details` | Get detailed selection info |
-| `set_selection` | Set instance selection |
-| `clear_selection` | Clear selection |
-| `add_to_selection` | Add to selection |
-| `remove_from_selection` | Remove from selection |
-| `get_place_info` | Get Place information |
-| `get_services` | Get game services list |
-| `get_studio_settings` | Get Studio settings |
-| `run_command` | Execute Studio command |
-| `watch_selection` | Watch selection changes |
-
-### Search - 2
-
-| Tool | Description |
-|------|-------------|
-| `search_by_name` | Search instances by name |
-| `search_by_class` | Search instances by class |
-
-### Tag - 5
-
-| Tool | Description |
-|------|-------------|
-| `add_tag` | Add tag to instance |
-| `remove_tag` | Remove tag from instance |
-| `get_tags` | Get instance tags |
-| `get_tagged` | Get instances with tag |
-| `has_tag` | Check if instance has tag |
-
-### Camera - 4
-
-| Tool | Description |
-|------|-------------|
-| `get_camera_info` | Get camera information |
-| `get_suggested_camera_view` | Get suggested camera view |
-| `focus_camera_path` | Focus camera on instance by path |
-| `focus_camera_position` | Focus camera on world position |
-
-### Log - 3
-
-| Tool | Description |
-|------|-------------|
-| `get_output_logs` | Get output logs |
-| `clear_output_logs` | Clear output logs |
-| `get_recent_errors` | Get recent errors |
-
-### Connection - 2
-
-| Tool | Description |
-|------|-------------|
-| `get_connection_info` | Get connection status |
-| `get_usage_status` | Get usage/quota status |
+## Basic (Free)
+
+### Object Management
+
+Create, clone, delete, and move game objects like parts, models, and folders. Tasks like "Make a red part" or "Clone this model and place it next to it" are possible.
+
+### Property Settings
+
+Read and change all properties of objects like size, color, position, and material. You can change multiple properties at once or adjust them relatively based on current values.
+
+### Scripts
+
+Create new scripts, read existing code, and modify it. You can edit specific lines, search for text within scripts, or identify dependencies to see which modules are referenced.
+
+### Selection
+
+Check currently selected objects, change selections, and clear selections. Essential for understanding and controlling what you're working with in Studio.
+
+### Search
+
+Find objects in your game by name or class (type).
+
+### Tags
+
+Add or remove tags from objects and find all objects with a specific tag at once. Useful for managing groups of similar objects.
+
+### Camera
+
+Move the camera to specific objects or positions. Convenient for quickly viewing the area you're working on.
+
+### Logs
+
+Check output logs and errors that occurred during game execution. Helps find and fix bugs.
+
+### Connection
+
+Check the connection status and usage between MCP server and Roblox Studio.
 
 ---
 
-## Pro Tools (+72)
-👉 [Pro Upgrade Guide](../pro-upgrade.md)
+## Pro
+
+Upgrade to Pro if you need more powerful features.
+
+### Advanced Selection
+
+Get detailed selection context with properties and source code, view selection hierarchy, add/remove items from selection, query Place information and game services. Useful for advanced workflows and automation.
 
-### Script - 2
-
-| Tool | Description |
-|------|-------------|
-| `replace_in_scripts` | Batch replace in scripts |
-| `execute_script` | Execute Luau code directly |
-
-### Search - 6
-
-| Tool | Description |
-|------|-------------|
-| `get_file_tree` | Get file tree |
-| `get_project_structure` | Get project structure tree |
-| `search_by_property` | Search by property |
-| `search_by_tag` | Search by tag |
-| `get_descendants` | Get all descendants |
-| `get_ancestors` | Get ancestors |
-
-### Bulk - 8
-
-| Tool | Description |
-|------|-------------|
-| `mass_create_instances` | Mass create instances |
-| `mass_delete_instances` | Mass delete instances |
-| `mass_set_property` | Mass set property |
-| `mass_get_property` | Mass get property |
-| `mass_duplicate` | Mass duplicate instances |
-| `smart_duplicate` | Smart duplicate with offset |
-| `batch_execute` | Batch execute commands |
-| `modify_children` | Modify all children |
-
-### Asset - 7
-
-| Tool | Description |
-|------|-------------|
-| `insert_model` | Insert model from Creator Store |
-| `get_asset_info` | Get asset information |
-| `search_creator_store` | Search Creator Store assets |
-| `search_and_insert_model` | Search and insert model |
-| `insert_free_model` | Insert free model |
-| `insert_package` | Insert package |
-| `export_selection` | Export selection |
-
-### Environment - 5
-
-| Tool | Description |
-|------|-------------|
-| `set_lighting` | Set lighting properties |
-| `set_atmosphere` | Set Atmosphere properties |
-| `set_sky` | Set Sky properties |
-| `set_terrain` | Set Terrain properties |
-| `set_time_of_day` | Set time of day |
-
-### State - 9
-
-| Tool | Description |
-|------|-------------|
-| `sync_workspace_state` | Sync Workspace state |
-| `get_workspace_snapshot` | Get Workspace snapshot |
-| `get_recent_changes` | Get recent changes |
-| `clear_change_history` | Clear change history |
-| `get_viewport_info` | Get viewport info |
-| `get_workspace_metadata` | Get Workspace metadata |
-| `get_script_list` | Get script list |
-| `get_selection_info` | Get selection info |
-| `clear_state_cache` | Clear state cache |
-
-### Spatial - 5
-
-| Tool | Description |
-|------|-------------|
-| `get_spatial_map` | Get spatial map of area |
-| `find_empty_space` | Find empty space in area |
-| `get_bounds` | Get instance bounding box |
-| `snap_to_grid` | Snap position to grid |
-| `check_collision` | Check collision between instances |
-
-### Raycast - 8
-
-| Tool | Description |
-|------|-------------|
-| `raycast` | Perform raycast and get hit info |
-| `find_ground` | Find ground position at point |
-| `check_placement` | Check if placement is valid |
-| `multi_raycast` | Perform multiple raycasts |
-| `scan_area` | Scan area and generate heightmap |
-| `find_flat_areas` | Find flat placement areas |
-| `find_spawn_positions` | Find valid spawn positions |
-| `analyze_walkable_area` | Analyze walkable area |
-
-### Terrain - 14
-
-| Tool | Description |
-|------|-------------|
-| `terrain_fill_block` | Fill terrain with block shape |
-| `terrain_fill_ball` | Fill terrain with ball shape |
-| `terrain_fill_cylinder` | Fill terrain with cylinder shape |
-| `terrain_fill_wedge` | Fill terrain with wedge shape |
-| `terrain_clear` | Clear terrain (Region object) |
-| `terrain_clear_region` | Clear terrain (min/max coords) |
-| `terrain_replace_material` | Replace terrain material |
-| `terrain_get_material_color` | Get terrain material color |
-| `terrain_set_material_color` | Set terrain material color |
-| `terrain_read_voxel` | Read single voxel |
-| `terrain_read_voxels` | Read voxel data |
-| `terrain_write_voxels` | Write voxel data |
-| `terrain_generate` | Generate procedural terrain |
-| `terrain_smooth` | Smooth terrain |
-
-### Visualization - 7
-
-| Tool | Description |
-|------|-------------|
-| `visualization_create_area` | Create area visualization |
-| `visualization_create_marker` | Create marker visualization (with preview) |
-| `visualization_create_line` | Create line visualization |
-| `visualization_remove` | Remove visualization |
-| `visualization_clear` | Clear all visualizations |
-| `visualization_get_status` | Get visualization status |
-| `visualization_focus` | Focus camera on visualization |
+### Advanced Scripts
+
+Batch replace content in multiple scripts or execute Luau code instantly. Useful for repetitive code modifications or quick testing.
+
+### Advanced Search
+
+Explore the entire file tree or search for objects by property or tag. Get a complete view of your project structure and query all descendants or ancestors of specific objects.
+
+### Bulk Operations
+
+Create, delete, modify, or duplicate hundreds of objects at once. Quickly handle large-scale tasks like planting trees on a map, changing the color of all parts, or placing objects according to patterns.
+
+### Assets
+
+Search the Roblox Creator Store for free models and insert them instantly. Add assets through conversation like "Find a medieval castle model" or "Insert a weapon model".
+
+### Environment Settings
+
+Configure lighting, sky, fog, terrain properties, and time of day with natural language. Requests like "Change to sunset vibes" or "Set time to midnight" are possible.
+
+### State Management
+
+Save the current state of Workspace as a snapshot, check recent changes and viewport state. Helps understand current state during complex tasks.
+
+### Spatial Analysis
+
+Accurately determine object size and position, find empty spaces, and check for collisions. You can also align objects to a grid.
+
+### Raycast
+
+Shoot invisible rays to find collision points with terrain or objects. Essential for game level design including finding ground positions, checking if objects can be placed, finding spawn locations, and analyzing walkable areas.
+
+### Terrain
+
+Fill, carve, and smooth terrain in various shapes like blocks, spheres, cylinders, and wedges. Change materials and colors, or procedurally generate natural terrain with mountains and rivers.
+
+### Visualization
+
+Display areas, markers, and lines on screen to visually confirm the space you're working in. Useful for debugging and level design review.
+
+👉 [Pro Upgrade Guide](../pro-upgrade.md)

package/docs/es/README.md

@@ -1,47 +1,46 @@
 # Roblox MCP
 
-[English](../en/README.md) | [한국어](../ko/README.md) | [日本語](../ja/README.md) | **Español** | [Português](../pt-br/README.md) | [Bahasa Indonesia](../id/README.md)
+> Habla con la IA y se ejecuta directamente en Roblox Studio.
 
-> Controla Roblox Studio con IA.
+[English](../../README.md) | [한국어](../ko/README.md) | [日本語](../ja/README.md) | **Español** | [Português](../pt-br/README.md) | [Bahasa Indonesia](../id/README.md)
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## Instrucciones de Instalacion
+## Qué puedes hacer
 
-### 1. Instalar el Plugin de Roblox
+### Crear juegos completos de una vez
+Puedes pedir cosas como "Crea un juego de supervivencia estilo Minecraft" o "Crea un juego de escape room", y la IA diseñará la estructura del juego, creará mapas, objetos y scripts por ti. Con una simple idea, puedes tener un juego jugable.
+> **Tip**: Pide primero "Haz un plan", revísalo y luego di "Ejecútalo" para obtener mejores resultados.
 
-👉 [Guia de instalacion del plugin](installation/roblox-plugin.md)
+### Crear y colocar objetos
+"Crea una casa de ladrillos rojos", "Planta 10 árboles en línea"
 
-### 2. Configuracion del Servidor MCP
+### Escribir y modificar scripts
+"Haz que salgan partículas cuando el jugador salte", "Encuentra el bug en este script"
 
-Se puede usar con cualquier aplicacion de IA que soporte MCP. Consulta la guia correspondiente a tu aplicacion de IA:
+### Configurar la atmósfera del mapa
+"Cámbialo a ambiente de atardecer", "Hazlo oscuro como un día lluvioso"
 
-| Aplicacion IA | Guia de instalacion |
-|---------------|---------------------|
-| Claude Code | [Como configurar](installation/claude-code.md) |
-| Claude Desktop | [Como configurar](installation/claude-app.md) |
-| Codex CLI | [Como configurar](installation/codex-cli.md) |
-| Codex Desktop | [Como configurar](installation/codex-app.md) |
-| Gemini CLI | [Como configurar](installation/gemini-cli.md) |
-| Cursor, Windsurf, etc. | [Como configurar](installation/antigravity.md) |
+### Generar terrenos
+Crea terrenos naturales como montañas, ríos, llanuras y cuevas solo con conversación
 
-## Lista de Herramientas
+### Buscar e insertar assets
+Busca e inserta modelos gratuitos del Creator Store. "Busca e inserta un modelo de castillo medieval"
 
-👉 [Ver lista completa de herramientas](tools/overview.md)
+### Análisis espacial y colocación
+"Encuentra espacios vacíos en esta área", "Analiza el área donde los monstruos pueden caminar"
 
-## Solucion de Problemas
+### Depuración y análisis
+Revisa logs de errores, encuentra problemas y corrige
 
-- **"Not Connected"**: Presiona el boton Connect nuevamente en el plugin
-- **Puerto**: Usa el puerto 3002 (localhost)
+> [Ver lista completa de funciones](tools/overview.md)
 
-## Enlaces
+## Comenzar
+1. **Instalar el plugin de Roblox Studio** — Conecta Studio con la IA
+2. **Registrar el servidor MCP en tu app de IA** — Para que la app de IA lo reconozca
+
+Toma solo 5 minutos. 👉 [Ver guía de instalación](installation/README.md)
 
+## Enlaces
 - [GitHub](https://github.com/hope1026/roblox-mcp)
 - [Reportar problemas](https://github.com/hope1026/roblox-mcp/issues)
-
-## Licencia
-
-Uso gratuito para desarrollo de juegos.
-
-✅ **Permitido**: Desarrollo de juegos, juegos comerciales, proyectos personales
-❌ **No permitido**: Reventa de software, desarrollo de productos competidores

package/docs/es/installation/README.md

@@ -0,0 +1,44 @@
+# Guía de Instalación
+
+Para usar Roblox MCP, necesitas configurar dos cosas:
+
+```
+App de IA (Claude, etc.)
+         ↓
+    Servidor MCP
+         ↓
+Plugin de Roblox Studio
+```
+
+## Paso 1: Instalar el Plugin de Roblox Studio
+
+El plugin conecta Roblox Studio con la IA.
+
+👉 [Guía de instalación del plugin](roblox-plugin.md)
+
+## Paso 2: Registrar el Servidor MCP en tu App de IA
+
+Configura el servidor MCP en tu app de IA para que pueda comunicarse con Roblox Studio.
+
+| App de IA | Cómo configurar |
+|-----------|----------------|
+| **Claude Code** (Recomendado) | [claude-code.md](ai-apps/claude-code.md) |
+| **Claude Desktop** | [claude-desktop.md](ai-apps/claude-desktop.md) |
+| **Cline** | [cline.md](ai-apps/cline.md) |
+| **Roo Code** | [roo-code.md](ai-apps/roo-code.md) |
+| **Cursor** | [cursor.md](ai-apps/cursor.md) |
+
+> **Nota**: Funciona con cualquier app compatible con MCP. El comando es:
+> ```bash
+> npx -y @weppy/roblox-mcp
+> ```
+
+## Después de la Instalación
+
+Prueba con un comando simple:
+
+```
+Crea una parte azul en Roblox Studio
+```
+
+Si funciona, ¡estás listo para empezar!

package/docs/es/installation/ai-apps/antigravity.md

@@ -0,0 +1,89 @@
+# Configuración de Antigravity
+
+Cómo usar Roblox MCP con [Google Antigravity](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/).
+
+> **Antigravity** es la plataforma de desarrollo basada en agentes de Google, donde los agentes de IA se mueven entre la edición de código, la terminal y el navegador para realizar tareas complejas de forma autónoma.
+
+## Requisitos previos
+
+1. **Antigravity** instalado (consulta la documentación oficial para SO compatibles y requisitos)
+2. **Node.js** (v18.0.0 o superior, `npx` disponible)
+3. **Plugin de Roblox Studio** instalado
+
+## Registrar servidor MCP
+
+En Antigravity, los servidores MCP se administran en el **panel de agente (Agent pane)**.
+
+### Registro manual mediante raw config (recomendado)
+
+1. En el panel de agente, haz clic en **⋯** → **MCP Servers** → **Manage MCP Servers** → **View raw config**
+
+![Abrir menú de MCP Servers](../../../assets/screenshots/antigravity/antigravity_mcp_services_menu.png)
+
+2. En la configuración (JSON) que se muestra, agrega/fusiona lo siguiente:
+
+```json
+{
+  "mcpServers": {
+    "weppy-roblox-mcp": {
+      "command": "npx",
+      "args": ["-y", "@weppy/roblox-mcp"]
+    }
+  }
+}
+```
+
+![Editar raw config](../../../assets/screenshots/antigravity/antigravity_mcp_raw.png)
+
+3. Guarda y ejecuta **Refresh** (o reinicia/actualiza según lo indique la UI)
+
+> La ruta/nombre real del archivo de configuración puede variar según el SO y la versión de Antigravity, así que edita siempre la ubicación indicada en **View raw config**.
+
+### Opción: Ajustar puerto/logs con variables de entorno
+
+Se recomienda mantener el valor predeterminado (HTTP `127.0.0.1:3002`). Si es necesario, puedes establecer variables de entorno así:
+
+```json
+{
+  "mcpServers": {
+    "weppy-roblox-mcp": {
+      "command": "npx",
+      "args": ["-y", "@weppy/roblox-mcp"],
+      "env": {
+        "HTTP_HOST": "127.0.0.1",
+        "HTTP_PORT": "3002",
+        "LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+## Prueba de conexión
+
+1. Abre **Roblox Studio** → pestaña Plugins → **W-MCP** → **Connect**
+2. En **Antigravity**, escribe:
+   ```
+   Dime qué está seleccionado actualmente en Roblox Studio
+   ```
+
+## Solución de problemas
+
+### Cuando el servidor no inicia
+
+Ejecuta el servidor MCP directamente para ver el error:
+```bash
+npx -y @weppy/roblox-mcp
+```
+
+### Falla de conexión
+
+- Verifica que el plugin de Roblox Studio esté en estado **Connected**
+- Verifica que el puerto **3002** no esté bloqueado por el firewall
+- Revisa el estado del servidor en el panel de agente **⋯** → **MCP Servers**
+- (Avanzado) Si cambiaste `HTTP_PORT`, el plugin/bridge de Roblox Studio también debe usar el mismo puerto.
+
+## Referencias
+
+- [Introducción a Google Antigravity](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/)
+- [Guía de inicio de Antigravity (Codelab)](https://codelabs.developers.google.com/getting-started-google-antigravity)

package/docs/es/installation/roblox-plugin.md

@@ -4,7 +4,7 @@ Instrucciones para instalar el plugin que conecta Roblox Studio con agentes de I
 
 ## 1. Descargar el Plugin
 
-1. Descarga `weppy-roblox-mcp-basic.zip` desde [GitHub Releases](https://github.com/hope1026/roblox-mcp/releases/latest)
+1. Descarga `weppy-roblox-mcp-basic-v{versión}.zip` desde [GitHub Releases](https://github.com/hope1026/roblox-mcp/releases/latest)
 2. Extrae el archivo ZIP — encontraras el archivo `roblox-plugin/WeppyRobloxMCP.rbxm` y guias de instalacion
 
 ## 2. Instalar el Plugin
@@ -32,12 +32,12 @@ El servidor MCP debe estar instalado. Completa primero la guia correspondiente a
 
 | Aplicacion IA | Guia de instalacion |
 |---------------|---------------------|
-| Claude Code | [Como configurar](claude-code.md) |
-| Claude Desktop | [Como configurar](claude-app.md) |
-| Codex CLI | [Como configurar](codex-cli.md) |
-| Codex Desktop | [Como configurar](codex-app.md) |
-| Gemini CLI | [Como configurar](gemini-cli.md) |
-| Cursor, Windsurf, etc. | [Como configurar](antigravity.md) |
+| Claude Code | [Como configurar](ai-apps/claude-code.md) |
+| Claude Desktop | [Como configurar](ai-apps/claude-app.md) |
+| Codex CLI | [Como configurar](ai-apps/codex-cli.md) |
+| Codex Desktop | [Como configurar](ai-apps/codex-app.md) |
+| Gemini CLI | [Como configurar](ai-apps/gemini-cli.md) |
+| Antigravity | [Como configurar](ai-apps/antigravity.md) |
 
 ### Conectar
 

package/docs/es/pro-upgrade.md

@@ -6,7 +6,7 @@
 
 **Juegos mas completos** - Con herramientas de terreno, entorno, assets y espacio, puedes crear mundos de juego terminados, no solo prototipos.
 
-## Herramientas que agrega Pro (72)
+## Herramientas que agrega Pro
 
 | Categoria | Funciones |
 |-----------|-----------|
@@ -21,8 +21,7 @@
 
 ### Paso 1: Comprar en Gumroad
 
-1. Visita [Gumroad - Weppy Roblox Plugin](https://sunityplugin.gumroad.com/l/chllph?utm_source=github&utm_medium=repo&utm_campaign=sunity_plugin
-)
+1. Visita [Gumroad - Weppy Roblox Plugin](https://gumroad.com/l/chllph?utm_source=github&utm_medium=repo&utm_campaign=sunity_plugin)
 2. Descarga el plugin
 
 ### Paso 2: Instalar el Plugin
@@ -37,12 +36,12 @@
 
 1. Abre el plugin W-MCP
 2. Verifica que aparezca la insignia "Pro"
-3. ¡Las 140 herramientas completas estan disponibles!
+3. Todas las herramientas estan disponibles!
 
 ## Comparacion de Funciones
 
-| Funcion | Basic (68) | Pro (140) |
-|---------|:----------:|:---------:|
+| Funcion | Basic | Pro |
+|---------|:-----:|:---:|
 | Instance, Script, Property | ✅ Acceso completo | ✅ Acceso completo |
 | Selection, Tag, Camera, Log | ✅ Acceso completo | ✅ Acceso completo |
 | Operaciones masivas (Bulk) | ― | ✅ Ilimitado |