Embody - MCP Server for TouchDesigner

Embody

以思维的速度创作。

embody.tools  ·  文档  ·  宣言  ·  更新日志

_{Embot——Envoy 构建时，它会在你的网络中穿梭}

Embody 能将你的想法呈现在屏幕上，速度快得就像你描述它们一样。运算符、连接、参数，应有尽有。想尝试不同的方向？几秒钟内就能启动一种新方案。并排比较各种尝试，从可行的方案分支出新版本。工具会跟上你的节奏，而不是反过来。

四种工具，一个理念

Envoy — 向前的速度。 内嵌的 MCP 服务让 Claude Code、Codex、OpenCode、Gemini、Cursor、Windsurf 和 GitHub Copilot（通过 VS Code）直接与正在运行的 TouchDesigner 会话对话。创建算子、连接算子、设置参数、编写扩展、调试错误——只需说出你的需求。无需复制粘贴代码，也无需在聊天中描述你的网络。想法 → 几秒内变成算子。

Embody — 横向延展的速度。 为任意算子添加标签，Embody 就会将其外置为磁盘上的文件，并映射你的网络层级。尝试新的方向，从出色的方案分支出一条路径，恢复昨天的状态——这一切都只需几秒。外置文件是真实数据源，因此每个项目打开时都已进入工作状态。

Convoy — 向外扩展的速度。 受信任的局域网中，启用了 Convoy 的 Embody 节点可以互相发现、检查和控制——一个 AI 会话就能向房间里的每台机器中继构建任务、测试运行、保存、屏幕截图、文件和重启操作。每位用户运行一个小型后台应用，即使 TouchDesigner 已关闭，每个节点也始终可访问。Convoy 指南

TDXN — 让一切成为可能的基底。 将 TouchDesigner 网络导出为人类可读的 YAML。正是这种格式，让你的 AI Agent 能理解屏幕上的内容，让你能对比不同尝试，也让网络能在下次打开项目时从文本重建。TDXN 让其余一切成为可能。

快速开始

要求： TouchDesigner 2025.33230 或更高版本（Windows / macOS）。无需设置 Python——Embody 会构建与 TouchDesigner 自带解释器相匹配的项目级 Python 环境（.venv），而且你自己的包也可以放在其中。也无需特殊的文件夹结构：Embody 可用于任何项目文件夹；如果你使用 git，每次更改也都会自动生成清晰的差异。

1. 安装

下载 Embody .tox 文件（位于 /release），并将其拖入 TouchDesigner 项目中。Setup Wizard 会打开并引导你完成重要选项的设置 — Embody 拥有多少自主权、要外置哪些内容、是否启用 AI 助手（Envoy）以及使用哪个工具、权限、是否加入可信局域网 Convoy，以及配置文件的存放位置。点击最后的确认按钮之前，不会有任何更改；你也可以随时通过 Embody COMP 上的 Setup Wizard 脉冲重新运行向导。

更新 Embody： Embody 会自行更新 — 在 About 页面触发 Check for Update 脉冲（或将 Auto-Update 设为在启动时检查），即可下载经过验证的版本、备份现有版本并原位替换。你的设置和已跟踪的外置内容都保存在磁盘上，更新时不会受到影响。请参阅自动更新指南。手动替代方法：删除旧的 Embody COMP，并将新的 .tox 拖到原位置 — 新版本会自动读取磁盘上的状态，不会重新扫描，也不会重写文件。

要为无人操作的机器（渲染节点、媒体服务器）配置环境？bootstrap 可使用 TouchDesigner 自带的工具，离线将 Embody 安装到 .toe 中，一行命令即可完成。

2. 标记并工作

1. 标记算子 — 将鼠标悬停在任意 COMP 或 DAT 上，然后按两次 lctrl 打开标记器（为 COMP 选择策略，为 DAT 选择文件格式）
2. 正常工作 — 按 ctrl + shift + u 更新所有外置内容，或按 ctrl + alt + u 仅更新当前 COMP。外置文件会在保存时写入；打开时，默认以 .toe 为准（保存时导出），而 Roundtrip 模式也会从磁盘重建 TDXN 策略的 COMP

提示： 外置功能默认关闭 — 在你进行标记之前，不会有任何内容写入磁盘。要自动捕获 AI 助手的工作，请设置 Auto-Externalize New Ops（Envoy 参数页），这样它通过 Envoy 创建的所有内容都会在构建时自动标记并外置。

