Embody - MCP Server for TouchDesigner

Embody

思考する速さで創作する。

embody.tools  ·  ドキュメント  ·  マニフェスト  ·  変更履歴

_{Embot — Envoyのビルド中、ネットワーク内をぴょんぴょん駆け回ります}

Embodyは、アイデアを説明するだけで、すぐに画面上に形にします。オペレーター、接続、パラメーターなど、必要なものがそろっています。別の方向性を試したくなったら、数秒で新しいアプローチを立ち上げられます。試行を並べて比較し、うまくいったものから分岐できます。ツールがあなたに合わせて動き、あなたがツールに合わせる必要はありません。

4つのツール、1つのアイデア

Envoy — 前進する力。 組み込みの MCP サーバーにより、Claude Code、Codex、OpenCode、Gemini、Cursor、Windsurf、GitHub Copilot（VS Code 経由）が、実行中の TouchDesigner セッションと直接やり取りできます。作りたいものを伝えるだけで、オペレーターの作成、接続、パラメーター設定、エクステンションの作成、エラーのデバッグを行えます。コードをコピー＆ペーストする必要はありません。チャットでネットワークを説明する必要もありません。アイデアからオペレーターまで、わずか数秒です。

Embody — 横に広がる力。 任意のオペレーターにタグを付けると、Embody がネットワーク階層を反映したディスク上のファイルへ外部化します。新しい方向性を試す、よい案から分岐する、昨日の状態に戻す、といった作業をすべて数秒で行えます。外部化したファイルが信頼できる唯一の情報源となるため、どのプロジェクトも、すぐに作業を始められる状態で開きます。

Convoy — 外へ広がる力。 信頼できる LAN 上の Convoy 対応 Embody ノードは、互いを検出、確認、制御できます。1つの AI セッションから、ビルド、テスト実行、保存、スクリーンショット、ファイル、再起動を、部屋にあるすべてのマシンへ中継できます。ユーザーごとに動作する小さなバックグラウンドアプリが、TouchDesigner を閉じている間も各ノードへの接続を維持します。Convoy ガイド

TDXN — すべてを可能にする基盤。 TouchDesigner ネットワークを、人が読める YAML としてエクスポートします。この形式により、AI エージェントは画面上の内容を理解でき、ある試行を別の試行と比較でき、次にプロジェクトを開いたときにネットワークをテキストから再構築できます。残りのすべてを可能にするのが TDXN です。

クイックスタート

要件： TouchDesigner 2025.33230 以降（Windows / macOS）。Python のセットアップは不要です。Embody は TouchDesigner 独自のインタープリターに合わせたプロジェクトごとの Python 環境（.venv）を構築し、独自のパッケージもその環境に配置できます。特別なフォルダー構成も必要ありません。Embody はどのプロジェクトフォルダーでも動作し、git を使っている場合は、すべての変更をきれいな差分として無料で確認できます。

1. インストール

Embody の .tox を /release からダウンロードし、TouchDesigner のプロジェクトにドラッグします。セットアップウィザードが開き、重要な選択肢について案内します。Embody にどの程度の自律性を持たせるか、何を外部化するか、AI アシスタント（Envoy）を有効にするか、どのツールで有効にするか、権限、信頼済み LAN の Convoy に参加するか、設定ファイルをどこに置くかなどです。最後にクリックするまで何も変更されず、Embody COMP のセットアップウィザードパルスからいつでも再実行できます。

Embody の更新： Embody は自動で更新されます。About ページの更新を確認をパルスする（または起動時に確認するよう自動更新を設定する）と、検証済みのリリースがダウンロードされ、バックアップを作成してからその場で置き換えられます。設定と追跡対象の外部化ファイルはディスク上に保存され、更新後もそのまま維持されます。自動更新ガイドを参照してください。手動で更新する場合は、古い Embody COMP を削除して、新しい .tox をその場所にドラッグします。新しいバージョンはディスク上の状態を自動で引き継ぐため、再スキャンやファイルの書き換えは不要です。

人のいないマシン（レンダーノードやメディアサーバーなど）をプロビジョニングしますか？ブートストラップを使うと、TouchDesigner 独自のツールを使い、オフラインで Embody を .toe に1行でインストールできます。

2. タグ付けと作業

