TouchDesigner MCP

Dies ist die Implementierung eines MCP-Servers (Model Context Protocol) für TouchDesigner. Ziel ist es, KI-Agenten die Steuerung und Bedienung von TouchDesigner-Projekten zu ermöglichen.

Englisch /日本語

Überblick

TouchDesigner MCP fungiert als Brücke zwischen KI-Modellen und dem TouchDesigner WebServer DAT und ermöglicht KI-Agenten:

• Erstellen, Ändern und Löschen von Knoten

• Knoteneigenschaften und Projektstruktur abfragen

• TouchDesigner programmgesteuert über Python-Skripte steuern

Related MCP server: td-mcp

Verwendung

Erfordert die Installation von Docker oder Node.js

1. Klonen Sie das Repository:

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

2. Richten Sie die Umgebungsdatei ein und erstellen Sie:

Kopieren Sie die Vorlagendatei und passen Sie TD_WEB_SERVER_HOST und TD_WEB_SERVER_PORT nach Bedarf an, bevor Sie das Docker-Image erstellen.

cp dotenv .env
make build

3. Installieren Sie den API-Server in Ihrem TouchDesigner-Projekt:

Starten Sie TouchDesigner und importieren Sie die Komponente td/mcp_webserver_base.tox direkt in das TouchDesigner-Projekt, das Sie steuern möchten. Beispiel: Platzieren Sie sie als /project1/mcp_webserver_base

Durch das Importieren des Tox wird das Skript td/import_modules.py ausgelöst, das Module wie API-Server-Controller lädt.

Sie können die Startprotokolle überprüfen, indem Sie den Textport über das TouchDesigner-Menü öffnen.

4. Starten Sie den MCP-Servercontainer

docker-compose up -d

5. Konfigurieren Sie Ihren KI-Agenten für die Verwendung des Docker-Containers:

Beispiel für 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"
      ]
    }
  }
}

Geben Sie auf Windows-Systemen den Laufwerksbuchstaben an, z. B. C: C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml

So verwenden Sie das vorgefertigte JS direkt von Node.js:

1. Installieren Sie das Paket

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

2. Installieren Sie den API-Server in Ihrem TouchDesigner-Projekt:

Starten Sie TouchDesigner und importieren Sie die Komponente some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox direkt unter dem TouchDesigner-Projekt, das Sie steuern möchten. Beispiel: Platzieren Sie sie als /project1/mcp_webserver_base

Durch das Importieren des Tox wird das Skript some/node_modules/touchdesigner-mcp-server/td/import_modules.py ausgelöst, das Module wie API-Server-Controller lädt.

Sie können die Startprotokolle überprüfen, indem Sie den Textport über das TouchDesigner-Menü öffnen.

3. Konfigurieren Sie Ihren KI-Agenten:

Beispiel für 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"
    }
  }
}

Geben Sie auf Windows-Systemen den Laufwerksbuchstaben an, z. B. C: C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js

3. Verbindung überprüfen

Wenn der MCP-Server erkannt wird, ist die Einrichtung abgeschlossen. Falls er nicht erkannt wird, starten Sie Ihren KI-Agenten neu. Tritt beim Start ein Fehler auf, starten Sie den Agenten erneut, nachdem Sie TouchDesigner gestartet haben. Wenn der API-Server in TouchDesigner ordnungsgemäß läuft, kann der Agent die bereitgestellten Tools zur Bedienung von TouchDesigner nutzen.

MCP-Serverfunktionen

Dieser Server ermöglicht Operationen auf TouchDesigner über das Model Context Protocol (MCP) und bietet Verweise auf verschiedene Implementierungsdokumente.

Werkzeuge

Mithilfe von Tools können KI-Agenten Aktionen im TouchDesigner ausführen.

Eingabeaufforderungen

Eingabeaufforderungen enthalten Anweisungen für KI-Agenten zum Ausführen bestimmter Aktionen in TouchDesigner.

Ressourcen

Nicht implementiert

Für Entwickler

Erstellen von Client- und API-Servercode

1. cp dotenv .env

2. Passen Sie TD_WEB_SERVER_HOST und TD_WEB_SERVER_PORT in der .env Datei an Ihre Entwicklungsumgebung an

3. Führen Sie make build oder npm run build um den Code neu zu generieren

Wenn Sie den erstellten Code widerspiegeln müssen, starten Sie sowohl den MCP-Server als auch TouchDesigner neu.

Überprüfen des API-Servers

• npm run test Führen Sie Unit-Tests für den MCP-Servercode und Integrationstests mit TouchDesigner aus. Sie können Kommunikationsprotokolle überprüfen, indem Sie den Textport über das TouchDesigner-Menü öffnen.

• npm run dev Starten Sie @modelcontextprotocol/inspector, um verschiedene Funktionen zu debuggen.

Projektstrukturübersicht

├── 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)

Workflow zur API-Codegenerierung

Dieses Projekt verwendet OpenAPI-basierte Codegenerierungstools (Orval / openapi-generator-cli):

API-Definition: Der API-Vertrag zwischen dem Node.js MCP-Server und dem Python-Server, der in TouchDesigner ausgeführt wird, ist in src/api/index.yml definiert.

1. Python-Servergenerierung ( npm run gen:webserver ):

   • Verwendet openapi-generator-cli über Docker.

   • Liest src/api/index.yml .

   • Generiert ein Python-Server-Skelett ( td/modules/td_server/ ) basierend auf der API-Definition. Dieser Code wird in TouchDesigner über WebServer DAT ausgeführt.

   • Erfordert, dass Docker installiert und ausgeführt wird.

2. Python-Handler-Generierung ( npm run gen:handlers ):

   • Verwendet ein benutzerdefiniertes Node.js-Skript ( td/genHandlers.js ) und Mustache-Vorlagen ( td/templates/ ).

   • Liest den generierten Python-Servercode oder die OpenAPI-Spezifikation.

   • Generiert Handler-Implementierungen ( td/modules/mcp/controllers/generated_handlers.py ), die eine Verbindung zur Geschäftslogik in td/modules/mcp/services/api_service.py herstellen.

3. TypeScript-Client-Generierung ( npm run gen:mcp ):

   • Verwendet Orval , um API-Clientcode und Zod-Schemas für die Toolvalidierung aus dem von openapi-generator-cli gebündelten YAML-Schema zu generieren.

   • Generiert einen typisierten TypeScript-Client ( src/tdClient/ ), der vom Node.js-Server verwendet wird, um Anfragen an das WebServer-DAT zu stellen.

Der Build-Prozess ( npm run build ) führt alle notwendigen Generierungsschritte ( npm run gen ) aus, gefolgt von der TypeScript-Kompilierung ( tsc ).

Beitragen

Wir freuen uns über Ihre Beiträge!

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Zweig ( git checkout -b feature/amazing-feature )

3. Nehmen Sie Ihre Änderungen vor

4. Fügen Sie Tests hinzu und stellen Sie sicher, dass alles funktioniert ( npm test ).

5. Übernehmen Sie Ihre Änderungen ( git commit -m 'Add some amazing feature' )

6. Pushen Sie zu Ihrem Zweig ( git push origin feature/amazing-feature )

7. Öffnen einer Pull-Anfrage

Bitte schließen Sie bei Implementierungsänderungen immer entsprechende Tests ein.

Lizenz

MIT