touchdesigner-mcp-server 0.3.0 → 0.4.0-alpha.0

package/README.ja.md

@@ -15,9 +15,41 @@ TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッ
 
 ## 利用方法
 
-*Docker または Node.js がインストールされていることが前提となります*
+<details>
+  <summary>方法1: npx を利用する（クイックスタート）</summary>
 
-#### 方法1: Dockerイメージを利用（推奨）
+*Node.jsがインストールされていることが前提となります*
+
+##### 1. TouchDesigner プロジェクトにMCP連携用のAPIサーバーを設置
+
+npxを使用する場合、TouchDesignerコンポーネントを別途ダウンロードする必要があります：
+1. [リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases)から `touchdesigner-mcp-td.zip` をダウンロード
+2. zipファイルを展開して `td` ディレクトリを取得
+3. 展開したファイルから `mcp_webserver_base.tox` を操作したいTouchDesignerプロジェクト直下にimportします。
+例: `/project1/mcp_webserver_base` となるように配置
+
+**⚠️ 重要:** `td` ディレクトリの構造は展開した状態を正確に保持する必要があります。`mcp_webserver_base.tox` コンポーネントは `modules/` ディレクトリやその他のファイルへの相対パスを参照しています。展開した `td` ディレクトリ内のファイルを移動したり再編成したりしないでください。
+
+##### 2. AIエージェントの設定：
+
+*例 Claude Desktop*
+```json
+{
+  "mcpServers": {
+    "touchdesigner": {
+      "command": "npx",
+      "args": [
+        "touchdesigner-mcp-server",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+</details>
+
+<details>
+  <summary>方法2: Dockerイメージを利用</summary>
 
 [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
 
@@ -70,7 +102,7 @@ docker-compose up -d
         "-i",
         "touchdesigner-mcp-server",
         "node",
-        "dist/index.js",
+        "dist/cli.js",
         "--stdio"
       ]
     }
@@ -79,58 +111,31 @@ docker-compose up -d
 ```
 
 *Windows環境では C:\\ の様にドライブレターを含めてください。 例. `C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
+</details>
 
 
-#### 方法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を起動してサーバーの起動ログを確認することができます。
+MCPサーバーが認識されていればセットアップは完了です。
+認識されない場合はAIエージェントを再起動するなどしてください。
+起動時にエラーが表示される場合はTouchDesignerを先に起動してから再度エージェントを起動してください。
+TouchDesigner で APIサーバーが実行されていれば、エージェントは提供された ツール等を通じてTouchDesignerを使用できます。
 
-![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
+### ディレクトリ構造要件
 
-##### 3. AIエージェントの設定：
+**重要:** どの方法（Docker、npx）を使用する場合でも、正確なディレクトリ構造を維持してください：
 
-*例 Claude Desktop*
-```json
-{
-  "mcpServers": {
-    "touchdesigner": {
-      "args": [
-        "/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js", // <-- node_modules/touchdesigner-mcp-server/dist/index.js への絶対パスに置き換えてください
-        "--stdio"
-      ],
-      "command": "node"
-    }
-  }
-}
+```
+td/
+├── import_modules.py          # モジュールローダースクリプト
+├── mcp_webserver_base.tox     # メインTouchDesignerコンポーネント
+└── modules/                   # Pythonモジュールディレクトリ
+    ├── mcp/                   # MCPコアロジック
+    ├── utils/                 # 共有ユーティリティ
+    └── td_server/             # 生成されたAPIサーバーコード
 ```
 
