@weppy/roblox-mcp 1.0.2 → 1.0.3

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Roblox MCP server and tools for AI-powered game development",
-    "version": "1.0.2"
+    "version": "1.0.3"
   },
   "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": "1.0.2",
+      "version": "1.0.3",
       "author": {
         "name": "hope1026"
       },

package/CHANGELOG.md

@@ -7,6 +7,28 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+## [1.0.3] - 2026-02-24
+
+### Features
+
+- add restoreToken support for license management
+
+### Documentation
+
+- update tool documentation to clarify sync actions and add `progress`
+
+### Chores
+
+- add initial planning and task documents for manifest-driven codegen architecture
+- remove unused license server deployment workflow and coverage reports
+
+### Other Changes
+
+- refactor: remove FooterCard module and integrate reset/feedback functionality directly into SettingsTab
+- refactor: centralize UI localization handling across MCP tab components
+
+
 ## [1.0.2] - 2026-02-23
 
 ### Bug Fixes

package/README.md

@@ -6,67 +6,40 @@
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## What You Can Do
+## Core Capabilities
 
-### From One Idea to a Playable Game
+### 1) MCP Tools: Direct execution in Studio from natural language
 
-"Make a Minecraft-style survival game with day/night, crafting, and wave defense." — One sentence and AI designs the game structure, builds the map, creates objects, and writes every script.
+The first pillar of Roblox MCP is **MCP tool execution**.
+AI can directly handle scripts, instances, properties, terrain, lighting, assets, audio, and animation inside Studio.
 
-> **Tip**: Ask "Make a plan first", review it, then say "Execute it" for better results.
+- "Add particles + sound + cooldown when the player jumps."
+- "Build a boss arena at map center and place collision-safe spawn points."
+- "Change this module interface and update every dependent script."
 
-### An AI That Has Read Your Entire Project
+This is not just code generation. It is **executable, production-oriented actions**.
 
-AI syncs your Roblox project to local files, learning every script, object, and structure. Dozens of files understood at once, changed consistently.
+### 2) Sync: Keep full project context stable for AI
 
-- "Find every place that uses RemoteEvents and map out the call flow."
-- "Refactor all enemy AI scripts to use a unified state machine."
-- "Summarize only the risky changes made since yesterday."
+The second pillar is **Project Sync**.
+AI works from a synchronized local mirror, so multi-file updates stay consistent.
 
-Manage multiple Places simultaneously. Track the full history of changes.
+- Basic: one-way sync (Studio -> Local)
+- Pro: bidirectional sync + per-type Direction/Apply Mode + history + multi-place
 
-### Scripts: Write, Refactor, Debug — Across Related Files
+You keep source-of-truth clear and avoid losing change context.
 
-Not just the file you point at. AI handles the whole dependency chain.
+## Immediate Value
 
-- "When the player jumps, add particles, a sound, and a cooldown."
-- "Find all event connections that could leak memory and fix them safely."
-- "Change this module's interface and update every script that references it."
+- Compress repetitive work: turn many manual edits into one request
+- Change related files together: not just one target file
+- Lower risk: rely on sync state and history before applying changes
+- Better token efficiency (Pro): reduce round trips with bulk actions
 
-### Build and Place Objects — Hundreds at Once
+## Detailed Docs
 
