@weppy/roblox-mcp 2.5.0 → 2.6.0

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)

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

@@ -1,120 +0,0 @@
-# Gemini CLI Setup
-
-How to use Roblox MCP with [Google Gemini CLI](https://github.com/google-gemini/gemini-cli).
-
-## Prerequisites
-
-1. **Node.js** (v18.0.0 or higher)
-   ```bash
-   node --version
-   ```
-
-2. **Gemini CLI** installed
-   ```bash
-   npm install -g @google/gemini-cli
-   ```
-
-3. **Roblox Studio Plugin** installed
-
-## Register MCP Server
-
-### Method 1: CLI Command (Recommended)
-
-Register with a single command in your terminal:
-
-```bash
-gemini mcp add weppy-roblox-mcp npx --trust -- -y @weppy/roblox-mcp
-```
-
-> The `--trust` flag skips confirmation prompts for each tool call.
-
-To register globally, add `-s user`:
-
-```bash
-gemini mcp add weppy-roblox-mcp npx -s user --trust -- -y @weppy/roblox-mcp
-```
-
-### Method 2: Edit Configuration File
-
-Add the following content to `.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"]
-    }
-  }
-}
-```
-
-**Configuration file locations:**
-| Scope | Path |
-|-------|------|
-| Project | `<project>/.gemini/settings.json` |
-| Global | `~/.gemini/settings.json` |
-
-### Method 3: Using Environment Variables
-
-If specific environment variables are needed:
-
-**CLI:**
-```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
-```
-
-**Configuration file:**
-```json
-{
-  "mcpServers": {
-    "weppy-roblox-mcp": {
-      "command": "npx",
-      "args": ["-y", "@weppy/roblox-mcp"],
-      "env": {
-        "HTTP_PORT": "3002"
-      }
-    }
-  }
-}
-```
-
-## Connection Test
-
-1. Open **Roblox Studio** → Plugins tab → **WEPPY** → **Connect**
-2. Run **Gemini CLI** and enter:
-   ```
-   Tell me what's currently selected in Roblox Studio
-   ```
-
-## Check MCP Server Status
-
-You can check connected server status with the `/mcp` command in Gemini CLI:
-
-```
-/mcp
-```
-
-## 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
-- Check server status with `/mcp` command
-
-### Tool conflicts
-
-If multiple MCP servers have tools with the same name, they will be prefixed with `serverAlias__toolName` format.
-
-## Reference
-
-- [Gemini CLI MCP Official Documentation](https://geminicli.com/docs/tools/mcp-server/)
-- [Gemini CLI Configuration Guide](https://geminicli.com/docs/get-started/configuration/)

package/docs/en/installation/roblox-explorer.md

@@ -1,68 +0,0 @@
-# WEPPY Roblox Explorer (VSCode · Antigravity Extension)
-
-> **Optional** — Explorer is not required. All core features work with just MCP and the plugin. Install it when you want to browse the project structure in your editor.
-
-Roblox Studio Explorer-like tree view for your editor. Browse synced instance trees, open scripts directly, and track sync status — all inside your editor.
-This is a companion extension for WEPPY, not a standalone Roblox integration.
-
-![WEPPY Roblox Explorer](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
-## Requirements
-
-- VSCode 1.85+ or Antigravity
-- [Roblox MCP](../../../README.md) installed with Sync enabled (Basic or Pro)
-- Sync has already generated `weppy-project-sync/place_*/.sync-meta.json` under your project root
-
-## Installation
-
-### VSCode
-
-Search for **WEPPY Roblox Explorer** in the VSCode Extensions sidebar (`Ctrl+Shift+X` / `Cmd+Shift+X`) and click **Install**.
-
-Or install directly from:
-
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer)
-- [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer)
-
-### Antigravity
-
-Antigravity is VSCode-based, so the same extension works. Search for **WEPPY Roblox Explorer** in the Antigravity Extensions tab and click **Install**.
-
----
-
-Core tree browsing works from synced files on disk. Live sync state, direction indicators, and Explorer telemetry forwarding are available when the local MCP server is reachable.
-
-## Features
-
-- **Instance tree**: Service/instance hierarchy matching Roblox Studio
-- **Roblox class icons**: Dark/light theme support with 200+ class icons
-- **Multi-place**: Separate tree roots per synced place
-- **Click-to-open**: Open backing files (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`)
-- **Instance search**: QuickPick search across all services
-- **Sync status badges**: See `modified`, `studio`, `conflict` states at a glance
-- **Auto-refresh**: Tree updates automatically when sync files change (500ms debounce)
-- **Copy instance path**: Right-click to copy `game.Workspace.Part` style paths
-
-## Settings
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `robloxExplorer.syncRoot` | `""` | Absolute path to the `weppy-project-sync` root. If empty, it is auto-discovered. WEPPY uses `{projectRoot}/weppy-project-sync`. |
-| `robloxExplorer.hidePropsFiles` | `false` | Hide sync artifact files (`.props.json`, `_tree.json`, `.value.json`) in the default VSCode explorer. |
-| `robloxExplorer.autoRefresh` | `true` | Auto-refresh tree when sync files change. |
-| `robloxExplorer.showSyncStatus` | `true` | Show sync status decorations on tree items. |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `WEPPY Explorer: Refresh` | Manually refresh the instance tree |
-| `WEPPY Explorer: Search Instances` | Search instances across all services |
-| `WEPPY Explorer: Open Backing File` | Open the file backing a 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 |
-
-## Related
-
-- [Sync Deep Dive](../sync/overview.md)
-- [Installation Guide](README.md)