内容
# overdare-studio-mcp
**Claude 通过 OVERDARE Studio 操作的 MCP 服务器。** Claude Desktop 或 Claude Code 中，
例如说“在 Workspace 中创建一个红色立方体”，实际的 Studio 世界中会创建、修改和删除部件和脚本。
> ⚠️ **这是一个非官方项目。** 与 OVERDARE 无关，也没有官方支持。 Studio 打开的本地端口
> 会被使用，因此 Studio 更新可能会改变其行为（使用 `npm run replay` 进行检测）。仅适用于本地单个用户。
---
## ⏱️ 5分钟快速入门
**0. 准备** — 运行 OVERDARE Studio 并打开一个世界。（需要 Node.js 20+）
**1. 构建**
```bash
git clone <此仓库> overdare-studio-mcp && cd overdare-studio-mcp
npm install
npm run build
```
**2. 连接到 Claude** （二选一）
Claude Code:
```bash
claude mcp add overdare-studio -- node /绝对路径/overdare-studio-mcp/dist/server/index.js
```
Claude Desktop — `claude_desktop_config.json`:
```json
{
"mcpServers": {
"overdare-studio": {
"command": "node",
"args": ["/绝对路径/overdare-studio-mcp/dist/server/index.js"],
"env": {
"OVERDARE_PROJECT_CWD": "/绝对路径/我的世界文件夹"
}
}
}
}
```
> `OVERDARE_PROJECT_CWD` 是 `.umap`/`.ovdrjm` 世界文件所在的目录。**写入工具需要**（读取不需要）。
**3. 调用第一个工具** — 对 Claude 说：
- *"显示 OVERDARE 世界结构"* → 使用 `studio_browse` 获取树。
- *"在 Workspace 中创建一个 2×2×2 的霓虹立方体 'Hello'"* → 使用 `studio_create_part` 实际创建。
就这样。创建、修改和删除会自动备份，如果失败，会回滚。
---
## 主要功能
- **CRUD** — 使用自然语言进行实例创建/查询/修改/删除 + 脚本添加。
- **安全写入** — 所有更改都经过 `备份 → 修改 → 验证 → 应用 → 保存` 管道，如果失败，则自动回滚。
- **资产导入** — 导入资产商店模型 + 本地图像（路径安全验证）。
- **发布保护** — 不可逆的发布受 4 重门控保护（防止错误发布）。
- **记录器 / 重放** — 记录所有 RPC，并检测 Studio 更新后的协议更改。
- **能力层** — 如果不支持的功能会在调用时以结构化错误报告。
---
## 支持的工具（13）
| 工具 | 功能 |
|---|---|
| `studio_browse` | 查询世界实例树（支持过滤/深度） |
| `studio_screenshot` | 视口截图 |
| `studio_create_part` | 创建部件（支持大小/框架/颜色/材质/锚点等） |
| `studio_update_part` | 修改实例名称/属性部分 |
| `studio_delete` | 删除实例（包括子实例，服务保护） |
| `studio_add_script` | 添加脚本/本地脚本/模块脚本 |
| `studio_import_model` | 导入资产商店模型 |
| `studio_import_image` | 导入本地图像（路径验证） |
| `studio_apply_action_sequence` | 在 ActionSequencer 上应用序列器 JSON |
| `studio_apply` / `studio_save` | 应用更改 / 保存世界 |
| `studio_publish` | 发布世界（默认为 dry-run，4 重门控） |
| `studio_capabilities` | 报告 Studio 功能支持情况 |
每个工具的输入模式/示例/返回值请参考 [docs/TOOLS.md](docs/TOOLS.md)。所有工具都返回相同的
`ToolResult`（success/operation/affected/warnings/data/error）作为 `structuredContent`。
---
## 安全措施
### 写入管道 + 自动回滚
所有 `.ovdrjm` 更改都必须经过以下顺序：
```
备份 → 修改 → 验证 → level.apply → level.save.file
```
如果任何步骤失败，则从备份中恢复并回滚到实时场景。如果同时进行外部修改，也会检测到并中止。
仅当 `--unsafe`（或 `OVERDARE_UNSAFE=1`）时才跳过备份（无法回滚）。
### 发布保护（不可逆操作）
`studio_publish` **默认为 dry-run（预览）**。实际发布必须满足以下所有条件：
```
能力支持 + OVERDARE_ALLOW_PUBLISH=1 + confirm:true + dryRun:false
```
如果任何条件未满足，则不会调用 RPC，并以结构化错误报告未满足的门控。
### 记录器 / 重放
使用 `OVERDARE_MCP_TRACE=1` 将跟踪信息输出到 stderr，并使用 `OVERDARE_MCP_TRACE_DIR=.trace` 保存
`rpc.jsonl`/`session.json`/`metadata.json`/`ovdrjm.diff`。
```bash
npm run replay .trace/session.json # 重放记录的会话以检测协议更改（漂移）
```
比较响应的形状（键/类型结构）以忽略数据更改并仅捕获协议更改。
（身份验证令牌等在跟踪中记录为 `<redacted>`。）
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OVERDARE_PROJECT_CWD` | 当前目录 | `.ovdrjm` 世界文件所在的目录（需要写入） |
| `STUDIO_HOST` / `STUDIO_PORT` | `127.0.0.1` / `13377` | Studio RPC 端点 |
| `OVERDARE_RPC_TIMEOUT_MS` | `30000` | RPC 超时 |
| `OVERDARE_MCP_TRACE` | — | `1` 时启用记录器（stderr） |
| `OVERDARE_MCP_TRACE_DIR` | — | 用于重放的文件保存目录 |
| `OVERDARE_ASSET_ROOTS` | — | 添加允许的图像导入路径（平台区分符） |
| `OVERDARE_ALLOW_PUBLISH` | — | `1` 时释放发布门控之一 |
| `OVERDARE_UNSAFE` | — | `1` 时跳过备份/回滚（不推荐） |
---
## 常见问题
**问：Studio 关闭时怎么办？** 读取/写入工具会以结构化错误报告连接错误。请启动 Studio 并打开世界后重试。
**问：写入工具报告“项目文件夹中没有 `.umap`”。** 必须将 `OVERDARE_PROJECT_CWD` 设置为实际的 `.umap`/`.ovdrjm` 世界文件所在的目录。
**问：我会意外损坏世界吗？** 所有写入操作都在备份后进行，如果失败，则会回滚。发布是不可逆的，但有 4 重门控保护。
**问：这是 OVERDARE 官方工具吗？** 不是。这是一个非官方的、仅限本地单个用户的工具。
**问：如果 Studio 更新后无法使用怎么办？** 可能是本地协议已更改。使用 `npm run replay` 检查更改点。
**问：我需要什么样的 Claude 客户端？** 需要支持 MCP 的 Claude Desktop 或 Claude Code。服务器通过 stdio 运行。
---
## 开发
```bash
npm run dev # 使用 tsx 运行服务器
npm test # 单元测试（vitest）
npm run typecheck # 类型检查
npm run ci # 类型检查 + 构建 + 测试 + 重放（dry）
npm run gen:docs # 重新生成 docs/TOOLS.md
```
有关更详细的结构和设计，请参考 [docs/Architecture.md](docs/Architecture.md)，贡献指南请参考
[CONTRIBUTING.md](CONTRIBUTING.md)，变更历史请参考 [CHANGELOG.md](CHANGELOG.md)。
## License
[MIT](LICENSE)
