TouchDesigner Atlas

英語 | ロシア語 | 簡体字中国語

td-atlas はエージェントに 3 つの機能を提供します。このコンピューターにある正確なオペレーター名とパラメーター名。起動中のインスタンスを操作し、1 ステップで元に戻す機能。そして、プロジェクトを開かずに保存済みプロジェクトを読む方法です。

できること

• アトムインデックス は名前の一覧です。2 回の処理で、アプリケーションの手元のコピーからすべてのオペレーターとパラメーターを読み取り、1 つの SQLite ファイルに格納します。そこに格納される値は、そのコピーが報告する値です。
• ブリッジ を使うと、TouchDesigner の実行中にエージェントがプロジェクトを変更できます。スクリプトは、Web Server DAT、callbacks DAT、ステータスパネル、保存時に実行される Execute DAT という 4 つの一般的なノードから、TouchDesigner 内にブリッジを構築します。内容を読み、変更を git で確認し、その場でアップグレードできます。
• TouchDesigner が報告しないこと。errors は TouchDesigner 自身がエラーと呼ぶ内容を扱い、td_health は表面化しない不具合を扱います。
• 呼び出しジャーナル は、ブリッジの呼び出しごとに 1 行をディスク上のファイルに記録し、セッション終了後も残します。
• オフラインでプロジェクトを読む と、TouchDesigner を終了した状態でプロジェクトを検査、検索、比較できます。元のファイルは変更されません。
• 保存時に書き込まれるネットワークテキスト は、保存のたびにブリッジが .toe の隣に書き込めるもので、プロジェクトの差分を確認できる履歴を git に残せます。

インストール

まず、次の3つが必要です。

• TouchDesignerがすでにインストールされていること。インデックスは、お使いのアプリケーションから構築され、そのアプリケーションが報告する値を保持します。ダウンロードするものはありません。
• TouchDesignerと同じコンピューターにPython 3.11以降があること。
• MCPに対応したAIエージェントがあること。このエージェントがこれらのツールを呼び出します。td-atlasはClaude Codeを基準に構築・計測されています。コマンドは後述のclaude mcp addの行です。どのMCPクライアントからでも同じツールにアクセスできます。

互換性には、対応プラットフォームと、コネクターがプロジェクト内で変更できる内容が記載されています。

macOSでは、ターミナルから1行実行します。インストーラーはPOSIXシェルスクリプトのため、Windowsでは以下の手順を順に実行してください。

curl -fsSL https://grigabyte.github.io/td-atlas/i | sh

このURLから応答がない場合は、リポジトリから同じスクリプトを取得できます。

curl -fsSL https://raw.githubusercontent.com/grigabyte/td-atlas/main/install.sh | sh

install.shはPythonを見つけ、リポジトリをクローンし、その隣に仮想環境を作成して、パッケージをインストールし、インデックスを構築して、ブリッジを配置します。各コマンドは実行前に表示されます。

質問は2つあります。クローン先と、今すぐインデックスを構築するかどうかです。1つ目の既定値は~/td-atlasです。質問できるターミナルがない場合は、両方とも既定値が使われます。

ディスク上には2つのディレクトリが作成されます。チェックアウト先（別の場所を指定しない限り~/td-atlas）と、~/.td-atlasです。このほか、他のパッケージと同様に、uvまたはpipが独自のパッケージキャッシュを使用します。sudoは不要です。システムディレクトリやシェルの起動ファイルには手を加えません。既存のチェックアウトに対して再実行すると、そのチェックアウトが更新されます。

git clone https://github.com/grigabyte/td-atlas
cd td-atlas
uv venv                     # or: python3 -m venv .venv
uv pip install -e .         # or: .venv/bin/pip install -e .

.venv/bin/td-atlas build      # offline index, 13–16 s, no TouchDesigner process
.venv/bin/td-atlas install    # stage the bridge, print the bootstrap and MCP lines