有关支持的格式、文件夹配置、重复项处理、Manager UI 等更多信息 — 请参阅 Embody 文档。

Envoy MCP 服务

Embody 内置了 Envoy，这是一个嵌入式 MCP 服务，可让 AI 编码助手直接访问实时运行的 TouchDesigner 会话。

设置

1. 在 Setup Wizard 中选择 AI 助手 — 首次安装时会打开向导，也可以随时重新运行（点击 Embody COMP 上的 Setup Wizard 脉冲）。偏好使用参数？切换 Envoy Enable（Envoyenable）即可用当前设置完成相同操作
2. 服务启动 — 监听 127.0.0.1:9870（可通过 Envoyport 配置；如果该端口已被另一个实例占用，Envoy 会自动依次尝试后续端口）
3. 自动配置 — Envoy 会在 AI 项目根目录下写入 .mcp.json（STDIO 桥接，因此即使 TD 尚未运行，工具也可用）。默认位置是 git 仓库根目录；向导的配置位置步骤 — 或 Aiprojectroot 参数 — 可将其设为 .toe 文件夹或自定义路径。即使项目没有 git 仓库，也会在 .toe 文件夹中生成配置
4. 连接 — 在该根目录下启动 Claude Code 会话（或重启 IDE）— 它会自动读取 .mcp.json

生成的配置使用 Envoy 的桥接 STDIO 传输（推荐 — 它可以为你启动并重启 TD）。如果你更愿意手动配置客户端，只要 TD 正在运行，也可以使用直接 HTTP 传输：

{
  "mcpServers": {
    "envoy": {
      "type": "http",
      "url": "http://127.0.0.1:9870/mcp"
    }
  }
}

工具一览

……另有 56 个工具。请参阅完整工具参考。

Envoy 启动时，总会在项目根目录中生成 AGENTS.md 文件，其中包含 TD 开发模式和项目专属指南。它还会根据你在 Aiclient 参数中选择的助手，写入对应客户端的配置（Claude Code 使用 CLAUDE.md + .claude/，OpenCode 使用 opencode.json + .claude/，Cursor/Windsurf 使用规则，Copilot 使用说明，Gemini 使用 GEMINI.md；Codex 和 OpenCode 会直接读取 AGENTS.md）。有关 OpenCode 和本地模型设置，请参阅本地模型与开放客户端指南。

TDXN 网络格式

TDXN（TouchDesigner eXternal Network）是一种文件格式，也是 Embody 其余功能得以实现的基础。它可以将整个算子网络——包括算子、连接、参数、布局、注释和 DAT 内容——导出为单个易读的 YAML 文件。你的 AI Agent 可以读取它，你也可以读取它。任何文本工具都可以比较其中的差异。网络可以据此自行重建。

这是底层基础。其他所有功能——AI 驱动的构建、版本控制、自动恢复——都构建于此之上。

• 整个项目：ctrl + shift + e
• 当前 COMP：ctrl + alt + e
• 通过 Envoy：export_network / import_network MCP 工具

有关格式详情、导入流程和往返保证，请参阅完整 TDXN 规范。

键盘快捷键

这些是默认快捷键——可以在 Embody COMP 的 Shortcuts 参数页中编辑每个快捷键（输入组合键，或点击 Record 后按下按键；留空则禁用）。请参阅键盘快捷键。

my-project/              ← project folder (optionally a git repo)
├── my-project.toe       ← your TouchDesigner project
├── base1/               ← externalized operators
│   ├── base2.tox        ← COMP (TOX strategy)
│   ├── base3.tdxn        ← COMP (TDXN strategy — diffable YAML)
│   └── text1.py         ← DAT
└── ...

op.Embody.Log('Something happened', 'INFO')
op.Embody.Warn('Check this out')
op.Embody.Error('Something broke')

op.unit_tests.RunTests()                              # All tests (non-blocking)
op.unit_tests.RunTests(suite_name='test_path_utils')   # Single suite
op.unit_tests.RunTestsSync()                           # All in one frame (blocks TD)

版本历史

每个版本的说明都记录在完整更新日志中。主要更新：

