TouchDesigner MCP

TouchDesigner MCP

これは、TouchDesigner 用の MCP（Model Context Protocol）サーバーの実装です。AI エージェントが TouchDesigner プロジェクトを制御、操作できるようにすることを目的としています。

English / 日本語

概要

TouchDesigner MCP は、AI モデルと TouchDesigner WebServer DAT の間のブリッジとして機能し、AI エージェントが以下を実行できるようにします。

• ノードの作成、変更、削除
• ノードのプロパティとプロジェクト構造の照会
• Python スクリプトによる TouchDesigner のプログラム制御

インストール

すでに使用している AI エージェントに、次のように伝えてください。

https://github.com/8beeeaaat/touchdesigner-mcp をセットアップしてください

以上です。手順の全容は**インストールガイド**に記載されています。最初に各 AI アプリに対応する手順をまとめた表があり、どの場合も TouchDesigner のセットアップから始めます。または、手順に沿ってご自身で進めてください。

アップデートする場合は、**最新リリース**の手順を参照してください。

MCP サーバーの機能

このサーバーでは、AI エージェントが Model Context Protocol（MCP）を使用して TouchDesigner 内で操作を実行できます。

ツール

ツールを使用すると、AI エージェントは TouchDesigner 内で操作を実行できます。

ツール名	説明
create_td_node	新しいノードを作成します。
delete_td_node	既存のノードを削除します。
describe_td_tools	使用可能な TouchDesigner ツールのマニフェストを生成します。
exec_node_method	ノードの Python メソッドを呼び出します。
execute_python_script	TouchDesigner で任意の Python スクリプトを実行します。
get_td_class_details	TouchDesigner の Python クラスまたはモジュールの詳細を取得します。
get_td_classes	TouchDesigner の Python クラスの一覧を取得します。
get_td_info	TouchDesigner サーバー環境に関する情報を取得します。
get_td_module_help	TouchDesigner のモジュール／クラスに関する Python help() ドキュメントを取得します。
get_td_node_errors	ノードとその子孫にあるエラーおよび警告を確認します。ファイルの欠落、参照切れ、シェーダーの失敗は警告として扱われるため、エラーがなくても正常とは限りません。
get_td_node_parameters	特定のノードのパラメーターを取得します。
get_td_nodes	親パス配下のノードを取得します。フィルタリングも指定できます。
get_top_image	TOP ノードの現在の出力を画像としてキャプチャします。
update_td_node_parameters	特定のノードのパラメーターを更新します。

プロンプト

プロンプトは、TouchDesigner で特定の操作を実行するよう AI エージェントに指示します。

プロンプト名	説明
Search node	ノード名、ファミリー、またはタイプをもとに、あいまい検索でノードを検索し、情報を取得します。
Node connection	TouchDesigner 内でノードを接続する手順を提示します。
Check node errors	指定したノードと、その子孫ノードを再帰的に調べて、エラーと警告を確認します。

リソース

実装されていません。

開発者ガイド

ローカル環境のセットアップ、クライアントの設定、プロジェクト構成、リリースのワークフローに関する情報をお探しですか？ 開発者向けドキュメントについては、開発者ガイド をご覧ください。

トラブルシューティング

バージョンの互換性に関するトラブルシューティング

MCP サーバーと TouchDesigner コンポーネントは、npm パッケージのバージョンと API バージョン（MCP サーバーと .tox コンポーネント間の契約）という、互いに独立した2 つの軸でバージョン管理されています。各リリースでは、同梱する API バージョン（expectedApiVersion）と、サポートする最小バージョン（minApiVersion、現在は 1.3.0）を宣言します。接続されたコンポーネントの API バージョンは、これら 2 つの値と比較されます。npm パッケージのバージョン自体は互換性の判定基準にならないため、MCP サーバーだけを更新しても、サポート対象のコンポーネントが非互換になることはありません。

API サーバー（コンポーネント）	条件	動作	状態
= 期待される API バージョン	同梱の .tox と一致	✅ 通知なしで動作	互換性あり
≥ 最小バージョン、< 期待されるバージョン	古いコンポーネント	⚠️ レスポンスに「更新を推奨」する通知が追加されますが、処理は続行されます	警告
> 期待されるバージョン、同じ MAJOR	新しいコンポーネント	⚠️ MCP サーバーの更新を促す警告が表示されますが、処理は続行されます	警告
MAJOR が期待値を上回る	新しい API 世代	❌ 実行が停止します — MCP サーバーを更新してください	エラー
< 最小バージョン（または未設定）	古すぎる	❌ 実行が停止します — コンポーネントを更新してください	エラー

• 互換性エラーを解決するには：

  1. リリースページから最新の touchdesigner-mcp-td.zip をダウンロードします。
  2. 既存の touchdesigner-mcp-td フォルダーを削除し、新たに展開した内容に置き換えます。
  3. TouchDesigner プロジェクトから古い mcp_webserver_base コンポーネントを削除し、新しいフォルダーにある .tox をインポートします。
  4. TouchDesigner と、MCP サーバーを実行している AI エージェント（例：Claude Desktop）を再起動します。

• 開発者向け： ローカルで開発する場合は、package.json の編集後に npm run version を実行します（または npm version ... を使用します）。これにより、Python API（pyproject.toml + td/modules/utils/version.py）、mcpCompatibility.expectedApiVersion、MCP バンドルマニフェスト、レジストリメタデータが同期され、実行時の互換性チェックが正常に行われます。

MCP サーバーがこれらのルールをどのように適用するかについて詳しくは、バージョン互換性の検証をご覧ください。

接続エラーのトラブルシューティング

• TouchDesignerClient は、接続チェックの失敗を60 秒間キャッシュします。以降のツール呼び出しではキャッシュされたエラーを再利用して TouchDesigner への過剰なリクエストを避け、TTL の期限が切れると自動的に再試行します。
• MCP サーバーが TouchDesigner に接続できない場合は、具体的な解決策を示すガイド付きエラーメッセージが表示されます。
  • ECONNREFUSED / "connect refused"：TouchDesigner を起動し、mcp_webserver_base.tox の WebServer DAT が実行中であることを確認します。また、設定されているポート（デフォルトは 9981）を確認してください。
  • ETIMEDOUT / "timeout"：TouchDesigner の応答が遅いか、ネットワークがブロックされています。TouchDesigner／WebServer DAT を再起動するか、ネットワーク接続を確認してください。
  • ENOTFOUND / getaddrinfo：ホスト名が無効です。明示的に変更していない場合は、127.0.0.1 を使用してください。
• 構造化されたエラーの内容は ILogger にも記録されるため、リクエストが TouchDesigner に到達する前に停止した理由を MCP のログで確認できます。
• 根本的な問題を解決したら、ツールを再度実行するだけでかまいません。クライアントがキャッシュされたエラーをクリアし、接続を自動的に再確認します。

貢献

皆さまからの貢献を歓迎します！

1. リポジトリをフォークします。
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）。
3. 変更を加えます。
4. テストを追加し、すべて正常に動作することを確認します（npm test）。
5. 変更をコミットします（git commit -m 'Add some amazing feature'）。
6. ブランチにプッシュします（git push origin feature/amazing-feature）。
7. プルリクエストを作成します。

実装を変更する際は、必ず適切なテストを含めてください。

ライセンス

MIT