touchdesigner-mcp-server 0.4.7 → 1.1.0

package/README.ja.md

@@ -9,35 +9,75 @@ TouchDesignerのためのMCP(Model Context Protocol) サーバー実装です。
 [![demo clip](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/particle_on_youtube.png)](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)
 
 TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッジとして機能し、AIエージェントが以下のことが可能になります
+
 - ノードの作成、変更、削除
 - ノードプロパティやプロジェクト構造の照会
 - PythonスクリプトによるTouchDesignerのプログラム的制御
 
+## アーキテクチャ
+
+```mermaid
+flowchart LR
+    A["🤖<br/>MCP client<br/>(Claude / Codex / ...)"]
+
+    subgraph S [Node.js MCP server]
+      B1["🧰<br/>Tools & prompts<br/>(src/features/tools)"]
+      B2["🖌️<br/>Presenters & formatters<br/>(markdown output)"]
+      B3["🌐<br/>OpenAPI HTTP client<br/>(src/tdClient)"]
+    end
+
+    subgraph T [TouchDesigner project]
+      C1["🧩<br/>WebServer DAT<br/>(mcp_webserver_base.tox)"]
+      C2["🐍<br/>Python controllers / services<br/>(td/modules/mcp)"]
+      C3["🎛️<br/>Project nodes & parameters<br/>(/project1/...)"]
+    end
+
+    A --> B1
+    B1 --> B2
+    B1 --> B3
+    B2 --> A
+    B3 <--> C1
+    C1 <--> C2
+    C2 <--> C3
+
+    %% Higher-contrast colors for readability
+    classDef client fill:#d8e8ff,stroke:#1f6feb,stroke-width:2px,color:#111,font-weight:bold
+    classDef server fill:#efe1ff,stroke:#8250df,stroke-width:2px,color:#111,font-weight:bold
+    classDef td fill:#d7f5e3,stroke:#2f9e44,stroke-width:2px,color:#111,font-weight:bold
+    class A client;
+    class B1,B2,B3 server;
+    class C1,C2,C3 td;
+```
+
 ## 利用方法
 
 <details>
   <summary>方法1: Claude Desktop + Desktop Extensions（推奨）</summary>
 
-##### 1. ファイルをダウンロード：
+##### 1. ファイルをダウンロード
+
 [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)から以下をダウンロード：
+
 - **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
 - **Desktop Extensions (.dxt)**: `touchdesigner-mcp.dxt`
 
-##### 2. TouchDesignerコンポーネントを設置：
+##### 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
+<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
 
   TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
 
   ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
 
-##### 3. Desktop Extensionをインストール：
+##### 3. Desktop Extensionをインストール
+
 `touchdesigner-mcp.dxt`ファイルをダブルクリックしてClaude Desktopに拡張機能をインストール
 
-https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
+<https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
 
 ##### 4. 拡張機能が自動的にTouchDesignerサーバー接続を処理
 
@@ -50,20 +90,22 @@ https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
 
 *Node.jsがインストールされていることが前提となります*
 
-##### 1. TouchDesignerコンポーネントを設置：
+##### 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
+<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
 
   TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
 
   ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
 
-##### 2. MCPサーバー設定：
+##### 2. MCPサーバー設定
 
 *例 Claude Desktop*
+
 ```json
 {
   "mcpServers": {
@@ -76,6 +118,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
 ```
 
 **カスタマイズ：** `--host`と`--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
+
 ```json
 "args": [
   "-y",
@@ -85,6 +128,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
   "--port=9982"
 ]
 ```
+
 </details>
 
 <details>
@@ -92,13 +136,15 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
 
 [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
 
-##### 1. リポジトリをクローン：
+##### 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
@@ -112,7 +158,7 @@ TouchDesignerを起動し、`td/mcp_webserver_base.tox`コンポーネントを
 
 toxファイルのインポートにより`td/import_modules.py`スクリプトが実行され、APIサーバーのコントローラなどのモジュールがロードされます。
 
-https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
+<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
 
 TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
 
@@ -124,9 +170,10 @@ TouchDesignerのメニューからTextportを起動してサーバーの起動
 docker-compose up -d
 ```
 
-##### 5. AIエージェントがDockerコンテナを使用するように設定：
+##### 5. AIエージェントがDockerコンテナを使用するように設定
 
 *例 Claude Desktop*
+
 ```json
 {
   "mcpServers": {
@@ -152,6 +199,7 @@ docker-compose up -d
 *Windows システムでは、ドライブレターを含めてください。例：`C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
 
 **カスタマイズ：** `--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
+
   ```json
 "args": [
   ...,
@@ -160,8 +208,8 @@ docker-compose up -d
   "--port=9982"
 ]
   ```
-</details>
 
+</details>
 
 ## 接続確認
 
@@ -223,12 +271,12 @@ td/
 
 未実装
 
-
 ## 開発者向け
 
 ### 開発のクイックスタート
 
 1. **環境設定:**
+
    ```bash
    # リポジトリをクローンして依存関係をインストール
    git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
