@weppy/roblox-mcp 1.3.1 → 1.4.1

package/.claude-plugin/marketplace.json

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

package/.gitattributes

@@ -0,0 +1 @@
+plugins/weppy-roblox-mcp/dist/index.js -linguist-generated -linguist-vendored

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+## [1.4.0] - 2026-03-08
+
+### New Features
+
+- Add Roblox Explorer VSCode extension — browse Studio instance tree directly in VSCode sidebar
+  - TreeDataProvider for real-time instance hierarchy visualization
+  - Auto-refresh via FileWatcher on sync data changes
+  - Icon mapping for Roblox class names (dark/light theme support)
+  - Copy instance path, open backing file, reveal in explorer commands
+
+### Improvements
+
+- Refactor MCP server deployment pipeline and build configuration
+- Improve camera and terrain sync stability and accuracy
+- Enhance plugin UI icons and visual consistency
+
+
 ## [1.3.1] - 2026-03-07
 
 ### Improvements

package/README.md

@@ -1,11 +1,21 @@
 # Roblox MCP
 
-> MCP server and plugin for Roblox Studio — control scripts, terrain, assets, and lighting with Claude Code, Cursor, Codex, and Gemini.
+> The MCP server that connects AI coding agents to Roblox Studio — control scripts, terrain, assets, lighting, audio, and animations via natural language.
 
 **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)
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
+## The Problem
+
+AI coding agents like Claude, Codex, and Gemini are powerful — but they cannot see or modify anything inside Roblox Studio. The DataModel, scripts, terrain, and lighting are all invisible to external tools. Without a bridge, AI can only generate code snippets that you must paste manually.
+
+## The Solution
+
+Roblox MCP provides a real-time bridge between AI agents and the Roblox Studio DataModel. It exposes the full Roblox API surface as executable MCP tools, so AI can **directly create, read, modify, and delete** instances, scripts, properties, terrain, and more — inside a live Studio session.
+
+This is not just code generation. It is **executable, production-oriented actions** running directly in Studio.
+
 ## Quick Install (5 minutes)
 
 **Step 1** — Install the Roblox Studio plugin (bridge between Studio and AI):
@@ -24,14 +34,15 @@ npx -y @weppy/roblox-mcp
 | Codex CLI | [Setup](docs/en/installation/ai-apps/codex-cli.md) |
 | Codex Desktop | [Setup](docs/en/installation/ai-apps/codex-app.md) |
 | Gemini CLI | [Setup](docs/en/installation/ai-apps/gemini-cli.md) |
+| Antigravity | [Setup](docs/en/installation/ai-apps/antigravity.md) |
 
 > Any MCP-compatible AI client works. The server command is `npx -y @weppy/roblox-mcp`.
 
 ## Compatibility
 
-| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI |
-|:-----------:|:--------------:|:------:|:---------:|:----------:|
-| ✅ | ✅ | ✅ | ✅ | ✅ |
+| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI | Antigravity |
+|:-----------:|:--------------:|:------:|:---------:|:----------:|:-----------:|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 **Requirements:** Node.js 18+, Roblox Studio, Windows 10+ or macOS 12+
 
@@ -44,8 +55,8 @@ AI can directly handle scripts, instances, properties, terrain, lighting, assets
 - "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."
-
-This is not just code generation. It is **executable, production-oriented actions**.
+- "Generate terrain with mountains and rivers, then place spawn points on flat areas."
+- "Search the Creator Store for a sword model and insert it into StarterPack."
 
 ### 2) Sync: Keep full project context stable for AI
 
@@ -56,6 +67,24 @@ AI works from a synchronized local mirror, so multi-file updates stay consistent
 - Basic: one-way sync (Studio -> Local)
 - Pro: bidirectional sync + per-type Direction/Apply Mode + history + multi-place
 
