@weppy/roblox-mcp 2.5.1 → 2.6.1

package/llms-full.txt

@@ -1,694 +1,14 @@
-# WEPPY — Full Documentation
+# WEPPY — Canonical Web Docs
 
-> WEPPY is an MCP server that lets AI coding agents (Claude, Codex,
-> Cursor, Gemini) control a live Roblox Studio session — create and edit scripts,
-> instances, terrain, lighting, assets, audio, and animations via natural language.
-> Action-based MCP tools · Bidirectional sync · Multi-place support
+> WEPPY is an MCP server that lets AI coding agents control a live Roblox Studio session and interact with scripts, instances, terrain, lighting, assets, audio, and animations.
 
----
+This package intentionally does not ship a standalone full documentation surface.
 
-# Installation Guide
+Canonical documentation lives on the web:
 
-To use Roblox MCP, you need to install **two things**.
+- Install and setup: https://weppyai.com/en/install
+- Product documentation: https://weppyai.com/en/install
+- Pro plans: https://weppyai.com/en/plans
 
-```
-AI App (Claude, Codex, Gemini, etc.)
-       │
-   MCP Server ← Converts AI commands into a format Roblox understands
-       │
-Roblox Studio Plugin ← Executes commands inside Studio
-```
+For app-specific setup, open the web install page and choose the relevant AI client guide.
 