1. オペレーターにタグを付ける — 任意の COMP または DAT にカーソルを合わせて lctrl を2回押すと、タグ付けツールが開きます（COMP ではストラテジー、DAT ではファイル形式を選択します）
2. 通常どおり作業する — ctrl + shift + u を押すとすべての外部化を更新し、ctrl + alt + u を押すと現在の COMP のみを更新します。外部化されたファイルは保存時に書き込まれます。デフォルトでは、開いたときに .toe が正として扱われます（保存時エクスポート）。一方、ラウンドトリップモードでは、TDXN ストラテジーの COMPs もディスクから再構築されます。

ヒント： 外部化はオプトイン方式です。タグを付けるまで、ディスクには何も書き込まれません。AI アシスタントの作業を自動で取り込むには、新しい OP を自動で外部化（Envoy のパラメータページ）を設定します。Envoy を通じて作成されたものにはすべて、作成時にタグが付けられ、外部化されます。

対応形式、フォルダー設定、重複の処理、Manager UI などについては、Embody のドキュメントを参照してください。

Envoy MCP サーバー

Embody には、AI コーディングアシスタントが実行中の TouchDesigner セッションに直接アクセスできる、組み込みの MCP サーバーである Envoy が含まれています。

セットアップ

1. セットアップウィザードで AI アシスタントを選択します。初回インストール時にウィザードが開きます。または、Embody COMP のセットアップウィザードパルスからいつでも再実行できます。パラメータを使う場合は、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 の起動時には、TD 開発のパターンとプロジェクト固有のガイダンスを記載した AGENTS.md ファイルが、必ずプロジェクトのルートに生成されます。また、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 エージェントも、あなたも読み取れます。あらゆるテキストツールで差分を確認できます。このファイルからネットワークを再構築できます。

