touchdesigner-mcp-server 0.4.0-alpha.4 → 0.4.0-alpha.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.ja.md +89 -40
  2. package/README.md +128 -81
  3. package/dist/api/customInstance.js +1 -2
  4. package/dist/cli.js +52 -22
  5. package/dist/gen/endpoints/TouchDesignerAPI.js +11 -11
  6. package/dist/gen/mcp/touchDesignerAPI.zod.js +1 -1
  7. package/dist/server/connectionManager.js +3 -1
  8. package/dist/server/touchDesignerServer.js +1 -1
  9. package/package.json +5 -3
package/README.ja.md CHANGED
@@ -16,20 +16,52 @@ TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッ
16
16
  ## 利用方法
17
17
 
18
18
  <details>
19
- <summary>方法1: npx を利用する（クイックスタート）</summary>
19
+ <summary>方法1: Claude Desktop + Desktop Extensions（推奨）</summary>
20
+
21
+ ##### 1. ファイルをダウンロード：
22
+ [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases)から以下をダウンロード：
23
+ - **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
24
+ - **Desktop Extensions (.dxt)**: `touchdesigner-mcp.dxt`
25
+
26
+ ##### 2. TouchDesignerコンポーネントを設置：
27
+ 1. `touchdesigner-mcp-td.zip`を展開
28
+ 2. 展開したフォルダから`mcp_webserver_base.tox`を操作したいTouchDesignerプロジェクト直下にインポート
29
+ 例: `/project1/mcp_webserver_base`となるように配置
30
+
31
+ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
32
+
33
+ TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
34
+
35
+ ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
36
+
37
+ ##### 3. Desktop Extensionをインストール：
38
+ `touchdesigner-mcp.dxt`ファイルをダブルクリックしてClaude Desktopに拡張機能をインストール
39
+
40
+ https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
41
+
42
+ ##### 4. 拡張機能が自動的にTouchDesignerサーバー接続を処理
43
+
44
+ **⚠️ 重要:** TouchDesignerコンポーネントのディレクトリ構造は展開した状態を正確に保持してください。`mcp_webserver_base.tox`コンポーネントは`modules/`ディレクトリやその他のファイルへの相対パスを参照しています。
45
+
46
+ </details>
47
+
48
+ <details>
49
+ <summary>方法2: npxを利用する</summary>
20
50
 
21
51
  *Node.jsがインストールされていることが前提となります*
22
52
 
23
- ##### 1. TouchDesigner プロジェクトにMCP連携用のAPIサーバーを設置
53
+ ##### 1. TouchDesignerコンポーネントを設置：
54
+ 1. [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases)から`touchdesigner-mcp-td.zip`をダウンロード
55
+ 2. zipファイルを展開し、`mcp_webserver_base.tox`を操作したいTouchDesignerプロジェクト直下にインポート
56
+ 例: `/project1/mcp_webserver_base`となるように配置
57
+
58
+ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
24
59
 
25
- npxを使用する場合、TouchDesignerコンポーネントを別途ダウンロードする必要があります：
26
- 1. [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases)から `touchdesigner-mcp-td.zip` をダウンロード
27
- 2. zipファイルを展開したフォルダから `mcp_webserver_base.tox` を操作したいTouchDesignerプロジェクト直下にimportします。
28
- 例: `/project1/mcp_webserver_base` となるように配置
60
+ TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
29
61
 
30
- **⚠️ 重要:** ディレクトリの構造は展開した状態を正確に保持する必要があります。`mcp_webserver_base.tox` コンポーネントは `modules/` ディレクトリやその他のファイルへの相対パスを参照しています。展開したディレクトリ内のファイルを移動したり再編成したりしないでください。
62
+ ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
31
63
 
32
- ##### 2. AIエージェントの設定：
64
+ ##### 2. MCPサーバー設定：
33
65
 
34
66
  *例 Claude Desktop*
35
67
  ```json
@@ -37,19 +69,26 @@ npxを使用する場合、TouchDesignerコンポーネントを別途ダウン
37
69
  "mcpServers": {
38
70
  "touchdesigner": {
39
71
  "command": "npx",
40
- "args": [
41
- "-y",
42
- "touchdesigner-mcp-server@prerelease",
43
- "--stdio"
44
- ]
72
+ "args": ["-y", "touchdesigner-mcp-server@prerelease", "--stdio"]
45
73
  }
46
74
  }
47
75
  }
48
76
  ```
77
+
78
+ **カスタマイズ：** `--host`と`--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
79
+ ```json
80
+ "args": [
81
+ "-y",
82
+ "touchdesigner-mcp-server@prerelease",
83
+ "--stdio",
84
+ "--host=http://custom_host",
85
+ "--port=9982"
86
+ ]
87
+ ```
49
88
  </details>
50
89
 
51
90
  <details>
52
- <summary>方法2: Dockerイメージを利用</summary>
91
+ <summary>方法3: Dockerイメージを利用</summary>
53
92
 
54
93
  [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
55
94
 
@@ -59,34 +98,33 @@ git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
59
98
  cd touchdesigner-mcp
60
99
  ```
61
100
 