-"Line up 50 street lights along this road", "Place 20 brick houses across the district with random rotations" — AI creates them directly in Studio. Batch-update properties across any number of objects with a single command.
-
-### Lighting, Weather, and Atmosphere in One Sentence
-
-"Change to a dusty desert at sunset", "Make it a stormy night where lightning briefly illuminates the area" — one sentence and lighting, sky, atmosphere, and fog all update at once.
-
-### Sculpt Terrain Through Conversation
-
-"Mountains in the north, a river through the center, open plains in the south" — generate any landscape through conversation. Control material, color, height, and smoothing. Build entire maps without touching the terrain editor.
-
-### Search Creator Store and Place Instantly
-
-"Find a medieval castle model, place it at the map center, and scale it up 1.5x" — search free assets and insert them directly into your project.
-
-### Spatial Intelligence for Level Design
-
-"Find open space for a new boss arena", "Show only the areas where monsters can actually patrol" — AI handles complex spatial reasoning and placement logic.
-
-### Animations, Physics, and Audio as Connected Systems
-
-- "While the dash animation plays, change the player-enemy collision rules."
-- "Fade in the boss BGM when the ultimate activates, and smoothly return when it ends."
-
-Characters, collision, and sound working together as a game system, not separate tools.
-
-### Run Any Roblox Code Directly
-
-When built-in tools aren't enough, AI executes arbitrary Luau in Studio.
-
-- "Find every Part in the Workspace with Anchored=false and list them."
-- "Batch-update matching objects and log every change."
-
-> [View all tools](docs/en/tools/overview.md)
+- [Tools Overview](docs/en/tools/overview.md)
+- [Sync Deep Dive](docs/en/sync/overview.md)
 
 ## Getting Started
 

package/docs/en/sync/overview.md

@@ -0,0 +1,104 @@
+# Roblox MCP Sync Deep Dive
+
+Sync connects Roblox Studio state and local files so AI can read and modify the full project context reliably.
+
+## Why Sync matters
+
+Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI works from the whole project.
+
+- Apply refactors consistently across multiple scripts
+- Review risky changes quickly using history
+- Keep source-of-truth clear between Studio and local files
+
+## How it works
+
+1. Full Sync: initial mirror from Studio tree/instances to local files
+2. Incremental Sync: continuous update of new changes
+3. History/Status tracking: inspect what changed, when, and in which direction
+
+Default local path is `roblox-project-sync/place_{placeId}/explorer`.
+
+## Basic vs Pro
+
+| Item | Basic | Pro |
+|------|------|-----|
+| Sync direction | Studio -> Local | Bidirectional |
+| Per-type Direction | Not supported | Supported (Scripts / Values / Containers / Data / Services) |
+| Per-type Apply Mode | Not supported | Supported (Auto / Manual) |
+| Status/history APIs | Not supported | Supported (`status`, `history`, `progress`) |
+| `manage_sync` tool | Not supported | Supported |
+| Multi-place sync | Not supported | Supported (up to 3 places) |
+
+## Sync targets and default exclusions
+
+Default syncable services:
+
+- `Workspace`
+- `Lighting`
+- `ReplicatedStorage`
+- `ServerStorage`
+- `ServerScriptService`
+- `StarterGui`
+- `StarterPlayer`
+- `StarterPack`
+- `ReplicatedFirst`
+- `SoundService`
+- `Chat`
+- `LocalizationService`
+
+Default exclusions:
+
+- Classes: `Terrain`, `Camera`
+- Security-restricted paths: `CoreGui`, `CorePackages`, `RobloxScript`, `RobloxScriptSecurity`
+
+## Direction and Apply Mode
+
+### Direction (per-type sync direction)
+
+- `forward`: Studio -> Local
+- `reverse`: Local -> Studio
+- `bidirectional`: both directions
+
+Types are managed separately: `scripts`, `values`, `containers`, `data`, `services`.
+
+### Apply Mode (how reverse changes are applied)
+
+- `manual`: user confirms before applying to Studio
+- `auto`: detected changes are auto-applied
+
+In Pro, Direction and Apply Mode can be controlled per type.
+
+## `manage_sync` action guide (Pro)
+
+| Action | Description | Key params |
+|------|------|-----------|
+| `status` | Check current sync state for a place | `placeId` |
+| `config` | Get sync configuration | `placeId` |
+| `history` | Query change history | `placeId`, `query.limit`, `query.offset` |
+| `directions` | Get per-type direction settings | `placeId` |
+| `read_file` | Read a synced file | `placeId`, `instancePath` |
+| `write_file` | Write a synced file | `placeId`, `instancePath`, `content` |
+| `progress` | Get realtime sync progress/throughput | `placeId` |
+
+## Recommended workflow
+
+### 1) Start safely
+
+- Complete Full Sync first to establish a stable baseline
+- Start with `manual` apply mode to reduce risk
+
+### 2) Work with AI
+
+- "Check sync status, then summarize only risky changes from recent history"
+- "Refactor scripts in `ServerScriptService` first and include history output"
+
+### 3) Recover when needed
+
+- Track recent entries with `history`
+- Inspect target file with `read_file`
+- Restore content with `write_file`, then verify Studio state
+
+## Related docs
+
+- [Tools Overview](../tools/overview.md)
+- [Pro Upgrade Guide](../pro-upgrade.md)

