タッチデザイナーMCP

これはTouchDesigner用のMCP（Model Context Protocol）サーバーの実装です。AIエージェントがTouchDesignerプロジェクトを制御・操作できるようにすることを目的としています。

英語/日本語

概要

TouchDesigner MCP は、AI モデルと TouchDesigner WebServer DAT 間のブリッジとして機能し、AI エージェントが次のことを実行できるようにします。

• ノードの作成、変更、削除

• クエリノードのプロパティとプロジェクト構造

• PythonスクリプトでTouchDesignerをプログラム的に制御する

Related MCP server: td-mcp

使用法

DockerまたはNode.jsのインストールが必要です

1. リポジトリをクローンします。

git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
cd touchdesigner-mcp

2. 環境ファイルを設定し、ビルドします。

Docker イメージをビルドする前に、テンプレート ファイルをコピーし、必要に応じて TD_WEB_SERVER_HOST と TD_WEB_SERVER_PORT を調整します。

cp dotenv .env
make build

3. TouchDesigner プロジェクトに API サーバーをインストールします。

TouchDesignerを起動し、制御したいTouchDesignerプロジェクトの直下にtd/mcp_webserver_base.toxコンポーネントをインポートします。例： /project1/mcp_webserver_baseに配置します。

tox をインポートすると、API サーバー コントローラーなどのモジュールをロードするtd/import_modules.pyスクリプトがトリガーされます。

TouchDesigner メニューから Textport を開くと、ブート ログを確認できます。

4. MCPサーバーコンテナを起動する

docker-compose up -d

5. Docker コンテナを使用するように AI エージェントを構成します。

Claude Desktopの例

{
  "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

Node.js から事前に構築された JS を直接使用するには:

1. パッケージをインストールする

mkdir some && cd ./some  # If you need a new directory
npm install touchdesigner-mcp-server

2. TouchDesigner プロジェクトに API サーバーをインストールします。

TouchDesignerを起動し、 some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.toxコンポーネントを、制御したいTouchDesignerプロジェクトの直下にインポートします。例： /project1/mcp_webserver_baseに配置します。

tox をインポートするとsome/node_modules/touchdesigner-mcp-server/td/import_modules.pyスクリプトがトリガーされ、API サーバー コントローラーなどのモジュールが読み込まれます。

TouchDesigner メニューから Textport を開くと、ブート ログを確認できます。

3. AIエージェントを設定します。

Claude Desktopの例

{
  "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"
    }
  }
}

Windows システムでは、C: のようなドライブ文字を含めます (例: C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js

3. 接続を確認する

MCPサーバーが認識されればセットアップは完了です。認識されない場合は、AIエージェントを再起動してください。起動時にエラーが表示される場合は、TouchDesignerを起動してからエージェントを再起動してください。TouchDesignerでAPIサーバーが正常に動作していれば、エージェントは提供されているツールを使用してTouchDesignerを操作できます。

MCP サーバーの機能

このサーバーは、モデル コンテキスト プロトコル (MCP) を介して TouchDesigner での操作を可能にし、さまざまな実装ドキュメントへの参照を提供します。

ツール

ツールを使用すると、AI エージェントは TouchDesigner でアクションを実行できます。

プロンプト

プロンプトは、AI エージェントに TouchDesigner で特定のアクションを実行するための指示を提供します。

リソース

実装されていません

開発者向け

クライアントとAPIサーバーコードの構築

1. cp dotenv .env

2. 開発環境に合わせて、 .envファイルのTD_WEB_SERVER_HOSTとTD_WEB_SERVER_PORTを調整します。

3. コードを再生成するには、 make buildまたはnpm run build実行します。

ビルドしたコードを反映する必要がある場合は、MCP サーバーと TouchDesigner の両方を再起動してください。

APIサーバーの検証

• npm run testでMCPサーバーコードの単体テストとTouchDesignerとの統合テストを実行します。TouchDesignerメニューからTextportを開くと、通信ログを確認できます。

• npm run devさまざまな機能をデバッグするには、@modelcontextprotocol/inspector を起動します。

プロジェクト構造の概要

├── src/                       # MCP server source code
│   ├── api/                  # OpenAPI spec for TD 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 OpenAPI schema for MCP server
│   ├── server/               # MCP server logic (connections, main server class)
│   ├── tdClient/             # TD connection API client
│   ├── index.ts              # Main entry point for Node.js server
│   └── ...
├── td/                        # TouchDesigner related files
│   ├── modules/              # Python modules for TouchDesigner
│   │   ├── mcp/              # Core logic for handling MCP requests in TD
│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
│   │   │   └── services/    # Business logic (api_service.py)
│   │   ├── td_server/        # Python model code generated from 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 TD
│   └── mcp_webserver_base.tox # Main TouchDesigner component
├── tests/                      # Test code
│   ├── integration/
│   └── unit/
├── .env                        # Local environment variables (git ignored)
├── dotenv                      # Template for .env
└── orval.config.ts             # Orval config (TS client generation)

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 クライアント コードと Zod スキーマを生成します。

   • Node.js サーバーが WebServer DAT にリクエストを行うために使用する、型指定された TypeScript クライアント ( src/tdClient/ ) を生成します。

ビルド プロセス ( npm run build ) では、必要なすべての生成ステップ ( npm run gen ) が実行され、その後に TypeScript コンパイル ( tsc ) が実行されます。

貢献

皆様のご協力をお待ちしております！

1. リポジトリをフォークする

2. 機能ブランチを作成する ( git checkout -b feature/amazing-feature )

3. 変更を加える

4. テストを追加してすべてが機能することを確認する（ npm test ）

5. 変更をコミットします ( git commit -m 'Add some amazing feature' )

6. ブランチにプッシュします ( git push origin feature/amazing-feature )

7. プルリクエストを開く

実装を変更するときは、常に適切なテストを含めてください。

ライセンス

マサチューセッツ工科大学