62
- ##### 2. 環境設定ファイルの設置とコードのビルド
63
- .envのテンプレートファイルをコピーし、必要に応じて TD_WEB_SERVER_HOST / TD_WEB_SERVER_PORT を調整してから Dockerイメージをビルドしてください。
64
-
101
+ ##### 2. Dockerイメージのビルド
65
102
  ```bash
66
- cp dotenv .env
103
+ git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
104
+ cd touchdesigner-mcp
67
105
  make build
68
106
  ```
69
107
 
70
- ##### 3. TouchDesigner プロジェクトにMCP連携用のAPIサーバーを設置
108
+ ##### 3. TouchDesignerプロジェクトにMCP連携用のAPIサーバーを設置
71
109
 
72
- TouchDesignerを起動し、`td/mcp_webserver_base.tox` コンポーネントを操作したいTouchDesignerプロジェクト直下にimportします。
73
- 例: `/project1/mcp_webserver_base` となるように配置
110
+ TouchDesignerを起動し、`td/mcp_webserver_base.tox`コンポーネントを操作したいTouchDesignerプロジェクト直下にインポートします。
111
+ 例: `/project1/mcp_webserver_base`となるように配置
74
112
 
75
- tox のimport により `td/import_modules.py` スクリプトが動作し、APIサーバのコントローラなどのモジュールがロードされます。
113
+ toxファイルのインポートにより`td/import_modules.py`スクリプトが実行され、APIサーバーのコントローラなどのモジュールがロードされます。
76
114
 
77
- ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/import.png)
115
+ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
78
116
 
79
- TouchDesigner のメニューから Textportを起動してサーバーの起動ログを確認することができます。
117
+ TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
80
118
 
81
119
  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
82
120
 
83
- #### 4. MCPサーバーのコンテナを起動
121
+ ##### 4. MCPサーバーのコンテナを起動
84
122
 
85
123
  ```bash
86
124
  docker-compose up -d
87
125
  ```
88
126
 
89
- ##### 5. AIエージェントがDockerコンテナを使用するように設定して起動：
127
+ ##### 5. AIエージェントがDockerコンテナを使用するように設定：
90
128
 
91
129
  *例 Claude Desktop*
92
130
  ```json
@@ -103,23 +141,34 @@ docker-compose up -d
103
141
  "touchdesigner-mcp-server",
104
142
  "node",
105
143
  "dist/cli.js",
106
- "--stdio"
144
+ "--stdio",
145
+ "--host=http://host.docker.internal"
107
146
  ]
108
147
  }
109
148
  }
110
149
  }
111
150
  ```
112
151
 
113
- *Windows環境では C:\\ の様にドライブレターを含めてください。 例. `C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
152
+ *Windows システムでは、ドライブレターを含めてください。例：`C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
153
+
154
+ **カスタマイズ：** `--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
155
+ ```json
156
+ "args": [
157
+ ...,
158
+ "--stdio",
159
+ "--host=http://host.docker.internal",
160
+ "--port=9982"
161
+ ]
162
+ ```
114
163
  </details>
115
164
 
116
165
 
117
166
  ## 接続確認
118
167
 
119
- MCPサーバーが認識されていればセットアップは完了です。
120
- 認識されない場合はAIエージェントを再起動するなどしてください。
121
- 起動時にエラーが表示される場合はTouchDesignerを先に起動してから再度エージェントを起動してください。
122
- TouchDesigner で APIサーバーが実行されていれば、エージェントは提供された ツール等を通じてTouchDesignerを使用できます。
168
+ MCPサーバーが認識されていればセットアップは完了です。
169
+ 認識されない場合は、AIエージェントを再起動してください。
170
+ 起動時にエラーが表示される場合は、TouchDesignerを先に起動してからAIエージェントを再度起動してください。
171
+ TouchDesignerでAPIサーバーが実行されていれば、エージェントは提供されたツール等を通じてTouchDesignerを使用できます。
123
172
 
124
173
  ### ディレクトリ構造要件
125
174
 
@@ -151,7 +200,7 @@ td/
151
200
  | :-------------------------- | :--------------------------------------------- |
152
201
  | `create_td_node` | 新しいノードを作成します。 |
153
202
  | `delete_td_node` | 既存のノードを削除します。 |
154
- | `exec_node_method`| ノードに対しPythonメソッドを呼び出します。 |
203
+ | `exec_node_method` | ノードに対してPythonメソッドを呼び出します。 |
155
204
  | `execute_python_script` | TD内で任意のPythonスクリプトを実行します。 |
156
205
  | `get_td_class_details` | TD Pythonクラス/モジュールの詳細情報を取得します。 |
157
206
  | `get_td_classes` | TouchDesigner Pythonクラスのリストを取得します。 |
@@ -181,8 +230,10 @@ td/
181
230
 
182
231
  1. **環境設定:**
183
232
  ```bash
184
- cp dotenv .env
185
- # .env ファイルの TD_WEB_SERVER_HOST, TD_WEB_SERVER_PORT を開発環境に合わせて変更
233
+ # リポジトリをクローンして依存関係をインストール
234
+ git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
235
+ cd touchdesigner-mcp
236
+ npm install
186
237
  ```
187
238
 
188
239
  2. **プロジェクトをビルド:**
@@ -194,7 +245,7 @@ td/
194
245
 
195
246
  3. **利用可能なコマンド:**
196
247
  ```bash
197
- npm run test # ユニットテストと結合テストを実行
248
+ npm run test # ユニットテストと統合テストを実行
198
249
  npm run dev # デバッグ用MCPインスペクターを起動
