README.ja.md•15.4 kB
# TouchDesigner MCP
TouchDesignerのためのMCP(Model Context Protocol) サーバー実装です。AIエージェントがTouchDesignerプロジェクトを制御・操作できるようになることを目指しています。
[English](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.md) / [日本語](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.ja.md)
## 概要
[](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)
TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッジとして機能し、AIエージェントが以下のことが可能になります
- ノードの作成、変更、削除
- ノードプロパティやプロジェクト構造の照会
- PythonスクリプトによるTouchDesignerのプログラム的制御
## 利用方法
<details>
<summary>方法1: Claude Desktop + Desktop Extensions（推奨）</summary>
##### 1. ファイルをダウンロード：
[リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)から以下をダウンロード：
- **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
- **Desktop Extensions (.dxt)**: `touchdesigner-mcp.dxt`
##### 2. TouchDesignerコンポーネントを設置：
1. `touchdesigner-mcp-td.zip`を展開
2. 展開したフォルダから`mcp_webserver_base.tox`を操作したいTouchDesignerプロジェクト直下にインポート
例: `/project1/mcp_webserver_base`となるように配置
https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
##### 3. Desktop Extensionをインストール：
`touchdesigner-mcp.dxt`ファイルをダブルクリックしてClaude Desktopに拡張機能をインストール
https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
##### 4. 拡張機能が自動的にTouchDesignerサーバー接続を処理
**⚠️ 重要:** TouchDesignerコンポーネントのディレクトリ構造は展開した状態を正確に保持してください。`mcp_webserver_base.tox`コンポーネントは`modules/`ディレクトリやその他のファイルへの相対パスを参照しています。
</details>
<details>
<summary>方法2: npxを利用する</summary>
*Node.jsがインストールされていることが前提となります*
##### 1. TouchDesignerコンポーネントを設置：
1. [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)から`touchdesigner-mcp-td.zip`をダウンロード
2. zipファイルを展開し、`mcp_webserver_base.tox`を操作したいTouchDesignerプロジェクト直下にインポート
例: `/project1/mcp_webserver_base`となるように配置
https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
##### 2. MCPサーバー設定：
*例 Claude Desktop*
```json
{
"mcpServers": {
"touchdesigner": {
"command": "npx",
"args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
}
}
}
```
**カスタマイズ：** `--host`と`--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
```json
"args": [
"-y",
"touchdesigner-mcp-server@latest",
"--stdio",
"--host=http://custom_host",
"--port=9982"
]
```
</details>
<details>
<summary>方法3: Dockerイメージを利用</summary>
[](https://www.youtube.com/watch?v=BRWoIEVb0TU)
##### 1. リポジトリをクローン：
```bash
git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
cd touchdesigner-mcp
```
##### 2. Dockerイメージのビルド
```bash
git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
cd touchdesigner-mcp
make build
```
##### 3. TouchDesignerプロジェクトにMCP連携用のAPIサーバーを設置
TouchDesignerを起動し、`td/mcp_webserver_base.tox`コンポーネントを操作したいTouchDesignerプロジェクト直下にインポートします。
例: `/project1/mcp_webserver_base`となるように配置
toxファイルのインポートにより`td/import_modules.py`スクリプトが実行され、APIサーバーのコントローラなどのモジュールがロードされます。
https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
##### 4. MCPサーバーのコンテナを起動
```bash
docker-compose up -d
```
##### 5. AIエージェントがDockerコンテナを使用するように設定：
*例 Claude Desktop*
```json
{
"mcpServers": {
"touchdesigner": {
"command": "docker",
"args": [
"compose",
"-f",
"/path/to/your/touchdesigner-mcp/docker-compose.yml",
"exec",
"-i",
"touchdesigner-mcp-server",
"node",
"dist/cli.js",
"--stdio",
"--host=http://host.docker.internal"
]
}
}
}
```
*Windows システムでは、ドライブレターを含めてください。例：`C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
**カスタマイズ：** `--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
```json
"args": [
...,
"--stdio",
"--host=http://host.docker.internal",
"--port=9982"
]
```
</details>
## 接続確認
MCPサーバーが認識されていればセットアップは完了です。
認識されない場合は、AIエージェントを再起動してください。
起動時にエラーが表示される場合は、TouchDesignerを先に起動してからAIエージェントを再度起動してください。
TouchDesignerでAPIサーバーが実行されていれば、エージェントは提供されたツール等を通じてTouchDesignerを使用できます。
### ディレクトリ構造要件
**重要:** どの方法（Docker、npx）を使用する場合でも、正確なディレクトリ構造を維持してください：
```
td/
├── import_modules.py # モジュールローダースクリプト
├── mcp_webserver_base.tox # メインTouchDesignerコンポーネント
└── modules/ # Pythonモジュールディレクトリ
├── mcp/ # MCPコアロジック
├── utils/ # 共有ユーティリティ
└── td_server/ # 生成されたAPIサーバーコード
```
`mcp_webserver_base.tox` コンポーネントは相対パスを使用してPythonモジュールを検索します。これらのファイルを移動したり再編成したりすると、TouchDesignerでインポートエラーが発生します。
## MCPサーバーの機能
このサーバーは、Model Context Protocol (MCP) を通じてTouchDesigner への操作、および各種実装ドキュメントへの参照を可能にします。
### ツール (Tools)
ツールは、AIエージェントがTouchDesignerでアクションを実行できるようにします。
| ツール名 | 説明 |
| :-------------------------- | :--------------------------------------------- |
| `create_td_node` | 新しいノードを作成します。 |
| `delete_td_node` | 既存のノードを削除します。 |
| `exec_node_method` | ノードに対してPythonメソッドを呼び出します。 |
| `execute_python_script` | TD内で任意のPythonスクリプトを実行します。 |
| `get_td_class_details` | TD Pythonクラス/モジュールの詳細情報を取得します。 |
| `get_td_classes` | TouchDesigner Pythonクラスのリストを取得します。 |
| `get_td_info` | TDサーバー環境に関する情報を取得します。 |
| `get_td_node_parameters` | 特定ノードのパラメータを取得します。 |
| `get_td_nodes` | 親パス内のノードを取得します（オプションでフィルタリング）。 |
| `update_td_node_parameters` | 特定ノードのパラメータを更新します。 |
### プロンプト (Prompts)
プロンプトは、AIエージェントがTouchDesignerで特定のアクションを実行するための指示を提供します。
| プロンプト名 | 説明 |
| :-------------------------- | :--------------------------------------------- |
| `Search node` | ノードをファジー検索し、指定されたノード名、ファミリー、タイプに基づいて情報を取得します。 |
| `Node connection` | TouchDesigner内でノード同士を接続するための指示を提供します。 |
| `Check node errors` | 指定されたノードのエラーをチェックします。子ノードがあれば再帰的にチェックします。 |
### リソース (Resources)
未実装
## 開発者向け
### 開発のクイックスタート
1. **環境設定:**
```bash
# リポジトリをクローンして依存関係をインストール
git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
cd touchdesigner-mcp
npm install
```
2. **プロジェクトをビルド:**
```bash
make build # Docker-based build（推奨）
# または
npm run build # Node.js-based build
```
3. **利用可能なコマンド:**
```bash
npm run test # ユニットテストと統合テストを実行
npm run dev # デバッグ用MCPインスペクターを起動
```
**注意:** コードを更新した場合は、MCPサーバーとTouchDesignerの両方を再起動して変更を反映してください。
### プロジェクト構造の概要
```
├── src/ # MCPサーバーソースコード
│ ├── api/ # TD WebServerに対するOpenAPI仕様
│ ├── core/ # コアユーティリティ（ロガー、エラーハンドリング）
│ ├── features/ # MCP機能実装
│ │ ├── prompts/ # プロンプトハンドラ
│ │ ├── resources/ # リソースハンドラ
│ │ └── tools/ # ツールハンドラ (例: tdTools.ts)
│ ├── gen/ # OpenAPIスキーマから生成されたMCPサーバー向けコード
│ ├── server/ # MCPサーバーロジック (接続, メインサーバークラス)
│ ├── tdClient/ # TD接続API用クライアント
│ ├── index.ts # Node.jsサーバーのメインエントリーポイント
│ └── ...
├── td/ # TouchDesigner関連ファイル
│ ├── modules/ # TouchDesigner用Pythonモジュール
│ │ ├── mcp/ # TD内でMCPからのリクエストを処理するコアロジック
│ │ │ ├── controllers/ # APIリクエストコントローラ (api_controller.py, generated_handlers.py)
│ │ │ └── services/ # ビジネスロジック (api_service.py)
│ │ ├── td_server/ # OpenAPIスキーマから生成されたPythonモデルコード
│ │ └── utils/ # 共有Pythonユーティリティ
│ ├── templates/ # Pythonコード生成用Mustacheテンプレート
│ ├── genHandlers.js # generated_handlers.py 生成用のNode.jsスクリプト
│ ├── import_modules.py # TDへ APIサーバ関連モジュールをインポートするヘルパースクリプト
│ └── mcp_webserver_base.tox # メインTouchDesignerコンポーネント
├── tests/ # テストコード
│ ├── integration/
│ └── unit/
└── orval.config.ts # Orval 設定 (TSクライアント生成)
```
### APIコード生成ワークフロー
このプロジェクトでは、OpenAPIによるコード生成ツール ( Orval / openapi-generator-cli )を使用しています：
**API定義:** Node.js MCPサーバーとTouchDesigner内で実行されるPythonサーバー間のAPI規約は `src/api/index.yml` で定義されます。
1. **Pythonサーバー生成 (`npm run gen:webserver`):**
* Docker経由で `openapi-generator-cli` を使用します。
* `src/api/index.yml` を読み取ります。
* API定義に基づいてPythonサーバーのスケルトン (`td/modules/td_server/`) を生成します。このコードはWebServer DATを介してTouchDesigner内で実行されます。
* **Dockerがインストールされ、実行されている必要があります。**
2. **Pythonハンドラ生成 (`npm run gen:handlers`):**
* カスタムNode.jsスクリプト (`td/genHandlers.js`) とMustacheテンプレート (`td/templates/`) を使用します。
* 生成されたPythonサーバーコードまたはOpenAPI仕様を読み取ります。
* `td/modules/mcp/services/api_service.py` にあるビジネスロジックに接続するハンドラ実装 (`td/modules/mcp/controllers/generated_handlers.py`) を生成します。
3. **TypeScriptクライアント生成 (`npm run gen:mcp`):**
* `Orval` を使用し `openapi-generator-cli` がバンドルしたスキーマYAMLからAPIクライアントコードとToolの検証に用いるZodスキーマを生成します。
* Node.jsサーバーが WebServerDAT にリクエストを行うために使用する、型付けされたTypeScriptクライアント (`src/tdClient/`) を生成します。
ビルドプロセス (`npm run build`) は、必要なすべての生成ステップ (`npm run gen`) を実行し、その後にTypeScriptコンパイル (`tsc`) を行います。
## 開発で貢献
ぜひ一緒に改善しましょう！
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