-When an AI app says "Create a blue part", the MCP server converts this request, and the Roblox Studio plugin actually creates the part.
-
-## Web Installer (Recommended)
-
-Open the installer page in Chrome, Edge, or Arc for one-click setup:
-
-https://hope1026.github.io/weppy-roblox-mcp/installer/
-
-It writes the supported AI app config for `npx -y @weppy/roblox-mcp` first.
-
-After you reopen the AI app, the first MCP run fetches the package through `npx` and auto-installs the Roblox Studio plugin.
-
-For Safari or Firefox, use the installer page as a guide or continue with the manual install below.
-
-## One-Line Install (Fallback)
-
-Advanced users can install everything in one command:
-
-```bash
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.sh | bash
-
-# Windows (PowerShell)
-irm https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.ps1 | iex
-```
-
-Then restart Roblox Studio — done!
-
-## Manual Install
-
-### Step 1: Install Roblox Studio Plugin
-
-Download the plugin file from GitHub, then place it in Roblox Studio's Plugins folder.
-
-### Download Plugin
-
-1. Open [GitHub Releases](https://github.com/hope1026/weppy-roblox-mcp/releases/latest)
-2. Download `weppy-roblox-mcp-v{version}.zip`
-3. Extract the ZIP file - you will find `roblox-plugin/WeppyRobloxMCP.rbxm` and setup guides
-
-Note: The same plugin package is used for all tiers.
-
-### Install Plugin
-
-1. Open **Roblox Studio**
-2. Click the **Plugins** tab in the top menu
-3. Click the **Plugins Folder** button
-4. **Copy** the `WeppyRobloxMCP.rbxm` file into the opened Plugins folder
-5. **Restart Roblox Studio**
-
-After restarting, the **WEPPY** button will appear in the Plugins tab.
-
-### Connect to AI Agent
-
-1. Open any project in **Roblox Studio**
-2. Go to **Plugins** tab -> **WEPPY**
-3. Click the **Connect** button in the plugin window
-4. Once **"Connected"** status is displayed, you're ready
-
-### Settings (Optional)
-
-- **Auto Connect**: Automatically connect to MCP server when Studio starts
-- **Auto Reconnect**: Automatically attempt to reconnect when connection is lost
-- **Auto Camera Focus**: Automatically move camera to created objects
-- **Language**: Change the plugin UI language
-
-## Step 2: Register MCP Server with AI App
-
-Register the MCP server with your AI app. You can use it with any AI app that supports MCP.
-
-The MCP server command is: `npx -y @weppy/roblox-mcp`
-
-### Claude Code Setup
-
-**Method 1: Install from Marketplace (Recommended)**
-
-```bash
-/plugin marketplace add hope1026/weppy-roblox-mcp
-/plugin install weppy-roblox-mcp@hope1026-roblox-mcp
-```
-
-**Method 2: Edit Configuration File**
-
-Create a `.mcp.json` file (project scope) or `~/.claude/mcp.json` (global):
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-### Claude Desktop Setup
-
-**Method 1: Desktop Extensions (Recommended)**
-
-Claude Desktop → Settings → Extensions → Search for `weppy-roblox-mcp` → Install
-
-**Method 2: Edit Configuration File**
-
-Add to `claude_desktop_config.json`:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-### Cursor Setup
-
-Add the following to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` (global):
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-### Codex CLI Setup
-
-```bash
-codex mcp add weppy-roblox-mcp -- npx -y @weppy/roblox-mcp
-```
-
-Or edit `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.weppy-roblox-mcp]
-command = "npx"
-args = ["-y", "@weppy/roblox-mcp"]
-```
-
-### Codex Desktop Setup
-
-If you've already configured MCP in Codex CLI, settings are automatically synced to the app.
-
-Otherwise, add in the app under Settings → MCP Servers:
-- Server name: weppy-roblox-mcp
-- Command: npx -y @weppy/roblox-mcp
-
-### Gemini CLI Setup
-
-```bash
-gemini mcp add weppy-roblox-mcp npx --trust -- -y @weppy/roblox-mcp
-```
-
-Or edit `.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-### Antigravity Setup
-
-In the agent pane, click ⋯ → MCP Servers → Manage MCP Servers → View raw config, then add:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-## Optional: Install Roblox Explorer (VSCode Extension)
-
-Browse synced instance trees inside VSCode with Roblox class icons.
-
-Search for **WEPPY Explorer** in the VSCode Extensions sidebar and click Install, or install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer) or [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer).
-
-Features:
-- Instance tree with Roblox class icons (dark/light theme)
-- Multi-place support with sync status indicators
-- Click-to-open scripts and property files
-- Instance search across all services
-- Auto-refresh when sync files change
-
-## After Installation
-
-1. Open Roblox Studio, go to Plugins tab and click WEPPY → Connect
-2. Test in your AI app: "Create a blue part in Roblox Studio"
-
----
-
-# Tools Reference
-
-Roblox MCP provides consolidated tools with action-based sub-commands. Each tool uses an `action` field to specify the operation.
-
-## Query Instances
-
-| Action | Description |
-|--------|-------------|
-| `get` | Get instance properties by path |
-| `children` | Get immediate children or all descendants |
-| `find_child` | Find first child by name and optional class filter |
-| `find_descendant` | Find first descendant by name |
-| `wait_for_child` | Wait for child to appear (with timeout) |
-| `class_info` | Get class information and valid properties |
-| `search_name` | Search instances by name pattern (supports wildcards) |
-| `search_class` | Search instances by class name |
-| `file_tree` | Get file tree structure from root |
-| `project_structure` | Get complete project structure |
-| `descendants` | Get all descendants of an instance |
-| `ancestors` | Get all ancestors of an instance |
-| `search_property` | Search instances by property value |
-| `search_tag` | Search instances by tag |
-
-## Mutate Instances
-
-| Action | Description |
-|--------|-------------|
-| `create` | Create a new instance |
-| `create_with_props` | Create instance with initial properties |
-| `delete` | Delete an instance |
-| `clone` | Clone an instance |
-| `move` | Move instance to new parent |
-| `rename` | Rename an instance |
-| `pivot` | Set pivot position or CFrame |
-| `create_tree` | Create hierarchical instance tree |
-| `mass_create` | Create multiple instances at once |
-| `mass_delete` | Delete multiple instances |
-| `mass_duplicate` | Duplicate multiple instances |
-| `smart_duplicate` | Duplicate with spacing and count |
-
-## Manage Properties
-
-| Action | Description |
-|--------|-------------|
-| `get` | Get a single property value |
-| `set` | Set a single property value |
-| `get_all` | Get all properties of an instance |
-| `set_multiple` | Set multiple properties at once |
-| `get_attr` | Get attribute value |
-| `set_attr` | Set attribute value |
-| `get_all_attrs` | Get all attributes |
-| `delete_attr` | Delete an attribute |
-| `add_tag` | Add a tag to instance |
-| `remove_tag` | Remove a tag from instance |
-| `check_tag` | Check if instance has a tag |
-| `get_tags` | Get all tags on an instance |
-| `get_tagged` | Get all instances with a specific tag |
-| `set_calculated` | Set property using mathematical expression |
-| `set_relative` | Set property relative to current value |
-| `mass_set` | Set property on multiple instances |
-| `mass_get` | Get property from multiple instances |
-| `modify_children` | Modify all children of a parent |
-
-## Manage Scripts
-
-| Action | Description |
-|--------|-------------|
-| `get_source` | Get script source code |
-| `set_source` | Set script source code |
-| `create` | Create a new script |
-| `delete` | Delete a script |
-| `edit_replace` | Replace specific lines in script |
-| `edit_insert` | Insert lines at position |
-| `edit_delete` | Delete specific lines |
-| `search` | Search for text in script |
-| `get_dependencies` | Get script dependencies |
-| `replace` | Batch replace across scripts |
-
-## Manage Lighting
-
-| Action | Description |
-|--------|-------------|
-| `lighting` | Set Lighting service properties |
-| `atmosphere` | Set Atmosphere properties |
-| `sky` | Set Sky properties |
-| `terrain_props` | Set Terrain water/visual properties |
-| `time` | Set time of day |
-
-## Manage Selection
-
-| Action | Description |
-|--------|-------------|
-| `get` | Get current selection |
-| `set` | Replace current selection |
-| `clear` | Clear selection |
-| `cached` | Get cached selection without round-trip |
-| `context` | Get detailed context with source and properties |
-| `details` | Get hierarchical details with ancestors/descendants |
-| `add` | Add items to selection |
-| `remove` | Remove items from selection |
-| `watch` | Monitor selection changes |
-
-## Manage Camera
-
-| Action | Description |
-|--------|-------------|
-| `info` | Get camera position, rotation, FOV, viewport size |
-| `focus_path` | Move camera to focus on instance |
-| `focus_position` | Move camera to focus on position |
-| `suggest` | Get suggested camera view for target |
-
-## Manage Tween
-
-| Action | Description |
-|--------|-------------|
-| `create` | Create a tween with target properties |
-| `play` | Play a created tween |
-| `pause` | Pause a running tween |
-| `cancel` | Cancel a tween |
-
-## Manage Audio
-
-| Action | Description |
-|--------|-------------|
-| `play` | Play a sound (creates Sound if needed) |
-| `stop` | Stop a playing sound |
-| `pause` | Pause a playing sound |
-| `resume` | Resume a paused sound |
-| `set_listener` | Set audio listener type/target |
-
-## Manage Animation
-
-| Action | Description |
-|--------|-------------|
-| `load` | Load animation on Humanoid/AnimationController |
-| `play` | Play a loaded animation track |
-| `stop` | Stop a playing animation |
-| `get_tracks` | List all loaded animation tracks |
-
-## Manage Physics
-
-| Action | Description |
-|--------|-------------|
-| `register_group` | Register a collision group |
-| `set_collidable` | Set whether two groups can collide |
-| `get_groups` | List all registered collision groups |
-
-## Manage Effects
-
-| Action | Description |
-|--------|-------------|
-| `emit` | Emit particles from ParticleEmitter |
-| `clear` | Clear all particles |
-| `toggle` | Enable or disable effect |
-
-## Manage Terrain
-
-| Action | Description |
-|--------|-------------|
-| `fill_block` | Fill block-shaped terrain |
-| `fill_ball` | Fill sphere-shaped terrain |
-| `fill_cylinder` | Fill cylinder-shaped terrain |
-| `fill_wedge` | Fill wedge-shaped terrain |
-| `clear_region` | Clear terrain in region |
-| `clear_bounds` | Clear terrain in bounds |
-| `replace_material` | Replace material in region |
-| `colors_get` | Get material colors |
-| `colors_set` | Set material colors |
-| `read_voxel` | Read single voxel data |
-| `read_voxels` | Read bulk voxel data |
-| `write_voxels` | Write bulk voxel data |
-| `generate` | Generate procedural terrain |
-| `smooth` | Smooth terrain |
-
-## Spatial Query
-
-| Action | Description |
-|--------|-------------|
-| `raycast` | Cast a single ray |
-| `find_ground` | Find ground position below point |
-| `check_placement` | Check if placement is collision-free |
-| `multi_raycast` | Cast multiple rays in batch |
-| `scan_area` | Generate heightmap of area |
-| `find_flat` | Find flat areas for building |
-| `find_spawn` | Find suitable spawn positions |
-| `analyze_walkable` | Analyze walkability grid |
-| `spatial_map` | Get all BasePart positions |
-| `find_space` | Find empty space for object |
-| `bounds` | Get bounding box of instances |
-| `snap_grid` | Snap position to grid |
-| `collision` | Check AABB collision |
-
-## Manage Assets
-
-| Action | Description |
-|--------|-------------|
-| `insert` | Insert model by asset ID |
-| `info` | Get asset metadata |
-| `search` | Search Creator Store |
-| `search_insert` | Search and insert first match |
-| `insert_free` | Insert free model |
-| `insert_package` | Insert package |
-| `export` | Export current selection |
-
-## Manage Sync
-
-| Action | Description |
-|--------|-------------|
-| `status` | Get sync status for a place |
-| `history` | Get change history |
-| `directions` | Get per-type sync directions |
-| `read_file` | Read a synced file |
-| `write_file` | Write to a synced file |
-| `progress` | Get real-time sync progress and bandwidth |
-
-## Workspace State
-
-| Action | Description |
-|--------|-------------|
-| `sync` | Fetch current Workspace state |
-| `snapshot` | Get full instance tree structure |
-| `changes` | Get recent changes |
-| `viewport` | Get camera and viewport info |
-
-## Manage Logs
-
-| Action | Description |
-|--------|-------------|
-| `get` | Get filtered logs |
-| `clear` | Clear log buffer |
-| `errors` | Get recent errors only |
-
-## System Info
-
-| Action | Description |
-|--------|-------------|
-| `ping` | Test connection |
-| `connection` | Get server/plugin connection info |
-| `usage` | Get current tier (basic/pro) |
-| `place_info` | Get place ID, name, creator (Pro) |
-| `services` | List all Roblox services (Pro) |
-| `studio_settings` | Get Studio preferences (Pro) |
-| `play` | Start playtest in Play mode (Pro) |
-| `stop` | Stop current playtest (Pro) |
-| `pause` | Pause current playtest (Pro) |
-| `resume` | Resume paused playtest (Pro) |
-| `play_status` | Get current playtest status (Pro) |
-| `run_test` | Run a test script and return results (Pro) |
-
-## Batch Execute
-
-Execute multiple commands in a single batch. Each command specifies a tool name and arguments. Commands execute sequentially with optional continue-on-error behavior.
-
-## Execute Luau
-
-Execute arbitrary Luau code in Roblox Studio sandbox. Blocked services: HttpService, DataStoreService, MessagingService. Cannot access CoreGui/CorePackages.
-
----
-
-# Sync Deep Dive
-
-Sync connects Roblox Studio state and local files so AI can read and modify the full project context reliably.
-
-## Why Sync matters
-
-Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI works from the whole project.
-
-- Apply refactors consistently across multiple scripts
-- Review risky changes quickly using history
-- Keep source-of-truth clear between Studio and local files
-
-## How it works
-
-1. Full Sync: initial mirror from Studio tree/instances to local files
-2. Incremental Sync: continuous update of new changes
-3. History/Status tracking: inspect what changed, when, and in which direction
-
-Sync data is stored under `{projectRoot}/weppy-project-sync/place_{placeId}/explorer`.
-
-## Sync Capabilities
-
-- Sync direction: one-way (Studio -> Local) or bidirectional
-- Per-type Direction: Scripts, Values, Containers, Data, Services can be set independently
-- Per-type Apply Mode: Auto or Manual
-- Status/history APIs: track what changed, when, and in which direction
-- Multi-place sync: up to 3 places simultaneously
-
-## Direction and Apply Mode
-
-### Direction (per-type sync direction)
-- `forward`: Studio -> Local
-- `reverse`: Local -> Studio
-- `bidirectional`: both directions
-
-Types: `scripts`, `values`, `containers`, `data`, `services`.
-
-### Apply Mode
-- `manual`: user confirms before applying to Studio
-- `auto`: detected changes are auto-applied
-
-## Conflict Resolution
-
-When changes are detected on both Studio and local sides during bidirectional sync:
-- **Studio Priority**: overwrite with Studio state as the source of truth
-- **Local Priority**: apply local files to Studio
-- **Per-File**: choose which side takes priority for each file individually
-
-## File format (v2 nested directory)
-
-Each Roblox instance is stored as its own directory:
-
-```
-explorer/
-├── Workspace/
-│   ├── _tree.json
-│   ├── Part/
-│   │   └── Part.props.json
-│   ├── MyScript/
-│   │   └── MyScript.server.luau
-│   └── Coins/
-│       └── Coins.value.json
-```
-
----
-
-# Dashboard
-
-The MCP server provides a web dashboard for monitoring and managing the server in real time. It opens automatically in your browser when the MCP server starts.
-
-```
-http://localhost:3002
-```
-
-Set `DASHBOARD_AUTO_OPEN=false` to disable automatic opening.
-
-## Pages
-
-| Page | Description |
-|------|-------------|
-| **Overview** | Server/Plugin/Agent/Sync status cards and recent game changes feed |
-| **Changelog** | Game change history — per-session cards, change summary, Before & After diff |
-| **Connection** | Server status, AI agent list, plugin connection info |
-| **Sync** | Sync status, direction settings, logs |
-| **Playtest** | Playtest status and test history |
-| **Tools** | Tool execution history, statistics, tier distribution |
-| **Settings** | License, log level, language |
-
-## Connection States
-
-| State | Condition | Available Pages |
-|-------|-----------|-----------------|
-| **Server disconnected** | Server not connected | Reconnection waiting screen only |
-| **Server connected** | Server connected, plugin not connected | Connection, Tools, Settings |
-| **Studio connected** | Both server and plugin connected | All pages |
-
-## Overview Page
-
-- **Status Cards**: Server, Plugin, Agent, Sync state at a glance
-- **Recent Game Changes**: Up to 20 most recent AI actions in Studio with category icons (Script, Instance, Property, Lighting, Terrain, Asset)
-- **Session Change Summary**: Aggregated change statistics by category for the current session
-
-## Real-Time Updates
-
-The dashboard uses SSE (Server-Sent Events) for real-time data:
-- Server status polled every 5 seconds
-- Change feed and connection events streamed via SSE
-- Auto-reconnect after 3 seconds on SSE disconnect
-
----
-
-# Compatibility
-
-## Supported AI Clients
-
-Claude Code, Claude Desktop, Cursor, Codex CLI, Codex Desktop, Gemini CLI, Antigravity, and any MCP-compatible client.
-
-## 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 |
-
-## Full Feature List
-
-- MCP tool execution: scripts, instances, properties, terrain, lighting, assets, audio, animation
-- 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)
-- Automated playtest: start/stop Play (F5) or Run (F8), inject test scripts, collect logs
-- Web dashboard at `http://localhost:3002`: connection status, tool history, sync state, changelog
-- Bulk operations (mass_create, mass_set, mass_get)
-- Advanced spatial queries (raycast, find_ground, find_spawn, analyze_walkable)
-- Terrain generation and fill (procedural, block, ball, cylinder, wedge)
-- Physics group management
-- Tween and animation control
-- Audio control
-- Lighting and atmosphere
-- Batch execution (multiple commands in one call)
-- Execute Luau (arbitrary Luau code in Studio sandbox)
-
----
-
-# Troubleshooting
-
-## Plugin not connecting
-
-1. Make sure the MCP server is running: `npx -y @weppy/roblox-mcp`
-2. In Roblox Studio: Plugins tab → WEPPY → Connect
-3. Confirm nothing is blocking `localhost:3002` (firewall, antivirus, VPN)
-4. Try restarting both Roblox Studio and the MCP server
-
-## MCP server not found by AI client
-
-1. Verify your AI client config uses the correct command: `npx -y @weppy/roblox-mcp`
-2. Ensure Node.js >= 18 is installed: `node --version`
-3. On Windows, try running your terminal as Administrator if permission errors appear
-
-## "Pro feature required" error
-
-The action you're requesting requires the Pro tier.
-
-## Sync not working
-
-1. Check sync status: ask AI `manage_sync status`
-2. Ensure the plugin is connected before starting sync
-3. For reverse sync (file → Studio), confirm Pro tier is active
-
-## Common error messages
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ECONNREFUSED localhost:3002` | MCP server not running | Run `npx -y @weppy/roblox-mcp` |
-| `Timeout waiting for plugin` | Studio plugin not connected | Click Connect in plugin panel |
-| `Rate limit exceeded` | Over 450 requests/min | Reduce or batch requests |
-| `Forbidden path` | Accessing CoreGui/CorePackages | Use valid instance paths only |
-
-## Still stuck?
-
-[Open a Discussion](https://github.com/hope1026/weppy-roblox-mcp/discussions) with your OS, Node.js version, AI client, and error details.
-
----
-
-# Security
-
-- Localhost only: 127.0.0.1:3002
-- Forbidden paths: CoreGui, CorePackages, RobloxScript
-- Rate limiting: 450 requests/minute
-- Timeout: 30 seconds per operation
-- Blocked in Execute Luau: HttpService, DataStoreService, MessagingService
-
----
-
-# Links
-
-- GitHub: https://github.com/hope1026/weppy-roblox-mcp
-- npm: https://www.npmjs.com/package/@weppy/roblox-mcp
-- Issues: https://github.com/hope1026/weppy-roblox-mcp/issues
-- Discussions: https://github.com/hope1026/weppy-roblox-mcp/discussions