内容
# fmod-studio-mcp
一个驱动 **FMOD Studio live** 的 [](https://modelcontextprotocol.io) 服务器，通过其内置的**脚本终端**（TCP，默认 `127.0.0.1:3663`）。与基于文件的编辑项目 XML 的方法不同（需要关闭并重新打开 Studio），该方法直接与正在运行的编辑器通信：更改立即生效，Studio 自身写入更改 — 因此不会覆盖，也不需要重新加载。
它将 [FMOD Studio 脚本 API](https://www.fmod.com/docs/2.02/studio/scripting-api-reference.html) 公开为 **一个 MCP 工具对应一个 API 成员** — 从爬取的引用中生成，而不是手动编写 — 另外还有一些通用工具用于静态文档无法枚举的部分。
**没有任意脚本 / 评估工具**：每个功能都是一个命名的、模式验证的操作，作用于 FMOD 的对象模型。
> ⚠️ **Alpha.** 为 AI 代理（Claude Code）构建，用于创作游戏音频。它编辑**实时**项目 — 调用 `fmod_project_save` 以持久化，并保持版本控制。
## 工作原理
FMOD Studio 的脚本控制台（在 Studio 中使用 **Ctrl + 0** 打开）监听 TCP 端口，并评估接收到的任何内容为 UTF-8 JavaScript，返回结果为文本。该服务器保持一个连接，并使用*读取直到空闲*的帧，因此它不依赖于特定的提示字符串。
每个工具为其成员生成一个小的脚本 API JavaScript 片段，运行它，并将结果作为字符串返回。任何返回对象的操作都会对象的路径或 `{guid}`，因此结果可以直接作为另一个工具的 `target`。
## 工具集
**生成 — 每个文档成员一个 (~148)。** 命名为 `fmod_<Owner>_<member>`，例如 `fmod_project_create`、`fmod_project_importAudioFile`、`fmod_Event_addGroupTrack`、`fmod_GroupTrack_addSound`、`fmod_Bank_getPath`、`fmod_system_getText`。成员的 `target_kind` 决定了如何访问它： | 访问方式 | 工具输入 |
|---|---|---|
| `module` | `studio.project.*`、`studio.system.*`、`console.*` … | 成员的参数 |
| `global` | `alert(...)` | 成员的参数 |
| `entity` | `studio.project.model[<className>].*`（类内省） | `className` + 参数 |
| `instance` | `studio.project.lookup(target).*` | `target`（路径或 `{guid}`）+ 参数 |
方法参数自动嵌入：数字/布尔值作为 JS 字面量，路径（`event:/…`、`bank:/Master`）或 `{guid}` 作为对象引用（`lookup(...)`），否则为字符串。可设置的属性采用可选的 `value`（省略则读取）。
**通用 — 访问动态的、模式定义的成员，中未列出（事件的 `timeline`、仪器的 `audioFile`、声音的 `pitch`/`looping` …）：**
| 工具 | 用途 |
|---|---|
| `fmod_get_property` | 读取对象的任何属性，包括每个类管理的属性。 |
| `fmod_set_property` | 设置任何属性（例如仪器的 `audioFile` = 资产）。 |
| `fmod_add_relationship` / `fmod_remove_relationship` | 编辑关系（例如事件的 `banks` → 银行）。 |
| `fmod_class_names` | 列出项目模型的类名称。 |
| `fmod_describe_class` | 列出类的模式定义的属性 + 关系名称（发现）。 |
| `fmod_create_event` | 复合：创建事件 → 导入一次性 → 添加轨道/声音 → 分配银行。 |
## 需求
- **FMOD.02+**，并启用**脚本控制台**（Ctrl+0，它在端口 3663 上启动 TCP 监听器 — 控制台显示 IP/端口）。
- Python 3.10+。
## 安装
```bash https://github.comamanS/fmod-studio-mcp
cd fmod-studio-mcp
python3 -m venv .venv && ./.venv/bin/pip install -e .
```
将其添加到 Claude Code（stdio）：
```bash
claude mcp add fmod-studio -- "$(pwd)/.venv" -m fmod_stcp
```
如有需要配置主机/端口：`FMOD_STUDIO_HOST`（默认 `127.0.0.1`），`FMOD_STUDIO_PORT`（默认 `3663`）。
## 为新 FMOD 版本重新生成
工具集从 `fmod_studio_mcp/api_spec.json` 生成，该文件通过爬取官方脚本 API：
```bash
python tools/build_spec.py fmod_studio_mcp/api_spec.json
```
新的 FMOD 版本意味着重新运行爬虫 — 而不是手动编辑工具注册表。
## 示例
使用一步一步的方式创建具有一次性声音的事件，并将其路由到 Master 银行（或使用 `fmod_create_event` 复合函数一次性完成）：
```
fmod_project_create { entityName: "Event" } -> event:/New Event
fmod_set_property { target:/New Event", property: "name", value: "Hit" }
fmod_project_importAudioFile { filePath: "/abs/path/hit.wav" } -> {asset-guid}
fmod_Event_addGroupTrack { target: "event:/Hit", name: "Audio 1" } -> {track-guid}
fmod_get_property target: "event:/Hit", property: "timeline" } -> {tl-guid}
fmod_GroupTrack_addSound { target: "{track-guid}", parameter: "{tl-guid}",
soundType:", start: 0, length: 2.5 } -> {inst-guid}
fmod_set_property { target: "{inst-guid}", property: "audioFile", value: "{asset-guid}" }
fmod_add_relationship { target: "event:/Hit", relationship: "banks", other: "bank:/Master" }
fmod_project_save {}
```
## 安全
- 编辑**实时**项目。运行 `fmod_project_save` 以持久化；将项目提交到 git。
- 避免在 Studio GUI 和通过此服务器同时以冲突的方式编辑同一个项目。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
