터치디자이너 MCP

TouchDesigner용 MCP(Model Context Protocol) 서버 구현입니다. AI 에이전트가 TouchDesigner 프로젝트를 제어하고 운영할 수 있도록 하는 것이 목표입니다.

영어 / 일본어

개요

데모 클립

TouchDesigner MCP는 AI 모델과 TouchDesigner WebServer DAT 간의 브리지 역할을 하여 AI 에이전트가 다음을 수행할 수 있도록 합니다.

노드 생성, 수정 및 삭제
쿼리 노드 속성 및 프로젝트 구조
Python 스크립트를 통해 TouchDesigner를 프로그래밍 방식으로 제어합니다.

Related MCP server: SupaUI MCP Server

용법

Docker 또는 Node.js가 설치되어 있어야 합니다.

지도 시간

1. 저장소를 복제합니다.

지엑스피1

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:와 같은 드라이브 문자를 포함합니다. 예

Node.js에서 미리 빌드된 JS를 직접 사용하려면:

지도 시간

1. 패키지 설치

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

2. TouchDesigner 프로젝트에 API 서버를 설치하세요.

TouchDesigner를 시작하고 제어하려는 TouchDesigner 프로젝트 바로 아래에 some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox 컴포넌트를 가져옵니다. 예: /project1/mcp_webserver_base 에 배치합니다.

tox를 가져오면 API 서버 컨트롤러와 같은 모듈을 로드하는 some/node_modules/touchdesigner-mcp-server/td/import_modules.py 스크립트가 트리거됩니다.

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:와 같이 드라이브 문자를 포함합니다. 예:

3. 연결 확인

MCP 서버가 인식되면 설정이 완료된 것입니다. 인식되지 않으면 AI 에이전트를 다시 시작해 보세요. 시작 시 오류가 발생하면 TouchDesigner를 먼저 실행한 후 에이전트를 다시 시작해 보세요. TouchDesigner에서 API 서버가 정상적으로 실행되면 에이전트가 제공된 도구를 사용하여 TouchDesigner를 작동할 수 있습니다.

MCP 서버 기능

이 서버는 MCP(Model Context Protocol)를 통해 TouchDesigner에서 작업을 수행할 수 있도록 하며 다양한 구현 문서에 대한 참조를 제공합니다.

도구

도구를 사용하면 AI 에이전트가 TouchDesigner에서 작업을 수행할 수 있습니다.

도구 이름	설명
`create_td_node`	새로운 노드를 만듭니다.
`delete_td_node`	기존 노드를 삭제합니다.
`exec_node_method`	노드에서 Python 메서드를 호출합니다.
`execute_python_script`	TD에서 임의의 Python 스크립트를 실행합니다.
`get_td_class_details`	TD Python 클래스/모듈에 대한 세부 정보를 얻으세요.
`get_td_classes`	TouchDesigner Python 클래스 목록을 가져옵니다.
`get_td_info`	TD 서버 환경에 대한 정보를 얻으세요.
`get_td_node_parameters`	특정 노드의 매개변수를 가져옵니다.
`get_td_nodes`	상위 경로 아래의 노드를 가져옵니다(선택적으로 필터링).
`update_td_node_parameters`	특정 노드의 매개변수를 업데이트합니다.

프롬프트

프롬프트는 AI 에이전트가 TouchDesigner에서 특정 작업을 수행하기 위한 지침을 제공합니다.

프롬프트 이름	설명
`Search node`	노드에 대한 퍼지 검색을 수행하고 이름, 패밀리, 유형을 기반으로 정보를 검색합니다.
`Node connection`	TouchDesigner 내에서 노드를 연결하는 방법에 대한 지침을 제공합니다.
`Check node errors`	지정된 노드의 오류를 확인하고, 자식 노드가 있는 경우 해당 자식 노드에 대해서도 재귀적으로 오류를 확인합니다.

자원

구현되지 않음

개발자를 위한

클라이언트 및 API 서버 코드 빌드

cp dotenv .env
개발 환경과 일치하도록 .env 파일에서 TD_WEB_SERVER_HOST 및 TD_WEB_SERVER_PORT 조정하세요.
make build 또는 npm run build 실행하여 코드를 다시 생성합니다.

빌드된 코드를 반영해야 할 때 MCP 서버와 TouchDesigner를 모두 다시 시작하세요.

API 서버 확인

npm run test TouchDesigner를 사용하여 MCP 서버 코드에 대한 단위 테스트와 통합 테스트를 실행합니다. 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 에 정의되어 있습니다.

Python 서버 생성(
- Docker를 통해 openapi-generator-cli 사용합니다.
- src/api/index.yml 읽습니다.
- API 정의를 기반으로 Python 서버 스켈레톤( td/modules/td_server/ )을 생성합니다. 이 코드는 TouchDesigner 내부에서 WebServer DAT를 통해 실행됩니다.
- Docker를 설치하고 실행해야 합니다.
Python 핸들러 생성(
- 사용자 정의 Node.js 스크립트( td/genHandlers.js )와 Mustache 템플릿( td/templates/ )을 사용합니다.
- 생성된 Python 서버 코드나 OpenAPI 사양을 읽습니다.
- td/modules/mcp/controllers/generated_handlers.py``td/modules/mcp/services/api_service.py generated_handlers.py)을 생성합니다.
TypeScript 클라이언트 생성(
- Orval 사용하여 openapi-generator-cli 에 포함된 스키마 YAML에서 도구 검증을 위한 API 클라이언트 코드와 Zod 스키마를 생성합니다.
- Node.js 서버가 WebServer DAT에 요청을 하는 데 사용되는 유형화된 TypeScript 클라이언트( src/tdClient/ )를 생성합니다.

빌드 프로세스( npm run build )는 모든 필수 생성 단계( npm run gen )를 실행한 후 TypeScript 컴파일( tsc )을 실행합니다.

기여하다

여러분의 기여를 환영합니다!

저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
변경 사항을 만드세요
테스트를 추가하고 모든 것이 제대로 작동하는지 확인합니다( npm test )
변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
브랜치에 푸시합니다( git push origin feature/amazing-feature )
풀 리퀘스트 열기

구현 내용을 변경할 때는 항상 적절한 테스트를 포함하세요.

특허

MIT

TouchDesigner MCP