+### 3) Roblox Explorer: Browse Studio hierarchy in VSCode
+
+View the full instance tree of your Roblox Studio place directly inside VSCode. Navigate services, open synced scripts and property files, and track sync status — all without switching to Studio.
+
+![Roblox Explorer — Studio instance tree displayed in VSCode sidebar](docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Class icons matching Studio for instant recognition
+- Click to open synced scripts and property files
+- Multi-place support with sync status indicators
+
+## Use Cases
+
+- **Rapid prototyping**: Describe a game mechanic in natural language and watch AI build it in Studio
+- **Bulk refactoring**: Rename a module interface and update every dependent script in one request
+- **Terrain & environment**: Generate procedural terrain, set lighting/atmosphere, place assets — all from a single prompt
+- **Multi-file consistency**: AI reads the full project via Sync and applies changes across related scripts together
+- **Asset integration**: Search the Creator Store, insert models, and configure properties without leaving your editor
+
 ## Why It Matters
 
 - Compress repetitive work: turn many manual edits into one request
@@ -68,9 +97,27 @@ AI works from a synchronized local mirror, so multi-file updates stay consistent
 - [Installation Guide](docs/en/installation/README.md)
 - [Tools Reference](docs/en/tools/overview.md)
 - [Sync Deep Dive](docs/en/sync/overview.md)
+- [Roblox Explorer (VSCode Extension)](docs/en/installation/roblox-explorer.md)
 - [Compatibility](docs/compatibility.md)
 - [Troubleshooting](docs/troubleshooting.md)
 
+## FAQ
+
+**How do I let Claude edit my Roblox scripts?**
+Install the Roblox Studio plugin, then register the MCP server (`npx -y @weppy/roblox-mcp`) in Claude Code or Claude Desktop. Claude can then directly read and write scripts inside Studio.
+
+**Can AI build Roblox games with this?**
+Yes. AI can create instances, write scripts, generate terrain, set up lighting, insert assets, configure physics, and more — all inside a live Roblox Studio session. It goes beyond code generation to executable actions.
+
+**Does it work with Cursor / Codex / Gemini?**
+Yes. Any MCP-compatible AI client works. Setup guides are provided for Claude Code, Claude Desktop, Cursor, Codex CLI, Codex Desktop, Gemini CLI, and Antigravity.
+
+**What is the difference between Basic and Pro?**
+Basic includes MCP tool execution and one-way sync (Studio -> Local). Pro adds bidirectional sync, bulk operations, terrain generation, spatial analysis, audio/animation control, and multi-place support. See the [Pro Upgrade Guide](docs/en/pro-upgrade.md).
+
+**Is it safe? Can AI break my game?**
+The server runs on localhost only (127.0.0.1:3002). Forbidden paths (CoreGui, CorePackages) are blocked. Rate limiting (450 req/min) and 30-second timeouts prevent runaway operations. All changes are trackable via sync history.
+
 ## Pro Upgrade
 
 Bidirectional Sync, advanced build capabilities, and AI token efficiency — all in one upgrade.
@@ -79,4 +126,6 @@ Bidirectional Sync, advanced build capabilities, and AI token efficiency — all
 
 ---
 
+[![npm version](https://img.shields.io/npm/v/@weppy/roblox-mcp)](https://www.npmjs.com/package/@weppy/roblox-mcp) [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/) [![Smithery](https://smithery.ai/badge/@hope1026/roblox-mcp)](https://smithery.ai/server/@hope1026/roblox-mcp)
+
 [GitHub Issues](https://github.com/hope1026/roblox-mcp/issues) · [Discussions](https://github.com/hope1026/roblox-mcp/discussions) · [npm](https://www.npmjs.com/package/@weppy/roblox-mcp)

package/SUPPORT.md

@@ -5,6 +5,7 @@
 - [Installation Guide](docs/en/installation/README.md)
 - [Tools Reference](docs/en/tools/overview.md)
 - [Sync Deep Dive](docs/en/sync/overview.md)
+- [Roblox Explorer (VSCode Extension)](docs/en/installation/roblox-explorer.md)
 - [Compatibility](docs/en/compatibility.md)
 - [Troubleshooting](docs/en/troubleshooting.md)
 

package/docs/assets/screenshots/roblox-explorer/install-from-vsix.png

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

package/docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png

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

package/docs/assets/screenshots/sync.png

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

package/docs/en/installation/README.md

@@ -39,6 +39,14 @@ Register the MCP server with your AI app. You can use it with any AI app that su
 
 ---
 
+## Optional: Install Roblox Explorer (VSCode Extension)
+
+Browse synced instance trees inside VSCode with Roblox class icons.
+
+👉 [Roblox Explorer Installation Guide](roblox-explorer.md)
+
+---
+
 ## After Installation
 
 1. Open **Roblox Studio**, go to Plugins tab and click **W-MCP** → **Connect**

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

@@ -0,0 +1,68 @@
+# Weepy Roblox Explorer (VSCode Extension)
+
+Roblox Studio Explorer-like tree view for VSCode. Browse synced instance trees, open scripts directly, and track sync status — all inside your editor.
+
+![Weepy Roblox Explorer](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+## Requirements
+
+- VSCode 1.85+
+- [Roblox MCP](../../../README.md) Sync enabled (Basic or Pro)
+
+## Installation
+
+### 1. Download VSIX
+
+Go to the [Releases](https://github.com/hope1026/roblox-mcp/releases) page and download the latest `weppy-roblox-explorer-*.vsix` file.
+
+> The VSIX file is attached as a release asset alongside the plugin ZIP.
+
+### 2. Install in VSCode
+
+1. Open VSCode
+2. Open the Extensions sidebar (`Ctrl+Shift+X` / `Cmd+Shift+X`)
+3. Click the `...` menu at the top → **Install from VSIX...**
+
+![Install from VSIX](../../assets/screenshots/roblox-explorer/install-from-vsix.png)
+
+4. Select the downloaded `.vsix` file
+5. Reload VSCode when prompted
+
+## Features
+
+- **Instance tree**: Service/instance hierarchy matching Roblox Studio
+- **Roblox class icons**: Dark/light theme support with 200+ class icons
+- **Multi-place**: Separate tree roots per synced place
+- **Click-to-open**: Open backing files (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`)
+- **Instance search**: QuickPick search across all services
+- **Sync status badges**: See `modified`, `studio`, `conflict` states at a glance
+- **Auto-refresh**: Tree updates automatically when sync files change (500ms debounce)
+- **Copy instance path**: Right-click to copy `game.Workspace.Part` style paths
+
+## Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `robloxExplorer.syncRoot` | `""` | Absolute path to `roblox-project-sync` root. Auto-discovered if empty. |
+| `robloxExplorer.hidePropsFiles` | `false` | Hide sync artifact files (`.props.json`, `_tree.json`, `.value.json`) in the default VSCode explorer. |
+| `robloxExplorer.autoRefresh` | `true` | Auto-refresh tree when sync files change. |
+| `robloxExplorer.showSyncStatus` | `true` | Show sync status decorations on tree items. |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `Weepy Roblox Explorer: Refresh` | Manually refresh the instance tree |
+| `Weepy Roblox Explorer: Search Instances` | Search instances across all services |
+| `Weepy Roblox Explorer: Open Backing File` | Open the file backing a selected instance |
+| `Weepy Roblox Explorer: Copy Instance Path` | Copy the full instance path (e.g. `game.Workspace.Part`) |
+| `Weepy Roblox Explorer: Reveal in Explorer` | Show the backing file in the default VSCode explorer |
+
+## Updating
+
+Download the latest `.vsix` from [Releases](https://github.com/hope1026/roblox-mcp/releases) and repeat the installation steps. VSCode will replace the existing version.
+
+## Related
+
+- [Sync Deep Dive](../sync/overview.md)
+- [Installation Guide](README.md)

package/docs/en/sync/overview.md

@@ -20,6 +20,16 @@ Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI work
 
 Default local path is `roblox-project-sync/place_{placeId}/explorer`.
 
+### Browse sync data in VSCode
+
+Install the [Weepy Roblox Explorer](../installation/roblox-explorer.md) extension to browse the synced instance tree in VSCode, just like in Roblox Studio.
+
+![Weepy Roblox Explorer — browse synced instance tree in VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Service/instance tree with Roblox class icons
+- Click a script to open it for editing
+- Sync status badges show modified/conflict state
+
 ## Basic vs Pro
 
 | Item | Basic | Pro |

package/docs/es/README.md

@@ -56,6 +56,16 @@ La IA trabaja sobre un espejo local sincronizado, asi que los cambios en multipl
 - Basic: sincronizacion unidireccional (Studio -> Local)
 - Pro: sincronizacion bidireccional + Direction/Apply Mode por tipo + historial + multiplace
 
+### 3) Roblox Explorer: explora la jerarquia de Studio en VSCode
+
+Visualiza el arbol completo de instancias de tu lugar en Roblox Studio directamente dentro de VSCode. Navega los servicios, abre scripts y archivos de propiedades sincronizados, y rastrea el estado de sincronizacion — todo sin cambiar a Studio.
+
+![Roblox Explorer — arbol de instancias de Studio mostrado en la barra lateral de VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Iconos de clase iguales a Studio para reconocimiento inmediato
+- Clic para abrir scripts y archivos de propiedades sincronizados
+- Soporte multiplace con indicadores de estado de sincronizacion
+
 ## Valor inmediato para el usuario
 
 - Comprime trabajo repetitivo: convierte muchas ediciones manuales en una sola instruccion
@@ -68,6 +78,7 @@ La IA trabaja sobre un espejo local sincronizado, asi que los cambios en multipl
 - [Guia de instalacion](../en/installation/README.md)
 - [Cobertura de herramientas](../en/tools/overview.md)
 - [Guia detallada de Sync](../en/sync/overview.md)
+- [Roblox Explorer (Extension VSCode)](../en/installation/roblox-explorer.md)
 - [Compatibilidad](../compatibility.md)
 - [Solucion de problemas](../troubleshooting.md)
 

package/docs/es/installation/README.md

@@ -34,6 +34,14 @@ Configura el servidor MCP en tu app de IA para que pueda comunicarse con Roblox
 > npx -y @weppy/roblox-mcp
 > ```
 
+## Opcional: Instalar Roblox Explorer (Extensión VSCode)
+
+Explora los árboles de instancias sincronizados dentro de VSCode con iconos de clases Roblox.
+
+👉 [Guía de instalación de Roblox Explorer](roblox-explorer.md)
+
+---
+
 ## Después de la Instalación
 
 Prueba con un comando simple:

package/docs/es/sync/overview.md

@@ -20,6 +20,16 @@ Sin Sync, la IA solo ve fragmentos pegados en el chat. Con Sync activo, trabaja
 
 La ruta local por defecto es `roblox-project-sync/place_{placeId}/explorer`.
 
+### Explorar datos sincronizados en VSCode
+
+Instala la extension [Weepy Roblox Explorer](../installation/roblox-explorer.md) para explorar el arbol de instancias sincronizado en VSCode, igual que en Roblox Studio.
+
+![Weepy Roblox Explorer — explorar el arbol de instancias sincronizado en VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Arbol de servicios/instancias con iconos de clases Roblox
+- Haz clic en un script para abrirlo y editarlo
+- Badges de estado de sync muestran el estado modificado/conflicto
+
 ## Basic vs Pro
 
 | Item | Basic | Pro |

package/docs/id/README.md

@@ -56,6 +56,16 @@ AI bekerja dari mirror lokal yang tersinkron, jadi perubahan lintas banyak file
 - Basic: sinkronisasi satu arah (Studio -> Local)
 - Pro: sinkronisasi dua arah + Direction/Apply Mode per tipe + riwayat + multiplace
 
+### 3) Roblox Explorer: jelajahi hierarki Studio di VSCode
+
+Lihat seluruh pohon instance dari place Roblox Studio langsung di dalam VSCode. Navigasi service, buka script dan file properti yang tersinkron, dan pantau status sinkronisasi — semua tanpa beralih ke Studio.
+
+![Roblox Explorer — pohon instance Studio ditampilkan di sidebar VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Ikon class yang sama dengan Studio untuk pengenalan instan
+- Klik untuk membuka script dan file properti yang tersinkron
+- Dukungan multiplace dengan indikator status sinkronisasi
+
 ## Nilai yang langsung terasa
 
 - Ringkas pekerjaan berulang: banyak edit manual jadi satu perintah
@@ -68,6 +78,7 @@ AI bekerja dari mirror lokal yang tersinkron, jadi perubahan lintas banyak file
 - [Panduan instalasi](../en/installation/README.md)
 - [Cakupan tool](../en/tools/overview.md)
 - [Panduan detail Sync](../en/sync/overview.md)
+- [Roblox Explorer (Ekstensi VSCode)](../en/installation/roblox-explorer.md)
 - [Kompatibilitas](../compatibility.md)
 - [Panduan pemecahan masalah](../troubleshooting.md)
 

package/docs/id/installation/README.md

@@ -39,6 +39,14 @@ Daftarkan MCP server ke aplikasi AI yang kamu pakai. Bisa digunakan di semua apl
 
 ---
 
+## Opsional: Install Roblox Explorer (Ekstensi VSCode)
+
+Jelajahi tree instance yang sudah disinkronkan di dalam VSCode dengan ikon kelas Roblox.
+
+👉 [Panduan Instalasi Roblox Explorer](roblox-explorer.md)
+
+---
+
 ## Setelah Instalasi Selesai
 
 1. Buka **Roblox Studio**, di tab Plugins klik **W-MCP** → **Connect**

package/docs/id/sync/overview.md

@@ -20,6 +20,16 @@ Tanpa Sync, AI hanya melihat potongan kode yang ditempel di chat. Dengan Sync ak
 
 Path lokal default adalah `roblox-project-sync/place_{placeId}/explorer`.
 
+### Jelajahi data sync di VSCode
+
+Instal ekstensi [Weepy Roblox Explorer](../installation/roblox-explorer.md) untuk menjelajahi tree instance yang sudah tersinkron di VSCode, seperti di Roblox Studio.
+
+![Weepy Roblox Explorer — jelajahi tree instance yang tersinkron di VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Tree service/instance dengan ikon kelas Roblox
+- Klik script untuk membukanya dan mengedit
+- Badge status sync menampilkan status modified/conflict
+
 ## Basic vs Pro
 
 | Item | Basic | Pro |

package/docs/ja/README.md

@@ -56,6 +56,16 @@ AIがStudio内で、スクリプト、インスタンス、プロパティ、地
 - Basic: 片方向同期（Studio -> Local）
 - Pro: 双方向同期 + タイプ別Direction/Apply Mode + 変更履歴 + マルチPlace
 
+### 3) Roblox Explorer: VSCodeでStudioの階層構造を閲覧
+
+Roblox Studioのインスタンスツリー全体をVSCode内で直接確認できます。サービスを探索し、同期されたスクリプトやプロパティファイルを開き、同期状態を追跡 — Studioに切り替える必要はありません。
+
+![Roblox Explorer — VSCodeサイドバーに表示されるStudioインスタンスツリー](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Studio同様のクラスアイコンで直感的に識別
+- クリックで同期済みスクリプトとプロパティファイルを開く
+- 同期状態表示付きのマルチPlaceサポート
+
 ## すぐに実感できる価値
 
 - 反復作業を圧縮: 多数の手作業を1つの指示に集約
@@ -68,6 +78,7 @@ AIがStudio内で、スクリプト、インスタンス、プロパティ、地
 - [インストールガイド](../en/installation/README.md)
 - [Tool対応範囲](../en/tools/overview.md)
 - [Sync機能詳細ガイド](../en/sync/overview.md)
+- [Roblox Explorer (VSCode拡張)](../en/installation/roblox-explorer.md)
 - [互換性](../compatibility.md)
 - [トラブルシューティング](../troubleshooting.md)
 

package/docs/ja/installation/README.md

@@ -39,6 +39,14 @@ GitHubからプラグインファイルをダウンロードして、Roblox Stud
 
 ---
 
+## オプション: Roblox Explorer (VSCode拡張) のインストール
+
+同期されたインスタンスツリーをRobloxクラスアイコン付きでVSCode内で閲覧できます。
+
+👉 [Roblox Explorerインストールガイド](roblox-explorer.md)
+
+---
+
 ## インストール後
 
 1. **Roblox Studio**を開き、Pluginsタブから **W-MCP** → **Connect** をクリック

package/docs/ja/sync/overview.md

@@ -20,6 +20,16 @@ Syncがない場合、AIはチャットに貼られた断片だけを見て判
 
 ローカルの既定パスは `roblox-project-sync/place_{placeId}/explorer` です。
 
+### VSCodeで同期データを閲覧する
+
+[Weepy Roblox Explorer](../installation/roblox-explorer.md) 拡張機能をインストールすると、Roblox Studioと同じようにVSCode上で同期済みインスタンスツリーを閲覧できます。
+
+![Weepy Roblox Explorer — VSCodeで同期済みインスタンスツリーを閲覧](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Robloxクラスアイコン付きのサービス/インスタンスツリー
+- スクリプトをクリックして編集用に開く
+- 同期ステータスバッジで変更/コンフリクト状態を表示
+
 ## Basic vs Pro
 
 | 項目 | Basic | Pro |

package/docs/ko/README.md

@@ -56,6 +56,16 @@ AI가 로컬 동기화된 프로젝트를 기준으로 전체 구조를 이해
 - Basic: Studio -> Local 단방향 동기화
 - Pro: 양방향 동기화 + 타입별 Direction/Apply Mode + 변경 기록 + 멀티 Place
 
+### 3) Roblox Explorer: VSCode에서 Studio 계층 구조 탐색
+
+Roblox Studio의 전체 인스턴스 트리를 VSCode 안에서 바로 확인할 수 있습니다. 서비스를 탐색하고, 동기화된 스크립트와 속성 파일을 열고, 동기화 상태를 추적하세요 — Studio로 전환할 필요 없이.
+
+![Roblox Explorer — VSCode 사이드바에 표시되는 Studio 인스턴스 트리](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Studio와 동일한 클래스 아이콘으로 직관적 구분
+- 클릭으로 동기화된 스크립트와 속성 파일 열기
+- 동기화 상태 표시를 포함한 멀티 Place 지원
+
 ## 유저가 바로 체감하는 장점
 
 - 반복 작업 압축: 수십 번 클릭/수정을 자연어 한 번으로 처리
@@ -68,6 +78,7 @@ AI가 로컬 동기화된 프로젝트를 기준으로 전체 구조를 이해
 - [설치 가이드](../en/installation/README.md)
 - [Tool 지원 범위](../en/tools/overview.md)
 - [Sync 기능 상세 가이드](../en/sync/overview.md)
+- [Roblox Explorer (VSCode 확장)](installation/roblox-explorer.md)
 - [호환성](../compatibility.md)
 - [문제 해결 가이드](../troubleshooting.md)
 

package/docs/ko/installation/README.md

@@ -39,6 +39,14 @@ GitHub에서 플러그인 파일을 다운로드한 뒤, Roblox Studio의 Plugin
 
 ---
 
+## 선택 사항: Roblox Explorer (VSCode 확장) 설치
+
+동기화된 인스턴스 트리를 Roblox 클래스 아이콘과 함께 VSCode에서 탐색할 수 있습니다.
+
+👉 [Roblox Explorer 설치 가이드](roblox-explorer.md)
+
+---
+
 ## 설치 완료 후
 
 1. **Roblox Studio**를 열고, Plugins 탭에서 **W-MCP** → **Connect** 클릭

package/docs/ko/installation/roblox-explorer.md

@@ -0,0 +1,68 @@
+# Weepy Roblox Explorer (VSCode 확장)
+
+Roblox Studio의 Explorer와 동일한 인스턴스 트리를 VSCode에서 볼 수 있는 확장입니다. 동기화된 인스턴스를 탐색하고, 스크립트를 바로 열고, Sync 상태를 에디터 안에서 확인할 수 있습니다.
+
+![Weepy Roblox Explorer](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+## 요구 사항
+
+- VSCode 1.85+
+- [Roblox MCP](../../../README.md) Sync 활성화 (Basic 또는 Pro)
+
+## 설치 방법
+
+### 1. VSIX 다운로드
+
+[Releases](https://github.com/hope1026/roblox-mcp/releases) 페이지에서 최신 `weppy-roblox-explorer-*.vsix` 파일을 다운로드합니다.
+
+> VSIX 파일은 플러그인 ZIP과 함께 릴리스 asset으로 첨부되어 있습니다.
+
+### 2. VSCode에서 설치
+
+1. VSCode를 엽니다
+2. Extensions 사이드바를 엽니다 (`Ctrl+Shift+X` / `Cmd+Shift+X`)
+3. 상단 `...` 메뉴 → **Install from VSIX...** 클릭
+
+![Install from VSIX](../../assets/screenshots/roblox-explorer/install-from-vsix.png)
+
+4. 다운로드한 `.vsix` 파일을 선택합니다
+5. 안내에 따라 VSCode를 리로드합니다
+
+## 기능
+
+- **인스턴스 트리**: Roblox Studio와 동일한 서비스/인스턴스 계층 구조
+- **Roblox 클래스 아이콘**: 200개 이상의 클래스 아이콘 (다크/라이트 테마 지원)
+- **멀티 Place**: 동기화된 Place별로 트리 루트 분리
+- **클릭으로 파일 열기**: `.server.luau`, `.client.luau`, `.module.luau`, `.props.json` 등 바로 열기
+- **인스턴스 검색**: 모든 서비스에 걸쳐 QuickPick 검색
+- **Sync 상태 배지**: `modified`, `studio`, `conflict` 상태를 한눈에 확인
+- **자동 새로고침**: Sync 파일 변경 시 트리 자동 갱신 (500ms 디바운스)
+- **인스턴스 경로 복사**: 우클릭으로 `game.Workspace.Part` 형식의 경로 복사
+
+## 설정
+
+| 설정 | 기본값 | 설명 |
+|------|--------|------|
+| `robloxExplorer.syncRoot` | `""` | `roblox-project-sync` 루트 절대 경로. 비워두면 자동 탐색. |
+| `robloxExplorer.hidePropsFiles` | `false` | 기본 VSCode 탐색기에서 동기화 파일(`.props.json`, `_tree.json`, `.value.json`)을 숨깁니다. |
+| `robloxExplorer.autoRefresh` | `true` | Sync 파일 변경 시 트리를 자동으로 새로고침합니다. |
+| `robloxExplorer.showSyncStatus` | `true` | 트리 항목에 Sync 상태 장식을 표시합니다. |
+
+## 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `Weepy Roblox Explorer: Refresh` | 인스턴스 트리 수동 새로고침 |
+| `Weepy Roblox Explorer: Search Instances` | 모든 서비스에서 인스턴스 검색 |
+| `Weepy Roblox Explorer: Open Backing File` | 선택한 인스턴스의 파일 열기 |
+| `Weepy Roblox Explorer: Copy Instance Path` | 전체 인스턴스 경로 복사 (예: `game.Workspace.Part`) |
+| `Weepy Roblox Explorer: Reveal in Explorer` | 기본 VSCode 탐색기에서 파일 표시 |
+
+## 업데이트
+
+[Releases](https://github.com/hope1026/roblox-mcp/releases)에서 최신 `.vsix`를 다운로드하고 동일한 설치 과정을 반복하면 됩니다. 기존 버전이 자동으로 교체됩니다.
+
+## 관련 문서
+
+- [Sync 기능 상세 가이드](../sync/overview.md)
+- [설치 가이드](README.md)

package/docs/ko/sync/overview.md

@@ -20,6 +20,16 @@ Sync가 없으면 AI는 대화에 붙여 넣은 코드 일부만 보고 판단
 
 로컬 기본 경로는 `roblox-project-sync/place_{placeId}/explorer` 형태로 생성됩니다.
 
+### VSCode에서 Sync 데이터 탐색
+
+[Weepy Roblox Explorer](../installation/roblox-explorer.md) 확장을 설치하면, 동기화된 인스턴스 트리를 Roblox Studio와 동일한 형태로 VSCode에서 탐색할 수 있습니다.
+
+![Weepy Roblox Explorer — 동기화된 인스턴스 트리를 VSCode에서 탐색하는 모습](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- 서비스/인스턴스 트리를 Roblox 클래스 아이콘과 함께 표시
+- 스크립트 파일을 클릭하면 바로 편집 가능
+- Sync 상태 배지로 변경/충돌 확인
+
 ## Basic vs Pro
 
 | 항목 | Basic | Pro |

package/docs/pt-br/README.md

@@ -56,6 +56,16 @@ A IA trabalha com um espelho local sincronizado, entao alteracoes em varios arqu
 - Basic: sincronizacao unidirecional (Studio -> Local)
 - Pro: sincronizacao bidirecional + Direction/Apply Mode por tipo + historico + multiplace
 
+### 3) Roblox Explorer: navegue a hierarquia do Studio no VSCode
+
+Visualize a arvore completa de instancias do seu lugar no Roblox Studio diretamente dentro do VSCode. Navegue pelos servicos, abra scripts e arquivos de propriedades sincronizados, e acompanhe o status de sincronizacao — tudo sem trocar para o Studio.
+
+![Roblox Explorer — arvore de instancias do Studio exibida na barra lateral do VSCode](../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
+
+- Icones de classe iguais ao Studio para reconhecimento imediato
+- Clique para abrir scripts e arquivos de propriedades sincronizados
+- Suporte multiplace com indicadores de status de sincronizacao
+
 ## Valor imediato para o usuario
 
 - Comprimir trabalho repetitivo: transformar muitas edicoes manuais em um pedido
@@ -68,6 +78,7 @@ A IA trabalha com um espelho local sincronizado, entao alteracoes em varios arqu
 - [Guia de instalacao](../en/installation/README.md)
 - [Cobertura de ferramentas](../en/tools/overview.md)
 - [Guia detalhado de Sync](../en/sync/overview.md)
+- [Roblox Explorer (Extensao VSCode)](../en/installation/roblox-explorer.md)
 - [Compatibilidade](../compatibility.md)
 - [Solucao de problemas](../troubleshooting.md)
 

package/docs/pt-br/installation/README.md

@@ -39,6 +39,14 @@ Registre o servidor MCP no seu app de IA. Funciona com qualquer app que suporte
 
 ---
 
+## Opcional: Instalar Roblox Explorer (Extensão VSCode)
+
+Navegue pelas árvores de instâncias sincronizadas dentro do VSCode com ícones de classes Roblox.
+
+👉 [Guia de instalação do Roblox Explorer](roblox-explorer.md)
+
+---
+
 ## Depois da instalação
 
 1. Abra o **Roblox Studio** e na aba Plugins clique em **W-MCP** → **Connect**