touchdesigner-mcp

TouchDesigner 連携（twozero MCP）

重要なルール

1. パラメーター名を絶対に推測しないでください。 まず、対象の OP タイプに対して td_get_par_info を呼び出してください。TD 2025.32 では学習データは正しくありません。
2. tdAttributeError が発生したら、そこで停止してください。 続行する前に、エラーが発生したノードに対して td_get_operator_info を呼び出してください。
3. スクリプトコールバックでは、絶対パスをハードコードしないでください。 me.parent() / scriptOp.parent() を使用してください。
4. td_execute_python よりネイティブ MCP ツールを優先してください。 td_create_operator、td_set_operator_pars、td_get_errors などを使用してください。td_execute_python に切り替えるのは、複雑な複数ステップのロジックが必要な場合に限ります。
5. 構築前に td_get_hints を呼び出してください。 作業対象の OP タイプに特化したパターンが返されます。

アーキテクチャ

Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python

ネイティブツールは36種類です。無料プラグイン（支払い・ライセンス不要 — 2026年4月確認済み）。 コンテキストを認識します（選択中の OP、現在のネットワークを把握）。 ハブのヘルスチェック：GET http://localhost:40404/mcp は、インスタンスの PID、プロジェクト名、TD のバージョンを含む JSON を返します。

セットアップ（自動）

セットアップスクリプトを実行すると、すべて処理されます。

bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh"

スクリプトは次の処理を行います。

1. TD が起動しているか確認する
2. キャッシュにない場合、twozero.tox をダウンロードする
3. Hermes の設定に twozero_td MCP サーバーを追加する（未登録の場合）
4. ポート40404で MCP 接続をテストする
5. 残っている手動作業（.tox を TD にドラッグし、MCP のトグルを有効にする）を報告する

手動での手順（一度だけ。自動化できません）

1. ~/Downloads/twozero.tox を TD のネットワークエディターにドラッグ → Install をクリック
2. MCP を有効にする： twozero アイコンをクリック → Settings → mcp → "auto start MCP" → Yes
3. 新しい MCP サーバーを読み込むため、Hermes のセッションを再起動する

セットアップ後、次の手順で確認します。

nc -z 127.0.0.1 40404 && echo "twozero MCP: READY"

環境に関する注意事項

• Non-Commercial TD では解像度が1280×1280に制限されます。outputresolution = 'custom' を使用し、幅と高さを明示的に設定してください。
• コーデック： prores（macOS で推奨）、またはフォールバックとして mjpa を使用します。H.264/H.265/AV1 には Commercial ライセンスが必要です。
• パラメーターを設定する前に、必ず td_get_par_info を呼び出してください。名前は TD のバージョンによって異なります（「重要なルール」#1を参照）。

ワークフロー

ステップ0：確認（何かを構築する前に）

Call td_get_par_info with op_type for each type you plan to use.
Call td_get_hints with the topic you're building (e.g. "glsl", "audio reactive", "feedback").
Call td_get_focus to see where the user is and what's selected.
Call td_get_network to see what already exists.

一時ノードもクリーンアップも不要です。これにより、従来の確認手順を完全に置き換えられます。

ステップ1：クリーンアップと構築

重要：クリーンアップと作成は、別々の MCP 呼び出しに分けてください。 1つの td_execute_python スクリプト内で同じ名前のノードを破棄して再作成すると、「Invalid OP object」エラーが発生します。「注意点」#11b を参照してください。

各ノードに td_create_operator を使用してください（ビューポートの位置は自動的に処理されます）。

td_create_operator(type="noiseTOP", parent="/project1", name="bg", parameters={"resolutionw": 1280, "resolutionh": 720})
td_create_operator(type="levelTOP", parent="/project1", name="brightness")
td_create_operator(type="nullTOP", parent="/project1", name="out")

一括作成や配線には、td_execute_python を使用してください。

# td_execute_python script:
root = op('/project1')
nodes = []
for name, optype in [('bg', noiseTOP), ('fx', levelTOP), ('out', nullTOP)]:
    n = root.create(optype, name)
    nodes.append(n.path)
# Wire chain
for i in range(len(nodes)-1):
    op(nodes[i]).outputConnectors[0].connect(op(nodes[i+1]).inputConnectors[0])
result = {'created': nodes}

ステップ2：パラメーターの設定

ネイティブツールを優先してください（パラメーターを検証し、クラッシュしません）。

td_set_operator_pars(path="/project1/bg", parameters={"roughness": 0.6, "monochrome": true})

