touchdesigner-mcp-server 1.1.1 → 1.2.0

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 (28) hide show
  1. package/README.ja.md +79 -30
  2. package/README.md +79 -30
  3. package/dist/cli.js +1 -1
  4. package/dist/core/constants.js +1 -0
  5. package/dist/features/tools/handlers/tdTools.js +162 -50
  6. package/dist/features/tools/metadata/touchDesignerToolMetadata.js +402 -0
  7. package/dist/features/tools/presenter/classListFormatter.js +187 -0
  8. package/dist/features/tools/presenter/index.js +11 -0
  9. package/dist/features/tools/presenter/markdownRenderer.js +25 -0
  10. package/dist/features/tools/presenter/nodeDetailsFormatter.js +140 -0
  11. package/dist/features/tools/presenter/nodeListFormatter.js +124 -0
  12. package/dist/features/tools/presenter/operationFormatter.js +117 -0
  13. package/dist/features/tools/presenter/presenter.js +62 -0
  14. package/dist/features/tools/presenter/responseFormatter.js +66 -0
  15. package/dist/features/tools/presenter/scriptResultFormatter.js +171 -0
  16. package/dist/features/tools/presenter/templates/markdown/classDetailsSummary.md +13 -0
  17. package/dist/features/tools/presenter/templates/markdown/classListSummary.md +7 -0
  18. package/dist/features/tools/presenter/templates/markdown/default.md +3 -0
  19. package/dist/features/tools/presenter/templates/markdown/detailedPayload.md +5 -0
  20. package/dist/features/tools/presenter/templates/markdown/nodeDetailsSummary.md +10 -0
  21. package/dist/features/tools/presenter/templates/markdown/nodeListSummary.md +8 -0
  22. package/dist/features/tools/presenter/templates/markdown/scriptSummary.md +15 -0
  23. package/dist/features/tools/presenter/toolMetadataFormatter.js +118 -0
  24. package/dist/features/tools/types.js +26 -1
  25. package/dist/gen/endpoints/TouchDesignerAPI.js +1 -1
  26. package/dist/gen/mcp/touchDesignerAPI.zod.js +1 -1
  27. package/dist/server/touchDesignerServer.js +1 -1
  28. package/package.json +7 -6
package/README.ja.md CHANGED
@@ -9,37 +9,77 @@ TouchDesignerのためのMCP(Model Context Protocol) サーバー実装です。
9
9
  [![demo clip](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/particle_on_youtube.png)](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)
10
10
 
11
11
  TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッジとして機能し、AIエージェントが以下のことが可能になります
12
+
12
13
  - ノードの作成、変更、削除
13
14
  - ノードプロパティやプロジェクト構造の照会
14
15
  - PythonスクリプトによるTouchDesignerのプログラム的制御
15
16
 
17
+ ## アーキテクチャ
18
+
19
+ ```mermaid
20
+ flowchart LR
21
+ A["🤖<br/>MCP client<br/>(Claude / Codex / ...)"]
22
+
23
+ subgraph S [Node.js MCP server]
24
+ B1["🧰<br/>Tools & prompts<br/>(src/features/tools)"]
25
+ B2["🖌️<br/>Presenters & formatters<br/>(markdown output)"]
26
+ B3["🌐<br/>OpenAPI HTTP client<br/>(src/tdClient)"]
27
+ end
28
+
29
+ subgraph T [TouchDesigner project]
30
+ C1["🧩<br/>WebServer DAT<br/>(mcp_webserver_base.tox)"]
31
+ C2["🐍<br/>Python controllers / services<br/>(td/modules/mcp)"]
32
+ C3["🎛️<br/>Project nodes & parameters<br/>(/project1/...)"]
33
+ end
34
+
35
+ A --> B1
36
+ B1 --> B2
37
+ B1 --> B3
38
+ B2 --> A
39
+ B3 <--> C1
40
+ C1 <--> C2
41
+ C2 <--> C3
42
+
43
+ %% Higher-contrast colors for readability
44
+ classDef client fill:#d8e8ff,stroke:#1f6feb,stroke-width:2px,color:#111,font-weight:bold
45
+ classDef server fill:#efe1ff,stroke:#8250df,stroke-width:2px,color:#111,font-weight:bold
46
+ classDef td fill:#d7f5e3,stroke:#2f9e44,stroke-width:2px,color:#111,font-weight:bold
47
+ class A client;
48
+ class B1,B2,B3 server;
49
+ class C1,C2,C3 td;
50
+ ```
51
+
16
52
  ## 利用方法
