@weppy/roblox-mcp 2.5.1 → 2.6.1

package/docs/compatibility.md

@@ -1,44 +0,0 @@
-# Compatibility
-
-## Supported AI Clients
-
-| Client | Basic | Pro | Setup guide |
-|--------|:-----:|:---:|-------------|
-| Claude Code | ✅ | ✅ | [Guide](en/installation/ai-apps/claude-code.md) |
-| Claude Desktop | ✅ | ✅ | [Guide](en/installation/ai-apps/claude-app.md) |
-| Cursor | ✅ | ✅ | [Guide](en/installation/ai-apps/cursor.md) |
-| Codex CLI | ✅ | ✅ | [Guide](en/installation/ai-apps/codex-cli.md) |
-| Codex Desktop | ✅ | ✅ | [Guide](en/installation/ai-apps/codex-app.md) |
-| Gemini CLI | ✅ | ✅ | [Guide](en/installation/ai-apps/gemini-cli.md) |
-| Any MCP client | ✅ | ✅ | Server command: `npx -y @weppy/roblox-mcp` |
-
-## System Requirements
-
-| Requirement | Minimum |
-|-------------|---------|
-| Node.js | 18.0.0+ |
-| Roblox Studio | Latest (keep auto-updated) |
-| OS | Windows 10+ or macOS 12+ |
-| Network | localhost:3002 must be accessible |
-
-## Feature Matrix (Basic vs Pro)
-
-| Feature | Basic | Pro |
-|---------|:-----:|:---:|
-| MCP tool execution (scripts, instances, properties) | ✅ | ✅ |
-| Studio → Local one-way sync | ✅ | ✅ |
-| Bidirectional sync (Local → Studio) | ❌ | ✅ |
-| Per-type Direction and Apply Mode | ❌ | ✅ |
-| Sync history and changelog | ❌ | ✅ |
-| Multi-place support (up to 3 places) | ❌ | ✅ |
-| Bulk operations (mass_create, mass_set) | ❌ | ✅ |
-| Advanced spatial queries | ❌ | ✅ |
-| Terrain generation and fill | ❌ | ✅ |
-| Physics group management | ❌ | ✅ |
-| Tween and animation control | ❌ | ✅ |
-| Audio control | ❌ | ✅ |
-| Lighting and atmosphere | ❌ | ✅ |
-
-## MCP Tool Count
-
-21 consolidated tools with action-based sub-commands. See [Tools Reference](en/tools/overview.md) for the full list.

package/docs/en/dashboard/changelog.md

@@ -1,114 +0,0 @@
-# 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
-
-- [WEPPY 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

@@ -1,77 +0,0 @@
-# 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 dashboard is in the **Server connected** or **Studio connected** state.
-
-## 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
-
-- [WEPPY 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

@@ -1,95 +0,0 @@
-# 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.
-
-![WEPPY 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, 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 States
-
-The features available in the dashboard depend on the connection state:
-
-| State | Condition | Available Pages |
-|-------|-----------|-----------------|
-| **Server disconnected** | Server not connected | Only the reconnection waiting screen is displayed |
-| **Server connected** | Server connected, plugin not connected | Connection, Tools, Settings |
-| **Studio connected** | Both server and plugin connected | All pages |
-
-When the dashboard is in the **Server connected** state, 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

@@ -1,61 +0,0 @@
-# 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 dashboard is in the **Studio connected** state.
-
-## 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
-
-- [WEPPY 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

@@ -1,60 +0,0 @@
-# Settings
-
-> View and manage license information, server 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 dashboard is in the **Server connected** or **Studio connected** state.
-
-## 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 |
-
-## 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
-
-- [WEPPY 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

@@ -1,68 +0,0 @@
-# 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 dashboard is in the **Studio connected** state.
-
-## 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 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
-
-- [WEPPY 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

@@ -1,69 +0,0 @@
-# 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 dashboard is in the **Server connected** or **Studio connected** state.
-
-## 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
-
-- [WEPPY 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)