@weppy/roblox-mcp 1.3.0 → 1.4.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Roblox MCP server and tools for AI-powered game development",
-    "version": "1.3.0"
+    "version": "1.4.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.3.0",
+      "version": "1.4.0",
       "author": {
         "name": "hope1026"
       },

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug Report
+description: Something isn't working correctly
+labels: ["bug"]
+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).
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "macOS 14 / Windows 11"
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version
+      placeholder: "node --version output"
+    validations:
+      required: true
+  - type: input
+    id: ai-client
+    attributes:
+      label: AI client
+      placeholder: "Claude Code 1.x / Cursor 0.4x / Codex CLI"
+    validations:
+      required: true
+  - type: input
+    id: plugin-version
+    attributes:
+      label: Plugin / MCP server version
+      placeholder: "v1.3.1"
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs (if any)
+      render: shell

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      placeholder: "e.g. I can't easily do X with the current tools"
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: tier
+    attributes:
+      label: Which tier would this apply to?
+      options:
+        - Basic
+        - Pro
+        - Both
+        - Not sure
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context

package/.github/ISSUE_TEMPLATE/install_help.yml

@@ -0,0 +1,48 @@
+name: Install Help
+description: Having trouble installing or connecting
+labels: ["question", "installation"]
+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.
+  - type: dropdown
+    id: ai-client
+    attributes:
+      label: AI client
+      options:
+        - Claude Code
+        - Claude Desktop
+        - Cursor
+        - Codex CLI
+        - Gemini CLI
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "macOS 14 / Windows 11"
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version
+      placeholder: "node --version output"
+    validations:
+      required: true
+  - type: textarea
+    id: issue
+    attributes:
+      label: What's happening?
+      placeholder: "Describe the problem and any error messages"
+    validations:
+      required: true
+  - type: textarea
+    id: tried
+    attributes:
+      label: What have you tried?

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Type of change
+
+- [ ] Documentation improvement
+- [ ] Example prompt or cookbook addition
+- [ ] Bug fix
+- [ ] Other
+
+## Checklist
+
+- [ ] I've read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] Changes are limited to docs or examples (plugin source is not in this repo)
+- [ ] Links and paths are correct

package/.github/workflows/deploy-docs.yml

@@ -0,0 +1,41 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'README.md'
+      - 'llms.txt'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+
+## [1.4.0] - 2026-03-08
+
+### New Features
+
+- Add Roblox Explorer VSCode extension — browse Studio instance tree directly in VSCode sidebar
+  - TreeDataProvider for real-time instance hierarchy visualization
+  - Auto-refresh via FileWatcher on sync data changes
+  - Icon mapping for Roblox class names (dark/light theme support)
+  - Copy instance path, open backing file, reveal in explorer commands
+
+### Improvements
+
+- Refactor MCP server deployment pipeline and build configuration
+- Improve camera and terrain sync stability and accuracy
+- Enhance plugin UI icons and visual consistency
+
+
+## [1.3.1] - 2026-03-07
+
+### Improvements
+
+- Improve sync robustness during rapid consecutive file changes
+- Enhance incremental change processor to reduce false-positive conflict detection
+- Strengthen sync index integrity checks on startup and reconnect
+- Improve LRU cache eviction to prevent stale place data after session switch
+
+### Bug Fixes
+
+- Fix sync stall when file watcher emits duplicate events for the same path
+- Fix reverse sync occasionally skipping files with identical hashes but different timestamps
+- Fix collision suffix (`~N`) not reindexing correctly after instance rename
+- Fix sync-init phase hanging when workspace contains deeply nested empty containers
+
+### Documentation
+
+- Restructure README for faster install path (Quick Install and compatibility table at top)
+- Add troubleshooting guide
+- Add compatibility matrix (supported clients, system requirements, Basic vs Pro)
+- Add `llms.txt` for AI crawler discovery
+- Add community health files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT
+- Add GitHub issue templates (bug report, feature request, install help)
+
+
 ## [1.3.0] - 2026-03-06
 
 ### Breaking Changes

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- Harassment, trolling, or personal attacks
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+## 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.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to Roblox MCP
+
+## Bug Reports
+
+Use the [Bug Report issue template](https://github.com/hope1026/roblox-mcp/issues/new?template=bug_report.yml).
+
+Include:
+- OS and Node.js version (`node --version`)
+- Roblox Studio version
+- AI client and version
+- Steps to reproduce
+- Expected vs actual behavior
+- Error logs if available
+
+## Feature Requests
+
+Use the [Feature Request template](https://github.com/hope1026/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.
+
+## Pull Requests
+
+This repository distributes the MCP server and plugin. The plugin source is not included here.
+
+PRs for **documentation improvements** and **example prompts** are welcome:
+
+1. Fork the repository
+2. Create a branch: `git checkout -b docs/your-improvement`
+3. Make your changes
+4. Open a Pull Request with a clear description
+
+## Code of Conduct
+
+Please read and follow the [Code of Conduct](CODE_OF_CONDUCT.md).

package/README.md

@@ -1,27 +1,65 @@
 # Roblox MCP
 
-**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)
+> The MCP server that connects AI coding agents to Roblox Studio — control scripts, terrain, assets, lighting, audio, and animations via natural language.
 
-> Tell AI what you want, and it happens in Roblox Studio.
+**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)
 