package/docs/en/tools/overview.md

@@ -2,6 +2,9 @@
 
 For detailed parameters, check MCP tool definitions directly.
 
+Related docs:
+- [Sync Deep Dive](../sync/overview.md)
+
 Sync policy:
 - Basic: Studio -> Local one-way sync
 - Pro: Bidirectional sync + broader advanced action coverage (better AI token efficiency with bulk workflows)
@@ -211,11 +214,12 @@ Sync policy:
 | Action | Description | Tier |
 |--------|-------------|------|
 | `status` | Get sync status for a place | Pro |
-| `config` | Get/set sync configuration | Pro |
+| `config` | Get sync configuration | Pro |
 | `history` | Get change history | Pro |
-| `directions` | Get/set per-type sync directions | Pro |
+| `directions` | Get per-type sync directions | Pro |
 | `read_file` | Read a synced file | Pro |
 | `write_file` | Write to a synced file | Pro |
+| `progress` | Get real-time sync progress and bandwidth | Pro |
 
 ## Workspace State (Pro)
 

package/docs/es/README.md

@@ -6,82 +6,55 @@
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## Qué puedes hacer
+## Funciones principales
 
-### De una idea a un juego jugable
+### 1) MCP Tool: ejecuta en Studio desde lenguaje natural
 
-"Crea un juego de supervivencia estilo Minecraft con ciclo día/noche, recolección, crafteo y defensa de oleadas." — Una frase y la IA diseña la estructura, construye el mapa, crea los objetos y escribe todos los scripts.
+El primer eje de Roblox MCP es la **ejecucion de MCP Tool**.
+La IA puede manejar directamente scripts, instancias, propiedades, terreno, iluminacion, assets, audio y animacion dentro de Studio.
 
-> **Tip**: Pide primero "Haz un plan", revísalo y luego di "Ejecútalo" para obtener mejores resultados.
+- "Agrega particulas + sonido + cooldown cuando el jugador salte."
+- "Crea una arena de boss en el centro del mapa y coloca spawns sin colision."
+- "Cambia la interfaz de este modulo y actualiza todos los scripts dependientes."
 
-### Una IA que ha leído todo tu proyecto
+No es solo generacion de codigo. Son **acciones ejecutables orientadas a produccion**.
 
-La IA sincroniza tu proyecto de Roblox en archivos locales y aprende cada script, objeto y estructura. Docenas de archivos entendidos a la vez, modificados de forma consistente.
+### 2) Sync: mantiene el contexto completo del proyecto
 
-- "Encuentra todos los lugares que usan RemoteEvents y mapea el flujo de llamadas."
-- "Refactoriza todos los scripts de IA enemiga para usar una máquina de estados unificada."
-- "Resume solo los cambios peligrosos realizados desde ayer."
+El segundo eje es **Project Sync**.
+La IA trabaja sobre un espejo local sincronizado, asi que los cambios en multiples archivos se mantienen consistentes.
 
-Gestiona múltiples Places simultáneamente. Rastrea el historial completo de cambios.
+- Basic: sincronizacion unidireccional (Studio -> Local)
+- Pro: sincronizacion bidireccional + Direction/Apply Mode por tipo + historial + multiplace
 
-### Scripts: escribir, refactorizar, depurar — en archivos relacionados a la vez
+Asi mantienes claro cual es la fuente de verdad y no pierdes contexto de cambios.
 
-No solo el archivo que señalas. La IA maneja toda la cadena de dependencias.
+## Valor inmediato para el usuario
 
