@weppy/roblox-mcp 0.1.8 → 0.1.9

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Roblox MCP server and tools for AI-powered game development",
-    "version": "0.1.8"
+    "version": "0.1.9"
   },
   "plugins": [
     {
       "name": "weppy-roblox-mcp",
       "source": "./plugins/weppy-roblox-mcp",
       "description": "MCP server for Roblox Studio integration - 132 tools for AI-powered game development with specialized agents and skills",
-      "version": "0.1.8",
+      "version": "0.1.9",
       "author": {
         "name": "hope1026"
       },

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 
 
+
+## [0.1.9] - 2026-02-08
+
+### Other Changes
+
+- update test
+- refactor: improve stability
+
+
 ## [0.1.8] - 2026-02-08
 
 ### Fix

package/README.md

@@ -2,46 +2,58 @@
 
 **English** | [한국어](docs/ko/README.md) | [日本語](docs/ja/README.md) | [Español](docs/es/README.md) | [Português](docs/pt-br/README.md) | [Bahasa Indonesia](docs/id/README.md)
 
-> Control Roblox Studio with AI.
+> Tell AI what you want, and it happens in Roblox Studio.
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## Installation
+## What You Can Do
 
-### 1. Install Roblox Plugin
+### Create Complete Games
 
-👉 [Plugin Installation Guide](docs/en/installation/roblox-plugin.md)
+Just ask "Make a Minecraft-style survival game" or "Create an escape room puzzle game", and AI will design the game structure, build the map, create objects, and write scripts for you. Turn a simple idea into a playable game.
 
-### 2. Configure MCP Server
+> **Tip**: Ask "Make a plan first", review it, then say "Execute it" for better results.
 
-Works with any AI app that supports MCP. Choose your AI app:
+### Create and Place Objects
 
-| AI App | Setup Guide |
-|--------|-------------|
-| Claude Code | [Setup](docs/en/installation/claude-code.md) |
-| Claude Desktop | [Setup](docs/en/installation/claude-app.md) |
-| Codex CLI | [Setup](docs/en/installation/codex-cli.md) |
-| Codex Desktop | [Setup](docs/en/installation/codex-app.md) |
-| Gemini CLI | [Setup](docs/en/installation/gemini-cli.md) |
-| Cursor, Windsurf, etc. | [Setup](docs/en/installation/antigravity.md) |
+Say "Make a red brick house" or "Plant 10 trees in a row" and AI creates them directly in Roblox Studio. Create one object or hundreds at once.
 
-## Tools
+### Write and Modify Scripts
 
-👉 [Full Tools List](docs/en/tools/overview.md)
+Ask "Make particles appear when players jump" or "Find the bug in this script" and AI writes and fixes code for you. It analyzes existing scripts and understands dependencies too.
 
-## Troubleshooting
+### Set Scene Atmosphere
 
-- **"Not Connected"**: Click Connect button in the plugin again
-- **Port**: Uses port 3002 (localhost only)
+Just say "Change to sunset vibes" or "Make it dark like a rainy day" and AI automatically adjusts lighting, sky, and fog.
 
-## Links
+### Generate Terrain
 
-- [GitHub](https://github.com/hope1026/roblox-mcp)
-- [Issue Report](https://github.com/hope1026/roblox-mcp/issues)
+Create natural landscapes like mountains, rivers, plains, and caves through conversation. Customize materials, colors, and sizes freely.
+
+### Search and Insert Assets
+
+Search the Creator Store for free models and assets, then add them to your game instantly. Just say "Find a medieval castle model and insert it".
+
+### Spatial Analysis and Placement
+
+AI handles spatial tasks like "Find empty space in this area" or "Analyze where monsters can walk".
+
+### Debugging and Analysis
 
-## License
+Check game error logs, find problems, and fix them together with AI.
 
-Free to use for game development.
+> [View all features](docs/en/tools/overview.md)
 
-✅ **Allowed**: Game development, commercial games, personal projects
-❌ **Not Allowed**: Software resale, creating competing products
+## Getting Started
+
+Installation is complete in two steps:
+
+1. **Install Roblox Studio Plugin** — Acts as a bridge between Studio and AI
+2. **Register MCP Server with AI App** — Configure your AI app to recognize Roblox MCP
+
+Takes just 5 minutes. 👉 [View Installation Guide](docs/en/installation/README.md)
+
+## Links
+
+- [GitHub](https://github.com/hope1026/roblox-mcp)
+- [Issue Reports](https://github.com/hope1026/roblox-mcp/issues)

package/docs/en/installation/README.md

@@ -0,0 +1,51 @@
+# Installation Guide
+
+To use Roblox MCP, you need to install **two things**.
+
+```
+AI App (Claude, Codex, Gemini, etc.)
+       │
+   MCP Server ← Converts AI commands into a format Roblox understands
+       │
+Roblox Studio Plugin ← Executes commands inside Studio
+```
+
+When an AI app says "Create a blue part", the MCP server converts this request, and the Roblox Studio plugin actually creates the part.
+
+---
+
+## Step 1: Install Roblox Studio Plugin
+
+Download the plugin file from GitHub, then place it in Roblox Studio's Plugins folder.
+
+👉 [Plugin Installation Guide](roblox-plugin.md)
+
+---
+
+## Step 2: Register MCP Server with AI App
+
+Register the MCP server with your AI app. You can use it with any AI app that supports MCP.
+
+| AI App | Installation Guide |
+|--------|-------------------|
+| Claude Code | [Setup Instructions](ai-apps/claude-code.md) |
+| Claude Desktop | [Setup Instructions](ai-apps/claude-app.md) |
+| Codex CLI | [Setup Instructions](ai-apps/codex-cli.md) |
+| Codex Desktop | [Setup Instructions](ai-apps/codex-app.md) |
+| Gemini CLI | [Setup Instructions](ai-apps/gemini-cli.md) |
+| Antigravity | [Setup Instructions](ai-apps/antigravity.md) |
+
+> Even if your AI app isn't listed above, you can use it if it supports MCP. The MCP server command is `npx -y @weppy/roblox-mcp`.
+
+---
+
+## After Installation
+
+1. Open **Roblox Studio**, go to Plugins tab and click **W-MCP** → **Connect**
+2. Test in your **AI app** with:
+
+```
+Create a blue part in Roblox Studio
+```
+
+If the part is created successfully, installation is complete!

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

@@ -32,12 +32,12 @@ The MCP server must be installed. Complete the guide for your AI app first:
 
 | AI App | Installation Guide |
 |--------|-------------------|
-| Claude Code | [Setup Guide](claude-code.md) |
-| Claude Desktop | [Setup Guide](claude-app.md) |
-| Codex CLI | [Setup Guide](codex-cli.md) |
-| Codex Desktop | [Setup Guide](codex-app.md) |
-| Gemini CLI | [Setup Guide](gemini-cli.md) |
-| Cursor, Windsurf, etc. | [Setup Guide](antigravity.md) |
+| Claude Code | [Setup Guide](ai-apps/claude-code.md) |
+| Claude Desktop | [Setup Guide](ai-apps/claude-app.md) |
+| Codex CLI | [Setup Guide](ai-apps/codex-cli.md) |
+| Codex Desktop | [Setup Guide](ai-apps/codex-app.md) |
+| Gemini CLI | [Setup Guide](ai-apps/gemini-cli.md) |
+| Antigravity | [Setup Guide](ai-apps/antigravity.md) |
 
 ### Connecting
 

package/docs/en/pro-upgrade.md

@@ -6,7 +6,7 @@
 
 **Build Complete Games** - Terrain, environment, assets, and spatial tools let you create polished game worlds, not just prototypes.
 
-## What Pro Unlocks (72 additional tools)
+## What Pro Unlocks
 
 | Category | What you can do |
 |----------|-----------------|
@@ -21,8 +21,7 @@
 
 ### Step 1: Buy on Gumroad
 
-1. Go to [Gumroad - Weppy Roblox Plugin](https://sunityplugin.gumroad.com/l/chllph?utm_source=github&utm_medium=repo&utm_campaign=sunity_plugin
-)
+1. Go to [Gumroad - Weppy Roblox Plugin](https://gumroad.com/l/chllph?utm_source=github&utm_medium=repo&utm_campaign=sunity_plugin)
 2. Download the plugin
 
 ### Step 2: Install Plugin
@@ -37,12 +36,12 @@
 
 1. Open the W-MCP plugin
 2. Check that "Pro" badge is displayed
-3. All 140 tools are now available!
+3. All tools are now available!
 
 ## Feature Comparison
 
-| Feature | Basic (68 tools) | Pro (140 tools) |
-|---------|:----------------:|:---------------:|
+| Feature | Basic | Pro |
+|---------|:-----:|:---:|
 | Instance, Script, Property | ✅ Full access | ✅ Full access |
 | Selection, Tag, Camera, Log | ✅ Full access | ✅ Full access |
 | Bulk Operations | ― | ✅ Unlimited |

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