エクスプレッションやモードには、td_execute_python を使用してください。

op('/project1/time_driver').par.colorr.expr = "absTime.seconds % 1000.0"

ステップ3：配線

td_execute_python を使用してください。ネイティブの配線ツールはありません。

op('/project1/bg').outputConnectors[0].connect(op('/project1/fx').inputConnectors[0])

ステップ4：確認

td_get_errors(path="/project1", recursive=true)
td_get_perf()
td_get_operator_info(path="/project1/out", detail="full")

ステップ5：表示／キャプチャ

td_get_screenshot(path="/project1/out")

または、スクリプトからウィンドウを開きます。

win = op('/project1').create(windowCOMP, 'display')
win.par.winop = op('/project1/out').path
win.par.winw = 1280; win.par.winh = 720
win.par.winopen.pulse()

MCP ツール クイックリファレンス

コア（特によく使うツール）：

ツール	内容
td_execute_python	TD で任意の Python を実行します。API にフルアクセスできます。
td_create_operator	パラメーターを指定してノードを作成し、自動で配置します
td_set_operator_pars	パラメーターを安全に設定します（検証を行い、クラッシュしません）
td_get_operator_info	1 つのノードの接続、パラメーター、エラーを確認します
td_get_operators_info	1 回の呼び出しで複数のノードを確認します
td_get_network	指定したパスのネットワーク構造を確認します
td_get_errors	エラーや警告を再帰的に検索します
td_get_par_info	OP タイプのパラメーター名を取得します（探索機能に代わるものです）
td_get_hints	構築前にパターンやヒントを取得します
td_get_focus	開いているネットワークと選択中の項目を確認します

読み取り／書き込み：

ツール	内容
td_read_dat	DAT のテキスト内容を読み取ります
td_write_dat	DAT の内容を書き込み／パッチします
td_read_chop	CHOP のチャンネル値を読み取ります
td_read_textport	TD コンソールの出力を読み取ります

ビジュアル：

ツール	内容
td_get_screenshot	1 つの OP ビューアーをファイルにキャプチャします
td_get_screenshots	複数の OP を一度にキャプチャします
td_get_screen_screenshot	TD を通じて実際の画面をキャプチャします
td_navigate_to	ネットワークエディターを指定した OP に移動します

検索：

ツール	内容
td_find_op	プロジェクト全体から名前／タイプで OP を検索します
td_search	コード、式、文字列パラメーターを検索します

システム：

ツール	内容
td_get_perf	パフォーマンスをプロファイリングします（FPS、遅い OP）
td_list_instances	実行中のすべての TD インスタンスを一覧表示します
td_get_docs	TD のトピックに関する詳細なドキュメントを取得します
td_agents_md	COMP ごとの Markdown ドキュメントを読み書きします
td_reinit_extension	コード編集後にエクステンションを再読み込みします
td_clear_textport	デバッグセッションの前にコンソールをクリアします

入力の自動化：

ツール	内容
td_input_execute	TD にマウス／キーボード入力を送信します
td_input_status	入力キューの状態を確認します
td_input_clear	入力の自動化を停止します
td_op_screen_rect	ノードの画面座標を取得します
td_click_screen_point	スクリーンショット内のポイントをクリックします
td_screen_point_to_global	スクリーンショットのピクセル座標を絶対画面座標に変換します

上記の表には、一般的なクリエイティブワークフローで使用する 32 個のツールが記載されています。残りの 4 個のツール（td_project_quit、td_test_session、td_dev_log、td_clear_dev_log）は管理者／開発モード用のユーティリティです。パラメーターのスキーマをすべて含む 36 個のツールの完全なリファレンスについては、references/mcp-tools.md をご覧ください。

主な実装ルール

GLSL の時間： GLSL TOP では uTDCurrentTime を使用できません。Values ページを使用してください：

# Call td_get_par_info(op_type="glslTOP") first to confirm param names
td_set_operator_pars(path="/project1/shader", parameters={"value0name": "uTime"})
# Then set expression via script:
# op('/project1/shader').par.value0.expr = "absTime.seconds"
# In GLSL: uniform float uTime;

代替方法：rgba32float 形式の Constant TOP を使用します（8 ビットでは 0～1 にクランプされ、シェーダーが停止します）。

Feedback TOP： 直接入力ワイヤーではなく、top パラメーター参照を使用します。「Not enough sources」は最初の cook 後に解消されます。「Cook dependency loop」の警告は想定内です。

解像度： Non-Commercial では 1280×1280 が上限です。outputresolution = 'custom' を使用してください。