-- "Cuando el jugador salte, agrega partículas, sonido y cooldown."
-- "Encuentra todas las conexiones de eventos que podrían tener memory leaks y corrígelas de forma segura."
-- "Cambia la interfaz de este módulo y actualiza todos los scripts que lo referencian."
+- Comprime trabajo repetitivo: convierte muchas ediciones manuales en una sola instruccion
+- Cambios relacionados en conjunto: no solo un archivo aislado
+- Menor riesgo: decide cambios con estado de sync e historial
+- Mejor eficiencia de tokens (Pro): menos idas y vueltas con acciones masivas
 
-### Crear y colocar objetos — cientos con un solo comando
+## Documentacion detallada
 
-"Alinea 50 farolas a lo largo de esta carretera", "Coloca 20 casas de ladrillo por el distrito con rotaciones aleatorias" — la IA los crea directamente en Studio. Actualiza propiedades en cualquier número de objetos con un solo comando.
-
-### Iluminación, clima y atmósfera en una frase
-
-"Cambia a un desierto polvoriento al atardecer", "Hazlo una noche tormentosa donde los relámpagos iluminen brevemente el área" — una frase y la iluminación, el cielo, la atmósfera y la niebla se actualizan al mismo tiempo.
-
-### Esculpe terreno a través de la conversación
-
-"Montañas al norte, un río en el centro, llanuras abiertas al sur" — genera cualquier paisaje conversando. Controla material, color, altura y suavizado. Construye mapas enteros sin tocar el editor de terreno.
-
-### Busca en Creator Store y coloca al instante
-
-"Encuentra un modelo de castillo medieval, colócalo en el centro del mapa y escálalo 1.5x" — busca assets gratuitos e insértalos directamente en tu proyecto.
-
-### Inteligencia espacial para el diseño de niveles
-
-"Encuentra espacio abierto para una nueva arena del jefe", "Muestra solo las áreas donde los monstruos realmente pueden patrullar" — la IA maneja el razonamiento espacial complejo y la lógica de colocación.
-
-### Animaciones, física y audio como sistemas conectados
-
-- "Mientras se reproduce la animación de dash, cambia las reglas de colisión jugador-enemigo."
-- "Haz fade in del BGM del jefe cuando se activa el ultimate, y vuelve suavemente cuando termina."
-
-Personajes, colisión y sonido trabajando juntos como sistema de juego, no como herramientas separadas.
-
-### Ejecuta cualquier código de Roblox directamente
-
-Cuando las herramientas integradas no son suficientes, la IA ejecuta Luau arbitrario en Studio.
-
-- "Encuentra todas las Parts en el Workspace con Anchored=false y listarlas."
-- "Actualiza en lote los objetos coincidentes y registra cada cambio."
-
-> [Ver todas las herramientas](tools/overview.md)
+- [Cobertura de herramientas (Tools Overview)](tools/overview.md)
+- [Guia detallada de Sync](sync/overview.md)
 
 ## Comenzar
 
-La instalación se completa en dos pasos:
+La instalacion se completa en dos pasos:
 
 1. **Instalar el plugin de Roblox Studio** — Hace de puente entre Studio e IA
 2. **Registrar el servidor MCP en tu app de IA** — Para que la app de IA lo reconozca
 
-Solo toma 5 minutos. 👉 [Ver guía de instalación](installation/README.md)
+Solo toma 5 minutos. 👉 [Ver guia de instalacion](installation/README.md)
 
 ## Upgrade Pro
 
-Sync bidireccional, capacidades de creación avanzadas y eficiencia de tokens de IA — todo en una sola actualización.
+Sync bidireccional, capacidades de creacion avanzadas y eficiencia de tokens de IA — todo en una sola actualizacion.
 
-👉 [Guía de actualización Pro](pro-upgrade.md)
+👉 [Guia de actualizacion Pro](pro-upgrade.md)
 
 ## Enlaces
 

package/docs/es/sync/overview.md