199
250
  ```
200
251
 
@@ -203,9 +254,9 @@ td/
203
254
  ### プロジェクト構造の概要
204
255
 
205
256
  ```
206
- ├── src/ # MCPサーバー ソースコード
257
+ ├── src/ # MCPサーバーソースコード
207
258
  │ ├── api/ # TD WebServerに対するOpenAPI仕様
208
- │ ├── core/ # コアユーティリティ (ロガー, エラーハンドリング)
259
+ │ ├── core/ # コアユーティリティ（ロガー、エラーハンドリング）
209
260
  │ ├── features/ # MCP機能実装
210
261
  │ │ ├── prompts/ # プロンプトハンドラ
211
262
  │ │ ├── resources/ # リソースハンドラ
@@ -229,8 +280,6 @@ td/
229
280
  ├── tests/ # テストコード
230
281
  │ ├── integration/
231
282
  │ └── unit/
232
- ├── .env # ローカル環境変数 (git無視)
233
- ├── dotenv # .env用テンプレート
234
283
  └── orval.config.ts # Orval 設定 (TSクライアント生成)
235
284
  ```
236
285
 
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # TouchDesigner MCP
2
2
 
3
- This is an implementation of an MCP (Model Context Protocol) server for TouchDesigner. The goal is to enable AI agents to control and operate TouchDesigner projects.
3
+ This is an implementation of an MCP (Model Context Protocol) server for TouchDesigner. Its goal is to enable AI agents to control and operate TouchDesigner projects.
4
4
 
5
5
  [English](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.md) / [日本語](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.ja.md)
6
6
 
@@ -16,80 +16,116 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
16
16
  ## Usage
17
17
 
18
18
  <details>
19
- <summary>Method 1: Using npx (Quick Start)</summary>
19
+ <summary>Method 1: Using Claude Desktop and Desktop Extensions (Recommended)</summary>
20
20
 
21
- *Requires Node.js to be installed*
21
+ ### 1. Download Files
22
+ Download the following from the [releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases):
23
+ - **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
24
+ - **Desktop Extension (.dxt)**: `touchdesigner-mcp.dxt`
22
25
 
23
- #### 1. Install the API Server in Your TouchDesigner Project:
26
+ ### 2. Set up TouchDesigner Components
27
+ 1. Extract the TouchDesigner components from `touchdesigner-mcp-td.zip`.
28
+ 2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
29
+ 3. Place it at `/project1/mcp_webserver_base`.
24
30
 
25
- Since you're using npx, you'll need to download the TouchDesigner components separately:
26
- 1. Download `touchdesigner-mcp-td.zip` from the [releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases)
27
- 2. Extract the zip file to get the directory
28
- 3. Import `mcp_webserver_base.tox` from the extracted files directly under the TouchDesigner project you want to control.
29
- Example: Place it as `/project1/mcp_webserver_base`
31
+ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
30
32
 
31
- **⚠️ Important:** The directory structure must be preserved exactly as extracted. The `mcp_webserver_base.tox` component references relative paths to the `modules/` directory and other files. Do not move or reorganize files within the extracted directory.
33
+ You can check the startup logs by opening the Textport from the TouchDesigner menu.
32
34
 
33
- #### 2. Configure your AI agent:
35
+ ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
36
+
37
+ ### 3. Install the Desktop Extension
38
+ Double-click the `touchdesigner-mcp.dxt` file to install the extension in Claude Desktop.
39
+
40
+ https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
41
+
42
+ ### 4. Connect to the Server
43
+ The extension will automatically handle the connection to the TouchDesigner server.
44
+
45
+ **⚠️ Important:** The directory structure must be preserved exactly as extracted. The `mcp_webserver_base.tox` component references relative paths to the `modules/` directory and other files.
46
+
47
+ </details>
48
+
49
+ <details>
50
+ <summary>Method 2: Using npx</summary>
51
+
52
+ *Requires Node.js to be installed.*
53
+
54
+ ### 1. Set up TouchDesigner Components
55
+ 1. Download and extract the TouchDesigner components from `touchdesigner-mcp-td.zip` ([releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases)).
56
+ 2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
57
+ 3. Place it at `/project1/mcp_webserver_base`.
58
+
59
+ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
60
+
61
+ You can check the startup logs by opening the Textport from the TouchDesigner menu.
34
62
 
35
- *Example for Claude Desktop*
63
+ ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
64
+
65
+ ### 2. Set up the MCP Server Configuration
66
+
67
+ *Example for Claude Desktop:*
36
68
  ```json
37
69
  {
38
70
  "mcpServers": {
39
71
  "touchdesigner": {
40
72
  "command": "npx",
41
- "args": [
42
- "-y",
43
- "touchdesigner-mcp-server@prerelease",
44
- "--stdio"
45
- ]
73
+ "args": ["-y", "touchdesigner-mcp-server@prerelease", "--stdio"]
46
74
  }
47
75
  }
48
76
  }
49
77
  ```
78
+
79
+ **Customization:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
80
+ ```json
81
+ "args": [
82
+ "-y",
83
+ "touchdesigner-mcp-server@prerelease",
84
+ "--stdio",
85
+ "--host=http://custom_host",
86
+ "--port=9982"
87
+ ]
88
+ ```
50
89
  </details>
51
90
 
52
91
  <details>
53
- <summary>Method 2: Using Docker Image</summary>
92
+ <summary>Method 3: Using a Docker Image</summary>
54
93
 
55
94
  [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
56
95
 
57
- #### 1. Clone the repository:
96
+ ### 1. Clone the repository
58
97
  ```bash