以降、コマンドは簡潔にtd-atlasと表記します。仮想環境が有効になっていない場合は、パスを指定して呼び出してください。チェックアウト内では.venv/bin/td-atlasです。それ以外の場所からは、既定のディレクトリの場合、~/td-atlas/.venv/bin/td-atlasのようにフルパスを指定します。Windowsでは.venv\Scripts\td-atlasです。システムのPythonからはこのパッケージを認識できません。

td-atlas installを実行すると、貼り付けるコマンドが2つ表示されます。curlの行で実行した場合は、どちらもすでに出力の末尾に表示されています。もう一度実行すると、再び表示されます。まず、各プロジェクトで1回、TouchDesignerのテキストポート（Dialogs → Textport and DATs）に貼り付けます。

exec(open('/Users/you/.td-atlas/bootstrap.py').read())

テキストポートには[td-atlas]の行が返されます。最後の行には、TouchDesignerのビルドと、ブリッジが接続したプロジェクトが表示されます。

[td-atlas] registered as /Users/you/.td-atlas/instances/9977.json
[td-atlas] bridge ready at /tdatlas on port 9977 (auth: token)
[td-atlas] TouchDesigner 2025.32460, project 'NewProject.1.toe'

次に、MCPクライアント用のclaude mcp addコマンドです。MCP サーバーとしてを参照してください。同じエントリーをDIR/.mcp.jsonに書き込む場合、または既存のエントリーに統合する場合は、--write-mcp-json DIRを指定します。

テキストポートから応答があったら、インデックスの作成を完了します。

td-atlas probe

この処理では、実行中のインスタンスだけが把握している情報を追加します。

最後に、インストールを確認します。途中から作業を始めた場合は、ここから実行してください。

td-atlas doctor

インストールが完了すると、すべてのリンクがokとなり、最後に完了を示す行が表示されます。

environment   : ok — running from /Users/you/td-atlas/.venv …
touchdesigner : ok — build 2025.32460 at /Applications/TouchDesigner.app …
index         : ok — 667 ops, 24251 params, 2060 articles …
index build   : ok — index and installation agree: 2025.32460
probe         : ok — runtime pass complete: 647 ops probed …
bridge        : ok — connected on port 9977 to 'NewProject.1.toe' …
mcp server    : ok — 'claude mcp add …' launches …

every link checked out.

件数はお使いのTouchDesignerのコピーから取得されるため、環境によって異なります。ok以外のリンクには、それぞれ修復方法が表示されます。リンクに問題があると、コマンドはゼロ以外の値で終了します。インデックスの構築前はindex : FAIL … fix: td-atlas build、ブリッジの配置前はbridge : warn … fix: td-atlas installと表示されます。

MCP サーバーとして

td-atlas install を実行し、表示された claude mcp add … の行を貼り付けます。 この行ではインタープリターが絶対パスで指定されるため、作業ディレクトリを問わず、仮想環境がアクティブかどうかにかかわらず動作します。手動で接続する場合は、次のようになります。

claude mcp add td-atlas -- /path/to/python -m td_atlas.cli mcp

ここからは、やりたいことを自然な言葉で伝えます。エージェントが呼び出すツールは次のとおりです。

3 つのグループに 47 個のツールがあります。9 個のインデックスツールはオフラインで動作し、29 個のライブツールは実行中のインスタンスに対して動作し、9 個のプロジェクトファイルツールはディスク上の .toe／.tox を読み書きします。各ツールの引数と用途については、plugin/skills/touchdesigner/references/tools.md に記載されており、テストでその一覧とコードの一致を確認しています。

td_build と td_set_params は、送信前にパラメーター名をインデックスと照合するため、よくある誤りは修正内容とともに返されます。

- t: is a parameter group, not a settable parameter (try: tx, ty, tz)
- typ: no such parameter (try: type, ty)
- type: 'simplex5d' is not a valid menu entry
        (try: simplex4d, simplex3d, simplex2d, sparse, perlin4d)
- period: -3 is below the clamped minimum 0.0

ドキュメント

ライセンス

MIT で、全文は LICENSE に記載されています。TouchDesigner は Derivative Inc. の製品です。 このプロジェクトは同社とは関係なく、インストール済みのファイルを再配布することもありません。 お使いのマシンにすでにあるものを読み取るだけです。