-## Core Capabilities
+## The Problem
+
+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.
+
+This is not just code generation. It is **executable, production-oriented actions** running directly in Studio.
+
+## Quick Install (5 minutes)
+
+**Step 1** — Install the Roblox Studio plugin (bridge between Studio and AI):
+[Plugin Installation Guide](docs/en/installation/roblox-plugin.md)
+
+**Step 2** — Register the MCP server with your AI app:
+
+```bash
+npx -y @weppy/roblox-mcp
+```
+
+| AI App | Guide |
+|--------|-------|
+| Claude Code | [Setup](docs/en/installation/ai-apps/claude-code.md) |
+| Claude Desktop | [Setup](docs/en/installation/ai-apps/claude-app.md) |
+| Codex CLI | [Setup](docs/en/installation/ai-apps/codex-cli.md) |
+| Codex Desktop | [Setup](docs/en/installation/ai-apps/codex-app.md) |
+| Gemini CLI | [Setup](docs/en/installation/ai-apps/gemini-cli.md) |
+| Antigravity | [Setup](docs/en/installation/ai-apps/antigravity.md) |
+
+> Any MCP-compatible AI client works. The server command is `npx -y @weppy/roblox-mcp`.
+
+## Compatibility
+
+| Claude Code | Claude Desktop | Cursor | Codex CLI | Gemini CLI | Antigravity |
+|:-----------:|:--------------:|:------:|:---------:|:----------:|:-----------:|
+| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+**Requirements:** Node.js 18+, Roblox Studio, Windows 10+ or macOS 12+
+
+## What It Does
 
 ### 1) MCP Tools: Direct execution in Studio from natural language
 
-The first pillar of Roblox MCP is **MCP tool execution**.
 AI can directly handle scripts, instances, properties, terrain, lighting, assets, audio, and animation inside Studio.
 
 - "Add particles + sound + cooldown when the player jumps."
 - "Build a boss arena at map center and place collision-safe spawn points."
 - "Change this module interface and update every dependent script."
-
-This is not just code generation. It is **executable, production-oriented actions**.
+- "Generate terrain with mountains and rivers, then place spawn points on flat areas."
+- "Search the Creator Store for a sword model and insert it into StarterPack."
 
 ### 2) Sync: Keep full project context stable for AI
 
-The second pillar is **Project Sync**.
 AI works from a synchronized local mirror, so multi-file updates stay consistent.
 
 ![Sync workflow — Studio and local files synchronized in real time](docs/assets/screenshots/sync.png)
@@ -29,36 +67,65 @@ AI works from a synchronized local mirror, so multi-file updates stay consistent
 - Basic: one-way sync (Studio -> Local)
 - Pro: bidirectional sync + per-type Direction/Apply Mode + history + multi-place
 
