@weppy/roblox-mcp 1.5.5 → 2.0.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Weppy Roblox MCP — MCP server that lets AI coding agents control a live Roblox Studio session with 21 tools, 140+ actions, bidirectional sync, automated playtest, and multi-place support",
-    "version": "1.5.5"
+    "version": "2.0.1"
   },
   "plugins": [
     {
       "name": "weppy-roblox-mcp",
       "source": "./plugins/weppy-roblox-mcp",
       "description": "Weppy Roblox MCP — MCP server that lets AI coding agents control a live Roblox Studio session with 21 tools, 140+ actions, bidirectional sync, automated playtest, and multi-place support",
-      "version": "1.5.5",
+      "version": "2.0.1",
       "author": {
         "name": "hope1026"
       },

package/CHANGELOG.md

@@ -13,6 +13,41 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+
+## [2.0.1] - 2026-03-22
+
+### Bug Fixes
+
+- Fix setup scripts (`setup-mcp.sh`, `setup-mcp.bat`) failing to resolve MCP server path on Windows and macOS
+- Fix project sync directory path resolution when multiple MCP instances share the same workspace
+
+
+## [2.0.0] - 2026-03-22
+
+### BREAKING CHANGES
+
+- **ZIP users**: Package directory structure has changed. You must re-run `setup-mcp.sh` (or `setup-mcp.bat`). The MCP server path in `.mcp.json` has moved from `mcp-server/index.js` to `plugins/weppy-roblox-mcp/dist/index.js`.
+
+### Highlights
+
+- **Built-in Dashboard**: The MCP server now includes an embedded dashboard. Access it at `http://127.0.0.1:3002/dashboard` — no extra setup required for npm or ZIP installs.
+- **Unified deploy structure**: npm, ZIP, and local dev environments all share the same `plugins/weppy-roblox-mcp/dist/index.js` runtime layout.
+
+### Features
+
+- Built-in dashboard with 7 pages: Overview, Connection, Tools, Sync, Changelog, Playtest, Settings
+- Multi-language support (en, ko) with auto-detection
+- Real-time SSE updates for connection status and license changes
+- Unified tool and sync changelog extraction
+- Sync apply modes (auto/manual per content type)
+
+### Bug Fixes
+
+- Unified MCP server path across all setup scripts and guides (6 languages)
+- Tooltip clipping at viewport edges
+
+
 ## [1.5.5] - 2026-03-16
 
 ### Improved

package/README.md

@@ -75,7 +75,17 @@ AI can control Roblox Studio playtests directly. It can start and stop Play (F5)
 - "Write a test that verifies the SpawnLocation is above the ground and run it."
 - "Validate that the script I just changed runs without errors in playtest."
 
-### 4) Roblox Explorer: Browse Studio hierarchy in VSCode
+### 4) Dashboard: Monitor AI work in real time
+
+The MCP server provides a web dashboard where you can check connection status, tool execution history, sync state, and game change logs in real time.
+
+![Dashboard Overview — Server status, recent changes, and session summary](docs/assets/screenshots/dashboard/dashboard_overview.png)
+
+- Server/Plugin/Agent connection status at a glance
+- Compare every change the AI made via Before & After in Changelog
+- Analyze workflow with tool execution history and statistics
+
+### 5) 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.
 
@@ -105,6 +115,7 @@ View the full instance tree of your Roblox Studio place directly inside VSCode.
 - [Installation Guide](docs/en/installation/README.md)
 - [Tools Reference](docs/en/tools/overview.md)
 - [Sync Deep Dive](docs/en/sync/overview.md)
+- [Dashboard Guide](docs/en/dashboard/overview.md)
 - [Roblox Explorer (VSCode Extension)](docs/en/installation/roblox-explorer.md)
 - [Compatibility](docs/compatibility.md)
 - [Troubleshooting](docs/troubleshooting.md)

package/docs/assets/screenshots/dashboard/dashboard_changelog1.png

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

package/docs/assets/screenshots/dashboard/dashboard_changelog2.png

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

package/docs/assets/screenshots/dashboard/dashboard_connection.png

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

package/docs/assets/screenshots/dashboard/dashboard_overview.png

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

package/docs/assets/screenshots/dashboard/dashboard_playtest.png

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

package/docs/assets/screenshots/dashboard/dashboard_sync.png

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

package/docs/assets/screenshots/dashboard/dashboard_tools.png

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

package/docs/en/dashboard/changelog.md

@@ -0,0 +1,114 @@
+# Changelog
+
+> Records every change the AI performs in Roblox Studio on a per-session basis, providing change summaries, timelines, and Before & After comparisons.
+
+![Changelog — Per-session change card list](../../assets/screenshots/dashboard/dashboard_changelog1.png)
+
+## Overview
+
+The Changelog page tracks the history of game changes made by the AI agent in Studio. Changes are grouped by session, making it easy to see what kinds of changes occurred and how many in each session at a glance.
+
+## Session Card List
+
+The Changelog's main view shows a list of cards organized by session.
+
+### Session Status
+
+Each session card displays a status:
+
+| Status | Meaning |
+|--------|---------|
+| **Active** | Currently in-progress session (updates in real time) |
+| **Completed** | Finished session |
+| **Bootstrap** | Initial sync session |
+
+### Session Summary
+
+Each card includes a summary of change counts by category:
+
+- Script — Number of scripts created/modified
+- Instance — Number of instances created/deleted/moved
+- Property — Number of property changes
+- Lighting — Number of lighting/environment changes
+- Terrain — Number of terrain changes
+- Asset — Number of assets inserted
+
+### Filter Tabs
+
+Use the tabs at the top to filter sessions:
+- **All** — All sessions
+- **Active** — In-progress sessions only
+- **Completed** — Finished sessions only
+
+## Session Detail View
+
+Click a session card to enter the detail view.
+
+![Changelog Detail View — Change summary, timeline, Before & After](../../assets/screenshots/dashboard/dashboard_changelog2.png)
+
+### Change Summary
+
+Visualizes the session's changes as 6 category cards:
+
+| Category | Icon | Description |
+|----------|------|-------------|
+| Scripts | Script | Number of scripts created/modified |
+| Instances | Instance | Number of instances created/deleted/moved |
+| Properties | Property | Number of property changes |
+| Lighting | Lighting | Number of lighting/environment changes |
+| Terrain | Terrain | Number of terrain changes |
+| Assets | Asset | Number of assets inserted |
+
+### Change Timeline
+
+Lists all changes within the session in chronological order.
+
+- Each item shows a timestamp, change category tag, and target path
+- Use the **Category** dropdown to filter by a specific category
+- Click an item to expand the Before & After comparison view
+
+### Before & After
+
+Compares data before and after a change. Different levels of detail are provided depending on the change type:
+
+| Confidence | Meaning | Example |
+|------------|---------|---------|
+| **exact** | Both before and after values are precisely recorded | Property changes, script modifications |
+| **partial** | Only some information is recorded | Compound changes |
+| **after-only** | Only the after value exists | New instance creation |
+| **intent-only** | Only the intent is recorded | Deletions, etc. |
+
+## Use Cases
+
+### Verifying Work
+
+```
+"I want to check which scripts the AI just modified"
+```
+
+Filter the Active session by the Script category in Changelog to see the list of modified scripts and compare before/after code.
+
+### Tracking Changes
+
+```
+"I want to review how Lighting was configured in yesterday's session"
+```
+
+Find the session in the Completed tab and filter by the Lighting category to view the change history and setting values.
+
+### Debugging Issues
+
+```
+"I need to find when a specific instance was deleted"
+```
+
+Filter the timeline by the Instance category and trace delete-type changes chronologically.
+
+## Related Documents
+
+- [Dashboard Overview](overview.md)
+- [Connection](connection.md)
+- [Sync](sync.md)
+- [Playtest](playtest.md)
+- [Tools](tools.md)
+- [Settings](settings.md)

package/docs/en/dashboard/connection.md

@@ -0,0 +1,77 @@
+# Connection
+
+> Monitor the connection status of the server, AI agents, and plugins all in one place.
+
+![Connection — Server status, AI agents, and plugin connection info](../../assets/screenshots/dashboard/dashboard_connection.png)
+
+## Overview
+
+The Connection page lets you monitor all connection states of the MCP system in one place. It is accessible whenever the server is connected (L1 or above).
+
+## Server Status
+
+Displays key server information:
+
+| Field | Description |
+|-------|-------------|
+| Status | Connection status badge (Online/Offline) |
+| Version | MCP server version |
+| PID | Server process ID |
+| Uptime | Server uptime |
+| Session ID | Current session identifier |
+| Exec Path | Server executable path |
+
+## AI Agents
+
+Displays a table of currently connected AI agents:
+
+| Column | Description |
+|--------|-------------|
+| Name | Agent name (e.g., Claude Code) |
+| PID | Agent process ID |
+| Working Dir | Agent working directory |
+| Connected | Time since connection |
+
+All agents are listed when multiple are connected simultaneously.
+
+## Plugins
+
+Displays a list of connected Roblox Studio plugins:
+
+| Column | Description |
+|--------|-------------|
+| Place | Place name |
+| Client ID | Plugin client identifier |
+| Last Seen | Time of last communication |
+| Version | Plugin version |
+
+## Connection Log
+
+Displays connection-related events in real time. Agent/plugin connect/disconnect events are automatically appended via SSE.
+
+## Use Cases
+
+### Diagnosing Connection Issues
+
+```
+"It seems like the AI isn't connecting to Studio"
+```
+
+Check whether Server Status is Online and whether a plugin appears in the Plugins table. You can trace connect/disconnect events in the Connection Log.
+
+### Checking Agents
+
+```
+"I want to see which AI is currently connected"
+```
+
+Check the name, PID, and working directory of connected agents in the AI Agents table.
+
+## Related Documents
+
+- [Dashboard Overview](overview.md)
+- [Changelog](changelog.md)
+- [Sync](sync.md)
+- [Playtest](playtest.md)
+- [Tools](tools.md)
+- [Settings](settings.md)

package/docs/en/dashboard/overview.md

@@ -0,0 +1,95 @@
+# Dashboard
+
+> Monitor and manage the MCP server's status, connections, sync state, tool execution history, and game change log in real time from your web browser.
+
+![Dashboard Overview — Server status, recent changes, and session summary at a glance](../../assets/screenshots/dashboard/dashboard_overview.png)
+
+## What Is the Dashboard?
+
+The dashboard is a web-based monitoring interface provided by the MCP server. It opens automatically in your browser when the MCP server starts, letting you track every action the AI agent performs in Roblox Studio in real time.
+
+- Visually monitor status without digging through terminal logs
+- Track what the AI changed in Studio via the change history
+- View sync status, connection state, and tool execution statistics in one place
+
+## Pages
+
+| Page | Description | Detailed Guide |
+|------|-------------|----------------|
+| [Overview](#overview) | Server/Plugin/Agent/Sync status cards, recent changes feed | This document |
+| [Changelog](changelog.md) | Game change history — per-session cards, change summary, timeline, Before & After | [Detailed Guide](changelog.md) |
+| [Connection](connection.md) | Server status, AI agent list, plugin connection info | [Detailed Guide](connection.md) |
+| [Sync](sync.md) | Sync status, direction settings, logs | [Detailed Guide](sync.md) |
+| [Playtest](playtest.md) | Playtest status, test history | [Detailed Guide](playtest.md) |
+| [Tools](tools.md) | Tool execution history, statistics, tier distribution | [Detailed Guide](tools.md) |
+| [Settings](settings.md) | License, log level, sync settings, language | [Detailed Guide](settings.md) |
+
+## How to Access
+
+The dashboard opens automatically in your browser when the MCP server starts. To access it manually:
+
+```
+http://localhost:3002
+```
+
+> Set `DASHBOARD_AUTO_OPEN=false` to disable automatic opening (see the [Settings](settings.md) page).
+
+## Connection Levels
+
+The features available in the dashboard depend on the connection state:
+
+| Level | Condition | Available Pages |
+|:-----:|-----------|-----------------|
+| **L0** | Server not connected | Only the reconnection waiting screen is displayed |
+| **L1** | Server connected, plugin not connected | Connection, Tools, Settings |
+| **L2** | Both server and plugin connected | All pages |
+
+When the plugin is not connected (L1), the Overview, Changelog, Sync, and Playtest pages are inaccessible.
+
+## Overview
+
+The Overview page is the dashboard's home screen, providing a quick look at the entire system status.
+
+### Status Cards
+
+| Card | Information Displayed |
+|------|-----------------------|
+| **Server** | Server connection state (Online/Offline) |
+| **Plugin** | Plugin connection state, Place info |
+| **Agent** | Currently connected AI agent name |
+| **Sync** | Sync state (Idle/Syncing/Error) |
+
+### Recent Game Changes
+
+Displays the most recent changes performed by the AI in Studio in real time (up to 20 items). Each item is shown with a change category icon, and clicking it navigates to the detailed view in [Changelog](changelog.md).
+
+Category icons:
+- Script — Script creation/modification
+- Instance — Instance creation/deletion/movement
+- Property — Property changes
+- Lighting — Lighting/environment settings
+- Terrain — Terrain changes
+- Asset — Asset insertion
+
+### Session Change Summary
+
+Aggregates the current session's change statistics by category (e.g., "4 scripts · 3 properties").
+
+## Real-Time Updates
+
+The dashboard uses SSE (Server-Sent Events) to update data in real time:
+
+- Server status: polled every 5 seconds
+- Change feed, connection events: SSE real-time streaming
+- On SSE disconnection: automatic reconnection after 3 seconds
+
+## Related Documents
+
+- [Changelog](changelog.md) — Game change history tracking
+- [Connection](connection.md) — Server/Agent/Plugin connection status
+- [Sync](sync.md) — Sync status monitoring
+- [Playtest](playtest.md) — Playtest history
+- [Tools](tools.md) — Tool execution history/statistics
+- [Settings](settings.md) — License, server settings, language
+- [Full Tool Reference](../tools/overview.md)
+- [Sync Deep Dive](../sync/overview.md)

package/docs/en/dashboard/playtest.md

@@ -0,0 +1,61 @@
+# Playtest
+
+> View the status and test results of playtests run by the AI.
+
+![Playtest — Playtest status and test history](../../assets/screenshots/dashboard/dashboard_playtest.png)
+
+## Overview
+
+The Playtest page shows the status and test results of playtests run by the AI. It is accessible only when the plugin is connected (L2).
+
+## Playtest Status
+
+Displays the current playtest state:
+
+| Status | Meaning |
+|--------|---------|
+| **NotRunning** | Playtest not running |
+| **Running** | Playtest in progress |
+| **Paused** | Playtest paused (Run mode) |
+
+## Test History
+
+Lists the results of tests executed by the AI via the `run_test` action in chronological order:
+
+| Field | Description |
+|-------|-------------|
+| Timestamp | Test execution time |
+| Test Report | Link to the test report |
+| Mode | Execution mode (play/run) |
+| Duration | Test duration |
+| Status | Result (Passed/Failed) |
+
+Click a test report to view the detailed report in markdown format along with logs.
+
+## Use Cases
+
+### Analyzing Test Failures
+
+```
+"I want to find out why the automated test I just ran failed"
+```
+
+Find the test with a Failed status in Test History and click the Test Report to view detailed logs and the failure cause.
+
+### Reviewing Test History
+
+```
+"I want to see the pass/fail results of today's tests"
+```
+
+Check the timestamps and Status in Test History to track test result trends.
+
+## Related Documents
+
+- [Dashboard Overview](overview.md)
+- [Changelog](changelog.md)
+- [Connection](connection.md)
+- [Sync](sync.md)
+- [Tools](tools.md)
+- [Settings](settings.md)
+- [Playtest & Automated Tests (Tools)](../tools/playtest.md)

package/docs/en/dashboard/settings.md

@@ -0,0 +1,67 @@
+# Settings
+
+> View and manage license information, server settings, sync settings, and language.
+
+## Overview
+
+The Settings page lets you view license information and server settings, and modify some of them. It is accessible whenever the server is connected (L1 or above).
+
+## License (Read-Only)
+
+Displays the current license status:
+
+| Field | Description |
+|-------|-------------|
+| Status | Status badge (Active/Inactive) |
+| Tier | Current tier (Basic/Pro) |
+| License Key | Masked license key |
+| Provider | License provider information |
+
+## General
+
+| Setting | Description |
+|---------|-------------|
+| Log Level | Log output level |
+| History Recording | Whether tool execution history is saved |
+| Stats Collection | Whether tool statistics are collected |
+| Request Timeout | Request timeout (seconds) |
+
+## Server Environment (Read-Only)
+
+Displays server settings configured via environment variables:
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `HTTP_PORT` | HTTP port | 3002 |
+| `HTTP_HOST` | HTTP host | 127.0.0.1 |
+| `DASHBOARD_AUTO_OPEN` | Auto-open dashboard | true |
+
+## Sync Settings
+
+| Setting | Description |
+|---------|-------------|
+| Max Depth | Maximum sync depth |
+| Max Instances | Maximum number of synced instances |
+
+## Language
+
+Change the dashboard UI language. 6 languages + Auto (automatic browser language detection) are supported.
+
+| Option | Language |
+|--------|----------|
+| Auto | Automatic browser language detection |
+| English | English |
+| 한국어 | Korean |
+| 日本語 | Japanese |
+| Español | Spanish |
+| Português | Portuguese |
+| Bahasa Indonesia | Indonesian |
+
+## Related Documents
+
+- [Dashboard Overview](overview.md)
+- [Changelog](changelog.md)
+- [Connection](connection.md)
+- [Sync](sync.md)
+- [Playtest](playtest.md)
+- [Tools](tools.md)

package/docs/en/dashboard/sync.md

@@ -0,0 +1,75 @@
+# Sync
+
+> Monitor the current status, direction settings, and logs for Studio <-> local file synchronization.
+
+![Sync — Sync status, direction settings, and logs](../../assets/screenshots/dashboard/dashboard_sync.png)
+
+> For a detailed guide on the Sync feature itself, see the [Sync Deep Dive](../sync/overview.md).
+
+## Overview
+
+The Sync page provides a visual overview of the current state and settings for Studio <-> local file synchronization. It is accessible only when the plugin is connected (L2).
+
+## Sync Status
+
+Displays the current sync state:
+
+| Status | Meaning |
+|--------|---------|
+| **Idle** | Waiting for sync |
+| **Initializing** | Initial sync in progress |
+| **Syncing** | Incremental sync in progress |
+| **Error** | Sync error occurred |
+
+The status card also shows the sync path, number of synced instances, and the current apply mode (Auto/Manual).
+
+## Sync Directions
+
+Shows sync directions by type in a table:
+
+| Column | Description |
+|--------|-------------|
+| Type | Sync target type (Scripts, Values, Instances, Data, Services) |
+| Direction | Sync direction (Local -> Studio, Studio -> Local) |
+| Apply Mode | Apply mode (Auto/Manual) |
+
+Check each type's sync direction to understand which changes are reflected in which direction.
+
+## Sync Config
+
+Displays sync configuration values:
+- Max Depth — Maximum sync depth
+- Max Instances — Maximum number of synced instances
+- Interval — Sync interval
+
+## Sync Log
+
+Displays sync events in chronological order. Each log entry includes a change type tag (create, update, delete, etc.) and the target path.
+
+## Use Cases
+
+### Checking Sync Status
+
+```
+"I want to verify that Sync is working properly"
+```
+
+Confirm that Sync Status is Idle and check the Sync Log to verify that recent changes were recorded normally.
+
+### Understanding Sync Direction
+
+```
+"I want to know which direction script changes are synced"
+```
+
+Check the Direction for the Scripts type in the Sync Directions table.
+
+## Related Documents
+
+- [Dashboard Overview](overview.md)
+- [Changelog](changelog.md)
+- [Connection](connection.md)
+- [Playtest](playtest.md)
+- [Tools](tools.md)
+- [Settings](settings.md)
+- [Sync Deep Dive](../sync/overview.md)

package/docs/en/dashboard/tools.md

@@ -0,0 +1,69 @@
+# Tools
+
+> View the execution history and statistics of MCP tools run by the AI.
+
+![Tools — Tool execution history and statistics](../../assets/screenshots/dashboard/dashboard_tools.png)
+
+## Overview
+
+The Tools page provides the execution history and statistics of MCP tools run by the AI. It consists of two sub-tabs: **History** and **Statistics**. It is accessible whenever the server is connected (L1 or above).
+
+## History Tab
+
+Shows tool execution records in a chronological table:
+
+| Column | Description |
+|--------|-------------|
+| Time | Execution time |
+| Tool.Action | Executed tool and action (e.g., `query_instances.get_instance`) |
+| Duration | Execution duration |
+| Status | Result status (OK/Error) |
+| Tier | Tier used (Basic/Pro) |
+
+Features:
+- **Tool filter** dropdown to show only a specific tool
+- Pagination for browsing large volumes of records
+- New execution records are added in real time
+
+## Statistics Tab
+
+Provides visual analysis of tool usage statistics:
+
+- **Tier distribution** — Basic/Pro tool usage ratio
+- **Per-tool statistics** — Call count and average response time for each tool
+- **Per-action breakdown** — Detailed statistics for each action within a tool
+
+## Basic Tier-Exclusive Features
+
+Additional UI is displayed for Basic tier users:
+
+- **Tier Usage Progress** — Usage progress bar
+- **Basic vs Pro comparison modal** — Information about additional Pro tier features
+
+## Use Cases
+
+### Analyzing Tool Performance
+
+```
+"I want to know which tool takes the longest"
+```
+
+Check the average response time per tool in the Statistics tab.
+
+### Tracking Errors
+
+```
+"I want to find out why the tool I just ran failed"
+```
+
+Find items with an Error status in the History tab to view detailed information.
+
+## Related Documents
+
+- [Dashboard Overview](overview.md)
+- [Changelog](changelog.md)
+- [Connection](connection.md)
+- [Sync](sync.md)
+- [Playtest](playtest.md)
+- [Settings](settings.md)
+- [Full Tool Reference](../tools/overview.md)