@weppy/roblox-mcp 1.5.4 → 2.0.0

package/.claude-plugin/marketplace.json

@@ -5,20 +5,20 @@
     "email": "hope841026@gmail.com"
   },
   "metadata": {
-    "description": "Roblox MCP server and tools for AI-powered game development",
-    "version": "1.5.4"
+    "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": "2.0.0"
   },
   "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.5.4",
+      "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": "2.0.0",
       "author": {
         "name": "hope1026"
       },
-      "homepage": "https://github.com/hope1026/roblox-mcp",
-      "repository": "https://github.com/hope1026/roblox-mcp",
+      "homepage": "https://github.com/hope1026/weppy-roblox-mcp",
+      "repository": "https://github.com/hope1026/weppy-roblox-mcp",
       "license": "SEE LICENSE IN LICENSE",
       "keywords": [
         "mcp",

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -5,8 +5,8 @@ body:
   - type: markdown
     attributes:
       value: |
-        Before reporting, check [Troubleshooting](https://github.com/hope1026/roblox-mcp/blob/main/docs/en/troubleshooting.md)
-        and [Discussions](https://github.com/hope1026/roblox-mcp/discussions).
+        Before reporting, check [Troubleshooting](https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/troubleshooting.md)
+        and [Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions).
   - type: input
     id: os
     attributes:

package/.github/ISSUE_TEMPLATE/install_help.yml

@@ -5,9 +5,9 @@ body:
   - type: markdown
     attributes:
       value: |
-        **First:** check the [Installation Guide](https://github.com/hope1026/roblox-mcp/blob/main/docs/en/installation/README.md)
-        and [Troubleshooting](https://github.com/hope1026/roblox-mcp/blob/main/docs/en/troubleshooting.md).
-        For general questions, use [Discussions](https://github.com/hope1026/roblox-mcp/discussions) instead.
+        **First:** check the [Installation Guide](https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/installation/README.md)
+        and [Troubleshooting](https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/troubleshooting.md).
+        For general questions, use [Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions) instead.
   - type: dropdown
     id: ai-client
     attributes:

package/CHANGELOG.md

@@ -12,6 +12,40 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+
+## [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
+
+- Enhanced overall stability and reliability
+
+
 ## [1.5.4] - 2026-03-16
 
 ### Improved
@@ -340,4 +374,4 @@ First public release of Roblox MCP - AI-powered Roblox Studio integration.
 - **Secure by design** - Localhost only, no external network access
 - **Basic tier included** - Essential tools, free forever
 
-[0.1.0]: https://github.com/hope1026/roblox-mcp/releases/tag/v0.1.0
+[0.1.0]: https://github.com/hope1026/weppy-roblox-mcp/releases/tag/v0.1.0

package/CODE_OF_CONDUCT.md

@@ -22,7 +22,7 @@ Examples of unacceptable behavior:
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainer via [GitHub Discussions](https://github.com/hope1026/roblox-mcp/discussions). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainer via [GitHub Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate.
 
 ## Attribution
 

package/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Bug Reports
 
-Use the [Bug Report issue template](https://github.com/hope1026/roblox-mcp/issues/new?template=bug_report.yml).
+Use the [Bug Report issue template](https://github.com/hope1026/weppy-roblox-mcp/issues/new?template=bug_report.yml).
 
 Include:
 - OS and Node.js version (`node --version`)
@@ -14,11 +14,11 @@ Include:
 
 ## Feature Requests
 
-Use the [Feature Request template](https://github.com/hope1026/roblox-mcp/issues/new?template=feature_request.yml).
+Use the [Feature Request template](https://github.com/hope1026/weppy-roblox-mcp/issues/new?template=feature_request.yml).
 
 ## Questions & Install Help
 
-Use [GitHub Discussions](https://github.com/hope1026/roblox-mcp/discussions) — not Issues — for questions and install help.
+Use [GitHub Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions) — not Issues — for questions and install help.
 
 ## Pull Requests
 

package/README.md

@@ -1,18 +1,18 @@
-# Roblox MCP
+# Roblox MCP — MCP Server for Roblox Studio | AI Game Development with Claude, Codex, Cursor & Gemini
 
-> The MCP server that connects AI coding agents to Roblox Studio — control scripts, terrain, assets, lighting, audio, and animations via natural language.
+> **Weppy Roblox MCP** is an MCP server that lets AI coding agents control a live Roblox Studio session — create and edit scripts, instances, terrain, lighting, assets, audio, and animations via natural language.
+
+**21 consolidated tools · 140+ actions · Bidirectional sync · Automated playtest · Multi-place support**
 
 **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)
+[![Demo — AI building a Roblox game in real time](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## The Problem
+## Why Weppy Roblox MCP?
 
 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.
+**Weppy 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.
 
@@ -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)
@@ -120,19 +131,25 @@ View the full instance tree of your Roblox Studio place directly inside VSCode.
 
 ## 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.
+### How do I connect Claude Code to Roblox Studio?
+Install the Roblox Studio plugin, then register the MCP server (`npx -y @weppy/roblox-mcp`) in Claude Code. Claude can then directly read and write scripts inside Studio. See [Claude Code Setup](docs/en/installation/ai-apps/claude-code.md).
 
-**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.
+### How do I use Codex CLI with Roblox Studio?
+Install the plugin, then add the MCP server config to Codex CLI. See [Codex CLI Setup](docs/en/installation/ai-apps/codex-cli.md).
 
-**Does it work with Cursor / Codex / Gemini?**
+### Does Roblox MCP work with Cursor?
 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).
+### 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.
+
+### What is the difference between Basic and Pro?
+Basic (Free) 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).
+
+### How is Weppy different from other Roblox MCP servers?
+Weppy uses 21 consolidated tools with action-based dispatching (140+ actions) instead of separate tools for each function. This reduces AI token consumption significantly. It also provides bidirectional project sync and multi-place support, which most alternatives lack.
 
-**Is it safe? Can AI break my game?**
+### 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
@@ -143,6 +160,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)
+[![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/weppy-roblox-mcp)](https://smithery.ai/server/@hope1026/weppy-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)
+[GitHub Issues](https://github.com/hope1026/weppy-roblox-mcp/issues) · [Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions) · [npm](https://www.npmjs.com/package/@weppy/roblox-mcp)

package/SECURITY.md

@@ -11,7 +11,7 @@
 
 Do **not** open a public GitHub issue for security vulnerabilities.
 
-Report security issues via [GitHub Issues](https://github.com/hope1026/roblox-mcp/issues/new) with the title prefixed `[SECURITY]`, or contact the maintainer via [GitHub Discussions](https://github.com/hope1026/roblox-mcp/discussions).
+Report security issues via [GitHub Issues](https://github.com/hope1026/weppy-roblox-mcp/issues/new) with the title prefixed `[SECURITY]`, or contact the maintainer via [GitHub Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions).
 
 We will respond within 72 hours and aim to release a fix within 14 days for confirmed vulnerabilities.
 

package/SUPPORT.md

@@ -11,7 +11,7 @@
 
 ## Community Help
 
-For questions and install issues, use [GitHub Discussions](https://github.com/hope1026/roblox-mcp/discussions).
+For questions and install issues, use [GitHub Discussions](https://github.com/hope1026/weppy-roblox-mcp/discussions).
 
 Please include:
 - Your OS and Node.js version
@@ -20,7 +20,7 @@ Please include:
 
 ## Bug Reports
 
-For confirmed bugs, open an [Issue](https://github.com/hope1026/roblox-mcp/issues/new?template=bug_report.yml).
+For confirmed bugs, open an [Issue](https://github.com/hope1026/weppy-roblox-mcp/issues/new?template=bug_report.yml).
 
 ## Pro Users
 

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)