59
98
  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
60
99
  cd touchdesigner-mcp
61
100
  ```
62
101
 
63
- #### 2. Set up the environment file and build:
64
- Copy the template file and adjust the TD_WEB_SERVER_HOST and TD_WEB_SERVER_PORT as needed before building the Docker image.
65
-
102
+ ### 2. Build the Docker image
66
103
  ```bash
67
- cp dotenv .env
68
104
  make build
69
105
  ```
70
106
 
71
- #### 3. Install the API Server in Your TouchDesigner Project:
107
+ ### 3. Install the API Server in Your TouchDesigner Project
72
108
 
73
- Start TouchDesigner and import the `td/mcp_webserver_base.tox` component directly under the TouchDesigner project you want to control.
74
- Example: Place it as `/project1/mcp_webserver_base`
109
+ Start TouchDesigner and import the `td/mcp_webserver_base.tox` component into the project you want to control.
110
+ Example: Place it at `/project1/mcp_webserver_base`.
75
111
 
76
- Importing the tox will trigger the `td/import_modules.py` script, which loads modules such as API server controllers.
112
+ Importing the `.tox` file will trigger the `td/import_modules.py` script, which loads the necessary modules for the API server.
77
113
 
78
- ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/import.png)
114
+ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
79
115
 
80
- You can check boot logs by opening the Textport from the TouchDesigner menu.
116
+ You can check the startup logs by opening the Textport from the TouchDesigner menu.
81
117
 
82
118
  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
83
119
 
84
- #### 4. Start the MCP server container
120
+ ### 4. Start the MCP server container
85
121
 
86
122
  ```bash
87
123
  docker-compose up -d
88
124
  ```
89
125
 
90
- #### 5. Configure your AI agent to use the Docker container:
126
+ ### 5. Configure your AI agent to use the Docker container
91
127
 
92
- *Example for Claude Desktop*
128
+ *Example for Claude Desktop:*
93
129
  ```json
94
130
  {
95
131
  "mcpServers": {
@@ -104,27 +140,38 @@ Example: Place it as `/project1/mcp_webserver_base`
104
140
  "touchdesigner-mcp-server",
105
141
  "node",
106
142
  "dist/cli.js",
107
- "--stdio"
143
+ "--stdio",
144
+ "--host=http://host.docker.internal"
108
145
  ]
109
146
  }
110
147
  }
111
148
  }
112
- ```
149
+ ```
113
150
 
114
- *On Windows systems, include the drive letter like C: e.g. `C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
151
+ *On Windows systems, include the drive letter, e.g., `C:\path\to\your\touchdesigner-mcp\docker-compose.yml`.*
152
+
153
+ **Note:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
154
+ ```json
155
+ "args": [
156
+ ...,
157
+ "--stdio",
158
+ "--host=http://host.docker.internal",
159
+ "--port=9982"
160
+ ]
161
+ ```
115
162
  </details>
116
163
 
117
164
 
118
165
  ## Verify Connection
119
166
 
120
- If the MCP server is recognized, setup is complete.
167
+ If the MCP server is recognized, the setup is complete.
121
168
  If it's not recognized, try restarting your AI agent.
122
- If you see an error at startup, try launching the agent again after starting TouchDesigner first.
123
- When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate TouchDesigner.
169
+ If you see an error at startup, try launching the agent again after starting TouchDesigner.
170
+ When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate it.
124
171
 
125
172
  ### Directory Structure Requirements
126
173
 
127
- **Critical:** When using any method (Docker, npx), maintain the exact directory structure:
174
+ **Critical:** When using any method, you must maintain the original directory structure:
128
175
 
129
176
  ```
130
177
  td/
@@ -143,7 +190,7 @@ The `mcp_webserver_base.tox` component uses relative paths to locate Python modu
143
190
 
144
191
  ## MCP Server Features
145
192
 
146
- This server enables operations on TouchDesigner via the Model Context Protocol (MCP) and provides references to various implementation documents.
193
+ This server enables AI agents to perform operations in TouchDesigner using the Model Context Protocol (MCP).
147
194
 
148
195
  ### Tools
149
196
 
@@ -151,16 +198,16 @@ Tools allow AI agents to perform actions in TouchDesigner.
151
198
 
152
199
  | Tool Name | Description |
153
200
  | :---------------------- | :----------------------------------------------------------------- |
