<div align="center">
  <img src="extension/assets/icon-256.png" width="180" alt="ZenMCPRoblox icon">
  <h1>ZenMCPRoblox</h1>
  <p><strong>A secure local AI controller for Roblox Studio.</strong></p>
  <p>ChatGPT, DeepSeek, Gemini, Kimi, Z.ai/GLM, Qwen, Arena, or Meta AI → authenticated local bridge → MCP controller → Roblox Studio</p>
</div>

> [!IMPORTANT]
> ZenMCPRoblox is an independent community project. It is not affiliated with,
> endorsed by, or an official product of Roblox Corporation, OpenAI, Google,
> DeepSeek, Moonshot AI, Alibaba, Meta, LMSYS/Arena, Z.ai, Chrrxs, or ZeroScript.

## What it does

ZenMCPRoblox connects supported AI chat websites to Roblox Studio without giving
web pages unrestricted access to your computer. It combines a Chromium extension,
an authenticated localhost bridge, a security-gated controller, and the current
[`@chrrxs/robloxstudio-mcp`](https://github.com/Chrrxs/robloxstudio-mcp) backend.

The controller can dynamically discover the backend's current tools, inspect and
edit places, route calls to multiple Studio instances, run playtests and debugging
workflows, keep change history, invoke Studio undo, and retrieve official Roblox
documentation for the AI.

Two frontend modes use the same browser-independent controller:

- **Browser mode:** AI website → ZenMCP extension → local bridge → controller.
- **Native MCP mode:** compatible MCP client → ZenMCP stdio server → controller.

## Highlights

- Strict structured action protocol; ordinary AI prose is never executed.
- Localhost-only WebSocket bridge with token authentication.
- Safe Mode blocks writes; Edit Mode must be enabled explicitly.
- Dynamic discovery of upstream MCP commands and schemas.
- Multi-Studio discovery and `instance_id` routing.
- Change history and rollback through Roblox Studio undo.
- Debug, playtest, runtime-log, and asset-security workflows.
- Official Roblox API retrieval through upstream `get_roblox_docs`.
- Generated models are moved from mandatory upstream staging into `Workspace`.
- Automatic plugin installation/update where supported upstream.
- Reconnecting Manifest V3 extension with heartbeats and background recovery.
- Custom draggable and collapsible panel on supported AI websites.
- Native stdio MCP adapter for future browser-independent integrations.

## Architecture

```text
Browser mode

AI chat website
      │ strict <zenmcp-action> JSON
      ▼
ZenMCPRoblox Chromium extension
      │ authenticated WebSocket on localhost
      ▼
ZenMCP local bridge
      │ validated requests, permissions, history
      ▼
ZenMCP controller
      │ MCP over stdio
      ▼
@chrrxs/robloxstudio-mcp
      │ upstream Studio plugin transport
      ▼
Roblox Studio


Native mode

MCP client ──stdio──▶ ZenMCP controller ──MCP──▶ Roblox Studio backend
```

Results travel back through the same stack. The controller does not depend on an
AI website's DOM; provider-specific browser code is isolated in the extension.

## Supported browser providers

| Provider | Website | Adapter status |
| --- | --- | --- |
| ChatGPT | `chatgpt.com` | Supported |
| DeepSeek | `chat.deepseek.com` | Supported |
| Gemini | `gemini.google.com` | Supported |
| Kimi | `kimi.com` | Supported |
| Z.ai / GLM | `chat.z.ai` | Supported |
| Qwen | `chat.qwen.ai` | Supported |
| Arena | `arena.ai` | Supported; use a single/direct chat mode |
| Meta AI | `meta.ai` | Supported |

AI websites can change their interfaces without notice. A site update may require
its selector profile to be updated even though the controller and Roblox
integration remain unaffected.

## Requirements

- Node.js 20 or newer.
- npm and npx.
- Roblox Studio.
- Chrome, Chromium, or a compatible Manifest V3 browser.
- A Roblox place open in Studio.
- **Allow HTTP Requests** enabled in Studio under Game Settings → Security.

## Installation

From the directory containing this project:

```powershell
cd ZenMCPRoblox
npm install
npm run setup
```

Setup performs the following operations:

1. Checks Node.js, npm, and npx.
2. Installs or updates `@chrrxs/robloxstudio-mcp@latest`.
3. Generates `.zenmcp/config.json` with a random local bridge token.
4. Builds the TypeScript controller and browser extension.
5. Installs or updates the matching upstream Roblox Studio plugin.
6. Runs connection diagnostics.

Fully close and reopen Roblox Studio after the plugin is first installed or
updated.

### Load the browser extension

1. Open `chrome://extensions`.
2. Enable **Developer mode**.
3. Select **Load unpacked**.
4. Select `ZenMCPRoblox/dist/extension/`.
5. Pin ZenMCPRoblox to the browser toolbar if desired.

The generated `dist/extension/config.json` contains your local bridge token. It is
ignored by Git and must not be published or shared.

## Everyday use

Start everything ZenMCPRoblox controls with one command:

```powershell
npm run start
```

Keep that terminal open. Then:

1. Open a place in Roblox Studio and wait for the MCP plugin to connect.
2. Open a supported AI website and refresh the tab after extension updates.
3. Open the ZenMCP popup and verify the bridge, backend, and Studio statuses.
4. Leave **Safe Mode** enabled for inspection, or enable **Edit Mode** for writes.
5. Click **Start session** in the floating ZenMCP panel.
6. Ask the AI to inspect, debug, test, or modify the open place.

Drag the floating panel by its header. Its position is remembered independently
for each provider. Chrome's toolbar popup itself is browser-anchored and cannot be
moved by an extension.

## Commands

| Command | Purpose |
| --- | --- |
| `npm run setup` | Update dependencies/backend, install the plugin, build, diagnose |
| `npm run start` | Start the upstream backend, controller, and localhost bridge |
| `npm run doctor` | Check Node, configuration, build, plugin, bridge, and Studio |
| `npm run build` | Compile TypeScript and build `dist/extension/` |
| `npm test` | Run unit and local integration tests |
| `npm run test:live` | Run the opt-in real Studio read/edit/rollback test |
| `npm run mcp` | Expose ZenMCP as a native stdio MCP server |
| `npm run safe` | Persist Safe Mode for the next process start |
| `npm run edit` | Persist Edit Mode for the next process start |

The same CLI is available after installation through commands such as:

```powershell
npm exec zenmcp -- doctor
npm exec zenmcp -- start
npm exec zenmcp -- mcp
```

## Safe Mode and Edit Mode

**Safe Mode** is the default. Known reads such as hierarchy inspection,
documentation retrieval, searches, and status checks are allowed. Write,
destructive, playtest, import, upload, and unfamiliar newly discovered commands
are blocked.

**Edit Mode** allows controller-classified writes. It does not enable arbitrary OS
commands or JavaScript evaluation in the browser. Unknown future upstream commands
fail closed as writes until ZenMCP can classify them safely.

## Browser protocol

The extension accepts only an exact block like this from the current AI session:

```xml
<zenmcp-action>
{"v":1,"id":"session-nonce:1","method":"tools/call","params":{"name":"get_place_info","arguments":{}}}
</zenmcp-action>
```

Security checks include:

- A random per-session action ID prefix.
- Exact protocol version and method allowlist.
- Schema validation and rejection of extra fields.
- No `eval`, arbitrary JavaScript, shell, or unrestricted file command.
- Authenticated local bridge requests with request IDs and timeouts.
- Rate limiting, payload limits, heartbeat checks, and structured errors.
- Asset URL/path validation.
- Controller-side Safe/Edit enforcement regardless of what the page requests.

## Roblox documentation

The upstream backend exposes `get_roblox_docs` and `get_roblox_skills` tools.
ZenMCP instructs the AI to consult these before assuming uncertain Roblox classes,
members, services, or Luau behavior. The popup and floating panel also link to the
[official Roblox Engine API reference](https://create.roblox.com/docs/reference/engine).

## Upstream updates

ZenMCP discovers the installed backend's tool catalogue every time it starts. The
browser fetches the current catalogue each time **Start session** is pressed.

To install a newly published Chrrxs backend and matching plugin:

```powershell
# Stop npm run start first
npm run setup
# Fully restart Roblox Studio if the plugin changed
npm run start
```

Ordinary added, removed, or schema-updated upstream tools require no extension
change. A breaking MCP protocol change or rename of a command used by a ZenMCP
composite may require a ZenMCP compatibility update.

## Generated model placement

The upstream `generate_model` operation intentionally stages generated models
under `game.ServerStorage.__MCPGeneratedModels`. ZenMCP preserves that required
generation step, then reparents a successful result into `game.Workspace` and
returns its final Workspace path.

## Multi-Studio routing

Multiple connected places are discovered through the upstream backend. When more
than one place is open, use `get_connected_instances` and supply the intended
`instance_id`. ZenMCP forwards that identifier through normal and composite tools.

## History and rollback

Write attempts are recorded as JSON Lines under `.agent-history/`. This directory
is local and ignored by Git. `zen_rollback` calls the upstream `undo` tool, which
uses Roblox Studio's change history. Rollback means undoing the most recent Studio
change, not replaying an arbitrary historical snapshot.

## Troubleshooting

### `ERR_CONNECTION_REFUSED` on port 39393

Nothing is listening on the configured bridge port. Run and keep open:

```powershell
npm run start
```

Then open `http://127.0.0.1:39393/health`. A running bridge returns JSON.

### Bridge connected, Studio offline

- Open Roblox Studio and load a place.
- Enable **Allow HTTP Requests**.
- Confirm the installed MCP plugin reports Connected.
- Fully restart Studio after plugin updates.
- Run `npm run doctor` for an actionable diagnosis.

### Extension changed but the page looks old

1. Open `chrome://extensions`.
2. Click **Reload** on ZenMCPRoblox.
3. Refresh every supported AI tab.

### Edit Mode does not enable

Edit Mode is stored in the running controller. Verify **Local Bridge** and
**Roblox MCP** are connected, then try the toggle again. The popup displays the
bridge's structured error if the mode request fails.

### AI site cannot find its composer or Send control

Reload the extension and refresh the page first. Provider adapters rely on each
website's current interface. If a site has changed, update its selectors in
`extension/src/content/provider-profiles.js` and rebuild.

## Testing

```powershell
npm test
```

The default suite covers the strict extension parser, authenticated WebSocket
flow, dynamic tool discovery, Safe/Edit permissions, provider configuration,
service-worker recovery, Workspace model placement, native MCP exposure, edit and
rollback flow, asset validation, and extension assets.

The real Studio test is opt-in because it creates a disposable object and invokes
real Studio undo:

```powershell
npm run test:live
```

It fails rather than pretending Studio is connected when the external plugin is
unavailable.

## Project layout

```text
ZenMCPRoblox/
├── extension/            Chromium extension source and icon assets
├── src/
│   ├── assets/           Asset request security
│   ├── bridge/           Authenticated localhost WebSocket bridge
│   ├── cli/              setup, start, doctor, mode, and native MCP commands
│   ├── config/           Local configuration model
│   ├── context/          Result summarization
│   ├── history/          Change history
│   ├── instances/        Multi-Studio discovery/routing
│   ├── orchestration/    Composite agent tools
│   ├── permissions/      Safe/Edit risk enforcement
│   ├── server/           Controller and application composition
│   ├── tools/            Dynamic capability registry
│   ├── types/            Shared TypeScript interfaces
│   └── upstream/         Chrrxs MCP client integration
├── tests/
│   ├── integration/
│   └── unit/
├── scripts/              Build helpers
├── .env.example
├── .gitignore
├── package.json
└── tsconfig.json
```

## Credits and acknowledgements

### Chrrxs / Roblox Studio MCP

Core Roblox Studio communication is provided by
[`@chrrxs/robloxstudio-mcp`](https://github.com/Chrrxs/robloxstudio-mcp), created
and maintained by **[Chrrxs](https://github.com/Chrrxs)** (referred to as Chris in
this project's development discussions). It supplies the MCP server, Studio
plugin, edit/runtime/playtest tools, multi-instance support, official Roblox docs
retrieval, and plugin installation workflow that ZenMCPRoblox controls and
security-gates. The upstream project is MIT licensed.

ZenMCPRoblox depends on the published npm package and does not claim authorship of
the Chrrxs backend or Studio plugin.

### ZeroScript-Free

The concept of isolating website-specific AI adapters behind a provider-neutral
browser agent loop was inspired by
[`ZeroScript-Free`](https://github.com/sebattfg/ZeroScript-Free), created and
maintained by **[sebattfg](https://github.com/sebattfg)**. ZeroScript demonstrated
practical browser support for DeepSeek, Gemini, Kimi, GLM, Qwen, Arena, and Meta
AI communicating with Roblox Studio through a local bridge.

ZeroScript-Free is GPL-3.0 licensed. ZenMCPRoblox's implementation is independent:
the ZeroScript repository is used only as an excluded local reference during
compatibility research, and its source is not copied or redistributed in this
project.

### Roblox documentation

Roblox API guidance is sourced from the
[Roblox Creator documentation](https://create.roblox.com/docs) and its
[Engine API reference](https://create.roblox.com/docs/reference/engine).

Thank you to these maintainers and communities for making this project possible.

## License and third-party notices

Original ZenMCPRoblox materials are distributed under the proprietary
[ZenMCPRoblox Reference-Only License](LICENSE). You may link to, cite, discuss,
review, and learn from the project's ideas, but you may not copy, modify,
redistribute, republish, create derivative works from, or incorporate its code,
assets, documentation, or other copyrightable expression without separate prior
written permission. This is not an open-source license.

Selling ZenMCPRoblox is prohibited. This includes paid downloads, subscriptions,
paywalled access, marketplace listings, monetized hosting, paid bundles,
rebranded copies, commercial derivatives, and donations tied to receiving or
using the software. Only a separate written agreement from the copyright holder
can authorize commercial use.

Copyright protects source-code expression rather than underlying ideas, methods,
or systems. Clean, independently written implementations of general ideas are
permitted by the license as long as they do not copy ZenMCPRoblox's protected
expression.

- `@chrrxs/robloxstudio-mcp`: MIT License; see its upstream repository/package.
- ZeroScript-Free: GPL-3.0; credited as architectural inspiration only.
- Roblox and Roblox Studio are trademarks of Roblox Corporation.
- Other product and company names belong to their respective owners.

Review dependency licenses before redistributing binaries or making this
repository public.