これは基盤となる仕組みです。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 自身の COMPs がファイルから除外され、タグが過剰に付いた古いプロジェクトは更新後に整理されます。また、初回の外部化前に保存したプロジェクトを再度開くと、追跡情報が保持されます（issue #176）
• 6.2.73 — Embody が解析できない .mcp.json は置き換えず、そのまま保持されるため、ほかの MCP サーバーが維持されます（issue #159）
• 6.2.72 — Convoy でブランチを切り替えられるようになり、任意の兄弟ワークツリーを使用して、ノードにファイルを送信できます（convoy_send_file）。プルしても別のブランチに移動しなくなりました。TDXN フォーマット 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 — 4 つの新しいスキル（glsl-shaders、operator-gotchas、testing、/collab）とスキルのリファレンスファイルを追加しました。Derivative の TDMCPSkills に感謝します。describe_op_type と run_soak_test を追加し、ユーザープロジェクトで常時読み込まれるガイダンスを 40% 削減しました
• 6.2.64 — 「オフラインノードを削除」では、各行の所有者がフリート全体の行を削除します。応答のないノードは 1 か月ではなく 1 週間後に廃止され、更新ジョブが誤った失敗を報告しなくなりました
• 6.2.63 — Windows のスーパーバイザーはインストール後も待機状態を維持します。ノードの行に TD ビルドが表示され、フリートのランタイム ID が更新されます。稼働中でも応答のないノードは停止状態として表示され、中断中のスキャン表示は再度開くと消去されます
• 6.2.62 — ホストの ID が再発行された場合、ゴーストレコードは永久に接続を試み続けるのではなく、ピア側で休止状態になります。ピン留めは維持され、連絡があると再びアクティブになります。ステータスには双方でゴーストが表示されます
• 6.2.61 — Convoy が Envoy の依存関係とホストの通知（拒否された証明書、再発行された ID、レルムの分割、VPN バインド）を表示するようになりました。変更されたピアを再度ピン留めし、自動バインド時には VPN とパブリックネットワークを避け、参加が許可されたピアのレルムに合流します。新たなレルムは作成しません
• 6.2.59 — 新しいクローンは採用した Envoy を保持し、ロールバック後に破棄したバージョンを現在のバージョンとして報告しなくなりました。リリースゲートの ID 検証が、正常なビルドを誤って失敗させたり、ランタイムテーブル上のビルドを誤って通過させたりする問題を修正しました
• 6.2.57 — TDXN がオペレーター参照を作成時のままエクスポートし、プロジェクト内の絶対パスを再設定します（#132 を修正）。新しいクローンはコミット済みの Envoy 宣言を採用します。新規インストールのリリーススモークテストをワンコマンドで実行でき、macOS のテストも CI に追加しました
• 6.2.56 — Python が停止した仮想環境は、インストール済みパッケージを保持したまま、バックグラウンドスレッドで削除せずに修復されます。Envoy を有効にしても TD がフリーズしなくなりました。devalue のセキュリティアップデートを適用しました
• 6.2.55 — 新しい作品例「Serenity and Beauty」をカバー動画付きで追加しました。同一の兄弟 COMP の有効なクローンは、値としてエクスポートされます（マンダラの .tdxn は 9,599 行から 2,834 行に短縮）。embody.tools のソースビューアーがブラウザーで表示されるようになりました。TDXN COMPs で Embot が使用可能になり、新しい同梱ルール tdxn-economy を追加しました
• 6.2.52 — 0 以外のデフォルト値を持つタプル形式のカスタムパラメーター（RGB、XYZ、複数コンポーネントの Float/Int）が、その値でインポートされるようになりました。0 にはなりません
• 6.2.51 — issue #94 のエージェントルールに関する注意事項 7 件を、リリース前に実機で検証しました。embody.tools のカバー画像は事前に用意したリストではなく、作品例の行から取得されます。新しい作品例「Prismatic Strata」を追加しました
• 6.2.50 — Export Release Toe：1 回のパルスで確認を促し、保存先を尋ねてから、プロジェクトをロック済みの .toe として出力します。Embody が pre_release_toe フックを書き込むこともできます
• 6.2.49 — 保存時に .tdxn で保持できない内容が通知されるようになり、VS Code でヘッダーが表示されたままになります。また、Envoy が自身のホストを削除して TouchDesigner をフリーズさせることがなくなりました（issues #106、#108～#110）
• 6.2.42 — ExportReleaseToe：Embody を削除したロック済み .toe 1 つとしてプロジェクト全体を出力します。事前にプレビューできます
• 6.2.41 — MCP SDK を 2.2.0 に更新しました。既存の仮想環境は次回起動時に自動でアップグレードされます
• 6.2.40 — TDXN タグ、strategy 列、ディスク上のファイル、git diff ドライバーの表記がすべて TDXN になりました。暗黙のうちに一致しなくなっていた 9 つの strategy の読み取り処理を修正しました
• 6.2.13 — ベクターのカスタムパラメーターのデフォルト値が、エクスポートとインポートの往復後も保持されます（issue #96）。6 つの定義フィールド、3 つの作成時フラグ、TDXN フォーマット 2.1 を追加しました
• 6.2.8 — ドキュメント、スキル、embody.tools 全体で TDXN への名称変更が完了しました（/tdn/ → /tdxn/、恒久リダイレクト付き）
• 6.2.5 — TDXN のレビューに関する修正：スナップショットのエクスポートが追跡対象ファイルに触れなくなり、ダーティ検出がエクスポートで書き込まれるすべての内容を対象にするようになりました
• 6.2.0 — 3 つの名前空間階層を導入しました。昇格された API サーフェスは 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 がエンドツーエンドで利用可能になりました。信頼された LAN 上のノードが互いを検出し、作業を中継して、互いを制御します
• 6.0.162 — MCP SDK 2.0 への移行と、自己アップグレードする仮想環境
• 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 の変更（バッチごとに 1 つの取り消しステップ）、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）です。OS ダイアログの閉じ方、呼び出しごとのインスタンス指定、修正のヒントを含む安定したエラーコード、OP Viewer TOP を通じたあらゆるファミリーのキャプチャ、DAT 書き込み時のシェーダーリンター、プロジェクトファイルへのオフラインインストールは、Embody が採用して発展させたアイデアです（ロードマップをご覧ください）。

Embody にあなたのアイデアが取り入れられているのに、このリストに記載がない場合は、issue を作成してください。追加します。

商標および関係性

Embody は独立したオープンソースプロジェクトです。Derivative との提携、同社による承認や後援はありません。TouchDesigner は Derivative の商標です。

ライセンス

MIT ライセンス