• 6.2.77 — 更新完成对话框提供“立即保存”，因此保存的 .toe 会保留新的 Embody
• 6.2.76 — “外置整个项目”会将 Embody 和 TouchDesigner 自带的 COMP 排除在文件之外；更新后，旧项目中标记过多的内容会清理干净；首次外置前保存的项目重新打开时会保留其跟踪信息（issue #176）
• 6.2.73 — 对于 Embody 无法解析的 .mcp.json，会保持原样而不是替换，因此其他 MCP 服务不会丢失（issue #159）
• 6.2.72 — Convoy 可切换分支、使用可选的同级工作树，并将文件发送到节点（convoy_send_file）；拉取操作不再切换到其他分支；TDXN format 2.2，剪贴板副本可独立使用
• 6.2.71 — 子项有自己的 .tdxn 时，父级 .tdxn 不再重复包含子项的自定义参数（一个包含 15 个 COMP 的实验室项目中，子项条目从 2,368 行缩减至 72 行）；从 COMP 自己的 .tdxn 导入时，会先创建自定义参数，再导入其内容
• 6.2.69 — TouchDesigner 关闭后，相应会话会以 envoy.instance.unavailable 停止，而不是转到另一个打开的项目；会话会跟随重命名 .toe 的保存操作；launch_td / restart_td 会对会话自身的实例执行操作（issue #147）
• 6.2.68 — 手动“检查更新”时，如果某个版本是为比你当前版本更新的 TouchDesigner 构建的，会提供“仍然安装”选项；无人值守更新仍会在最低版本要求处停止（issue #145）
• 6.2.65 — 新增四项技能（glsl-shaders、operator-gotchas、testing、/collab）和技能参考文件，感谢 Derivative 的 TDMCPSkills；新增 describe_op_type 和 run_soak_test；用户项目中始终加载的指导内容减少了 40%
• 6.2.64 — “忘记离线节点”会由各自所有者清除整个节点群中的相应行；静默节点一周后退役，不再等待一个月；更新任务不再报告虚假的失败
• 6.2.63 — Windows 监控程序在安装后仍会保持启用；节点行会显示 TD 构建版本，节点群更新也会显示其运行时 ID；在线但无响应的节点会标记为停滞；重新打开后会清除扫描期间的读数
• 6.2.62 — 重新生成身份的主机，其幽灵记录会在对等节点上进入休眠状态，而不是被无限拨号；固定关系会保留，建立联系后会唤醒该记录，双方的状态中都会注明幽灵记录
• 6.2.61 — Convoy 会注明其 Envoy 依赖项和主机的警告信息（证书被拒、身份重新生成、Realm 分裂、VPN 绑定）；对等节点变更后会重新固定；自动绑定时会避开 VPN 和公共网络；加入已获准的对等节点所在的 Realm，而不是新建 Realm
• 6.2.59 — 新克隆会保留其采用的 Envoy；回滚后不再错误地报告已丢弃的版本；发布门禁的身份检查不再导致正常构建失败，也不再放行运行时表格
• 6.2.57 — TDXN 导出会按编写时的形式导出运算符引用，并会重新定位项目内的绝对路径（修复 #132）；新克隆会采用已提交的 Envoy 声明；新增一键式全新安装发布冒烟测试，macOS 测试也纳入 CI
• 6.2.56 — 当 venv 中的 Python 停止运行时，会在后台线程中原地修复，而不是删除 venv，并保留已安装的软件包；启用 Envoy 不再冻结 TD；devalue 安全更新
• 6.2.55 — 新增示例 Serenity and Beauty，并附带封面视频；同级 COMP 的启用克隆会按其值导出（曼陀罗 .tdxn 从 9,599 行缩减至 2,834 行）；embody.tools 源码查看器可在浏览器中呈现；TDXN COMP 允许使用 Embot；新增随附规则 tdxn-economy
• 6.2.52 — 默认值非零的元组自定义参数（RGB、XYZ、多分量 Float/Int）导入时会保留该值，而不是变为 0
• 6.2.51 — issue #94 中的七项 Agent 规则易错点均已在线验证后再发布；embody.tools 的封面来自示例条目，不再来自内置列表；新增示例 Prismatic Strata
• 6.2.50 — Export Release Toe：触发一次后会显示提示并询问保存位置，然后将项目打包为锁定的 .toe；Embody 可为你编写 pre_release_toe 钩子
• 6.2.49 — 保存时会说明 .tdxn 无法保存的内容；标题在 VS Code 中保持可见；Envoy 不再会因删除自身主机而冻结 TouchDesigner（issues #106、#108–#110）
• 6.2.42 — ExportReleaseToe：先预览，再将整个项目打包为单个锁定的 .toe，并移除 Embody
• 6.2.41 — MCP SDK 升级至 2.2.0；现有 venv 会在下次启动时自行升级
• 6.2.40 — TDXN 标签、strategy 列、磁盘上的文件和 git diff 驱动程序统一使用 TDXN；修复了九处已悄然失效的策略读取
• 6.2.13 — 向量自定义参数默认值在往返过程中得以保留（issue #96）；六个定义字段、三个编写时标志，以及 TDXN format 2.1
• 6.2.8 — TDXN 重命名已在文档、技能和 embody.tools 中全面完成（/tdn/ → /tdxn/，并设置永久重定向）
• 6.2.5 — TDXN 审查修复：快照导出绝不会修改已跟踪文件；脏状态检测涵盖导出写入的所有内容
• 6.2.0 — 三层命名空间；提升后的接口从 214 个成员缩减至 43 个（issue #94——未记录名称存在破坏性变更）
• 6.1.5 — 每个 AI 客户端都会从同一个注册表获取自己实际读取的 MCP 配置；编辑保护机制内置于生成的文件中
• 6.1.2 — 格式更名为 TDXN（TouchDesigner eXternal Network）；现有 .tdn 文件可照常使用，并提供可选的迁移触发器
• 6.0.201–6.0.280 — Convoy 加固阶段：启用 macOS 支持、推出自动更新守护进程和全节点群 Embody 更新，并确保自动更新器不再会因下载卡住而陷入锁定状态
• 6.0.171 — Convoy 全面推出：可信局域网中的节点可相互发现、中继任务并控制彼此
• 6.0.162 — 移植至 MCP SDK 2.0，并支持自动升级 venv
• 6.0.145 — 推出自我更新：由清单控制、经过验证，并支持备份和回滚

