@weppy/roblox-mcp 1.0.3 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Roblox MCP server and tools for AI-powered game development",
-    "version": "1.0.3"
+    "version": "1.2.1"
   },
   "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.3",
+      "description": "MCP server for Roblox Studio integration - AI-powered game development with specialized agents and skills",
+      "version": "1.2.1",
       "author": {
         "name": "hope1026"
       },

package/CHANGELOG.md

@@ -8,6 +8,23 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+
+## [1.2.1] - 2026-02-28
+
+### Other Changes
+
+- UI improvements and stability enhancements
+
+
+## [1.2.0] - 2026-02-26
+
+### Features
+
+- Update documentation and scripts for CommandHandlers structure and verification process
+- Implement extended handlers for Roblox Engine API access
+
+
 ## [1.0.3] - 2026-02-24
 
 ### Features

package/README.md

@@ -24,6 +24,8 @@ This is not just code generation. It is **executable, production-oriented action
 The second pillar is **Project Sync**.
 AI works from a synchronized local mirror, so multi-file updates stay consistent.
 
+![Sync workflow — Studio and local files synchronized in real time](docs/assets/screenshots/sync.png)
+
 - Basic: one-way sync (Studio -> Local)
 - Pro: bidirectional sync + per-type Direction/Apply Mode + history + multi-place
 

package/docs/assets/screenshots/sync.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5888be201ba145eef507686b9fb2495c8aeb281d7dfc7b48260fd9d53242e938
+size 856271

package/docs/assets/screenshots/sync_conflict.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed1a1407d6760d00ae2b14c7a676788383a320388fc6977d14bec78e4c217476
+size 53297

package/docs/en/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ If specific environment variables are needed:
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **Configuration file:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/en/sync/overview.md

@@ -12,6 +12,8 @@ Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI work
 
 ## How it works
 
+![Sync workflow — Studio tree mirrored to local files](../../assets/screenshots/sync.png)
+
 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
@@ -92,7 +94,17 @@ In Pro, Direction and Apply Mode can be controlled per type.
 - "Check sync status, then summarize only risky changes from recent history"
 - "Refactor scripts in `ServerScriptService` first and include history output"
 