@@ -237,6 +285,7 @@ td/
    ```
 
 2. **プロジェクトをビルド:**
+
    ```bash
    make build        # Docker-based build（推奨）
    # または
@@ -244,6 +293,7 @@ td/
    ```
 
 3. **利用可能なコマンド:**
+
    ```bash
    npm run test      # ユニットテストと統合テストを実行
    npm run dev       # デバッグ用MCPインスペクターを起動
@@ -283,25 +333,24 @@ td/
 └── 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/`) を生成します。
+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`) を行います。
 

package/README.md

@@ -9,37 +9,78 @@ This is an implementation of an MCP (Model Context Protocol) server for TouchDes
 [![demo clip](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/particle_on_youtube.png)](https://youtu.be/V2znaqGU7f4?si=6HDFbcBHCFPdttkM&t=635)
 
 TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebServer DAT, enabling AI agents to:
+
 - Create, modify, and delete nodes
 - Query node properties and project structure
 - Programmatically control TouchDesigner via Python scripts
 
+## Architecture
+
+```mermaid
+flowchart LR
+    A["🤖<br/>MCP client<br/>(Claude / Codex / ...)"]
+
+    subgraph S [Node.js MCP server]
+      B1["🧰<br/>Tools & prompts<br/>(src/features/tools)"]
+      B2["🖌️<br/>Presenters & formatters<br/>(markdown output)"]
+      B3["🌐<br/>OpenAPI HTTP client<br/>(src/tdClient)"]
+    end
+
+    subgraph T [TouchDesigner project]
+      C1["🧩<br/>WebServer DAT<br/>(mcp_webserver_base.tox)"]
+      C2["🐍<br/>Python controllers / services<br/>(td/modules/mcp)"]
+      C3["🎛️<br/>Project nodes & parameters<br/>(/project1/...)"]
+    end
+
+    A --> B1
+    B1 --> B2
+    B1 --> B3
+    B2 --> A
+    B3 <--> C1
+    C1 <--> C2
+    C2 <--> C3
+
+    %% Higher-contrast colors for readability
+    classDef client fill:#d8e8ff,stroke:#1f6feb,stroke-width:2px,color:#111,font-weight:bold
+    classDef server fill:#efe1ff,stroke:#8250df,stroke-width:2px,color:#111,font-weight:bold
+    classDef td fill:#d7f5e3,stroke:#2f9e44,stroke-width:2px,color:#111,font-weight:bold
+    class A client;
+    class B1,B2,B3 server;
+    class C1,C2,C3 td;
+```
+
 ## Usage
 
 <details>
   <summary>Method 1: Using Claude Desktop and Desktop Extensions (Recommended)</summary>
 
 ### 1. Download Files
+
 Download the following from the [releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest):
+
 - **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
 - **Desktop Extension (.dxt)**: `touchdesigner-mcp.dxt`
 
 ### 2. Set up TouchDesigner Components
+
 1. Extract the TouchDesigner components from `touchdesigner-mcp-td.zip`.
 2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
 3. Place it at `/project1/mcp_webserver_base`.
 
-https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
+<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
 
   You can check the startup logs by opening the Textport from the TouchDesigner menu.
 
   ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
 
 ### 3. Install the Desktop Extension
+
 Double-click the `touchdesigner-mcp.dxt` file to install the extension in Claude Desktop.
 
-https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854
+<https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
 
 ### 4. Connect to the Server
+
 The extension will automatically handle the connection to the TouchDesigner server.
 
 **⚠️ 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.
@@ -52,11 +93,12 @@ The extension will automatically handle the connection to the TouchDesigner serv
 *Requires Node.js to be installed.*
 
 ### 1. Set up TouchDesigner Components
+
 1. Download and extract the TouchDesigner components from `touchdesigner-mcp-td.zip` ([releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)).
 2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
 3. Place it at `/project1/mcp_webserver_base`.
 
-https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
+<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
 
   You can check the startup logs by opening the Textport from the TouchDesigner menu.
 
@@ -65,6 +107,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
 ### 2. Set up the MCP Server Configuration
 
 *Example for Claude Desktop:*
+
 ```json
 {
   "mcpServers": {
@@ -77,6 +120,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
 ```
 
 **Customization:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
+
 ```json
 "args": [
   "-y",
@@ -86,6 +130,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
   "--port=9982"
 ]
 ```
+
 </details>
 
 <details>
@@ -93,39 +138,42 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
 
   [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
 
-  ### 1. Clone the repository
+### 1. Clone the repository
+
   ```bash
   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
   cd touchdesigner-mcp
   ```
 
-  ### 2. Build the Docker image
+### 2. Build the Docker image
+
   ```bash
   make build
   ```
 
-  ### 3. Install the API Server in Your TouchDesigner Project
+### 3. Install the API Server in Your TouchDesigner Project
 
   Start TouchDesigner and import the `td/mcp_webserver_base.tox` component into the project you want to control.
   Example: Place it at `/project1/mcp_webserver_base`.
 
   Importing the `.tox` file will trigger the `td/import_modules.py` script, which loads the necessary modules for the API server.
 
-https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
+<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
 
   You can check the startup logs by opening the Textport from the TouchDesigner menu.
 
   ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
 
-  ### 4. Start the MCP server container
+### 4. Start the MCP server container
 
   ```bash
   docker-compose up -d
   ```
 
-  ### 5. Configure your AI agent to use the Docker container
+### 5. Configure your AI agent to use the Docker container
 
   *Example for Claude Desktop:*
+
   ```json
   {
     "mcpServers": {
@@ -151,6 +199,7 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
   *On Windows systems, include the drive letter, e.g., `C:\path\to\your\touchdesigner-mcp\docker-compose.yml`.*
 
 **Note:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
+
   ```json
 "args": [
   ...,
@@ -159,8 +208,8 @@ https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4
   "--port=9982"
 ]
   ```
-</details>
 
+</details>
 
 ## Verify Connection
 
@@ -187,7 +236,6 @@ The `mcp_webserver_base.tox` component uses relative paths to locate Python modu
 
 ![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
 
-
 ## MCP Server Features
 
 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
 
 Not implemented.
 
-
 ## For Developers
 
 ### Quick Start for Development
 
 1. **Set up your environment:**
+
    ```bash
    # Clone and install dependencies
    git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
@@ -237,6 +285,7 @@ Not implemented.
    ```
 
 2. **Build the project:**
+
    ```bash
    make build        # Docker-based build (recommended)
    # OR
@@ -244,6 +293,7 @@ Not implemented.
    ```
 
 3. **Available commands:**
+
    ```bash
    npm run test      # Run unit and integration tests
    npm run dev       # Launch the MCP inspector for debugging
@@ -283,25 +333,24 @@ Not implemented.
 └── orval.config.ts             # Orval config (TypeScript client generation)
 ```
 
-
 ### API Code Generation Workflow
 
 This project uses OpenAPI-based code generation tools (Orval and openapi-generator-cli).
 
 **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`.
 
-1.  **Python server generation (`npm run gen:webserver`):**
-    *   Uses `openapi-generator-cli` via Docker.
-    *   Reads `src/api/index.yml`.
-    *   Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner's WebServer DAT.
-    *   **Requires Docker to be installed and running.**
-2.  **Python handler generation (`npm run gen:handlers`):**
-    *   Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
-    *   Reads the generated Python server code or OpenAPI spec.
-    *   Generates handler implementations (`td/modules/mcp/controllers/generated_handlers.py`) that connect to the business logic in `td/modules/mcp/services/api_service.py`.
-3.  **TypeScript client generation (`npm run gen:mcp`):**
-    *   Uses `Orval` to generate an API client and Zod schemas for tool validation from the schema YAML, which is bundled by `openapi-generator-cli`.
-    *   Generates a typed TypeScript client (`src/tdClient/`) used by the Node.js server to make requests to the WebServer DAT.
+1. **Python server generation (`npm run gen:webserver`):**
+    - Uses `openapi-generator-cli` via Docker.
+    - Reads `src/api/index.yml`.
+    - Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner's WebServer DAT.
+    - **Requires Docker to be installed and running.**
+2. **Python handler generation (`npm run gen:handlers`):**
+    - Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
+    - Reads the generated Python server code or OpenAPI spec.
+    - Generates handler implementations (`td/modules/mcp/controllers/generated_handlers.py`) that connect to the business logic in `td/modules/mcp/services/api_service.py`.
+3. **TypeScript client generation (`npm run gen:mcp`):**
+    - Uses `Orval` to generate an API client and Zod schemas for tool validation from the schema YAML, which is bundled by `openapi-generator-cli`.
+    - Generates a typed TypeScript client (`src/tdClient/`) used by the Node.js server to make requests to the WebServer DAT.
 
 The build process (`npm run build`) runs all necessary generation steps (`npm run gen`), followed by TypeScript compilation (`tsc`).
 

package/dist/core/constants.js

@@ -9,6 +9,7 @@ export const TD_PYTHON_CLASS_REFERENCE_INDEX_URL = `${TD_PYTHON_CLASS_REFERENCE_
 export const TOOL_NAMES = {
     CREATE_TD_NODE: "create_td_node",
     DELETE_TD_NODE: "delete_td_node",
+    DESCRIBE_TD_TOOLS: "describe_td_tools",
     EXECUTE_PYTHON_SCRIPT: "execute_python_script",
     EXECUTE_NODE_METHOD: "exec_node_method",
     GET_TD_INFO: "get_td_info",