@@ -0,0 +1,104 @@
+# Guia detallada de Sync en Roblox MCP
+
+Sync conecta el estado de Roblox Studio con archivos locales para que la IA pueda leer y modificar el contexto completo del proyecto de forma confiable.
+
+## Por que Sync es importante
+
+Sin Sync, la IA solo ve fragmentos pegados en el chat. Con Sync activo, trabaja sobre todo el proyecto.
+
+- Aplicar refactors de forma consistente en multiples scripts
+- Revisar cambios riesgosos rapidamente usando historial
+- Mantener clara la fuente de verdad entre Studio y archivos locales
+
+## Como funciona
+
+1. Full Sync: espejo inicial del arbol/instancias de Studio a local
+2. Incremental Sync: reflejo continuo de cambios nuevos
+3. Seguimiento de History/Status: ver que cambio, cuando y en que direccion
+
+La ruta local por defecto es `roblox-project-sync/place_{placeId}/explorer`.
+
+## Basic vs Pro
+
+| Item | Basic | Pro |
+|------|------|-----|
+| Direccion de sync | Studio -> Local | Bidireccional |
+| Direction por tipo | No soportado | Soportado (Scripts / Values / Containers / Data / Services) |
+| Apply Mode por tipo | No soportado | Soportado (Auto / Manual) |
+| APIs de estado/historial | No soportado | Soportado (`status`, `history`, `progress`) |
+| Herramienta `manage_sync` | No soportado | Soportado |
+| Sync multiplace | No soportado | Soportado (hasta 3 places) |
+
+## Objetivos de sync y exclusiones por defecto
+
+Servicios sincronizables por defecto:
+
+- `Workspace`
+- `Lighting`
+- `ReplicatedStorage`
+- `ServerStorage`
+- `ServerScriptService`
+- `StarterGui`
+- `StarterPlayer`
+- `StarterPack`
+- `ReplicatedFirst`
+- `SoundService`
+- `Chat`
+- `LocalizationService`
+
+Exclusiones por defecto:
+
+- Clases: `Terrain`, `Camera`
+- Rutas restringidas por seguridad: `CoreGui`, `CorePackages`, `RobloxScript`, `RobloxScriptSecurity`
+
+## Direction y Apply Mode
+
+### Direction (direccion por tipo)
+
+- `forward`: Studio -> Local
+- `reverse`: Local -> Studio
+- `bidirectional`: ambas direcciones
+
+Los tipos se gestionan por separado: `scripts`, `values`, `containers`, `data`, `services`.
+
+### Apply Mode (como se aplican cambios reverse)
+
+- `manual`: el usuario confirma antes de aplicar a Studio
+- `auto`: los cambios detectados se aplican automaticamente
+
+En Pro puedes controlar Direction y Apply Mode por tipo.
+
+## Guia de acciones `manage_sync` (Pro)
+
+| Accion | Descripcion | Parametros clave |
+|------|------|-----------|
+| `status` | Consultar estado actual de sync de un place | `placeId` |
+| `config` | Obtener configuracion de sync | `placeId` |
+| `history` | Consultar historial de cambios | `placeId`, `query.limit`, `query.offset` |
+| `directions` | Obtener direcciones por tipo | `placeId` |
+| `read_file` | Leer archivo sincronizado | `placeId`, `instancePath` |
+| `write_file` | Escribir archivo sincronizado | `placeId`, `instancePath`, `content` |
+| `progress` | Obtener progreso/throughput en tiempo real | `placeId` |
+
+## Flujo recomendado
+
+### 1) Empezar con seguridad
+
+- Completa Full Sync primero para establecer una base estable
+- Empieza con modo `manual` para reducir riesgo
+
+### 2) Trabajar con IA
+
+- "Revisa el estado de sync y resume solo cambios riesgosos del historial reciente"
+- "Refactoriza primero scripts de `ServerScriptService` y deja registro en historial"
+
+### 3) Recuperar cuando sea necesario
+
+- Sigue cambios recientes con `history`
+- Inspecciona archivo objetivo con `read_file`
+- Restaura contenido con `write_file` y verifica en Studio
+
+## Documentos relacionados
+
+- [Cobertura de herramientas (Tools Overview)](../tools/overview.md)
+- [Guia de upgrade Pro](../pro-upgrade.md)