-*Windows環境では C:\\ の様にドライブレターを含めてください。 例. `C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js`*
-
-### 3. 接続確認
-
-MCPサーバーが認識されていればセットアップは完了です。
-認識されない場合はAIエージェントを再起動するなどしてください。
-起動時にエラーが表示される場合はTouchDesignerを先に起動してから再度エージェントを起動してください。
-TouchDesigner で APIサーバーが実行されていれば、エージェントは提供された ツール等を通じてTouchDesignerを使用できます。
+`mcp_webserver_base.tox` コンポーネントは相対パスを使用してPythonモジュールを検索します。これらのファイルを移動したり再編成したりすると、TouchDesignerでインポートエラーが発生します。
 
 ![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
 
@@ -172,21 +177,28 @@ TouchDesigner で APIサーバーが実行されていれば、エージェン
 
 ## 開発者向け
 
-### クライアント・APIサーバーコードのビルド
+### 開発のクイックスタート
 
-1. `cp dotenv .env`
-2. `.env` ファイルの `TD_WEB_SERVER_HOST`, `TD_WEB_SERVER_PORT` を開発環境に合わせて変更
-3. `make build` もしくは `npm run build` を実行してコードを再生成する
+1. **環境設定:**
+   ```bash
+   cp dotenv .env
+   # .env ファイルの TD_WEB_SERVER_HOST, TD_WEB_SERVER_PORT を開発環境に合わせて変更
+   ```
 
-ビルドしたコードを再反映する場合は MCPサーバーと TouchDesigner を再起動してください
+2. **プロジェクトをビルド:**
+   ```bash
+   make build        # Docker-based build（推奨）
+   # または
+   npm run build     # Node.js-based build
+   ```
 
-### APIサーバの動作確認
-- `npm run test`
-MCPサーバーコードのユニットテストと TouchDesigner への結合テストが実行されます。
-TouchDesigner のメニューから Textportを起動すると通信のログを確認することができます。
+3. **利用可能なコマンド:**
+   ```bash
+   npm run test      # ユニットテストと結合テストを実行
+   npm run dev       # デバッグ用MCPインスペクターを起動
+   ```
 
-- `npm run dev`
-@modelcontextprotocol/inspector が起動し、各種機能をデバッグすることができます。
+**注意:** コードを更新した場合は、MCPサーバーとTouchDesignerの両方を再起動して変更を反映してください。
 
 ### プロジェクト構造の概要
 

package/README.md

@@ -15,10 +15,41 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
 
 ## Usage
 
-*Requires Docker or Node.js to be installed*
+<details>
+  <summary>Method 1: Using npx (Quick Start)</summary>
+
+*Requires Node.js to be installed*
+
+#### 1. Install the API Server in Your TouchDesigner Project:
+
+Since you're using npx, you'll need to download the TouchDesigner components separately:
+1. Download `touchdesigner-mcp-td.zip` from the [releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases)
+2. Extract the zip file to get the `td` directory
+3. Import `mcp_webserver_base.tox` from the extracted files directly under the TouchDesigner project you want to control.
+Example: Place it as `/project1/mcp_webserver_base`
+
+**⚠️ Important:** The `td` 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 `td` directory.
+
+#### 2. Configure your AI agent:
+
+*Example for Claude Desktop*
+```json
+{
+  "mcpServers": {
+    "touchdesigner": {
+      "command": "npx",
+      "args": [
+        "touchdesigner-mcp-server",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+</details>
 
 <details>
-  <summary>Method 1: Using Docker Image (Recommended)</summary>
+  <summary>Method 2: Using Docker Image</summary>
 
   [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
 
@@ -71,7 +102,7 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
           "-i",
           "touchdesigner-mcp-server",
           "node",
-          "dist/index.js",
+          "dist/cli.js",
           "--stdio"
         ]
       }
@@ -82,59 +113,30 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
   *On Windows systems, include the drive letter like C: e.g. `C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
 </details>
 
-<details>
-  <summary>Method 2: Using the NPM Package</summary>
-
-  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": {
-      "touchdesigner": {
-        "args": [
-          "/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"
-      }
-    }
-  }
-  ```
-
-  *On Windows systems, include the drive letter like C: e.g. `C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js`*
-</details>
 
-### 3. Verify Connection
+## Verify Connection
 
 If the MCP server is recognized, setup is complete.
 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.
 
+### Directory Structure Requirements
+
+**Critical:** When using any method (Docker, npx), maintain the exact directory structure:
+
+```
+td/
+├── import_modules.py          # Module loader script
+├── mcp_webserver_base.tox     # Main TouchDesigner component
+└── modules/                   # Python modules directory
+    ├── mcp/                   # MCP core logic
+    ├── utils/                 # Shared utilities
+    └── td_server/             # Generated API server code
+```
+
+The `mcp_webserver_base.tox` component uses relative paths to locate Python modules. Moving or reorganizing these files will cause import errors in TouchDesigner.
+
 ![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
 
 
@@ -176,21 +178,28 @@ Not implemented
 
 ## For Developers
 
-### Building Client and API Server Code
+### Quick Start for Development
 
-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
+1. **Setup environment:**
+   ```bash
+   cp dotenv .env
+   # Adjust TD_WEB_SERVER_HOST and TD_WEB_SERVER_PORT in .env file
+   ```
 
-When you need to reflect the built code, please restart both the MCP server and TouchDesigner.
+2. **Build the project:**
+   ```bash
+   make build        # Docker-based build (recommended)
+   # OR
+   npm run build     # Node.js-based build
+   ```
 
-### 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.
+3. **Available commands:**
+   ```bash
+   npm run test      # Run unit and integration tests
+   npm run dev       # Launch MCP inspector for debugging
+   ```
 
-- `npm run dev`
-Launch @modelcontextprotocol/inspector to debug various features.
+**Note:** When you update the code, restart both the MCP server and TouchDesigner to reflect changes.
 
 ### Project Structure Overview
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { resolve } from "node:path";
+import path, { resolve } from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { config } from "dotenv";
 import { TouchDesignerServer } from "./server/touchDesignerServer.js";
@@ -28,7 +28,11 @@ export async function startServer() {
         process.exit(1);
     }
 }
-if (process.argv[1]) {
+// Start server if this file is executed directly
+import { fileURLToPath } from "node:url";
+const currentFilePath = path.normalize(fileURLToPath(import.meta.url));
+const argvFilePath = path.normalize(process.argv[1]);
+if (currentFilePath === argvFilePath) {
     startServer().catch((error) => {
         console.error("Failed to start server:", error);
         process.exit(1);

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.3.0
+ * OpenAPI spec version: 0.4.0-alpha.0
  */
 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.3.0
+ * OpenAPI spec version: 0.4.0-alpha.0
  */
 import { z as zod } from 'zod';
 /**

package/dist/server/connectionManager.js

@@ -33,7 +33,7 @@ export class ConnectionManager {
         catch (error) {
             this.transport = null;
             const err = error instanceof Error ? error : new Error(String(error));
-            console.error("Fatal error starting server! Check TouchDesigner setup and starting webserver.", err);
+            console.error("Fatal error starting server! Check TouchDesigner setup and starting webserver. For detailed setup instructions, see https://github.com/8beeeaaat/touchdesigner-mcp", err);
             return createErrorResult(err);
         }
     }

package/dist/server/touchDesignerServer.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "0.3.0",
+	"version": "0.4.0-alpha.0",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -41,9 +41,17 @@
 		"yaml": "^2.7.1"
 	},
 	"type": "module",
-	"main": "src/index.ts",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
 	"bin": {
-		"touchdesigner-mcp-server": "dist/cli.js"
+		"touchdesigner-mcp-server": "dist/cli.js",
+		"touchdesigner-mcp": "dist/cli.js"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
 	},
 	"scripts": {
 		"build": "run-s build:*",

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.3.0
+  version: 0.4.0-alpha.0
 servers:
 - url: "{baseUrl}"
   variables:

package/src/index.ts

@@ -1,6 +0,0 @@
-export { startServer } from "./cli.js";
-export { TouchDesignerServer } from "./server/touchDesignerServer.js";
-export {
-	createTouchDesignerClient,
-	TouchDesignerClient,
-} from "./tdClient/index.js";