大きなシェーダー： GLSL を /tmp/file.glsl に書き込み、その後 td_write_dat または td_execute_python で読み込みます。

頂点／ポイントへのアクセス（TD 2025.32）： point.P[0]、point.P[1]、point.P[2] を使用します。.x、.y、.z は使用しないでください。

エクステンション： CONSTANT モードでは、ext0object の形式は "op('./datName').module.ClassName(me)" です。td_write_dat でエクステンションコードを編集した後は、td_reinit_extension を呼び出してください。

スクリプトコールバック： 必ず me.parent()／scriptOp.parent() を使って相対パスを指定してください。

ノードのクリーンアップ： 反復処理の前に必ず list(root.children) を使用し、child.valid を確認してください。

動画の録画／書き出し

# via td_execute_python:
root = op('/project1')
rec = root.create(moviefileoutTOP, 'recorder')
op('/project1/out').outputConnectors[0].connect(rec.inputConnectors[0])
rec.par.type = 'movie'
rec.par.file = '/tmp/output.mov'
rec.par.videocodec = 'prores'  # Apple ProRes — NOT license-restricted on macOS
rec.par.record = True   # start
# rec.par.record = False  # stop (call separately later)

H.264／H.265／AV1 には Commercial ライセンスが必要です。macOS では prores を使用し、代替として mjpa を使用してください。 フレームの抽出：ffmpeg -i /tmp/output.mov -vframes 120 /tmp/frames/frame_%06d.png

TOP.save() はアニメーションには使えません — 毎回同じ GPU テクスチャをキャプチャします。必ず MovieFileOut を使用してください。

録画前のチェックリスト

1. td_get_perf で FPS が 0 より大きいことを確認します。FPS が 0 の場合、録画は空になります。落とし穴 #38～39 を参照してください。
2. td_get_screenshot で シェーダーの出力が黒くないことを確認します。出力が黒い場合は、シェーダーエラーまたは入力の欠落が考えられます。落とし穴 #8、#40 を参照してください。
3. 音声を使って録画する場合： まず音声を開始するように設定し、その後、録画を 3 フレーム遅らせます。落とし穴 #19 を参照してください。
4. 録画を開始する前に出力パスを設定します。同じスクリプト内で両方を設定すると競合する可能性があります。

音声反応型 GLSL（実証済みのレシピ）

正しい信号チェーン（2026 年 4 月にテスト済み）

AudioFileIn CHOP (playmode=sequential)
  → AudioSpectrum CHOP (FFT=512, outputmenu=setmanually, outlength=256, timeslice=ON)
  → Math CHOP (gain=10)
  → CHOP to TOP (dataformat=r, layout=rowscropped)
  → GLSL TOP input 1 (spectrum texture, 256x2)

Constant TOP (rgba32float, time) → GLSL TOP input 0
GLSL TOP → Null TOP → MovieFileOut

音声反応型の重要なルール（実証済み）

1. AudioSpectrum では TimeSlice を必ず ON にします。 OFF にすると音声ファイル全体が処理され、24000 以上のサンプルが生成されて CHOP to TOP のオーバーフローが発生します。
2. Output Length を手動で 256 に設定します。 outputmenu='setmanually' と outlength=256 を指定します。デフォルトでは 22050 サンプルが出力されます。
3. スペクトラムの平滑化に Lag CHOP を使わないでください。 Lag CHOP は TimeSlice モードで動作し、256 サンプルを 2400 以上に増やして、すべての値をほぼゼロ（約 1e-06）に平均化します。シェーダーは使用可能なデータを受け取れなくなります。テストで発生した音声同期の失敗のうち、最も多かった原因です。
4. Filter CHOP も使わないでください。 スペクトラムデータが同じ TimeSlice 拡張の問題を引き起こします。
5. 必要な場合は、GLSL シェーダー内で平滑化します。 フィードバックテクスチャを使った時間方向の lerp（mix(prevValue, newValue, 0.3)）を使用します。これにより、パイプライン遅延なしでフレーム単位の同期が実現します。
6. CHOP to TOP の dataformat は 'r'、layout は 'rowscropped' にします。 スペクトラム出力は 256x2（ステレオ）です。最初のチャンネルは y=0.25 でサンプリングします。
7. Math のゲインは 10 にします（5 ではありません）。 低音域のスペクトラム値は約 0.19 です。ゲインを 10 にすると、シェーダーで使いやすい約 5.0 になります。
8. Resample CHOP は不要です。 AudioSpectrum の outlength パラメーターで出力サイズを直接制御します。