154
- | `create_td_node` | Create a new node. |
155
- | `delete_td_node` | Delete an existing node. |
156
- | `exec_node_method` | Call a Python method on a node. |
157
- | `execute_python_script` | Execute an arbitrary Python script in TD. |
158
- | `get_td_class_details` | Get details of a TD Python class/module. |
159
- | `get_td_classes` | Get a list of TouchDesigner Python classes. |
160
- | `get_td_info` | Get information about the TD server environment. |
161
- | `get_td_node_parameters`| Get parameters of a specific node. |
162
- | `get_td_nodes` | Get nodes under a parent path (optionally filtered). |
163
- | `update_td_node_parameters` | Update parameters of a specific node. |
201
+ | `create_td_node` | Creates a new node. |
202
+ | `delete_td_node` | Deletes an existing node. |
203
+ | `exec_node_method` | Calls a Python method on a node. |
204
+ | `execute_python_script` | Executes an arbitrary Python script in TouchDesigner. |
205
+ | `get_td_class_details` | Gets details of a TouchDesigner Python class or module. |
206
+ | `get_td_classes` | Gets a list of TouchDesigner Python classes. |
207
+ | `get_td_info` | Gets information about the TouchDesigner server environment. |
208
+ | `get_td_node_parameters`| Gets the parameters of a specific node. |
209
+ | `get_td_nodes` | Gets nodes under a parent path, with optional filtering. |
210
+ | `update_td_node_parameters` | Updates the parameters of a specific node. |
164
211
 
165
212
  ### Prompts
166
213
 
@@ -168,23 +215,25 @@ Prompts provide instructions for AI agents to perform specific actions in TouchD
168
215
 
169
216
  | Prompt Name | Description |
170
217
  | :------------------| :-------------------------------------------------------------------------- |
171
- | `Search node` | Fuzzy search for nodes and retrieve information based on name, family, type. |
172
- | `Node connection` | Provide instructions to connect nodes within TouchDesigner. |
173
- | `Check node errors`| Check errors for a specified node, recursively for child nodes if any. |
218
+ | `Search node` | Fuzzy searches for nodes and retrieves information based on name, family, or type. |
219
+ | `Node connection` | Provides instructions to connect nodes within TouchDesigner. |
220
+ | `Check node errors`| Checks for errors on a specified node, and recursively for its children. |
174
221
 
175
222
  ### Resources
176
223
 
177
- Not implemented
224
+ Not implemented.
178
225
 
179
226
 
180
227
  ## For Developers
181
228
 
182
229
  ### Quick Start for Development
183
230
 
184
- 1. **Setup environment:**
231
+ 1. **Set up your environment:**
185
232
  ```bash
186
- cp dotenv .env
187
- # Adjust TD_WEB_SERVER_HOST and TD_WEB_SERVER_PORT in .env file
233
+ # Clone and install dependencies
234
+ git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
235
+ cd touchdesigner-mcp
236
+ npm install
188
237
  ```
189
238
 
190
239
  2. **Build the project:**
@@ -197,63 +246,61 @@ Not implemented
197
246
  3. **Available commands:**
198
247
  ```bash
199
248
  npm run test # Run unit and integration tests
200
- npm run dev # Launch MCP inspector for debugging
249
+ npm run dev # Launch the MCP inspector for debugging
201
250
  ```
202
251
 
203
- **Note:** When you update the code, restart both the MCP server and TouchDesigner to reflect changes.
252
+ **Note:** When you update the code, you must restart both the MCP server and TouchDesigner to apply the changes.
204
253
 
205
254
  ### Project Structure Overview
206
255
 
207
256
  ```
208
257
  ├── src/ # MCP server source code
209
- │ ├── api/ # OpenAPI spec for TD WebServer
258
+ │ ├── api/ # OpenAPI spec for the TouchDesigner WebServer
210
259
  │ ├── core/ # Core utilities (logger, error handling)
211
260
  │ ├── features/ # MCP feature implementations
212
261
  │ │ ├── prompts/ # Prompt handlers
213
262
  │ │ ├── resources/ # Resource handlers
214
263
  │ │ └── tools/ # Tool handlers (e.g., tdTools.ts)
215
- │ ├── gen/ # Code generated from OpenAPI schema for MCP server
264
+ │ ├── gen/ # Code generated from the OpenAPI schema for the MCP server
216
265
  │ ├── server/ # MCP server logic (connections, main server class)
217
- │ ├── tdClient/ # TD connection API client
218
- │ ├── index.ts # Main entry point for Node.js server
266
+ │ ├── tdClient/ # TouchDesigner connection API client
267
+ │ ├── index.ts # Main entry point for the Node.js server
219
268
  │ └── ...
220
- ├── td/ # TouchDesigner related files
269
+ ├── td/ # TouchDesigner-related files
221
270
  │ ├── modules/ # Python modules for TouchDesigner
222
- │ │ ├── mcp/ # Core logic for handling MCP requests in TD
271
+ │ │ ├── mcp/ # Core logic for handling MCP requests in TouchDesigner
223
272
  │ │ │ ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
224
273
  │ │ │ └── services/ # Business logic (api_service.py)
225
- │ │ ├── td_server/ # Python model code generated from OpenAPI schema
274
+ │ │ ├── td_server/ # Python model code generated from the OpenAPI schema
226
275
  │ │ └── utils/ # Shared Python utilities
227
276
  │ ├── templates/ # Mustache templates for Python code generation
228
277
  │ ├── genHandlers.js # Node.js script for generating generated_handlers.py
229
- │ ├── import_modules.py # Helper script to import API server modules into TD
278
+ │ ├── import_modules.py # Helper script to import API server modules into TouchDesigner
230
279
  │ └── mcp_webserver_base.tox # Main TouchDesigner component
231
280
  ├── tests/ # Test code
232
281
  │ ├── integration/
233
282
  │ └── unit/
234
- ├── .env # Local environment variables (git ignored)
235
- ├── dotenv # Template for .env
236
- └── orval.config.ts # Orval config (TS client generation)
283
+ └── orval.config.ts # Orval config (TypeScript client generation)
237
284
  ```
