touchdesigner-mcp-server 0.2.8 → 0.2.10

package/README.ja.md

@@ -15,20 +15,29 @@ TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッ
 
 ## 利用方法
 
-*Node.js がインストールされていることが前提となります*
+*Docker または Node.js がインストールされていることが前提となります*
 
-[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial.png)](https://www.youtube.com/watch?v=jFaUP1fYum0)
+#### 方法1: Dockerイメージを利用（推奨）
+
+[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
 
-### 1. touchdesigner-mcp-server パッケージのインストール
+##### 1. リポジトリをクローン：
+```bash
+git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
+cd touchdesigner-mcp
+```
 
-`mkdir some && cd ./some` *（必要に応じて作成）*
-`npm install touchdesigner-mcp-server`
+##### 2. 環境設定ファイルの設置とコードのビルド
+.envのテンプレートファイルをコピーし、必要に応じて TD_WEB_SERVER_HOST / TD_WEB_SERVER_PORT を調整してから Dockerイメージをビルドしてください。
 
-### 2. TouchDesignerとの接続
+```bash
+cp dotenv .env
+make build
+```
 
-#### mcp_webserver_base.tox を TouchDesigner に配置
+##### 3. TouchDesigner プロジェクトにMCP連携用のAPIサーバーを設置
 
-TouchDesignerを起動し、`td/mcp_webserver_base.tox` コンポーネントをTouchDesignerプロジェクト直下にimportします。
+TouchDesignerを起動し、`td/mcp_webserver_base.tox` コンポーネントを操作したいTouchDesignerプロジェクト直下にimportします。
 例: `/project1/mcp_webserver_base` となるように配置
 
 tox のimport により `td/import_modules.py` スクリプトが動作し、APIサーバのコントローラなどのモジュールがロードされます。
@@ -39,8 +48,65 @@ TouchDesigner のメニューから Textportを起動してサーバーの起動
 
 ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
 
-### 3. TouchDesigner MCP Server の設定
-TouchDesignerが起動した状態で、AIエージェント（Claude Desktop,Cursor, VSCode CopilotChatなど）をMCPサーバーに接続するように設定します。
+#### 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/index.js",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+*Windows環境では C:\\ の様にドライブレターを含めてください。 例. `C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
+
+
+#### 方法2: NPMパッケージ を利用する
+
+Node.jsから直接ビルド済みのjsを利用する場合は、以下の手順に従います：
+
+[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial.png)](https://www.youtube.com/watch?v=jFaUP1fYum0)
+
+##### 1. パッケージのインストール
+```bash
+mkdir some && cd ./some  # 必要に応じて任意のディレクトリを作成
+npm install touchdesigner-mcp-server
+```
+
+##### 2. TouchDesigner プロジェクトにMCP連携用のAPIサーバーを設置
+
+TouchDesignerを起動し、`some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox` コンポーネントを操作したいTouchDesignerプロジェクト直下にimportします。
+例: `/project1/mcp_webserver_base` となるように配置
+
+tox のimport により `some/node_modules/touchdesigner-mcp-server/td/import_modules.py` スクリプトが動作し、APIサーバのコントローラなどのモジュールがロードされます。
+
+![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/import.png)
+
+TouchDesigner のメニューから Textportを起動してサーバーの起動ログを確認することができます。
+
+![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
+
+##### 3. AIエージェントの設定：
 
 *例 Claude Desktop*
 ```json
@@ -51,8 +117,7 @@ TouchDesignerが起動した状態で、AIエージェント（Claude Desktop,Cu
         "/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js", // <-- node_modules/touchdesigner-mcp-server/dist/index.js への絶対パスに置き換えてください
         "--stdio"
       ],
-      "command": "node",
-      "transportType": "stdio"
+      "command": "node"
     }
   }
 }
@@ -60,10 +125,12 @@ TouchDesignerが起動した状態で、AIエージェント（Claude Desktop,Cu
 
 *Windows環境では C:\\ の様にドライブレターを含めてください。 例. `C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js`*
 
+### 3. 接続確認
+
 MCPサーバーが認識されていればセットアップは完了です。
 認識されない場合はAIエージェントを再起動するなどしてください。
 起動時にエラーが表示される場合はTouchDesignerを先に起動してから再度エージェントを起動してください。
-TouchDesigner で APIサーバーが実行されていれば、エージェントは提供された TouchDesigner ツールを通じてTouchDesignerを使用できます。
+TouchDesigner で APIサーバーが実行されていれば、エージェントは提供された ツール等を通じてTouchDesignerを使用できます。
 
 ![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
 
@@ -105,77 +172,23 @@ TouchDesigner で APIサーバーが実行されていれば、エージェン
 
 ## 開発者向け
 
-### MCPサーバーコードのビルド
+### クライアント・APIサーバーコードのビルド
 
-1. リポジトリのクローン
-```bash
-git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-```
-
-2. 依存パッケージのインストール
-```bash
-cd touchdesigner-mcp
-npm install
-```
-3. 環境設定ファイルの設置とビルド
-```
-# テンプレートをコピーし、必要に応じて TD_WEB_SERVER_URL を調整してください
-cp dotenv .env
-
-# プロジェクトのビルド（APIクライアント/サーバー向けスキーマを生成し、MCPリソースをコンパイルします）
-# このコマンドを実行する前にDockerデーモンが実行されていることを確認してください
-npm run build
-```
+1. `cp dotenv .env`
+2. `.env` ファイルの `TD_WEB_SERVER_HOST`, `TD_WEB_SERVER_PORT` を開発環境に合わせて変更
+3. `make build` もしくは `npm run build` を実行してコードを再生成する
 
-### TouchDesignerのセットアップ
+ビルドしたコードを再反映する場合は MCPサーバーと TouchDesigner を再起動してください
 
-#### 1.  **コード生成:**
-`npm run build` を実行します。これにより以下のコードが生成されます。
-- MCPサーバコード
-- TouchDesigner WebSever DAT向けのAPIサーバーコード
-
-#### 2.  **TouchDesigner に MCPサーバー向けWebServerをインポートする:**
-TouchDesignerを起動し、`td/mcp_webserver_base.tox` コンポーネントをTouchDesignerプロジェクト直下にimportします。
-tox のimport により `td/import_modules.py` スクリプトが動作し、APIサーバのコントローラなどのモジュールがロードされます。
-
-#### 3.  **APIサーバの動作確認:**
-`td/modules` ディレクトリ内のPythonモジュールが `mcp_webserver_base` コンポーネントからアクセス可能であることを確認します。
-`npm run test` を実行することでMCPサーバーコードのユニットテストと TouchDesigner への結合テストが実行されます。
+### APIサーバの動作確認
+- `npm run test`
+MCPサーバーコードのユニットテストと TouchDesigner への結合テストが実行されます。
 TouchDesigner のメニューから Textportを起動すると通信のログを確認することができます。
 
-`npm run dev` で @modelcontextprotocol/inspector させデバッグすることができます。
-
-*TIPS*
-`mcp_webserver_base.tox` には、MCPサーバーとTouchDesignerを連携させるように設定された WebServer DAT が含まれています。
-このDATがActiveであり、`.env` ファイルの `TD_WEB_SERVER_URL` で指定されたポートで実行されていることを確認してください。（デフォルト: `9981`）
-実行するポートを任意のものに変更したい場合は、以下の手順に従ってください。
-1. `.env` ファイルの `TD_WEB_SERVER_PORT` を変更
-2. `npm run build` を再実行
-3. mcp_webserver_base (WebServer DAT) のポートを変更し、WebServer DATをRestart
-
-### MCP対応 AIエージェントとの接続
-
-TouchDesignerが起動した状態で、AIエージェント（Cursor, Claude Desktop, VSCode CopilotChatなど）をMCPサーバーに接続するように設定します。
-
-#### 例. Claude Desktop
-```json
-{
-  "mcpServers": {
-    "dev_touchdesigner": {
-      "args": [
-        "/path/to/your/touchdesigner-mcp/dist/index.js", // <-- ビルド後の /dist/index.js への絶対パスに置き換えてください
-        "--stdio"
-      ],
-      "command": "node",
-      "transportType": "stdio"
-    }
-  }
-}
-```
-
-*Windows環境では C:\\ の様にドライブレターを含めてください。 例. `C:\\path\\to\\your\\touchdesigner-mcp\\dist\\index.js`*
+- `npm run dev`
+@modelcontextprotocol/inspector が起動し、各種機能をデバッグすることができます。
 
-### セットアップ後のプロジェクト構造概要
+### プロジェクト構造の概要
 
 ```
 ├── src/                       # MCPサーバー ソースコード

package/README.md

@@ -15,20 +15,29 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
 
 ## Usage
 
-*Requires Node.js to be installed*
+*Requires Docker or Node.js to be installed*
 
-[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial.png)](https://www.youtube.com/watch?v=jFaUP1fYum0)
+#### Method 1: Using Docker Image (Recommended)
+
+[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
 
-### 1. Install the touchdesigner-mcp-server package
+##### 1. Clone the repository:
+```bash
+git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
+cd touchdesigner-mcp
+```
 
-`mkdir some && cd ./some` *(If you need)*
-`npm install touchdesigner-mcp-server`
+##### 2. Set up the environment file and build:
+Copy the template file and adjust the TD_WEB_SERVER_HOST and TD_WEB_SERVER_PORT as needed before building the Docker image.
 
-### 2. Connect to TouchDesigner
+```bash
+cp dotenv .env
+make build
+```
 
-#### Place mcp_webserver_base.tox in TouchDesigner
+##### 3. Install the API Server in Your TouchDesigner Project:
 
-Start TouchDesigner and import the `td/mcp_webserver_base.tox` component directly under your TouchDesigner project.
+Start TouchDesigner and import the `td/mcp_webserver_base.tox` component directly under the TouchDesigner project you want to control.
 Example: Place it as `/project1/mcp_webserver_base`
 
 Importing the tox will trigger the `td/import_modules.py` script, which loads modules such as API server controllers.
@@ -39,10 +48,66 @@ You can check boot logs by opening the Textport from the TouchDesigner menu.
 
 ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
 
-### 3. Configure the TouchDesigner MCP Server
-With TouchDesigner running, configure your AI agent (Claude Desktop, Cursor, VSCode CopilotChat, etc.) to connect to the MCP server.
+##### 4. Start the MCP server container
 
-*Example: Claude Desktop*
+```bash
+docker-compose up -d
+```
+
+##### 5. Configure your AI agent to use the Docker container:
+
+*Example for 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/index.js",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+*On Windows systems, include the drive letter like C: e.g. `C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
+
+#### Method 2: Using the NPM Package
+
+To use the pre-built JS directly from Node.js:
+
+[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial.png)](https://www.youtube.com/watch?v=jFaUP1fYum0)
+
+##### 1. Install the package
+```bash
+mkdir some && cd ./some  # If you need a new directory
+npm install touchdesigner-mcp-server
+```
+
+##### 2. Install the API Server in Your TouchDesigner Project:
+
+Start TouchDesigner and import the `some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox` component directly under the TouchDesigner project you want to control.
+Example: Place it as `/project1/mcp_webserver_base`
+
+Importing the tox will trigger the `some/node_modules/touchdesigner-mcp-server/td/import_modules.py` script, which loads modules such as API server controllers.
+
+![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/import.png)
+
+You can check boot logs by opening the Textport from the TouchDesigner menu.
+
+![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
+
+##### 3. Configure your AI agent:
+
+*Example for Claude Desktop*
 ```json
 {
   "mcpServers": {
@@ -51,19 +116,20 @@ With TouchDesigner running, configure your AI agent (Claude Desktop, Cursor, VSC
         "/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js", // <-- Replace with the absolute path to node_modules/touchdesigner-mcp-server/dist/index.js
         "--stdio"
       ],
-      "command": "node",
-      "transportType": "stdio"
+      "command": "node"
     }
   }
 }
 ```
 
-*On Windows system, please include the drive letter such as C: e.g. `C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js`*
+*On Windows systems, include the drive letter like C: e.g. `C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js`*
+
+### 3. Verify Connection
 
 If the MCP server is recognized, setup is complete.
-Restart the agent, if not recognized.
-If you see an error at startup, try launching the agent again after starting TouchDesigner.
-If the API server is running in TouchDesigner, the agent can use TouchDesigner via the provided tools.
+If it's not recognized, try restarting your AI agent.
+If you see an error at startup, try launching the agent again after starting TouchDesigner first.
+When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate TouchDesigner.
 
 ![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
 
@@ -106,77 +172,23 @@ Not implemented
 
 ## For Developers
 
-### Building the MCP Server Code
-
-1. Clone the repository
-```bash
-git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-```
-
-2. Install dependencies
-```bash
-cd touchdesigner-mcp
-npm install
-```
-3. Set up environment file and build
-```
-# Copy the template and adjust TD_WEB_SERVER_URL as needed
-cp dotenv .env
-
-# Build the project (generates API client/server schemas and compiles MCP resources)
-# Make sure the Docker daemon is running before executing this command
-npm run build
-```
-
-### TouchDesigner Setup
+### Building Client and API Server Code
 
-#### 1. **Code Generation:**
-Run `npm run build` to generate the following code:
-- MCP server code
-- API server code for TouchDesigner WebServer DAT
+1. `cp dotenv .env`
+2. Adjust `TD_WEB_SERVER_HOST` and `TD_WEB_SERVER_PORT` in the `.env` file to match your  development environment
+3. Run `make build` or `npm run build` to regenerate the code
 
-#### 2. **Import the WebServer for MCP server into TouchDesigner:**
-Start TouchDesigner and import the `td/mcp_webserver_base.tox` component directly under your project.
-Importing the tox will trigger the `td/import_modules.py` script, which loads modules such as API server controllers.
+When you need to reflect the built code, please restart both the MCP server and TouchDesigner.
 
-#### 3. **Verify API server operation:**
-Ensure that the Python modules in the `td/modules` directory are accessible from the `mcp_webserver_base` component.
-Run `npm run test` to execute unit and integration tests for the MCP server code and TouchDesigner connection.
+### Verifying the API Server
+- `npm run test`
+Run unit tests for the MCP server code and integration tests with TouchDesigner.
 You can check communication logs by opening the Textport from the TouchDesigner menu.
 
-You can debug with @modelcontextprotocol/inspector using `npm run dev`.
-
-*TIPS*
-`mcp_webserver_base.tox` includes a WebServer DAT configured to link the MCP server and TouchDesigner.
-Ensure this DAT is active and running on the port specified by `TD_WEB_SERVER_URL` in your `.env` file (default: `9981`).
-To change the port:
-1. Change `TD_WEB_SERVER_PORT` in `.env`
-2. Re-run `npm run build`
-3. Change the port in mcp_webserver_base (WebServer DAT) and restart the DAT
-
-### Connecting with MCP-compatible AI Agents
-
-With TouchDesigner running, configure your AI agent (Cursor, Claude Desktop, VSCode CopilotChat, etc.) to connect to the MCP server.
-
-#### Example: Claude Desktop
-```json
-{
-  "mcpServers": {
-    "dev_touchdesigner": {
-      "args": [
-        "/path/to/your/touchdesigner-mcp/dist/index.js", // <-- Replace with the absolute path to /dist/index.js after build
-        "--stdio"
-      ],
-      "command": "node",
-      "transportType": "stdio"
-    }
-  }
-}
-```
-
-*On Windows system, please include the drive letter such as C: e.g. `C:\\path\\to\\your\\touchdesigner-mcp\\dist\\index.js`*
+- `npm run dev`
+Launch @modelcontextprotocol/inspector to debug various features.
 
-### Project Structure After Setup
+### Project Structure Overview
 
 ```
 ├── src/                       # MCP server source code

package/dist/api/customInstance.js

@@ -1,8 +1,6 @@
 import Axios from "axios";
-const API_BASE_URL = process.env.API_BASE_URL || "http://localhost:9981";
-export const AXIOS_INSTANCE = Axios.create({
-    baseURL: API_BASE_URL,
-});
+const API_BASE_URL = `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}`;
+export const AXIOS_INSTANCE = Axios.create(API_BASE_URL ? { baseURL: API_BASE_URL } : {});
 export const customInstance = (config, options) => {
     const source = Axios.CancelToken.source();
     const promise = AXIOS_INSTANCE({

package/dist/gen/endpoints/TouchDesignerAPI.js

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 0.2.8
+ * OpenAPI spec version: 0.2.10
  */
 import { customInstance } from '../../api/customInstance.js';
 // eslint-disable-next-line @typescript-eslint/no-redeclare

package/dist/gen/mcp/touchDesignerAPI.zod.js

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 0.2.8
+ * OpenAPI spec version: 0.2.10
  */
 import { z as zod } from 'zod';
 /**

package/dist/server/connectionManager.js

@@ -23,7 +23,7 @@ export class ConnectionManager {
         this.transport = transport;
         try {
             await this.server.connect(transport);
-            this.logger.log("Server connected and ready to process requests");
+            this.logger.log(`Server connected and ready to process requests: ${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}`);
             const connectionResult = await this.checkTDConnection();
             if (!connectionResult.success) {
                 throw new Error(`Failed to connect to TouchDesigner: ${connectionResult.error.message}`);

package/dist/server/touchDesignerServer.js

@@ -18,7 +18,7 @@ export class TouchDesignerServer {
     constructor() {
         this.server = new McpServer({
             name: "TouchDesigner",
-            version: "0.2.8",
+            version: "0.2.10",
         }, {
             capabilities: {
                 prompts: {},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "0.2.8",
+	"version": "0.2.10",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -17,26 +17,27 @@
 	},
 	"homepage": "https://github.com/8beeeaaat/touchdesigner-mcp#readme",
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.10.2",
+		"@modelcontextprotocol/sdk": "^1.11.1",
 		"@mozilla/readability": "^0.6.0",
 		"@types/axios": "^0.14.4",
 		"@types/ws": "^8.18.1",
 		"@types/yargs": "^17.0.33",
 		"axios": "^1.9.0",
 		"dotenv": "^16.5.0",
-		"zod": "^3.24.3"
+		"zod": "^3.24.4"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
+		"@openapitools/openapi-generator-cli": "^2.20.0",
 		"@types/jsdom": "^21.1.7",
-		"@types/node": "^22.15.3",
-		"@vitest/coverage-v8": "^3.1.2",
-		"msw": "^2.7.5",
+		"@types/node": "^22.15.17",
+		"@vitest/coverage-v8": "^3.1.3",
+		"msw": "^2.8.2",
 		"mustache": "^4.2.0",
 		"npm-run-all": "^4.1.5",
 		"orval": "^7.9.0",
 		"typescript": "^5.8.3",
-		"vitest": "^3.1.2",
+		"vitest": "^3.1.3",
 		"yaml": "^2.7.1"
 	},
 	"type": "module",
@@ -58,7 +59,7 @@
 		"test:unit": "vitest run ./tests/unit",
 		"coverage": "vitest run --coverage",
 		"gen": "run-s gen:*",
-		"gen:webserver": "docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -i /local/src/api/index.yml -g python-flask -o /local/td/modules/td_server",
+		"gen:webserver": "openapi-generator-cli generate -i ./src/api/index.yml -g python-flask -o ./td/modules/td_server",
 		"gen:handlers": "node td/genHandlers.js",
 		"gen:mcp": "orval --config ./orval.config.ts"
 	},

package/td/modules/td_server/.openapi-generator/VERSION

@@ -1 +1 @@
-7.14.0-SNAPSHOT
+7.13.0

package/td/modules/td_server/openapi_server/openapi/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.0
 info:
   description: OpenAPI schema for generating TouchDesigner API client code
   title: TouchDesigner API
-  version: 0.2.8
+  version: 0.2.10
 servers:
 - url: "{baseUrl}"
   variables: