Content
# overdare-studio-mcp
**This is an MCP server for controlling OVERDARE Studio with Claude.**
You can say things like "Create a red cube in the workspace" to Claude Desktop or Claude Code,
and it will actually create, modify, or delete parts and scripts in the Studio world.
> ⚠️ **This is an unofficial project.** It is not affiliated with OVERDARE and does not have official support.
> Since it uses the local port opened by Studio,
> its behavior may change with Studio updates (detectable with `npm run replay`).
> It is intended for local single-user use.
## ⏱️ 5-Minute Quick Start
**0. Preparation** — Run OVERDARE Studio and open a world. (Node.js 20+ required)
**1. Build**
```bash
git clone <this-repo> overdare-studio-mcp && cd overdare-studio-mcp
npm install
npm run build
```
**2. Connect to Claude** (either one)
Claude Code:
```bash
claude mcp add overdare-studio -- node /absolute/path/to/overdare-studio-mcp/dist/server/index.js
```
Claude Desktop — `claude_desktop_config.json`:
```json
{
"mcpServers": {
"overdare-studio": {
"command": "node",
"args": ["/absolute/path/to/overdare-studio-mcp/dist/server/index.js"],
"env": {
"OVERDARE_PROJECT_CWD": "/absolute/path/to/your-world-folder"
}
}
}
}
```
> `OVERDARE_PROJECT_CWD` is the folder containing the `.umap`/`.ovdrjm` world file.
> **Required for writing tools** (not necessary for reading).
**3. First Tool Invocation** — Try saying to Claude:
- *"Show me the OVERDARE world structure"* → Get the tree with `studio_browse`.
- *"Create a 2×2×2 neon cube 'Hello' in the workspace"* → Actually create it with `studio_create_part`.
That's it. Creation, modification, and deletion are automatically backed up and rolled back if they fail.
## Key Features
- **CRUD** — Create, read, update, and delete instances + add scripts naturally.
- **Safe Writing** — All changes go through a `backup → modify → verify → apply → save` pipeline,
and automatically roll back if they fail.
- **Asset Import** — Import Asset Store models + local images (with path security verification).
- **Publish Guard** — Irreversible publishing is protected by a 4-layer gate (to prevent accidental release).
- **Recorder / Replay** — Record all RPCs and detect protocol changes after Studio updates.
- **Capability Layer** — Unsupported features are reported as structural errors when called.
## Supported Tools (13)
| Tool | Description |
|---|---|
| `studio_browse` | Browse world instance tree (with filter and depth support) |
| `studio_screenshot` | Take a viewport screenshot |
| `studio_create_part` | Create a part (with Size, CFrame, Color, Material, Anchored, etc.) |
| `studio_update_part` | Partially modify instance name and properties |
| `studio_delete` | Delete an instance (including children, with service protection) |
| `studio_add_script` | Add a Script, LocalScript, or ModuleScript |
| `studio_import_model` | Import an Asset Store model |
| `studio_import_image` | Import a local image (with path verification) |
| `studio_apply_action_sequence` | Apply an action sequence JSON to ActionSequencer |
| `studio_apply` / `studio_save` | Apply changes / save the world |
| `studio_publish` | Publish the world (default dry-run, with 4-layer gate) |
| `studio_capabilities` | Report Studio feature support |
See [docs/TOOLS.md](docs/TOOLS.md) for tool-specific input schema, examples, and return values.
All tools return a `ToolResult` (success, operation, affected, warnings, data, error) as `structuredContent`.
## Safety Features
### Write Pipeline + Auto-Rollback
All `.ovdrjm` changes are forced to go through:
```
backup → modify → verify → level.apply → level.save.file
```
If any step fails, it restores from the backup and reverts the live scene.
Concurrent external modifications are also detected and interrupted.
Skip backup (and rollback) only when `--unsafe` (or `OVERDARE_UNSAFE=1`) is specified.
### Publish Guard (Irreversible Operation)
`studio_publish` defaults to **dry-run (preview)**.
Actual publishing requires all four conditions to be met:
```
capability supported + OVERDARE_ALLOW_PUBLISH=1 + confirm:true + dryRun:false
```
If any condition is not met, the RPC is not called, and the unmet gate is structurally reported.
### Recorder / Replay
Set `OVERDARE_MCP_TRACE=1` to output traces to stderr,
and `OVERDARE_MCP_TRACE_DIR=.trace` to save `rpc.jsonl`, `session.json`, `metadata.json`, and `ovdrjm.diff`.
```bash
npm run replay .trace/session.json # Replay a recorded session to detect protocol changes (drift)
```
Compare response shapes (key and type structure) to ignore data changes and detect only protocol changes.
(Authentication tokens are recorded as `<redacted>` in the trace.)
## Environment Variables
| Variable | Default Value | Description |
|---|---|---|
| `OVERDARE_PROJECT_CWD` | Current folder | Folder containing the `.ovdrjm` world file (required for writing) |
| `STUDIO_HOST` / `STUDIO_PORT` | `127.0.0.1` / `13377` | Studio RPC endpoint |
| `OVERDARE_RPC_TIMEOUT_MS` | `30000` | RPC timeout |
| `OVERDARE_MCP_TRACE` | — | Enable Recorder (stderr) when `1` |
| `OVERDARE_MCP_TRACE_DIR` | — | Folder to save replay files |
| `OVERDARE_ASSET_ROOTS` | — | Additional paths to allow image import (with platform separator) |
| `OVERDARE_ALLOW_PUBLISH` | — | Allow publishing when `1` |
| `OVERDARE_UNSAFE` | — | Skip backup and rollback when `1` (not recommended) |
## FAQ
**Q. What happens if Studio is closed?**
Read and write tools will structurally return a connection error.
Please restart Studio, open the world, and try again.
**Q. The write tool says there is no `.umap` in the project folder.**
You must set `OVERDARE_PROJECT_CWD` to the folder containing the actual world file (`.umap`/`.ovdrjm`).
**Q. Will I accidentally break the world?**
All writes are backed up and rolled back if they fail.
Publishing is irreversible but protected by a 4-layer gate.
**Q. Is this an official OVERDARE tool?**
No, it is an unofficial, local, single-user tool.
**Q. What if it doesn't work after a Studio update?**
The local protocol may have changed.
Use `npm run replay` to detect the change.
**Q. Which Claude client do I need?**
You need Claude Desktop or Claude Code that supports MCP.
The server works with stdio.
## Development
```bash
npm run dev # Run the server with tsx
npm test # Unit tests (vitest)
npm run typecheck # Type checking
npm run ci # Type checking + build + test + replay (dry)
npm run gen:docs # Regenerate docs/TOOLS.md
```
See [docs/Architecture.md](docs/Architecture.md) for more structure and design,
[CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines,
and [CHANGELOG.md](CHANGELOG.md) for change history.
## License
[MIT](LICENSE)