238
285
 
239
286
 
240
287
  ### API Code Generation Workflow
241
288
 
242
- This project uses OpenAPI-based code generation tools (Orval / openapi-generator-cli):
289
+ This project uses OpenAPI-based code generation tools (Orval and openapi-generator-cli).
243
290
 
244
291
  **API Definition:** The API contract between the Node.js MCP server and the Python server running inside TouchDesigner is defined in `src/api/index.yml`.
245
292
 
246
293
  1. **Python server generation (`npm run gen:webserver`):**
247
294
  * Uses `openapi-generator-cli` via Docker.
248
295
  * Reads `src/api/index.yml`.
249
- * Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner via WebServer DAT.
296
+ * Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner's WebServer DAT.
250
297
  * **Requires Docker to be installed and running.**
251
298
  2. **Python handler generation (`npm run gen:handlers`):**
252
299
  * Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
253
300
  * Reads the generated Python server code or OpenAPI spec.
254
- * Generates handler implementations (`td/modules/mcp/controllers/generated_handlers.py`) that connect to business logic in `td/modules/mcp/services/api_service.py`.
301
+ * Generates handler implementations (`td/modules/mcp/controllers/generated_handlers.py`) that connect to the business logic in `td/modules/mcp/services/api_service.py`.
255
302
  3. **TypeScript client generation (`npm run gen:mcp`):**
256
- * Uses `Orval` to generate API client code and Zod schemas for tool validation from the schema YAML bundled by `openapi-generator-cli`.
303
+ * Uses `Orval` to generate an API client and Zod schemas for tool validation from the schema YAML, which is bundled by `openapi-generator-cli`.
257
304
  * Generates a typed TypeScript client (`src/tdClient/`) used by the Node.js server to make requests to the WebServer DAT.
258
305
 
259
306
  The build process (`npm run build`) runs all necessary generation steps (`npm run gen`), followed by TypeScript compilation (`tsc`).
@@ -262,13 +309,13 @@ The build process (`npm run build`) runs all necessary generation steps (`npm ru
262
309
 
263
310
  We welcome your contributions!
264
311
 
265
- 1. Fork the repository
266
- 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
267
- 3. Make your changes
268
- 4. Add tests and ensure everything works (`npm test`)
269
- 5. Commit your changes (`git commit -m 'Add some amazing feature'`)
270
- 6. Push to your branch (`git push origin feature/amazing-feature`)
271
- 7. Open a pull request
312
+ 1. Fork the repository.
313
+ 2. Create a feature branch (`git checkout -b feature/amazing-feature`).
314
+ 3. Make your changes.
315
+ 4. Add tests and ensure everything works (`npm test`).
316
+ 5. Commit your changes (`git commit -m 'Add some amazing feature'`).
317
+ 6. Push to your branch (`git push origin feature/amazing-feature`).
318
+ 7. Open a pull request.
272
319
 
273
320
  Please always include appropriate tests when making implementation changes.
274
321
 
package/dist/api/customInstance.js CHANGED
@@ -1,6 +1,5 @@
1
1
  import Axios from "axios";
2
- const API_BASE_URL = `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}`;
3
- export const AXIOS_INSTANCE = Axios.create(API_BASE_URL ? { baseURL: API_BASE_URL } : {});
2
+ export const AXIOS_INSTANCE = Axios.create();
4
3
  export const customInstance = (config, options) => {
5
4
  const source = Axios.CancelToken.source();
6
5
  const promise = AXIOS_INSTANCE({
package/dist/cli.js CHANGED
@@ -1,37 +1,67 @@
1
1
  #!/usr/bin/env node
2
- import { resolve } from "node:path";
3
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
- import { config } from "dotenv";
5
3
  import { TouchDesignerServer } from "./server/touchDesignerServer.js";
6
- config({ path: resolve(process.cwd(), ".env") });
4
+ // Note: Environment variables should be set by the Desktop Extensions runtime or CLI arguments
5
+ /**
6
+ * Parse command line arguments
7
+ */
8
+ export function parseArgs(args) {
9
+ const argsToProcess = args || process.argv.slice(2);
10
+ const parsed = {
11
+ host: "http://localhost",
12
+ port: 9981,
13
+ };
14
+ for (let i = 0; i < argsToProcess.length; i++) {
15
+ const arg = argsToProcess[i];
16
+ if (arg.startsWith("--host=")) {
17
+ parsed.host = arg.split("=")[1];
18
+ }
19
+ else if (arg.startsWith("--port=")) {
20
+ parsed.port = Number.parseInt(arg.split("=")[1], 10);
21
+ }
22
+ }
23
+ return parsed;
24
+ }
25
+ /**
26
+ * Determine if the server should run in stdio mode
27
+ */
28
+ export function isStdioMode(nodeEnv, argv) {
29
+ const env = nodeEnv ?? process.env.NODE_ENV;
30
+ const args = argv ?? process.argv;
31
+ return env === "cli" || args.includes("--stdio");
32
+ }
7
33
  /**
8
34
  * Start TouchDesigner MCP server
9
35
  */
10
- export async function startServer() {
11
- const isStdioMode = process.env.NODE_ENV === "cli" || process.argv.includes("--stdio");
36
+ export async function startServer(params) {
12
37
  try {
13
- const server = new TouchDesignerServer();
14
- if (isStdioMode) {
15
- const transport = new StdioServerTransport();
16
- const result = await server.connect(transport);
17
- if (!result.success) {
18
- throw new Error(`Failed to connect: ${result.error.message}`);
19
- }
20
- }
21
- else {
38
+ const isStdioModeFlag = isStdioMode(params?.nodeEnv, params?.argv);
39
+ if (!isStdioModeFlag) {
22
40
  throw new Error("Sorry, this server is not yet available in the browser. Please use the CLI mode.");
23
41
  }
42
+ // Parse command line arguments and set environment variables
43
+ const args = parseArgs(params?.argv);
44
+ process.env.TD_WEB_SERVER_HOST = args.host;
45
+ process.env.TD_WEB_SERVER_PORT = args.port.toString();
46
+ const server = new TouchDesignerServer();
47
+ const transport = new StdioServerTransport();
48
+ const result = await server.connect(transport);
49
+ if (!result.success) {
50
+ throw new Error(`Failed to connect: ${result.error.message}`);
51
+ }
24
52
  }
25
53
  catch (error) {
26
54
  const errorMessage = error instanceof Error ? error.message : String(error);
27
- console.error(`Failed to initialize server: ${errorMessage}`);
28
- process.exit(1);
55
+ throw new Error(`Failed to initialize server: ${errorMessage}`);
29
56
  }
30
57
  }
31
58
  // Start server if this file is executed directly
32
- if (process.argv[1]) {
33
- startServer().catch((error) => {
34
- console.error("Failed to start server:", error);
35
- process.exit(1);
36
- });
37
- }
59
+ startServer({
60
+ nodeEnv: process.env.NODE_ENV,
61
+ argv: process.argv,
62
+ }).catch((error) => {
63
+ console.error("Failed to start server:", error);
64
+ if (process.env.NODE_ENV === "test")
65
+ return;
66
+ process.exit(1);
67
+ });
package/dist/gen/endpoints/TouchDesignerAPI.js CHANGED
@@ -3,7 +3,7 @@
3
3
  * Do not edit manually.
4
4
  * TouchDesigner API
5
5
  * OpenAPI schema for generating TouchDesigner API client code
6
- * OpenAPI spec version: 0.4.0-alpha.4
6
+ * OpenAPI spec version: 0.4.0-alpha.6
7
7
  */
8
8
  import { customInstance } from '../../api/customInstance.js';
9
9
  // eslint-disable-next-line @typescript-eslint/no-redeclare
@@ -34,7 +34,7 @@ export const TdPythonClassDetailsType = {
34
34
  * @summary Delete an existing node
35
35
  */
36
36
  export const deleteNode = (params, options) => {
37
- return customInstance({ url: `http://localhost:9981/api/nodes`, method: 'DELETE',
37
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'DELETE',
38
38
  params
