TouchDesigner МКП

Это реализация сервера MCP (Model Context Protocol) для TouchDesigner. Цель — позволить агентам ИИ контролировать и управлять проектами TouchDesigner.

Английский /日本語

Обзор

TouchDesigner MCP выступает в качестве моста между моделями ИИ и TouchDesigner WebServer DAT, позволяя агентам ИИ:

• Создание, изменение и удаление узлов

• Запрос свойств узла и структуры проекта

• Программное управление TouchDesigner с помощью скриптов Python

Related MCP server: SupaUI MCP Server

Использование

Требуется установка Docker или Node.js

1. Клонируйте репозиторий:

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

2. Настройте файл среды и выполните сборку:

Скопируйте файл шаблона и при необходимости настройте TD_WEB_SERVER_HOST и TD_WEB_SERVER_PORT перед созданием образа Docker.

cp dotenv .env
make build

3. Установите API-сервер в свой проект TouchDesigner:

Запустите TouchDesigner и импортируйте компонент td/mcp_webserver_base.tox непосредственно в проект TouchDesigner, которым вы хотите управлять. Пример: поместите его как /project1/mcp_webserver_base

Импорт tox запустит скрипт td/import_modules.py , который загружает модули, такие как контроллеры сервера API.

Вы можете проверить журналы загрузки, открыв Textport из меню TouchDesigner.

4. Запустите контейнер сервера MCP.

docker-compose up -d

5. Настройте свой ИИ-агент для использования контейнера Docker:

Пример для 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:, например

Чтобы использовать готовый JS-код непосредственно из Node.js:

1. Установить пакет

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

2. Установите API-сервер в свой проект TouchDesigner:

Запустите 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.

Вы можете проверить журналы загрузки, открыв Textport из меню TouchDesigner.

3. Настройте своего ИИ-агента:

Пример для 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. Если сервер API работает правильно в TouchDesigner, агент может использовать предоставленные инструменты для работы TouchDesigner.

Возможности сервера MCP

Этот сервер позволяет выполнять операции на TouchDesigner через протокол контекста модели (MCP) и предоставляет ссылки на различные документы по реализации.

Инструменты

Инструменты позволяют агентам ИИ выполнять действия в TouchDesigner.

Подсказки

Подсказки предоставляют инструкции агентам ИИ по выполнению определенных действий в TouchDesigner.

Ресурсы

Не реализовано

Для разработчиков

Создание клиентского и серверного кода API

1. cp dotenv .env

2. Настройте TD_WEB_SERVER_HOST и TD_WEB_SERVER_PORT в файле .env в соответствии с вашей средой разработки.

3. Запустите make build или npm run build для повторной генерации кода.

Если вам необходимо отразить построенный код, перезапустите сервер MCP и TouchDesigner.

Проверка API-сервера

• npm run test Запуск модульных тестов для кода сервера MCP и интеграционных тестов с TouchDesigner. Вы можете проверить журналы связи, открыв Textport из меню TouchDesigner.

• 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: контракт API между сервером Node.js MCP и сервером Python, работающим внутри TouchDesigner, определен в src/api/index.yml .

1. Генерация сервера Python (

   • Использует openapi-generator-cli через Docker.

   • Читает src/api/index.yml .

   • Генерирует скелет сервера Python ( td/modules/td_server/ ) на основе определения API. Этот код выполняется внутри TouchDesigner через WebServer DAT.

   • Требуется установленный и запущенный Docker.

2. Генерация обработчика 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 .

3. Генерация клиента TypeScript (

   • Использует Orval для генерации клиентского кода API и схем Zod для проверки инструментов из схемы YAML, объединенной с openapi-generator-cli .

   • Генерирует типизированный клиент TypeScript ( src/tdClient/ ), используемый сервером Node.js для выполнения запросов к WebServer DAT.

Процесс сборки ( 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. Откройте запрос на извлечение

При внесении изменений в реализацию всегда включайте соответствующие тесты.

Лицензия

Массачусетский технологический институт