npm - touchdesigner-mcp-server - Versions diffs - 1.3.1 → 1.4.0 - Mend

touchdesigner-mcp-server 1.3.1 → 1.4.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 (13) hide show

package/README.ja.md +4 -307
package/README.md +9 -308
package/dist/cli.js +132 -16
package/dist/core/logger.js +13 -0
package/dist/server/touchDesignerServer.js +19 -0
package/dist/transport/config.js +75 -0
package/dist/transport/expressHttpManager.js +235 -0
package/dist/transport/factory.js +198 -0
package/dist/transport/index.js +12 -0
package/dist/transport/sessionManager.js +276 -0
package/dist/transport/transportRegistry.js +272 -0
package/dist/transport/validator.js +78 -0
package/package.json +4 -1

package/README.ja.md CHANGED Viewed

@@ -2,7 +2,7 @@
 TouchDesignerのためのMCP(Model Context Protocol) サーバー実装です。AIエージェントがTouchDesignerプロジェクトを制御・操作できるようになることを目指しています。
-[English](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.md) / [日本語](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.ja.md)
+[English](README.md) / [日本語](README.ja.md)
 ## 概要
@@ -14,227 +14,9 @@ TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッ
 - ノードプロパティやプロジェクト構造の照会
 - 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 + MCP Bundle（推奨）</summary>