17
53
 
18
54
  <details>
19
- <summary>方法1: Claude Desktop + Desktop Extensions(推奨)</summary>
55
+ <summary>方法1: Claude Desktop + MCP Bundle(推奨)</summary>
56
+
57
+ ##### 1. ファイルをダウンロード
20
58
 
21
- ##### 1. ファイルをダウンロード:
22
59
  [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)から以下をダウンロード:
60
+
23
61
  - **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
24
- - **Desktop Extensions (.dxt)**: `touchdesigner-mcp.dxt`
62
+ - **[MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (.mcpb)**: `touchdesigner-mcp.mcpb`
63
+
64
+ ##### 2. TouchDesignerコンポーネントを設置
25
65
 
26
- ##### 2. TouchDesignerコンポーネントを設置:
27
66
  1. `touchdesigner-mcp-td.zip`を展開
28
67
  2. 展開したフォルダから`mcp_webserver_base.tox`を操作したいTouchDesignerプロジェクト直下にインポート
29
68
  例: `/project1/mcp_webserver_base`となるように配置
30
69
 
31
- https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
70
+ <https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
32
71
 
33
72
  TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
34
73
 
35
74
  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
36
75
 
37
- ##### 3. Desktop Extensionをインストール:
38
- `touchdesigner-mcp.dxt`ファイルをダブルクリックしてClaude Desktopに拡張機能をインストール
76
+ ##### 3. MCP Bundleをインストール
39
77
 
40
- https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
78
+ `touchdesigner-mcp.mcpb`ファイルをダブルクリックしてClaude DesktopにMCP Bundleをインストール
41
79
 
42
- ##### 4. 拡張機能が自動的にTouchDesignerサーバー接続を処理
80
+ <https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
81
+
82
+ ##### 4. MCP Bundleが自動的にTouchDesignerサーバー接続を処理
43
83
 
44
84
  **⚠️ 重要:** TouchDesignerコンポーネントのディレクトリ構造は展開した状態を正確に保持してください。`mcp_webserver_base.tox`コンポーネントは`modules/`ディレクトリやその他のファイルへの相対パスを参照しています。
45
85
 
@@ -50,20 +90,22 @@ https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
50
90
 
51
91
  *Node.jsがインストールされていることが前提となります*
52
92
 
53
- ##### 1. TouchDesignerコンポーネントを設置:
93
+ ##### 1. TouchDesignerコンポーネントを設置
94
+
54
95
  1. [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)から`touchdesigner-mcp-td.zip`をダウンロード
55
96
  2. zipファイルを展開し、`mcp_webserver_base.tox`を操作したいTouchDesignerプロジェクト直下にインポート
56
97
  例: `/project1/mcp_webserver_base`となるように配置
57
98
 
58
- https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
99
+ <https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
59
100
 
60
101
  TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
61
102
 
62
103
  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
63
104
 
64
- ##### 2. MCPサーバー設定:
105
+ ##### 2. MCPサーバー設定
65
106
 
66
107
  *例 Claude Desktop*
108
+
67
109
  ```json
68
110
  {
69
111
  "mcpServers": {
@@ -76,6 +118,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
76
118
  ```
77
119
 
78
120
  **カスタマイズ:** `--host`と`--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます:
121
+
79
122
  ```json
80
123
  "args": [
81
124
  "-y",
@@ -85,6 +128,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
85
128
  "--port=9982"
86
129
  ]
87
130
  ```
131
+
88
132
  </details>
89
133
 
90
134
  <details>
@@ -92,13 +136,15 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
92
136
 
93
137
  [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
94
138
 
95
- ##### 1. リポジトリをクローン:
139
+ ##### 1. リポジトリをクローン
140
+
96
141
  ```bash
97
142
  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
98
143
  cd touchdesigner-mcp
99
144
  ```
100
145
 
101
146
  ##### 2. Dockerイメージのビルド
147
+
102
148
  ```bash
103
149
  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
104
150
  cd touchdesigner-mcp
@@ -112,7 +158,7 @@ TouchDesignerを起動し、`td/mcp_webserver_base.tox`コンポーネントを
112
158
 
113
159
  toxファイルのインポートにより`td/import_modules.py`スクリプトが実行され、APIサーバーのコントローラなどのモジュールがロードされます。
114
160
 
115
- https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
161
+ <https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
116
162
 
117
163
  TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
118
164
 
@@ -124,9 +170,10 @@ TouchDesignerのメニューからTextportを起動してサーバーの起動
124
170
  docker-compose up -d
125
171
  ```
126
172
 
127
- ##### 5. AIエージェントがDockerコンテナを使用するように設定:
173
+ ##### 5. AIエージェントがDockerコンテナを使用するように設定
128
174
 
129
175
  *例 Claude Desktop*
176
+
130
177
  ```json
131
178
  {
132
179
  "mcpServers": {
@@ -152,6 +199,7 @@ docker-compose up -d
152
199
  *Windows システムでは、ドライブレターを含めてください。例:`C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
153
200
 
154
201
  **カスタマイズ:** `--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます:
202
+
155
203
  ```json
156
204
  "args": [
157
205
  ...,
@@ -160,8 +208,8 @@ docker-compose up -d
160
208
  "--port=9982"
161
209
  ]
162
210
  ```
163
- </details>
164
211
 
212
+ </details>
165
213
 
166
214
  ## 接続確認
167
215
 
@@ -223,12 +271,12 @@ td/
223
271
 
224
272
  未実装
225
273
 
226
-
227
274
  ## 開発者向け
228
275
 
229
276
  ### 開発のクイックスタート
230
277
 
231
278
  1. **環境設定:**
279
+
232
280
  ```bash
233
281
  # リポジトリをクローンして依存関係をインストール
234
282
  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
@@ -237,6 +285,7 @@ td/
237
285
  ```
238
286
 
239
287
  2. **プロジェクトをビルド:**
288
+
240
289
  ```bash
241
290
  make build # Docker-based build(推奨)
242
291
  # または
@@ -244,6 +293,7 @@ td/
244
293
  ```
245
294
 
246
295
  3. **利用可能なコマンド:**
296
+
247
297
  ```bash
248
298
  npm run test # ユニットテストと統合テストを実行
249
299
  npm run dev # デバッグ用MCPインスペクターを起動
@@ -283,25 +333,24 @@ td/
283
333
  └── orval.config.ts # Orval 設定 (TSクライアント生成)
284
334
  ```
285
335
 
286
-
287
336
  ### APIコード生成ワークフロー
288
337
 
289
338
  このプロジェクトでは、OpenAPIによるコード生成ツール ( Orval / openapi-generator-cli )を使用しています:
290
339
 
291
340
  **API定義:** Node.js MCPサーバーとTouchDesigner内で実行されるPythonサーバー間のAPI規約は `src/api/index.yml` で定義されます。
292
341
 
293
- 1. **Pythonサーバー生成 (`npm run gen:webserver`):**
294
- * Docker経由で `openapi-generator-cli` を使用します。
295
- * `src/api/index.yml` を読み取ります。
296
- * API定義に基づいてPythonサーバーのスケルトン (`td/modules/td_server/`) を生成します。このコードはWebServer DATを介してTouchDesigner内で実行されます。
297
- * **Dockerがインストールされ、実行されている必要があります。**
298
- 2. **Pythonハンドラ生成 (`npm run gen:handlers`):**
299
- * カスタムNode.jsスクリプト (`td/genHandlers.js`) とMustacheテンプレート (`td/templates/`) を使用します。
300
- * 生成されたPythonサーバーコードまたはOpenAPI仕様を読み取ります。
301
- * `td/modules/mcp/services/api_service.py` にあるビジネスロジックに接続するハンドラ実装 (`td/modules/mcp/controllers/generated_handlers.py`) を生成します。
302
- 3. **TypeScriptクライアント生成 (`npm run gen:mcp`):**
303
- * `Orval` を使用し `openapi-generator-cli` がバンドルしたスキーマYAMLからAPIクライアントコードとToolの検証に用いるZodスキーマを生成します。
304
- * Node.jsサーバーが WebServerDAT にリクエストを行うために使用する、型付けされたTypeScriptクライアント (`src/tdClient/`) を生成します。
342
+ 1. **Pythonサーバー生成 (`npm run gen:webserver`):**
343
+ - Docker経由で `openapi-generator-cli` を使用します。
344
+ - `src/api/index.yml` を読み取ります。
345
+ - API定義に基づいてPythonサーバーのスケルトン (`td/modules/td_server/`) を生成します。このコードはWebServer DATを介してTouchDesigner内で実行されます。
346
+ - **Dockerがインストールされ、実行されている必要があります。**
347
+ 2. **Pythonハンドラ生成 (`npm run gen:handlers`):**
348
+ - カスタムNode.jsスクリプト (`td/genHandlers.js`) とMustacheテンプレート (`td/templates/`) を使用します。
349
+ - 生成されたPythonサーバーコードまたはOpenAPI仕様を読み取ります。
350
+ - `td/modules/mcp/services/api_service.py` にあるビジネスロジックに接続するハンドラ実装 (`td/modules/mcp/controllers/generated_handlers.py`) を生成します。
351
+ 3. **TypeScriptクライアント生成 (`npm run gen:mcp`):**
352
+ - `Orval` を使用し `openapi-generator-cli` がバンドルしたスキーマYAMLからAPIクライアントコードとToolの検証に用いるZodスキーマを生成します。
353
+ - Node.jsサーバーが WebServerDAT にリクエストを行うために使用する、型付けされたTypeScriptクライアント (`src/tdClient/`) を生成します。
305
354
 
306
355
  ビルドプロセス (`npm run build`) は、必要なすべての生成ステップ (`npm run gen`) を実行し、その後にTypeScriptコンパイル (`tsc`) を行います。
307
356
 
package/README.md CHANGED
@@ -9,38 +9,79 @@ This is an implementation of an MCP (Model Context Protocol) server for TouchDes
9
9
  [![demo clip](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/particle_on_youtube.png)](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)
10
10
 
11
11
  TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebServer DAT, enabling AI agents to:
12
+
12
13
  - Create, modify, and delete nodes
13
14
  - Query node properties and project structure
14
15
  - Programmatically control TouchDesigner via Python scripts
15
16
 
17
+ ## Architecture
18
+
19
+ ```mermaid
20
+ flowchart LR
21
+ A["🤖<br/>MCP client<br/>(Claude / Codex / ...)"]
22
+
23
+ subgraph S [Node.js MCP server]
24
+ B1["🧰<br/>Tools & prompts<br/>(src/features/tools)"]
25
+ B2["🖌️<br/>Presenters & formatters<br/>(markdown output)"]
26
+ B3["🌐<br/>OpenAPI HTTP client<br/>(src/tdClient)"]
27
+ end
28
+
29
+ subgraph T [TouchDesigner project]
30
+ C1["🧩<br/>WebServer DAT<br/>(mcp_webserver_base.tox)"]
31
+ C2["🐍<br/>Python controllers / services<br/>(td/modules/mcp)"]
32
+ C3["🎛️<br/>Project nodes & parameters<br/>(/project1/...)"]
33
+ end
34
+
35
+ A --> B1
36
+ B1 --> B2
37
+ B1 --> B3
38
+ B2 --> A
39
+ B3 <--> C1
40
+ C1 <--> C2
41
+ C2 <--> C3
42
+
43
+ %% Higher-contrast colors for readability
44
+ classDef client fill:#d8e8ff,stroke:#1f6feb,stroke-width:2px,color:#111,font-weight:bold
45
+ classDef server fill:#efe1ff,stroke:#8250df,stroke-width:2px,color:#111,font-weight:bold
46
+ classDef td fill:#d7f5e3,stroke:#2f9e44,stroke-width:2px,color:#111,font-weight:bold
47
+ class A client;
48
+ class B1,B2,B3 server;
49
+ class C1,C2,C3 td;
50
+ ```
51
+
16
52
  ## Usage
17
53
 
18
54
  <details>
19
- <summary>Method 1: Using Claude Desktop and Desktop Extensions (Recommended)</summary>
55
+ <summary>Method 1: Using Claude Desktop and MCP Bundle (Recommended)</summary>
20
56
 
21
57
  ### 1. Download Files
58
+
22
59
  Download the following from the [releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest):
60
+
23
61
  - **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
24
- - **Desktop Extension (.dxt)**: `touchdesigner-mcp.dxt`
62
+ - **[MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (.mcpb)**: `touchdesigner-mcp.mcpb`
25
63
 
26
64
  ### 2. Set up TouchDesigner Components
65
+
27
66
  1. Extract the TouchDesigner components from `touchdesigner-mcp-td.zip`.
28
67
  2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
29
68
  3. Place it at `/project1/mcp_webserver_base`.
30
69
 
31
- https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
70
+ <https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
32
71
 
33
72
  You can check the startup logs by opening the Textport from the TouchDesigner menu.
34
73
 
35
74
  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
36
75
 
37
- ### 3. Install the Desktop Extension
38
- Double-click the `touchdesigner-mcp.dxt` file to install the extension in Claude Desktop.
76
+ ### 3. Install the MCP Bundle
39
77
 
40
- https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
78
+ Double-click the `touchdesigner-mcp.mcpb` file to install the bundle in Claude Desktop.
79
+
80
+ <https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
41
81
 
42
82
  ### 4. Connect to the Server
43
- The extension will automatically handle the connection to the TouchDesigner server.
83
+
84
+ The MCP bundle will automatically handle the connection to the TouchDesigner server.
44
85
 
45
86
  **⚠️ 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
87
 
@@ -52,11 +93,12 @@ The extension will automatically handle the connection to the TouchDesigner serv
52
93
  *Requires Node.js to be installed.*
53
94
 
54
95
  ### 1. Set up TouchDesigner Components
96
+
55
97
  1. Download and extract the TouchDesigner components from `touchdesigner-mcp-td.zip` ([releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)).
56
98
  2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
57
99
  3. Place it at `/project1/mcp_webserver_base`.
58
100
 
59
- https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
101
+ <https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
60
102
 
61
103
  You can check the startup logs by opening the Textport from the TouchDesigner menu.
62
104
 
@@ -65,6 +107,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
65
107
  ### 2. Set up the MCP Server Configuration
66
108
 
67
109
  *Example for Claude Desktop:*
110
+
68
111
  ```json
69
112
  {
70
113
  "mcpServers": {
@@ -77,6 +120,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
77
120
  ```
78
121
 
79
122
  **Customization:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
123
+
80
124
  ```json
81
125
  "args": [
82
126
  "-y",
@@ -86,6 +130,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
86
130
  "--port=9982"
87
131
  ]
88
132
  ```
133
+
89
134
  </details>
90
135
 
91
136
  <details>
@@ -93,39 +138,42 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
93
138
 
94
139
  [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
95
140
 
96
- ### 1. Clone the repository
141
+ ### 1. Clone the repository
142
+
97
143
  ```bash
98
144
  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
99
145
  cd touchdesigner-mcp
100
146
  ```
101
147
 
102
- ### 2. Build the Docker image
148
+ ### 2. Build the Docker image
149
+
103
150
  ```bash
104
151
  make build
105
152
  ```
106
153
 
107
- ### 3. Install the API Server in Your TouchDesigner Project
154
+ ### 3. Install the API Server in Your TouchDesigner Project
108
155
 
109
156
  Start TouchDesigner and import the `td/mcp_webserver_base.tox` component into the project you want to control.
110
157
  Example: Place it at `/project1/mcp_webserver_base`.
111
158
 
112
159
  Importing the `.tox` file will trigger the `td/import_modules.py` script, which loads the necessary modules for the API server.
113
160
 
114
- https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
161
+ <https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
115
162
 
116
163
  You can check the startup logs by opening the Textport from the TouchDesigner menu.
117
164
 
118
165
  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
119
166
 
120
- ### 4. Start the MCP server container
167
+ ### 4. Start the MCP server container
121
168
 
122
169
  ```bash
123
170
  docker-compose up -d
124
171
  ```
125
172
 
126
- ### 5. Configure your AI agent to use the Docker container
173
+ ### 5. Configure your AI agent to use the Docker container
127
174
 
128
175
  *Example for Claude Desktop:*
176
+
129
177
  ```json
130
178
  {
131
179
  "mcpServers": {
@@ -151,6 +199,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
151
199
  *On Windows systems, include the drive letter, e.g., `C:\path\to\your\touchdesigner-mcp\docker-compose.yml`.*
152
200
 
153
201
  **Note:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
202
+
154
203
  ```json
155
204
  "args": [
156
205
  ...,
@@ -159,8 +208,8 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
159
208
  "--port=9982"
160
209
  ]
161
210
  ```
162
- </details>
163
211
 
212
+ </details>
164
213
 
165
214
  ## Verify Connection
166
215
 
@@ -187,7 +236,6 @@ The `mcp_webserver_base.tox` component uses relative paths to locate Python modu
187
236
 
188
237
  ![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
189
238
 
190
-
191
239
  ## MCP Server Features
192
240
 
193
241
  This server enables AI agents to perform operations in TouchDesigner using the Model Context Protocol (MCP).
@@ -223,12 +271,12 @@ Prompts provide instructions for AI agents to perform specific actions in TouchD
223
271
 
224
272
  Not implemented.
225
273
 
226
-
227
274
  ## For Developers
228
275
 
229
276
  ### Quick Start for Development
230
277
 
231
278
  1. **Set up your environment:**
279
+
232
280
  ```bash
233
281
  # Clone and install dependencies
234
282
  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
@@ -237,6 +285,7 @@ Not implemented.
237
285
  ```
238
286
 
239
287
  2. **Build the project:**
288
+
240
289
  ```bash
241
290
  make build # Docker-based build (recommended)
242
291
  # OR
@@ -244,6 +293,7 @@ Not implemented.
244
293
  ```
245
294
 
246
295
  3. **Available commands:**
296
+
247
297
  ```bash
248
298
  npm run test # Run unit and integration tests
249
299
  npm run dev # Launch the MCP inspector for debugging
@@ -283,25 +333,24 @@ Not implemented.
283
333
  └── orval.config.ts # Orval config (TypeScript client generation)
284
334
  ```
285
335
 
286
-
287
336
  ### API Code Generation Workflow
288
337
 
289
338
  This project uses OpenAPI-based code generation tools (Orval and openapi-generator-cli).
290
339
 
291
340
  **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`.
292
341
 
293
- 1. **Python server generation (`npm run gen:webserver`):**
294
- * Uses `openapi-generator-cli` via Docker.
295
- * Reads `src/api/index.yml`.
296
- * Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner's WebServer DAT.
297
- * **Requires Docker to be installed and running.**
298
- 2. **Python handler generation (`npm run gen:handlers`):**
299
- * Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
300
- * Reads the generated Python server code or OpenAPI spec.
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`.
302
- 3. **TypeScript client generation (`npm run gen:mcp`):**
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`.
304
- * Generates a typed TypeScript client (`src/tdClient/`) used by the Node.js server to make requests to the WebServer DAT.
342
+ 1. **Python server generation (`npm run gen:webserver`):**
343
+ - Uses `openapi-generator-cli` via Docker.
344
+ - Reads `src/api/index.yml`.
345
+ - Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner's WebServer DAT.
346
+ - **Requires Docker to be installed and running.**
347
+ 2. **Python handler generation (`npm run gen:handlers`):**
348
+ - Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
349
+ - Reads the generated Python server code or OpenAPI spec.
350
+ - Generates handler implementations (`td/modules/mcp/controllers/generated_handlers.py`) that connect to the business logic in `td/modules/mcp/services/api_service.py`.
351
+ 3. **TypeScript client generation (`npm run gen:mcp`):**
352
+ - Uses `Orval` to generate an API client and Zod schemas for tool validation from the schema YAML, which is bundled by `openapi-generator-cli`.
353
+ - Generates a typed TypeScript client (`src/tdClient/`) used by the Node.js server to make requests to the WebServer DAT.
305
354
 
306
355
  The build process (`npm run build`) runs all necessary generation steps (`npm run gen`), followed by TypeScript compilation (`tsc`).
307
356
 
package/dist/cli.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
3
  import { TouchDesignerServer } from "./server/touchDesignerServer.js";
4
- // Note: Environment variables should be set by the Desktop Extensions runtime or CLI arguments
4
+ // Note: Environment variables should be set by the MCP Bundle runtime or CLI arguments
5
5
  const DEFAULT_HOST = "http://127.0.0.1";
6
6
  const DEFAULT_PORT = 9981;
7
7
  /**
@@ -9,6 +9,7 @@ export const TD_PYTHON_CLASS_REFERENCE_INDEX_URL = `${TD_PYTHON_CLASS_REFERENCE_
9
9
  export const TOOL_NAMES = {
10
10
  CREATE_TD_NODE: "create_td_node",
11
11
  DELETE_TD_NODE: "delete_td_node",
12
+ DESCRIBE_TD_TOOLS: "describe_td_tools",
12
13
  EXECUTE_PYTHON_SCRIPT: "execute_python_script",
13
14
  EXECUTE_NODE_METHOD: "exec_node_method",
14
15
  GET_TD_INFO: "get_td_info",