内容
# overdare-studio-mcp
**Claude 通过 OVERDARE Studio 进行操作的 MCP 服务器。** Claude Desktop 或 Claude Code 中，
例如说“在工作空间中创建一个红色立方体”，实际会在 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` 获取树。
- *"在工作空间中创建一个 2×2×2 的霓虹立方体 'Hello'"* → 使用 `studio_create_part` 实际创建。
就这样。创建、修改和删除会自动备份，如果失败则回滚。
---
## 主要功能
- **CRUD** — 使用自然语言进行实例创建/查询/修改/删除 + 脚本添加。
- **安全写入** — 所有更改都经过 `备份 → 修改 → 验证 → 应用 → 保存` 管道，如果失败则自动回滚。
- **资产导入** — 导入资产商店模型 + 本地图像（路径安全验证）。
- **发布保护** — 不可逆的发布受四重保护（防止错误发布）。
- **记录器/重放器** — 记录所有 RPC 调用，并在 Studio 更新后检测协议更改。
- **能力层** — 不支持的功能会在调用时以结构性错误报告。
---
## 支持的工具（13）
| 工具 | 功能 |
|---|---|
| `studio_browse` | 查询世界实例树（支持过滤/深度） |
| `studio_screenshot` | 视口截图 |
| `studio_create_part` | 创建部件（支持尺寸/CFrame/颜色/材质/锚点等） |
| `studio_update_part` | 实例名称/属性部分修改 |
| `studio_delete` | 实例删除（包括子实例，服务保护） |
| `studio_add_script` | 添加脚本/LocalScript/ModuleScript |
| `studio_import_model` | 导入资产商店模型 |
| `studio_import_image` | 导入本地图像（路径验证） |
| `studio_apply_action_sequence` | 将操作序列 JSON 应用到 ActionSequencer |
| `studio_apply` / `studio_save` | 应用更改 / 保存世界 |
| `studio_publish` | 发布世界（默认为 dry-run，四重保护） |
| `studio_capabilities` | 报告 Studio 功能支持情况 |
每个工具的输入模式/示例/返回值请参见 [docs/TOOLS.md](docs/TOOLS.md)。所有工具都以结构化的 `ToolResult`（success/operation/affected/warnings/data/error）返回。
---
## 安全措施
### 写入管道 + 自动回滚
所有 `.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 # 重放记录的会话以检测协议更改（偏移）
```
比较响应的形状（键/类型结构）以检测协议更改（偏移）。
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `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` 世界文件所在的目录。
**问：会不会意外损坏世界？** 所有写入操作都在备份后进行，如果失败则回滚。只有发布操作是不可逆的，并受四重保护。
**问：这是官方 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)