39
39
  }, options);
40
40
  };
@@ -42,7 +42,7 @@ export const deleteNode = (params, options) => {
42
42
  * @summary Get nodes in the path
43
43
  */
44
44
  export const getNodes = (params, options) => {
45
- return customInstance({ url: `http://localhost:9981/api/nodes`, method: 'GET',
45
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'GET',
46
46
  params
47
47
  }, options);
48
48
  };
@@ -50,7 +50,7 @@ export const getNodes = (params, options) => {
50
50
  * @summary Create a new node
51
51
  */
52
52
  export const createNode = (createNodeRequest, options) => {
53
- return customInstance({ url: `http://localhost:9981/api/nodes`, method: 'POST',
53
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'POST',
54
54
  headers: { 'Content-Type': 'application/json', },
55
55
  data: createNodeRequest
56
56
  }, options);
@@ -60,7 +60,7 @@ export const createNode = (createNodeRequest, options) => {
60
60
  * @summary Get node detail
61
61
  */
62
62
  export const getNodeDetail = (params, options) => {
63
- return customInstance({ url: `http://localhost:9981/api/nodes/detail`, method: 'GET',
63
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes/detail`, method: 'GET',
64
64
  params
65
65
  }, options);
66
66
  };
@@ -68,7 +68,7 @@ export const getNodeDetail = (params, options) => {
68
68
  * @summary Update node properties
69
69
  */
70
70
  export const updateNode = (updateNodeRequest, options) => {
71
- return customInstance({ url: `http://localhost:9981/api/nodes/detail`, method: 'PATCH',
71
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes/detail`, method: 'PATCH',
72
72
  headers: { 'Content-Type': 'application/json', },
73
73
  data: updateNodeRequest
74
74
  }, options);
@@ -78,7 +78,7 @@ export const updateNode = (updateNodeRequest, options) => {
78
78
  * @summary Get a list of Python classes and modules
79
79
  */
80
80
  export const getTdPythonClasses = (options) => {
81
- return customInstance({ url: `http://localhost:9981/api/td/classes`, method: 'GET'
81
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/classes`, method: 'GET'
82
82
  }, options);
83
83
  };
84
84
  /**
@@ -86,7 +86,7 @@ export const getTdPythonClasses = (options) => {
86
86
  * @summary Get details of a specific Python class or module
87
87
  */
88
88
  export const getTdPythonClassDetails = (className, options) => {
89
- return customInstance({ url: `http://localhost:9981/api/td/classes/${className}`, method: 'GET'
89
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/classes/${className}`, method: 'GET'
90
90
  }, options);
91
91
  };
92
92
  /**
@@ -97,7 +97,7 @@ This allows operations equivalent to TouchDesigner's Python API such as
97
97
  * @summary Call a method of the specified node
98
98
  */
99
99
  export const execNodeMethod = (execNodeMethodRequest, options) => {
100
- return customInstance({ url: `http://localhost:9981/api/td/nodes/exec`, method: 'POST',
100
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/nodes/exec`, method: 'POST',
101
101
  headers: { 'Content-Type': 'application/json', },
102
102
  data: execNodeMethodRequest
103
103
  }, options);
@@ -111,7 +111,7 @@ This endpoint allows you to interact with TouchDesigner nodes programmatically.
111
111
  * @summary Execute python code on the server
112
112
  */
113
113
  export const execPythonScript = (execPythonScriptRequest, options) => {
114
- return customInstance({ url: `http://localhost:9981/api/td/server/exec`, method: 'POST',
114
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/server/exec`, method: 'POST',
115
115
  headers: { 'Content-Type': 'application/json', },
116
116
  data: execPythonScriptRequest
117
117
  }, options);
@@ -121,6 +121,6 @@ export const execPythonScript = (execPythonScriptRequest, options) => {
121
121
  * @summary Get TouchDesigner information
122
122
  */
123
123
  export const getTdInfo = (options) => {
124
- return customInstance({ url: `http://localhost:9981/api/td/server/td`, method: 'GET'
124
+ return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/server/td`, method: 'GET'
125
125
  }, options);
126
126
  };
package/dist/gen/mcp/touchDesignerAPI.zod.js CHANGED
@@ -3,7 +3,7 @@
3
3
  * Do not edit manually.
4
4
  * TouchDesigner API
5
5
  * OpenAPI schema for generating TouchDesigner API client code
6
- * OpenAPI spec version: 0.4.0-alpha.4
6
+ * OpenAPI spec version: 0.4.0-alpha.6
7
7
  */
8
8
  import { z as zod } from 'zod';
9
9
  /**
package/dist/server/connectionManager.js CHANGED
@@ -24,10 +24,12 @@ export class ConnectionManager {
24
24
  try {
25
25
  await this.server.connect(transport);
26
26
  this.logger.log(`Server connected and ready to process requests: ${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}`);
27
+ // Connection will be checked when tools are actually used
27
28
  const connectionResult = await this.checkTDConnection();
28
29
  if (!connectionResult.success) {
29
- throw new Error(`Failed to connect to TouchDesigner: ${connectionResult.error.message}`);
30
+ throw new Error(`Failed to connect to TouchDesigner. The mcp_webserver_base on TouchDesigner not currently available: ${connectionResult.error.message}`);
30
31
  }
32
+ this.logger.log("TouchDesigner connection verified");
31
33
  return createSuccessResult(undefined);
32
34
  }
33
35
  catch (error) {
package/dist/server/touchDesignerServer.js CHANGED
@@ -18,7 +18,7 @@ export class TouchDesignerServer {
18
18
  constructor() {
19
19
  this.server = new McpServer({
20
20
  name: "TouchDesigner",
21
- version: "0.4.0-alpha.4",
21
+ version: "0.4.0-alpha.6",
22
22
  }, {
23
23
  capabilities: {
24
24
  prompts: {},
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "touchdesigner-mcp-server",
3
- "version": "0.4.0-alpha.4",
3
+ "version": "0.4.0-alpha.6",
4
4
  "description": "MCP server for TouchDesigner",
5
5
  "repository": {
6
6
  "type": "git",
@@ -28,7 +28,6 @@
28
28
  "@types/ws": "^8.18.1",
29
29
  "@types/yargs": "^17.0.33",
30
30
  "axios": "^1.10.0",
31
- "dotenv": "^17.0.0",
32
31
  "zod": "^3.25.67"
33
32
  },
34
33
  "devDependencies": {
@@ -37,6 +36,7 @@
37
36
  "@types/jsdom": "^21.1.7",
38
37
  "@types/node": "^24.0.7",
39
38
  "@vitest/coverage-v8": "^3.2.4",
39
+ "archiver": "^7.0.1",
40
40
  "msw": "^2.10.2",
41
41
  "mustache": "^4.2.0",
42
42
  "npm-run-all": "^4.1.5",
@@ -61,6 +61,7 @@
61
61
  "build": "run-s build:*",
62
62
  "build:gen": "npm run gen",
63
63
  "build:dist": "tsc && shx chmod +x dist/*.js",
64
+ "build:dxt": "npx @anthropic-ai/dxt pack",
64
65
  "lint": "run-p lint:*",
65
66
  "lint:biome": "biome check",
66
67
  "lint:tsc": "tsc --noEmit",
@@ -73,7 +74,8 @@
73
74
  "gen": "run-s gen:*",
74
75
  "gen:webserver": "openapi-generator-cli generate -i ./src/api/index.yml -g python-flask -o ./td/modules/td_server",
75
76
  "gen:handlers": "node td/genHandlers.js",
76
- "gen:mcp": "orval --config ./orval.config.ts"
77
+ "gen:mcp": "orval --config ./orval.config.ts",
78
+ "package:dxt": "run-s build build:dxt"
77
79
  },
78
80
  "files": [
79
81
  "dist/**/*"