-### 3) Recover when needed
+### 3) Resolve conflicts
+
+When changes are detected on both Studio and local sides during bidirectional sync, a conflict resolution dialog appears.
+
+![Local Changes Detected — conflict resolution options (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+
+- **Studio Priority**: overwrite with Studio state as the source of truth
+- **Local Priority**: apply local files to Studio
+- **Per-File**: choose which side takes priority for each file individually
+
+### 4) Recover when needed
 
 - Track recent entries with `history`
 - Inspect target file with `read_file`

package/docs/es/README.md

@@ -24,6 +24,8 @@ No es solo generacion de codigo. Son **acciones ejecutables orientadas a producc
 El segundo eje es **Project Sync**.
 La IA trabaja sobre un espejo local sincronizado, asi que los cambios en multiples archivos se mantienen consistentes.
 
+![Flujo de Sync — Studio y archivos locales sincronizados en tiempo real](../assets/screenshots/sync.png)
+
 - Basic: sincronizacion unidireccional (Studio -> Local)
 - Pro: sincronizacion bidireccional + Direction/Apply Mode por tipo + historial + multiplace
 

package/docs/es/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ Si se necesitan variables de entorno específicas:
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **Archivo de configuración:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/es/sync/overview.md

@@ -12,6 +12,8 @@ Sin Sync, la IA solo ve fragmentos pegados en el chat. Con Sync activo, trabaja
 
 ## Como funciona
 
+![Flujo de Sync — arbol de Studio reflejado en archivos locales](../../assets/screenshots/sync.png)
+
 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
@@ -92,7 +94,17 @@ En Pro puedes controlar Direction y Apply Mode por tipo.
 - "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
+### 3) Resolver conflictos
+
+Cuando se detectan cambios tanto en Studio como en local durante la sincronizacion bidireccional, aparece un dialogo de resolucion de conflictos.
+
+![Local Changes Detected — opciones de resolucion de conflictos (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+
+- **Studio Priority**: sobrescribir usando el estado de Studio como fuente de verdad
+- **Local Priority**: aplicar los archivos locales a Studio
+- **Per-File**: elegir que lado tiene prioridad para cada archivo individualmente
+
+### 4) Recuperar cuando sea necesario
 
 - Sigue cambios recientes con `history`
 - Inspecciona archivo objetivo con `read_file`

package/docs/id/README.md

@@ -24,6 +24,8 @@ Ini bukan sekadar generate kode. Ini adalah **aksi yang benar-benar bisa dieksek
 Pilar kedua adalah **Project Sync**.
 AI bekerja dari mirror lokal yang tersinkron, jadi perubahan lintas banyak file tetap konsisten.
 
+![Alur Sync — Studio dan file lokal tersinkron secara real time](../assets/screenshots/sync.png)
+
 - Basic: sinkronisasi satu arah (Studio -> Local)
 - Pro: sinkronisasi dua arah + Direction/Apply Mode per tipe + riwayat + multiplace
 

package/docs/id/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ Jika variabel lingkungan tertentu diperlukan:
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **File konfigurasi:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/id/sync/overview.md

@@ -12,6 +12,8 @@ Tanpa Sync, AI hanya melihat potongan kode yang ditempel di chat. Dengan Sync ak
 
 ## Cara kerjanya
 
+![Alur Sync — tree Studio di-mirror ke file lokal](../../assets/screenshots/sync.png)
+
 1. Full Sync: mirror awal dari tree/instance Studio ke lokal
 2. Incremental Sync: perubahan baru terus disinkronkan
 3. Pelacakan History/Status: cek apa yang berubah, kapan, dan ke arah mana
@@ -92,7 +94,17 @@ Di Pro, Direction dan Apply Mode bisa diatur per tipe.
 - "Cek status sync, lalu rangkum hanya perubahan berisiko dari riwayat terbaru"
 - "Refactor dulu script di `ServerScriptService` dan sertakan catatan riwayat"
 
-### 3) Pemulihan saat dibutuhkan
+### 3) Menyelesaikan konflik
+
+Ketika perubahan terdeteksi di sisi Studio maupun lokal selama sinkronisasi dua arah, dialog resolusi konflik akan muncul.
+
+![Local Changes Detected — opsi resolusi konflik (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+
+- **Studio Priority**: timpa dengan status Studio sebagai sumber kebenaran
+- **Local Priority**: terapkan file lokal ke Studio
+- **Per-File**: pilih sisi mana yang diprioritaskan untuk setiap file secara individual
+
+### 4) Pemulihan saat dibutuhkan
 
 - Lacak perubahan terbaru dengan `history`
 - Periksa file target dengan `read_file`

package/docs/ja/README.md

@@ -24,6 +24,8 @@ AIがStudio内で、スクリプト、インスタンス、プロパティ、地
 第二の柱は**Project Sync**です。
 同期されたローカルミラーを基準にAIが作業するため、複数ファイルにまたがる変更も一貫して適用できます。
 
+![Syncワークフロー — Studioとローカルファイルがリアルタイムで同期される様子](../assets/screenshots/sync.png)
+
 - Basic: 片方向同期 (Studio -> Local)
 - Pro: 双方向同期 + タイプ別Direction/Apply Mode + 変更履歴 + マルチPlace
 

package/docs/ja/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ gemini mcp add weppy-roblox-mcp npx -s user --trust -- -y @weppy/roblox-mcp
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **設定ファイル:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/ja/sync/overview.md

@@ -12,6 +12,8 @@ Syncがない場合、AIはチャットに貼られた断片だけを見て判
 
 ## 基本の動作
 
+![Syncワークフロー — Studioツリーがローカルファイルにミラーされる様子](../../assets/screenshots/sync.png)
+
 1. Full Sync: Studioツリー/インスタンスをローカルに初期ミラー
 2. Incremental Sync: 以後の変更分のみを継続反映
 3. History/Status追跡: いつ・どの方向で何が変わったかを確認
@@ -92,7 +94,17 @@ ProではタイプごとにDirection/Apply Modeを細かく制御できます。
 - 「Sync状態を確認して、直近履歴からリスクの高い変更だけ要約して」
 - 「`ServerScriptService` のスクリプトを先にリファクタリングして、履歴も残して」
 
-### 3) 問題時の復旧
+### 3) コンフリクトの解決
+
+双方向同期中にStudioとローカルの両方で変更が検出されると、コンフリクト解決ダイアログが表示されます。
+
+![Local Changes Detected — コンフリクト解決オプション (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+
+- **Studio Priority**: Studio側の状態を基準に上書き
+- **Local Priority**: ローカルファイルをStudioに反映
+- **Per-File**: ファイルごとにどちら側を優先するか個別に選択
+
+### 4) 問題時の復旧
 
 - `history` で最近の変更を追跡
 - `read_file` で対象ファイルを確認

package/docs/ko/README.md

@@ -21,9 +21,11 @@ Roblox MCP의 첫 번째 축은 **MCP Tool 실행 능력**입니다.
 
 ### 2) Sync: AI가 프로젝트 전체 문맥을 읽고 유지
 
-두 번째 축은 **Project Sync**입니다.  
+두 번째 축은 **Project Sync**입니다.
 AI가 로컬 동기화된 프로젝트를 기준으로 전체 구조를 이해해, 여러 파일에 걸친 변경을 일관되게 수행합니다.
 
+![Sync 워크플로우 — Studio와 로컬 파일이 실시간으로 동기화되는 모습](../assets/screenshots/sync.png)
+
 - Basic: Studio -> Local 단방향 동기화
 - Pro: 양방향 동기화 + 타입별 Direction/Apply Mode + 변경 기록 + 멀티 Place
 

package/docs/ko/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ gemini mcp add weppy-roblox-mcp npx -s user --trust -- -y @weppy/roblox-mcp
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **설정 파일:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/ko/sync/overview.md

@@ -12,6 +12,8 @@ Sync가 없으면 AI는 대화에 붙여 넣은 코드 일부만 보고 판단
 
 ## 기본 동작 방식
 
+![Sync 워크플로우 — Studio 트리가 로컬 파일로 동기화된 모습](../../assets/screenshots/sync.png)
+
 1. Full Sync: Studio 트리와 인스턴스를 로컬 미러로 초기 동기화
 2. Incremental Sync: 변경 감시로 이후 변경분만 반영
 3. History/Status 추적: 어떤 변경이 언제 어떤 방향으로 반영됐는지 확인
@@ -92,7 +94,17 @@ Pro에서는 타입별로 Direction/Apply Mode를 다르게 설정해 워크플
 - "Sync 상태 확인하고, 최근 변경 기록 기준으로 위험한 변경만 요약해줘"
 - "`ServerScriptService` 쪽 스크립트만 우선 리팩터링하고, 변경 이력까지 남겨줘"
 
-### 3) 문제 발생 시 복구하기
+### 3) 충돌 발생 시 해결하기
+
+양방향 동기화 중 Studio와 로컬 양쪽에서 변경이 감지되면, 아래와 같은 충돌 해결 화면이 나타납니다.
+
+![Local Changes Detected — 충돌 해결 옵션 (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+
+- **Studio Priority**: Studio 쪽 상태를 기준으로 덮어쓰기
+- **Local Priority**: 로컬 파일을 기준으로 Studio에 반영
+- **Per-File**: 파일별로 어느 쪽을 우선할지 개별 선택
+
+### 4) 문제 발생 시 복구하기
 
 - `history`로 최근 변경을 추적
 - 필요한 파일을 `read_file`로 확인

package/docs/pt-br/README.md

@@ -24,6 +24,8 @@ Nao e apenas geracao de codigo. Sao **acoes executaveis para fluxo real de desen
 O segundo eixo e o **Project Sync**.
 A IA trabalha com um espelho local sincronizado, entao alteracoes em varios arquivos continuam consistentes.
 
+![Fluxo de Sync — Studio e arquivos locais sincronizados em tempo real](../assets/screenshots/sync.png)
+
 - Basic: sincronizacao unidirecional (Studio -> Local)
 - Pro: sincronizacao bidirecional + Direction/Apply Mode por tipo + historico + multiplace
 

package/docs/pt-br/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ Se variáveis de ambiente específicas forem necessárias:
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **Arquivo de configuração:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/pt-br/sync/overview.md

@@ -12,6 +12,8 @@ Sem Sync, a IA so enxerga trechos colados no chat. Com Sync ativo, ela trabalha
 
 ## Como funciona
 
+![Fluxo de Sync — arvore do Studio espelhada em arquivos locais](../../assets/screenshots/sync.png)
+
 1. Full Sync: espelho inicial da arvore/instancias do Studio para local
 2. Incremental Sync: atualizacao continua das mudancas novas
 3. Rastreamento de History/Status: ver o que mudou, quando e em qual direcao
@@ -92,7 +94,17 @@ No Pro, voce controla Direction e Apply Mode por tipo.
 - "Verifica o estado do sync e resume so mudancas de risco do historico recente"
 - "Refatora primeiro scripts de `ServerScriptService` e registra no historico"
 
-### 3) Recuperar quando necessario
+### 3) Resolver conflitos
+
+Quando mudancas sao detectadas tanto no Studio quanto no local durante a sincronizacao bidirecional, um dialogo de resolucao de conflitos aparece.
+
+![Local Changes Detected — opcoes de resolucao de conflitos (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/sync_conflict.png)
+
+- **Studio Priority**: sobrescrever usando o estado do Studio como fonte de verdade
+- **Local Priority**: aplicar arquivos locais ao Studio
+- **Per-File**: escolher qual lado tem prioridade para cada arquivo individualmente
+
+### 4) Recuperar quando necessario
 
 - Acompanhe mudancas recentes com `history`
 - Inspecione o arquivo alvo com `read_file`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weppy/roblox-mcp",
-  "version": "1.0.3",
+  "version": "1.2.1",
   "description": "MCP (Model Context Protocol) server for Roblox Studio integration - enables AI coding agents to interact with Roblox Studio in real-time",
   "main": "plugins/weppy-roblox-mcp/dist/index.js",
   "type": "module",

package/plugins/weppy-roblox-mcp/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "weppy-roblox-mcp",
-  "description": "MCP server for Roblox Studio integration - 130+ tools for AI-powered game development with specialized agents and skills",
-  "version": "1.0.3",
+  "description": "MCP server for Roblox Studio integration - AI-powered game development with specialized agents and skills",
+  "version": "1.2.1",
   "author": {
     "name": "hope1026"
   },