Content
# overdare-studio-mcp
**An MCP server for controlling OVERDARE Studio with Claude.** Claude Desktop or Claude Code can be used to interact with the studio world by voice commands, such as "Create a red cube in the workspace."
> ⚠️ **This is an unofficial project.** It is not affiliated with OVERDARE and does not have official support. The studio may change its behavior with updates, which can be detected by `npm run replay`. This tool is for local single-user use.
---
## ⏱️ Quick Start in 5 Minutes
**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** (choose 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 files. **Required for write operations** (not needed for read-only operations).
**3. First Tool Invocation** — Try saying to Claude:
- *"Show me the OVERDARE world structure"* → Use `studio_browse` to retrieve the tree.
- *"Create a 2×2×2 neon cube named 'Hello' in the workspace"* → Use `studio_create_part` to create it.
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 and add scripts using natural language.
- **Safe Writing** — All changes go through a pipeline of backup → modification → verification → application → saving, and failings are automatically rolled back.
- **Asset Import** — Import asset store models and local images (with path security verification).
- **Publish Guard** — Irreversible publishing is protected by a 4-layer gate (to prevent accidental launches).
- **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` | Update instance name and properties |
| `studio_delete` | Delete an instance (with children, and service protection) |
| `studio_add_script` | Add a script, local script, or module script |
| `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 sequencer JSON |
| `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 capability support |
See [docs/TOOLS.md](docs/TOOLS.md) for tool input schema, examples, and returns. All tools return a `ToolResult` (success, operation, affected, warnings, data, error) as `structuredContent`.
---
## Safety Features
### Write Pipeline + Auto-Rollback
All `.ovdrjm` changes are forced through the following sequence:
```
backup → modification → verification → level.apply → level.save.file
```
If any step fails, it is restored from the backup and the live scene is rolled back. Concurrent external modifications are also detected and aborted.
Skip backup (and rollback) only when `--unsafe` (or `OVERDARE_UNSAFE=1`) is specified.
### Publish Guard (Irreversible Operation)
`studio_publish` **defaults to dry-run**. Actual launch requires all 4 conditions to be met:
```
capability support + 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`/`ovdrjm.diff`.
```bash
npm run replay .trace/session.json # Replay a recorded session to detect protocol changes
```
Compare response shapes (key/type structure) to ignore data changes and detect only protocol changes.
(Authentication tokens are recorded as `<redacted>` in traces.)
---
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `OVERDARE_PROJECT_CWD` | Current folder | Folder containing `.ovdrjm` world files (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 image import path roots (with platform separators) |
| `OVERDARE_ALLOW_PUBLISH` | — | Allow publish gate when `1` |
| `OVERDARE_UNSAFE` | — | Skip backup and rollback when `1` (not recommended) |
---
## Frequently Asked Questions
**Q. What happens if Studio is closed?** Read/write tools return a structural connection error. Try again after opening Studio and the world.
**Q. Why does the write tool say there is no `.umap` in the project folder?** Specify `OVERDARE_PROJECT_CWD` as the folder containing the actual world files (`.umap`/`.ovdrjm`).
**Q. Will I accidentally break my world?** All writes are backed up and rolled back if they fail. Publishing is irreversible and 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 changes.
**Q. What Claude client do I need?** MCP-enabled Claude Desktop or Claude Code is required. The server works with stdio.
---
## Development
```bash
npm run dev # Run 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 detailed architecture and design, [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, and [CHANGELOG.md](CHANGELOG.md) for change history.
## License
[MIT](LICENSE)