-You keep source-of-truth clear and avoid losing change context.
+### 3) 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.
+
+![Roblox Explorer — Studio instance tree displayed in VSCode sidebar](docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
 
-## Immediate Value
+- Class icons matching Studio for instant recognition
+- Click to open synced scripts and property files
+- Multi-place support with sync status indicators
+
+## Use Cases
+
+- **Rapid prototyping**: Describe a game mechanic in natural language and watch AI build it in Studio
+- **Bulk refactoring**: Rename a module interface and update every dependent script in one request
+- **Terrain & environment**: Generate procedural terrain, set lighting/atmosphere, place assets — all from a single prompt
+- **Multi-file consistency**: AI reads the full project via Sync and applies changes across related scripts together
+- **Asset integration**: Search the Creator Store, insert models, and configure properties without leaving your editor
+
+## Why It Matters
 
 - Compress repetitive work: turn many manual edits into one request
 - Change related files together: not just one target file
 - Lower risk: rely on sync state and history before applying changes
 - Better token efficiency (Pro): reduce round trips with bulk actions
 
-## Detailed Docs
+## Docs
 
-- [Tools Overview](docs/en/tools/overview.md)
+- [Installation Guide](docs/en/installation/README.md)
+- [Tools Reference](docs/en/tools/overview.md)
 - [Sync Deep Dive](docs/en/sync/overview.md)
+- [Roblox Explorer (VSCode Extension)](docs/en/installation/roblox-explorer.md)
+- [Compatibility](docs/compatibility.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
-## Getting Started
+## FAQ
 
-Installation is complete in two steps:
+**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.
 
-1. **Install Roblox Studio Plugin** — Acts as a bridge between Studio and AI
-2. **Register MCP Server with AI App** — Configure your AI app to recognize Roblox MCP
+**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.
 
-Takes just 5 minutes. 👉 [View Installation Guide](docs/en/installation/README.md)
+**Does it work with Cursor / Codex / Gemini?**
+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).
+
+**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
 
 Bidirectional Sync, advanced build capabilities, and AI token efficiency — all in one upgrade.
 
-👉 [Pro Upgrade Guide](docs/en/pro-upgrade.md)
+[Pro Upgrade Guide](docs/en/pro-upgrade.md)
+
+---
 
-## Links
+[![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)
 
-- [GitHub](https://github.com/hope1026/roblox-mcp)
-- [Issue Reports](https://github.com/hope1026/roblox-mcp/issues)
+[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)

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x (latest) | ✅ |
+| < 1.0 | ❌ |
+
+## Reporting a Vulnerability
+
+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).
+
+We will respond within 72 hours and aim to release a fix within 14 days for confirmed vulnerabilities.
+
+## Scope
+
+- MCP server HTTP bridge (localhost:3002)
+- Plugin authentication and session token handling
+- License server communication
+
+## Out of Scope
+
+- Roblox Studio itself
+- Third-party AI client security
+- Issues requiring physical access to the machine

package/SUPPORT.md

@@ -0,0 +1,27 @@
+# Support
+
+## Documentation
+
+- [Installation Guide](docs/en/installation/README.md)
+- [Tools Reference](docs/en/tools/overview.md)
+- [Sync Deep Dive](docs/en/sync/overview.md)
+- [Roblox Explorer (VSCode Extension)](docs/en/installation/roblox-explorer.md)
+- [Compatibility](docs/en/compatibility.md)
+- [Troubleshooting](docs/en/troubleshooting.md)
+
+## Community Help
+
+For questions and install issues, use [GitHub Discussions](https://github.com/hope1026/roblox-mcp/discussions).
+
+Please include:
+- Your OS and Node.js version
+- AI client you're using
+- What you've already tried
+
+## Bug Reports
+
+For confirmed bugs, open an [Issue](https://github.com/hope1026/roblox-mcp/issues/new?template=bug_report.yml).
+
+## Pro Users
+
+Pro users can reach out via the contact information provided in your Gumroad receipt.

package/docs/assets/screenshots/roblox-explorer/install-from-vsix.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b3d3d23843bb9049cb64e84bac8043e29747848661674fcb2270c86a12a77ac8
+size 85677

package/docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8db99920628c97321f10cc4b8a2144de542fcb309bc5fd2a53218e12258a1653
+size 111692

package/docs/assets/screenshots/sync.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:5888be201ba145eef507686b9fb2495c8aeb281d7dfc7b48260fd9d53242e938
-size 856271
+oid sha256:b7ce0e0e4eeb4ca467e4d8b9208c0d9ac9db62f307285b41418856fa3f3729d0
+size 804532

package/docs/compatibility.md

@@ -0,0 +1,44 @@
+# 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 | ✅ | ✅ | MCP config: `npx -y @weppy/roblox-mcp` |
+| 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/installation/README.md

@@ -39,6 +39,14 @@ Register the MCP server with your AI app. You can use it with any AI app that su
 
 ---
 
+## Optional: Install Roblox Explorer (VSCode Extension)
+
+Browse synced instance trees inside VSCode with Roblox class icons.
+
+👉 [Roblox Explorer Installation Guide](roblox-explorer.md)
+
+---
+
 ## After Installation
 
 1. Open **Roblox Studio**, go to Plugins tab and click **W-MCP** → **Connect**