GLSL でのスペクトラムのサンプリング

// Input 0 = time (1x1 rgba32float), Input 1 = spectrum (256x2)
float iTime = texture(sTD2DInputs[0], vec2(0.5)).r;

// Sample multiple points per band and average for stability:
// NOTE: y=0.25 for first channel (stereo texture is 256x2, first row center is 0.25)
float bass = (texture(sTD2DInputs[1], vec2(0.02, 0.25)).r +
              texture(sTD2DInputs[1], vec2(0.05, 0.25)).r) / 2.0;
float mid  = (texture(sTD2DInputs[1], vec2(0.2, 0.25)).r +
              texture(sTD2DInputs[1], vec2(0.35, 0.25)).r) / 2.0;
float hi   = (texture(sTD2DInputs[1], vec2(0.6, 0.25)).r +
              texture(sTD2DInputs[1], vec2(0.8, 0.25)).r) / 2.0;

完全な構築スクリプトとシェーダーコードについては、references/network-patterns.md を参照してください。

オペレーター早見表

ファミリー	色	Python クラス / MCP タイプ	サフィックス
TOP	紫	noiseTOP, glslTOP, compositeTOP, levelTop, blurTOP, textTOP, nullTOP	TOP
CHOP	緑	audiofileinCHOP, audiospectrumCHOP, mathCHOP, lfoCHOP, constantCHOP	CHOP
SOP	青	gridSOP, sphereSOP, transformSOP, noiseSOP	SOP
DAT	白	textDAT, tableDAT, scriptDAT, webserverDAT	DAT
MAT	黄	phongMAT, pbrMAT, glslMAT, constMAT	MAT
COMP	グレー	geometryCOMP, containerCOMP, cameraCOMP, lightCOMP, windowCOMP	COMP

セキュリティに関する注意

• MCP は localhost 上（ポート 40404）でのみ動作します。認証はありません。ローカルのプロセスであれば、どれでもコマンドを送信できます。
• td_execute_python は、TD プロセスのユーザーとして TD Python 環境とファイルシステムに無制限にアクセスできます。
• setup.sh は公式の 404zero.com URL から twozero.tox をダウンロードします。懸念がある場合は、ダウンロード内容を確認してください。
• このスキルが localhost の外部にデータを送信することはありません。すべての MCP 通信はローカルで行われます。

参考資料

ファイル	内容
references/pitfalls.md	実際のセッションで得た、苦労の末の教訓
references/operators.md	すべてのオペレーターの種類とパラメーター、ユースケース
references/network-patterns.md	レシピ：オーディオ連動、ジェネレーティブ、GLSL、インスタンシング
references/mcp-tools.md	twozero MCP ツールの全パラメータースキーマ
references/python-api.md	TD Python：op()、スクリプティング、拡張機能
references/troubleshooting.md	接続の診断、デバッグ
references/glsl.md	GLSL のユニフォーム、組み込み関数、シェーダーテンプレート
references/postfx.md	ポストエフェクト：ブルーム、CRT、色収差、フィードバックグロー
references/layout-compositor.md	HUD レイアウトのパターン、パネルグリッド、BSP 方式のレイアウト
references/operator-tips.md	ワイヤーフレームレンダリング、フィードバック TOP の設定
references/geometry-comp.md	Geometry COMP：インスタンシング、POP と SOP、モーフィング
references/audio-reactive.md	オーディオ帯域の抽出、ビート検出、エンベロープ追従
references/animation.md	LFO、タイマー、キーフレーム、イージング、エクスプレッション駆動の動き
references/midi-osc.md	MIDI/OSC コントローラー、TouchOSC、複数マシン間の同期
references/particles.md	POP と旧式の particleSOP — 放出、力、衝突
references/projection-mapping.md	マルチウィンドウ出力、コーナーピン、メッシュワープ、エッジブレンディング
references/external-data.md	HTTP、WebSocket、MQTT、Serial、TCP、webserverDAT
references/panel-ui.md	カスタムパラメーター、パネル COMP、ボタン／スライダー／フィールド、panelExecuteDAT
references/replicator.md	replicatorCOMP — データ駆動型の複製、レイアウト、コールバック
references/dat-scripting.md	Execute DAT ファミリー — chop/dat/parameter/panel/op/executeDAT
references/3d-scene.md	ライティングのセットアップ、シャドウ、IBL／キューブマップ、マルチカメラ、PBR
scripts/setup.sh	セットアップを自動化するスクリプト

---

コードを書くのではありません。光を奏でるのです。