@weppy/roblox-mcp 2.5.1 → 2.6.1

package/docs/en/explorer/overview.md

@@ -1,104 +0,0 @@
-# WEPPY Roblox Explorer Guide
-
-**WEPPY Roblox Explorer** is a companion VSCode/Antigravity extension that mirrors the Roblox Studio Explorer tree directly inside your editor. Browse synced instances, open scripts, and edit properties without constantly switching between Studio and your editor.
-
-> **Optional** — Explorer is not required. The MCP server and the Roblox Studio plugin are enough to use every core feature. Install Explorer when you want to browse project structure or inspect/edit properties right from your editor.
-
-![WEPPY Roblox Explorer — Studio instance tree displayed in the VSCode sidebar](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
-## Why Use Explorer
-
-AI agents can already understand the entire project context from the files generated by Sync, but when a human browses the mirror, file paths alone do not make the hierarchy obvious. Explorer reuses the same sync data and renders it as the **same tree you see in Roblox Studio**, which makes the following much easier:
-
-- See at a glance which service/instance a script belongs to
-- Quickly locate instances across services by name or path
-- Check per-file sync status (modified / studio / conflict)
-- Edit properties without switching to Studio
-
-## Requirements
-
-- VSCode 1.85+ or Antigravity
-- [Roblox MCP](../installation/README.md) installed with Sync enabled (Basic or Pro)
-- A Sync-generated `weppy-project-sync/place_*/.sync-meta.json` under your project root
-
-Explorer works purely from the on-disk sync files by default. When the local MCP server is running, live sync state and direction information are reflected as well.
-
-## Installation
-
-Search for **WEPPY Roblox Explorer** in the Extensions sidebar (`Ctrl+Shift+X` / `Cmd+Shift+X`) of VSCode or Antigravity and click **Install**.
-
-Direct marketplace links:
-
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
-- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
-
-## Browsing the Instance Tree
-
-After installing, a **WEPPY Explorer** view appears in the VSCode Activity Bar and auto-discovers the sync directory from your project root.
-
-- **Service roots**: Synced services such as `Workspace`, `ReplicatedStorage`, and `ServerScriptService` appear at the top level.
-- **Roblox class icons**: Over 200 Studio-style icons that switch automatically between dark and light themes.
-- **Multi-place support**: Each synced Place is shown as its own tree root when multiple places exist.
-- **Auto refresh**: The tree updates with a 500ms debounce whenever sync files change.
-- **Sync status badges**: `modified`, `studio`, and `conflict` states are shown next to icons so you can spot changes and conflicts immediately.
-
-Clicking a tree item opens the file that backs the instance (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`, ...). The right-click menu lets you copy the instance path in `game.Workspace.Part` format or reveal the backing file in the default VSCode explorer.
-
-## Property Panel
-
-Select an instance in the Explorer tree and run **Open Properties** to launch a panel that looks just like the Properties window in Studio. You can inspect and edit properties in grouped form without touching the `.props.json` file directly.
-
-![Property Panel — edit Studio-style properties inside VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-property-window.png)
-
-- **Grouped display**: Properties are sorted into the same groups as Studio (Appearance, Behavior, Data, Part, Transform, and so on).
-- **Type-aware editors**: Input widgets match the property type — numbers, strings, booleans, colors, Vector3, enums, and more.
-- **File-backed editing**: Changes are written to the instance's `*.props.json` file and flow back to Studio through Sync's reverse path (Pro, when bidirectional is enabled).
-- **Custom editor binding**: Opening a `.props.json` file directly uses the Property Panel instead of the default text editor.
-
-If you want the Property Panel to open automatically as you click around the tree, set `robloxExplorer.propertyPanel.autoOpen` to `true` in settings.
-
-## Searching Instances
-
-Run `WEPPY Explorer: Search Instances` (from the view title icon or the Command Palette) to open a QuickPick that searches across every synced service.
-
-- Partial matches against instance names
-- Selecting a result focuses the tree on the matching item
-- When multiple places are synced, results are scoped per place
-
-## Settings
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `robloxExplorer.mcpBaseUrl` | `""` | Local MCP HTTP base URL. If empty, Explorer tries `http://127.0.0.1:3002` and then `http://127.0.0.1:3003`. |
-| `robloxExplorer.syncRoot` | `""` | Absolute path to the `weppy-project-sync` root. Auto-discovered from workspace folders when empty. |
-| `robloxExplorer.hidePropsFiles` | `false` | Hide sync artifacts (`.props.json`, `_tree.json`, `.value.json`) in the default VSCode explorer. |
-| `robloxExplorer.autoRefresh` | `true` | Auto-refresh the tree when sync files change. |
-| `robloxExplorer.showSyncStatus` | `true` | Show sync status decorations on tree items. |
-| `robloxExplorer.followFocusCue` | `false` | Follow external focus cue files by best-effort tree reveal and script file open. |
-| `robloxExplorer.propertyPanel.autoOpen` | `false` | Automatically open the Property Panel when you select an instance in the tree. |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `WEPPY Explorer: Refresh` | Manually refresh the instance tree |
-| `WEPPY Explorer: Search Instances` | Search for instances across every service |
-| `WEPPY Explorer: Open Backing File` | Open the backing file for the selected instance |
-| `WEPPY Explorer: Open Properties` | Open the Property Panel for the selected instance |
-| `WEPPY Explorer: Copy Instance Path` | Copy the full instance path (e.g. `game.Workspace.Part`) |
-| `WEPPY Explorer: Reveal in Explorer` | Show the backing file in the default VSCode explorer |
-| `WEPPY Explorer: Collapse All` | Collapse every tree node |
-| `WEPPY Explorer: Open Settings` | Open the Explorer settings page |
-
-## Troubleshooting
-
-- **Tree is empty**: Check that the `weppy-project-sync/place_*` directory exists and that Sync has completed at least one Full Sync. Set `robloxExplorer.syncRoot` manually if needed.
-- **Sync status does not appear**: Make sure the local MCP server is running and try setting `robloxExplorer.mcpBaseUrl` explicitly.
-- **Property Panel does not open**: If a `.props.json` file opens in the default text editor, right-click the file and choose **Reopen Editor With... → WEPPY Property Panel**.
-- **Icons look broken**: Re-select your VSCode theme or restart the window to refresh the icon cache.
-
-## See Also
-
-- [Roblox MCP Installation Guide](../installation/README.md)
-- [Sync Guide](../sync/overview.md)
-- [Tools Overview](../tools/overview.md)

package/docs/en/installation/README.md

@@ -1,95 +0,0 @@
-# Installation Guide
-
-To use Roblox MCP, you need to install **two things**.
-
-```
-AI App (Claude, Codex, Gemini, etc.)
-       │
-   MCP Server ← Converts AI commands into a format Roblox understands
-       │
-Roblox Studio Plugin ← Executes commands inside Studio
-```
-
-When an AI app says "Create a blue part", the MCP server converts this request, and the Roblox Studio plugin actually creates the part.
-
----
-
-## One-Line Install (Recommended)
-
-Install everything in one command:
-
-**macOS / Linux**
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.sh | bash
-```
-
-**Windows (PowerShell)**
-
-```powershell
-irm https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.ps1 | iex
-```
-
-Then reopen your AI app and restart Roblox Studio.
-
-If the installer fails, it writes an error log to a temporary file and keeps the console open in interactive runs so you can read the reason before exiting.
-
-Automatic MCP registration supports **Claude Code, Claude Desktop, Cursor, Codex CLI/App, Gemini CLI, and Antigravity**.
-
-If PowerShell execution is blocked on Windows, use the manual install path below. If you're using the ZIP package, you can also run `setup-plugin.bat` and `setup-mcp.bat`.
-
----
-
-## Manual Install
-
-If the one-line install does not work, or automatic installation is not available in your environment, use the manual install path below as an alternative.
-
-### Step 1: Install Roblox Studio Plugin
-
-Download the plugin file from GitHub, then place it in Roblox Studio's Plugins folder.
-
-👉 [Plugin Installation Guide](https://weppyai.com/en/install#plugin)
-
----
-
-### 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.
-
-| AI App | Installation Guide |
-|--------|-------------------|
-| Claude Code | [Setup Instructions](ai-apps/claude-code.md) |
-| Claude Desktop | [Setup Instructions](ai-apps/claude-app.md) |
-| Cursor | [Setup Instructions](ai-apps/cursor.md) |
-| Codex CLI | [Setup Instructions](ai-apps/codex-cli.md) |
-| Codex Desktop | [Setup Instructions](ai-apps/codex-app.md) |
-| Gemini CLI | [Setup Instructions](ai-apps/gemini-cli.md) |
-| Antigravity | [Setup Instructions](ai-apps/antigravity.md) |
-
-> Even if your AI app isn't listed above, you can use it if it supports MCP. The MCP server command is `npx -y @weppy/roblox-mcp`.
-
----
-
-## Optional: Install WEPPY Roblox Explorer (VSCode Extension)
-
-Browse synced instance trees inside VSCode with Roblox class icons.
-This optional extension requires the Roblox MCP setup above, because it reads sync data from `weppy-project-sync` under your project root.
-
-👉 [WEPPY Roblox Explorer Installation Guide](https://weppyai.com/en/install#explorer)
-
-Direct listings:
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
-- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
-
----
-
-## After Installation
-
-1. Open **Roblox Studio**, go to Plugins tab and click **WEPPY** → **Connect**
-2. Test in your **AI app** with:
-
-```
-Create a blue part in Roblox Studio
-```
-
-If the part is created successfully, installation is complete!

package/docs/en/installation/ai-apps/antigravity.md

@@ -1,89 +0,0 @@
-# Antigravity Setup
-
-How to use Roblox MCP with [Google Antigravity](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/).
-
-> **Antigravity** is Google's agentic development platform where AI agents autonomously move between code editing, terminal, and browser to carry out complex tasks.
-
-## Prerequisites
-
-1. **Antigravity** installed (see official docs for supported OS/requirements)
-2. **Node.js** (v18.0.0 or later, `npx` available)
-3. **Roblox Studio plugin** installed
-
-## Register MCP Server
-
-In Antigravity, MCP servers are managed in the **agent pane (Agent pane)**.
-
-### Manual registration via raw config (recommended)
-
-1. In the agent pane, click **⋯** → **MCP Servers** → **Manage MCP Servers** → **View raw config**
-
-![Open MCP Servers menu](../../../assets/screenshots/antigravity/antigravity_mcp_services_menu.png)
-
-2. Add/merge the following into the displayed config (JSON):
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-![Edit raw config](../../../assets/screenshots/antigravity/antigravity_mcp_raw.png)
-
-3. After saving, do **Refresh** (or restart/refresh per the UI guidance)
-
-> The actual path/name of the config file can vary by OS and Antigravity version, so always edit based on the location shown in **View raw config**.
-
-### Optional: Adjust port/logs with environment variables
-
-We recommend keeping the defaults (HTTP `127.0.0.1:3002`). If needed, you can set environment variables like this:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"],
-      "env": {
-        "HTTP_HOST": "127.0.0.1",
-        "HTTP_PORT": "3002",
-        "LOG_LEVEL": "INFO"
-      }
-    }
-  }
-}
-```
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. In **Antigravity**, enter:
-   ```
-   Tell me what's currently selected in Roblox Studio
-   ```
-
-## Troubleshooting
-
-### When the server won't start
-
-Run the MCP server directly to check for errors:
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Connection failed
-
-- Verify the Roblox Studio plugin is **Connected**
-- Check whether port **3002** is blocked by a firewall
-- Check server status in the agent pane **⋯** → **MCP Servers**
-- (Advanced) If you changed `HTTP_PORT`, the Roblox Studio plugin/bridge must be configured to use the same port.
-
-## References
-
-- [Google Antigravity introduction](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/)
-- [Antigravity Getting Started Guide (Codelab)](https://codelabs.developers.google.com/getting-started-google-antigravity)

package/docs/en/installation/ai-apps/claude-app.md

@@ -1,78 +0,0 @@
-# Claude Desktop App Setup
-
-How to use Roblox MCP with [Claude Desktop App](https://claude.ai/download).
-
-## Prerequisites
-
-- **Claude Desktop App** installed
-- **Node.js** (v18.0.0 or higher)
-- **Roblox Studio Plugin** installed
-
-## Register MCP Server
-
-### Method 1: Desktop Extensions (Recommended)
-
-> One-click installation available like browser extensions since 2026
-
-1. Claude Desktop → **Settings** → **Extensions**
-2. Search for `weppy-roblox-mcp`
-3. Click **Install**
-
-### Method 2: Edit Configuration File Directly
-
-1. Claude Desktop → **Settings** → **Developers** → Click **Edit Config**
-
-2. Add the following content to the `claude_desktop_config.json` file:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-3. **Completely quit** and restart Claude Desktop
-
-**Configuration file locations:**
-
-| OS | Path |
-|----|------|
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. Start a new conversation in **Claude Desktop** and test:
-   ```
-   Create a blue part in Roblox Studio
-   ```
-
-## Troubleshooting
-
-### MCP server not loading
-
-1. **Check JSON syntax**: Validate configuration file with an online JSON validator
-2. **Fully restart Claude Desktop**: After configuration changes, completely quit and restart the app
-3. **Verify paths**: Check that command and args are correct
-
-### Server won't start
-
-Run the MCP server directly to check for errors:
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Connection failed
-
-- Verify the Roblox Studio plugin is in **Connected** state
-- Check if port 3002 is blocked by a firewall
-
-## Reference
-
-- [Claude Desktop MCP Official Guide](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
-- [MCP Server Connection Guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers)

package/docs/en/installation/ai-apps/claude-code.md

@@ -1,104 +0,0 @@
-# Claude Code Setup
-
-How to use Roblox MCP with [Claude Code](https://claude.ai/code) (terminal-based AI coding tool).
-
-## Prerequisites
-
-- **Claude Code** installed
-- **Roblox Studio Plugin** installed
-
-## Installation
-
-```bash
-npm install -g @anthropic-ai/claude-code
-```
-
-## Register MCP Server
-
-### Method 1: Install from Marketplace (Recommended)
-
-Run in Claude Code terminal:
-
-```bash
-# Add marketplace
-/plugin marketplace add hope1026/weppy-roblox-mcp
-
-# Install plugin
-/plugin install weppy-roblox-mcp@hope1026-roblox-mcp
-```
-
-Verify installation:
-```bash
-/plugin list
-```
-
-### Method 2: Edit Configuration File Directly
-
-Create a `.mcp.json` file:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-**Configuration file locations:**
-
-| Scope | Path |
-|-------|------|
-| Project | `<project>/.mcp.json` |
-| Global | `~/.claude/mcp.json` |
-
-## Automatic Server Management
-
-Claude Code manages MCP servers automatically:
-
-- Starts automatically when needed
-- Stops automatically when session ends
-- No additional configuration required
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. Test in **Claude Code**:
-   ```
-   Create a blue part in Roblox Studio
-   ```
-
-## Troubleshooting
-
-### Plugin installation failed
-
-```bash
-# Clear cache and retry
-/plugin cache clear
-/plugin install weppy-roblox-mcp@hope1026-roblox-mcp
-```
-
-### Server won't start
-
-1. Check Node.js version (18.0 or higher required):
-   ```bash
-   node --version
-   ```
-
-2. Test starting the server manually:
-   ```bash
-   npx -y @weppy/roblox-mcp
-   ```
-
-### MCP tools not visible
-
-Check in Claude Code:
-```
-Show me the list of available MCP tools
-```
-
-## Reference
-
-- [Claude Code Official Documentation](https://docs.anthropic.com/claude-code)

package/docs/en/installation/ai-apps/codex-app.md

@@ -1,56 +0,0 @@
-# Codex App Setup
-
-How to use Roblox MCP with [OpenAI Codex App](https://openai.com/codex/) (macOS).
-
-> **Released February 2, 2026** - Native macOS app supporting multi-agent workflows
-
-## Prerequisites
-
-- **Codex App** installed (macOS)
-- **Roblox Studio Plugin** installed
-
-## Register MCP Server
-
-### Auto-sync with Codex CLI Settings
-
-If you've already configured MCP in Codex CLI, you can use it in the app **without additional setup**.
-
-```
-CLI session history and settings are automatically synced to the app.
-```
-
-### New Setup
-
-Add in the app under **Settings** → **MCP Servers**:
-
-```
-Server name: weppy-roblox-mcp
-Command: npx -y @weppy/roblox-mcp
-```
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. Start a new conversation in **Codex App** and test:
-   ```
-   Tell me what's currently selected in Roblox Studio
-   ```
-
-## Troubleshooting
-
-### Server won't start
-
-Run the MCP server directly to check for errors:
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Connection failed
-
-- Verify the Roblox Studio plugin is in **Connected** state
-- Check if port 3002 is blocked by a firewall
-
-## Reference
-
-- [Codex App Introduction](https://openai.com/index/introducing-the-codex-app/)
-- [Codex MCP Official Documentation](https://developers.openai.com/codex/mcp/)

package/docs/en/installation/ai-apps/codex-cli.md

@@ -1,67 +0,0 @@
-# Codex CLI Setup
-
-How to use Roblox MCP with [OpenAI Codex CLI](https://github.com/openai/codex) (terminal-based AI coding tool).
-
-## Prerequisites
-
-- **Node.js** (v18.0.0 or higher)
-- **Roblox Studio Plugin** installed
-
-## Installation
-
-```bash
-npm install -g @openai/codex
-```
-
-## Register MCP Server
-
-### Method 1: CLI Command (Recommended)
-
-```bash
-codex mcp add weppy-roblox-mcp -- npx -y @weppy/roblox-mcp
-```
-
-### Method 2: Edit Configuration File Directly
-
-Add the following content to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.weppy-roblox-mcp]
-command = "npx"
-args = ["-y", "@weppy/roblox-mcp"]
-```
-
-**Configuration file locations:**
-
-| OS | Path |
-|----|------|
-| macOS/Linux | `~/.codex/config.toml` |
-| Windows | `%USERPROFILE%\.codex\config.toml` |
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. Run **Codex CLI** and enter:
-   ```
-   Tell me what's currently selected in Roblox Studio
-   ```
-
-## Troubleshooting
-
-### Server won't start
-
-Run the MCP server directly to check for errors:
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Connection failed
-
-- Verify the Roblox Studio plugin is in **Connected** state
-- Check if port 3002 is blocked by a firewall
-
-## Reference
-
-- [Codex CLI GitHub](https://github.com/openai/codex)
-- [Codex MCP Official Documentation](https://developers.openai.com/codex/mcp/)
-- [Codex Configuration Reference](https://developers.openai.com/codex/config-reference/)

package/docs/en/installation/ai-apps/cursor.md

@@ -1,77 +0,0 @@
-# Cursor Setup
-
-How to use Roblox MCP with [Cursor](https://cursor.com/).
-
-## Prerequisites
-
-- **Cursor** installed
-- **Node.js** (v18.0.0 or higher)
-- **Roblox Studio Plugin** installed
-
-## Register MCP Server
-
-### Method 1: Project Configuration
-
-Add the following to `.cursor/mcp.json` in your project:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-### Method 2: Global Configuration
-
-Add the same content to your global Cursor MCP config file.
-
-**Configuration file locations:**
-
-| Scope | Path |
-|-------|------|
-| Project | `<project>/.cursor/mcp.json` |
-| Global (macOS/Linux) | `~/.cursor/mcp.json` |
-| Global (Windows) | `%USERPROFILE%\\.cursor\\mcp.json` |
-
-> If the file already exists, merge the `weppy-roblox-mcp` entry into the existing `mcpServers` object.
-
-### Apply Changes
-
-After editing the config, reload the Cursor window or restart the app.
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. In **Cursor**, enter:
-   ```
-   Tell me what's currently selected in Roblox Studio
-   ```
-
-## Troubleshooting
-
-### MCP server not showing up
-
-- Check that the config file path is correct
-- Verify the JSON syntax is valid
-- Reload Cursor after editing the config
-
-### Server won't start
-
-Run the MCP server directly to check for errors:
-
-```bash
-npx -y @weppy/roblox-mcp
-```
-
-### Connection failed
-
-- Verify the Roblox Studio plugin is in **Connected** state
-- Check if port 3002 is blocked by a firewall
-
-## Reference
-
-- [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol)