tdmcp

Português

English

Português

English

Appearance

Arquitetura ​

O tdmcp são três programas que conversam entre si na sua máquina:

   Assistente de IA          servidor tdmcp               TouchDesigner
  (Claude / Cursor)   ──▶   (Node / TypeScript)    ──▶   (a ponte Python dentro do TD)
   "faça um túnel de         tools MCP + a base de         cria / conecta /
    feedback a partir        conhecimento de operadores    inspeciona / dá preview dos nós
    de noise"
  1. O assistente de IA é qualquer cliente compatível com MCP — Claude Desktop, Claude Code, Codex ou Cursor. É onde você descreve o que quer.
  2. O servidor tdmcp é um pequeno programa Node. Ele expõe à IA um conjunto de "tools" do TouchDesigner e uma base de conhecimento de operadores embutida, pelo Model Context Protocol.
  3. A ponte (bridge) é um pacote Python que roda dentro do TouchDesigner (atrás de um Web Server DAT). É o que de fato dirige o TD. Veja Bridge & REST API (em inglês).
cliente MCP ──stdio──▶ servidor tdmcp (Node/TS) ──HTTP──▶ ponte do TouchDesigner (Python)
                        ├── Camada 1  tools de artista (create_visual_system, …)
                        ├── Camada 2  blocos de montagem (create_node_chain, …)
                        ├── Camada 3  operações atômicas (create_td_node, …)
                        ├── Base de conhecimento (recursos MCP)
                        ├── Recipes (templates de rede validados)
                        └── Motor de feedback (erros / preview / performance)

As três camadas de tools ​

As tools são organizadas em camadas para que a IA escolha a altitude certa para cada tarefa. Veja a lista completa e sempre atualizada na referência de Tools (em inglês).

  • Camada 1 — tools de artista. Descreva um resultado (create_feedback_network, create_audio_reactive, create_generative_art, …) e receba uma rede inteira, conectada e organizada, muitas vezes já com um painel de controle pronto para performar.
  • Camada 2 — blocos de montagem. Peças de nível intermediário (create_node_chain, connect_nodes, create_control_panel, animate_parameter, create_external_io, …) para montar e controlar redes na mão.
  • Camada 3 — operações atômicas. CRUD de um nó só, mais inspeção, análise, renderização e as válvulas de escape em Python (create_td_node, find_td_nodes, get_td_node_errors, execute_python_script, …).

Um grupo separado de tools de vault (em inglês) faz a ponte entre um vault do Obsidian e o TouchDesigner.

O ciclo criar → verificar → visualizar ​

Toda construção de alto nível segue o mesmo ciclo, para que a IA veja e corrija o próprio trabalho em vez de chutar:

  1. Criar a rede a partir de uma recipe, de um padrão GLSL ou de Python gerado.
  2. Verificar lendo os erros de cook/compilação (get_td_node_errors, summarize_td_errors).
  3. Visualizar (preview) capturando o TOP de saída como uma imagem inline (get_preview).

As redes geradas são auto-organizadas num layout legível da esquerda para a direita (arrange_network) em vez de empilhar os nós uns sobre os outros.

Base de conhecimento ​

O servidor já vem com uma referência embutida e offline, para que a IA use operadores de verdade em vez de inventá-los: 629 operadores, 68 classes Python, padrões de fluxo de trabalho, técnicas de GLSL e tutoriais. Tudo isso é exposto como recursos MCP que a IA pode ler sob demanda:

tdmcp://operators/{category|name} · tdmcp://python-api/{class} · tdmcp://patterns/{name} · tdmcp://glsl/{name} · tdmcp://recipes/{name} · tdmcp://tutorials/{name}

A base de conhecimento é versionada no repositório, então um clone novo precisa só de npm install && npm run build. O npm run import:bottobot a regenera a partir do @bottobot/td-mcp e só é necessário para atualizá-la.

Recipes ​

Recipes são templates de rede validados (JSON) que a IA pode instanciar com apply_recipe. Elas cobrem pontos de partida comuns — túneis de feedback, reaction-diffusion, galáxias de partículas, barras de espectro de áudio, projection mapping e mais. Veja a Galeria de receitas para o que cada uma constrói, e o Contributing (em inglês) para adicionar as suas.

Transportes e eventos ​

O servidor fala dois transportes MCP:

  • stdio (padrão) — para clientes locais como Claude Desktop e Claude Code.
  • Streamable HTTP (TDMCP_TRANSPORT=http) — serve o MCP em POST/GET/DELETE /mcp no loopback com sessões com estado, para configurações remotas/headless. Veja Deployment (em inglês).

Ele também pode assinar um fluxo de eventos por WebSocket do TD (node.created / node.deleted / node.error / project.saved / timeline.frame / node.cook) e encaminhar os eventos como notificações de log do MCP. Eventos de alta frequência (timeline.frame, node.cook) são descartados a menos que você opte por recebê-los. Controle com TDMCP_EVENTS.

Segurança ​

A ponte do TouchDesigner roda Python arbitrário dentro do seu processo do TD — é justamente isso que permite ao assistente construir redes por você. Trate-a como uma porta aberta para a máquina onde o TD roda:

  • O Web Server DAT escuta na sua porta (padrão 9980) em todas as interfaces de rede. Qualquer um que alcance http://<seu-ip>:9980 pode rodar código naquela máquina. Só use numa rede confiável e/ou bloqueie a porta no firewall para o localhost.
  • Ligue a autenticação da ponte em redes não confiáveis: defina TDMCP_BRIDGE_TOKEN com um segredo compartilhado no ambiente do servidor e no ambiente do TouchDesigner. A ponte então rejeita qualquer requisição sem um Authorization: Bearer <token> correspondente (HTTP 401). Sem definir (padrão), mantém o fluxo local sem configuração.
  • TDMCP_RAW_PYTHON=off esconde apenas as duas tools de Python cru (execute_python_script, exec_node_method), onde o cliente escreve o código. Não é um botão de desligar a execução de código: muitas tools de mais alto nível ainda enviam o próprio Python templado para /api/exec, e um chamador direto na rede poderia atingir /api/exec e o method de um nó de qualquer forma. Para realmente fechar a execução de código, defina TDMCP_BRIDGE_ALLOW_EXEC=0 no ambiente do TouchDesigner — o controle definitivo (defesa em profundidade que vale até sem token); os endpoints estruturados continuam funcionando.
  • O servidor MCP escuta só no loopback (127.0.0.1) nos dois transportes e ativa a proteção contra DNS-rebinding no HTTP.
  • A ponte recusa requisições cross-origin de navegador. Qualquer requisição que traga um header Origin que não seja loopback é rejeitada (HTTP 401), então uma página web maliciosa não consegue fazer um POST silencioso para a ponte (CSRF / DNS-rebinding → execução de código drive-by). O servidor MCP não envia Origin, então o uso normal não é afetado.
  • A UI de chat do copiloto local (tdmcp chat) aplica a mesma proteção. Ela escuta só no loopback e rejeita (HTTP 403) qualquer requisição cujo Host ou Origin não seja um nome de loopback, então uma página que o artista visita não consegue dirigir o CRUD de nós contra o projeto ao vivo via http://127.0.0.1:<porta-do-chat>/chat.

Tudo isso é configurado pelas variáveis de ambiente.

Limitações conhecidas ​

  • Eventos de WebSocket são encaminhados como notificações de log do MCP nos dois transportes; eventos de alta frequência são descartados a menos que você opte por recebê-los.
  • Os construtores de áudio / partículas / 3D e as recipes exóticas (kinect, LED, projeção) produzem redes válidas e conectadas, mas usam nomes de parâmetro do TD em "melhor esforço" — pode ser preciso ajustar finamente, e elas emitem avisos nesse sentido.
  • O preview retorna o TOP na sua resolução nativa (o tamanho pedido é apenas uma sugestão).
  • A ponte é entregue como módulos Python mais um template de callbacks (um .tox binário não pode ser gerado a partir do código-fonte); o instalador de uma linha monta tudo para você.