贡献者

最初源自 Tim Franklin 的 External Tox Saver。Dylan Roscover 对其进行了全面重构，并从 Elburz Sorkhabi、Matthew Ragan 和 Wieland Hilker 那里获得了灵感和指导。

想要帮忙？请从 CONTRIBUTING.md 开始——此代码库的运作方式与典型的 Python 项目不同（许多文件由 TouchDesigner 写入），该页面会说明哪些内容可以安全修改，以及如何运行测试。

致谢

Embody 建立在他人的工作之上，本节将一一列出。TouchDesigner MCP 项目之间的创意会双向流动；Embody 借鉴的内容会在此处以及落地的代码中注明出处。

• External Tox Saver，作者是 Tim Franklin —— Embody 于 2020 年从对该项目的重构起步。
• TDMCP，作者是 Derivative（他们的 MCP 服务；在其仍为私有项目时经许可使用，自 2026 年 9 月起公开）——可撤销的 MCP 修改（每批操作一个撤销步骤）、get_docs 设计（优先使用版本精确匹配的离线帮助，其次使用 wiki API）、参数写入时扩展序列块、传输安全强化提示词，以及将代码审查规则视为查询。从 v6.0.87（2026-07-04）起引入。
• TDMCPSkills，作者是 Derivative（经许可使用）——pop-networks 技能改编自 td-pop-family；编写 glsl-shaders 和 operator-gotchas 时，以他们的 td-glsl-shaders 和系列技能作为主题检查清单，并在 TD 2025.33230（2026-09-25）上逐项实时重新验证所有说法。
• touchdesigner-mcp，作者是 8beeeaaat —— 首个广泛使用的 TouchDesigner MCP 服务（2025）。Envoy 最早期的工具命名（get_td_classes、get_td_class_details、get_td_info、get_module_help、exec_node_method、execute_python）沿用了该项目确立的名称。
• td-mcp-rs，作者是 asyade —— 用 Rust 守护进程实现的同类方案（2026）。Embody 借鉴并完善了其中的操作系统对话框关闭、按调用指定实例、带修复提示的稳定错误代码、通过 OP Viewer TOP 捕获任意类型、写入 DAT 时检查着色器，以及离线安装到项目文件等创意（参见路线图）。

如果 Embody 使用了你的创意，而此列表中没有注明，请提交 issue，我们会将其补上。

商标与关联关系

Embody 是一个独立的开源项目，与 Derivative 无关联，也未获其认可或赞助。TouchDesigner 是 Derivative 的商标。

许可证

MIT 许可证