-##### 1. ファイルをダウンロード
-[リリースページ](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)から以下をダウンロード：
-- **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
-- **[MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (.mcpb)**: `touchdesigner-mcp.mcpb`
-##### 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>
-  TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
-  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
-##### 3. MCP Bundleをインストール
-`touchdesigner-mcp.mcpb`ファイルをダブルクリックしてClaude DesktopにMCP Bundleをインストール
-<https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
-##### 4. MCP Bundleが自動的にTouchDesignerサーバー接続を処理
-**⚠️ 重要:** TouchDesignerコンポーネントのディレクトリ構造は展開した状態を正確に保持してください。`mcp_webserver_base.tox`コンポーネントは`modules/`ディレクトリやその他のファイルへの相対パスを参照しています。
-</details>
-<details>
-  <summary>方法2: npxを利用する</summary>
-*Node.jsがインストールされていることが前提となります*
-##### 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>
-  TouchDesignerのメニューからTextportを起動してサーバーの起動ログを確認できます。
-  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
-##### 2. MCPサーバー設定
-*例 Claude Desktop*
-```json
-{
-  "mcpServers": {
-    "touchdesigner": {
-      "command": "npx",
-      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
-    }
-  }
-}
-```
-**カスタマイズ：** `--host`と`--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
-```json
-"args": [
-  "-y",
-  "touchdesigner-mcp-server@latest",
-  "--stdio",
-  "--host=http://custom_host",
-  "--port=9982"
-]
-```
-</details>
-<details>
-  <summary>方法3: Dockerイメージを利用</summary>
-[![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
-##### 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
-make build
-```
-##### 3. TouchDesignerプロジェクトにMCP連携用のAPIサーバーを設置
-TouchDesignerを起動し、`td/mcp_webserver_base.tox`コンポーネントを操作したいTouchDesignerプロジェクト直下にインポートします。
-例: `/project1/mcp_webserver_base`となるように配置
-toxファイルのインポートにより`td/import_modules.py`スクリプトが実行され、APIサーバーのコントローラなどのモジュールがロードされます。
-<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)
-##### 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/cli.js",
-        "--stdio",
-        "--host=http://host.docker.internal"
-      ]
-    }
-  }
-}
-```
-*Windows システムでは、ドライブレターを含めてください。例：`C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml`*
-**カスタマイズ：** `--port`引数を追加してTouchDesignerサーバー接続をカスタマイズできます：
-  ```json
-"args": [
-  ...,
-  "--stdio",
-  "--host=http://host.docker.internal",
-  "--port=9982"
-]
-  ```
-</details>
-## 接続確認
-MCPサーバーが認識されていればセットアップは完了です。
-認識されない場合は、AIエージェントを再起動してください。
-起動時にエラーが表示される場合は、TouchDesignerを先に起動してからAIエージェントを再度起動してください。
-TouchDesignerでAPIサーバーが実行されていれば、エージェントは提供されたツール等を通じてTouchDesignerを使用できます。
-### ディレクトリ構造要件
-**重要:** どの方法（Docker、npx）を使用する場合でも、正確なディレクトリ構造を維持してください：
-```
-td/
-├── import_modules.py          # モジュールローダースクリプト
-├── mcp_webserver_base.tox     # メインTouchDesignerコンポーネント
-└── modules/                   # Pythonモジュールディレクトリ
-    ├── mcp/                   # MCPコアロジック
-    ├── utils/                 # 共有ユーティリティ
-    └── td_server/             # 生成されたAPIサーバーコード
-```
-`mcp_webserver_base.tox` コンポーネントは相対パスを使用してPythonモジュールを検索します。これらのファイルを移動したり再編成したりすると、TouchDesignerでインポートエラーが発生します。
-![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
+**[インストールガイド](docs/installation.ja.md)** を参照してください。
 ## MCPサーバーの機能
@@ -275,92 +57,7 @@ td/
 ## 開発者向け
-### 開発のクイックスタート
-1. **環境設定:**
-   ```bash
-   # リポジトリをクローンして依存関係をインストール
-   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-   cd touchdesigner-mcp
-   npm install
-   ```
-2. **プロジェクトをビルド:**
-   ```bash
-   make build        # Docker-based build（推奨）
-   # または
-   npm run build     # Node.js-based build
-   ```
-3. **利用可能なコマンド:**
-   ```bash
-   npm run test      # ユニットテストと統合テストを実行
-   npm run dev       # デバッグ用MCPインスペクターを起動
-   ```
-**注意:** コードを更新した場合は、MCPサーバーとTouchDesignerの両方を再起動して変更を反映してください。
-### プロジェクト構造の概要
-```
-├── src/                       # MCPサーバーソースコード
-│   ├── api/                  # TD WebServerに対するOpenAPI仕様
-│   ├── core/                 # コアユーティリティ（ロガー、エラーハンドリング）
-│   ├── features/             # MCP機能実装
-│   │   ├── prompts/         # プロンプトハンドラ
-│   │   ├── resources/       # リソースハンドラ
-│   │   └── tools/           # ツールハンドラ (例: tdTools.ts)
-│   ├── gen/                  # OpenAPIスキーマから生成されたMCPサーバー向けコード
-│   ├── server/               # MCPサーバーロジック (接続, メインサーバークラス)
-│   ├── tdClient/             # TD接続API用クライアント
-│   ├── index.ts              # Node.jsサーバーのメインエントリーポイント
-│   └── ...
-├── td/                        # TouchDesigner関連ファイル
-│   ├── modules/              # TouchDesigner用Pythonモジュール
-│   │   ├── mcp/              # TD内でMCPからのリクエストを処理するコアロジック
-│   │   │   ├── controllers/ # APIリクエストコントローラ (api_controller.py, generated_handlers.py)
-│   │   │   └── services/    # ビジネスロジック (api_service.py)
-│   │   ├── td_server/        # OpenAPIスキーマから生成されたPythonモデルコード
-│   │   └── utils/            # 共有Pythonユーティリティ
-│   ├── templates/             # Pythonコード生成用Mustacheテンプレート
-│   ├── genHandlers.js         # generated_handlers.py 生成用のNode.jsスクリプト
-│   ├── import_modules.py      # TDへ APIサーバ関連モジュールをインポートするヘルパースクリプト
-│   └── mcp_webserver_base.tox # メインTouchDesignerコンポーネント
-├── tests/                      # テストコード
-│   ├── integration/
-│   └── unit/
-└── 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/`) を生成します。
-ビルドプロセス (`npm run build`) は、必要なすべての生成ステップ (`npm run gen`) を実行し、その後にTypeScriptコンパイル (`tsc`) を行います。
-### バージョン管理
-- `package.json` はすべてのコンポーネントバージョンの唯一の信頼できる情報源です（Node.js MCPサーバー、TouchDesigner Python API、MCPバンドル、および `server.json` メタデータ）。
-- バージョンを更新する際は `npm version <patch|minor|major>`（または内部で使用される `npm run gen:version`）を実行してください。このスクリプトは `pyproject.toml`、`td/modules/utils/version.py`、`mcpb/manifest.json`、および `server.json` を書き換え、リリースワークフローがタグ値を信頼できるようにします。
-- GitHubリリースワークフロー（`.github/workflows/release.yml`）はコミットを `v${version}` としてタグ付けし、同じバージョン番号から `touchdesigner-mcp-td.zip` / `touchdesigner-mcp.mcpb` を公開します。リリースをトリガーする前に必ず同期ステップを実行し、すべてのアーティファクトが整合するようにしてください。
+ローカル環境構築やクライアント設定、コード生成ワークフローなどの詳細は **[開発者ガイド](docs/development.ja.md)** を参照してください。
 ## トラブルシューティング

package/README.md CHANGED Viewed

@@ -2,7 +2,7 @@
 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.
-[English](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.md) / [日本語](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.ja.md)
+[English](README.md) / [日本語](README.ja.md)
 ## Overview
@@ -14,227 +14,12 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
 - Query node properties and project structure
 - Programmatically control TouchDesigner via Python scripts
-## Architecture
+## Installation
-```mermaid
-flowchart LR
-    A["🤖<br/>MCP client<br/>(Claude / Codex / ...)"]
+Read the **[Installation Guide](docs/installation.md)**.
-    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 MCP Bundle (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`
-- **[MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (.mcpb)**: `touchdesigner-mcp.mcpb`
-### 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>
-  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 MCP Bundle
-Double-click the `touchdesigner-mcp.mcpb` file to install the bundle in Claude Desktop.
-<https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
-### 4. Connect to the Server
-The MCP bundle 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.
-</details>
-<details>
-  <summary>Method 2: Using npx</summary>
-*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>
-  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)
-### 2. Set up the MCP Server Configuration
-*Example for Claude Desktop:*
-```json
-{
-  "mcpServers": {
-    "touchdesigner": {
-      "command": "npx",
-      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
-    }
-  }
-}
-```
-**Customization:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
-```json
-"args": [
-  "-y",
-  "touchdesigner-mcp-server@latest",
-  "--stdio",
-  "--host=http://custom_host",
-  "--port=9982"
-]
-```
-</details>
-<details>
-  <summary>Method 3: Using a Docker Image</summary>
-  [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
-### 1. Clone the repository
-  ```bash
-  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-  cd touchdesigner-mcp
-  ```
-### 2. Build the Docker image
-  ```bash
-  make build
-  ```
-### 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>
-  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
-  ```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/cli.js",
-          "--stdio",
-          "--host=http://host.docker.internal"
-        ]
-      }
-    }
-  }
-```
-  *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": [
-  ...,
-  "--stdio",
-  "--host=http://host.docker.internal",
-  "--port=9982"
-]
-  ```
-</details>
-## Verify Connection
-If the MCP server is recognized, the 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.
-When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate it.
-### Directory Structure Requirements
-**Critical:** When using any method, you must maintain the original 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)
+The guide includes the required TouchDesigner preparation, per-agent setup, verification steps, and
+troubleshooting tips.
 ## MCP Server Features
@@ -273,94 +58,10 @@ 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
-   cd touchdesigner-mcp
-   npm install
-   ```
-2. **Build the project:**
-   ```bash
-   make build        # Docker-based build (recommended)
-   # OR
-   npm run build     # Node.js-based build
-   ```
-3. **Available commands:**
-   ```bash
-   npm run test      # Run unit and integration tests
-   npm run dev       # Launch the MCP inspector for debugging
-   ```
-**Note:** When you update the code, you must restart both the MCP server and TouchDesigner to apply the changes.
-### Project Structure Overview
-```
-├── src/                       # MCP server source code
-│   ├── api/                  # OpenAPI spec for the TouchDesigner WebServer
-│   ├── core/                 # Core utilities (logger, error handling)
-│   ├── features/             # MCP feature implementations
-│   │   ├── prompts/         # Prompt handlers
-│   │   ├── resources/       # Resource handlers
-│   │   └── tools/           # Tool handlers (e.g., tdTools.ts)
-│   ├── gen/                  # Code generated from the OpenAPI schema for the MCP server
-│   ├── server/               # MCP server logic (connections, main server class)
-│   ├── tdClient/             # TouchDesigner connection API client
-│   ├── index.ts              # Main entry point for the Node.js server
-│   └── ...
-├── td/                        # TouchDesigner-related files
-│   ├── modules/              # Python modules for TouchDesigner
-│   │   ├── mcp/              # Core logic for handling MCP requests in TouchDesigner
-│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
-│   │   │   └── services/    # Business logic (api_service.py)
-│   │   ├── td_server/        # Python model code generated from the OpenAPI schema
-│   │   └── utils/            # Shared Python utilities
-│   ├── templates/             # Mustache templates for Python code generation
-│   ├── genHandlers.js         # Node.js script for generating generated_handlers.py
-│   ├── import_modules.py      # Helper script to import API server modules into TouchDesigner
-│   └── mcp_webserver_base.tox # Main TouchDesigner component
-├── tests/                      # Test code
-│   ├── integration/
-│   └── unit/
-└── 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.
-The build process (`npm run build`) runs all necessary generation steps (`npm run gen`), followed by TypeScript compilation (`tsc`).
-### Version management
-- `package.json` is the single source of truth for every component version (Node.js MCP server, TouchDesigner Python API, MCP bundle, and `server.json` metadata).
-- Run `npm version <patch|minor|major>` (or the underlying `npm run gen:version`) whenever you bump the version. The script rewrites `pyproject.toml`, `td/modules/utils/version.py`, `mcpb/manifest.json`, and `server.json` so that the release workflow can trust the tag value.
-- The GitHub release workflow (`.github/workflows/release.yml`) tags the commit as `v${version}` and publishes `touchdesigner-mcp-td.zip` / `touchdesigner-mcp.mcpb` from the exact same version number. Always run the sync step before triggering a release so that every artifact stays aligned.
+## Developer Guide
+Looking for local setup, client configuration, project structure, or release workflow notes?
+See the **[Developer Guide](docs/development.md)** for all developer-facing documentation.
 ## Troubleshooting