TouchDesigner MCP

TouchDesigner MCP

Esta é uma implementação de um servidor MCP (Model Context Protocol) para TouchDesigner. Seu objetivo é permitir que agentes de IA controlem e operem projetos TouchDesigner.

English / 日本語

Visão Geral

O TouchDesigner MCP atua como uma ponte entre modelos de IA e o TouchDesigner WebServer DAT, permitindo que agentes de IA:

• Criem, modifiquem e excluam nós
• Consultem propriedades de nós e estrutura de projetos
• Controlem o TouchDesigner programaticamente via scripts Python

Instalação

Diga ao agente de IA que você já usa:

Configure https://github.com/8beeeaaat/touchdesigner-mcp

É isso. O procedimento completo está no Guia de Instalação — ele começa com uma tabela que associa cada aplicativo de IA à sua rota, e todos começam em TouchDesigner Setup. Ou siga você mesmo, passo a passo.

Se estiver atualizando, consulte o procedimento na Última Versão.

Recursos do Servidor MCP

Este servidor permite que agentes de IA realizem operações no TouchDesigner usando o Model Context Protocol (MCP).

Ferramentas

As ferramentas permitem que agentes de IA executem ações no TouchDesigner.

Nome da Ferramenta	Descrição
create_td_node	Cria um novo nó.
delete_td_node	Exclui um nó existente.
describe_td_tools	Gera um manifesto das ferramentas TouchDesigner disponíveis.
exec_node_method	Chama um método Python em um nó.
execute_python_script	Executa um script Python arbitrário no TouchDesigner.
get_td_class_details	Obtém detalhes de uma classe ou módulo Python do TouchDesigner.
get_td_classes	Obtém uma lista de classes Python do TouchDesigner.
get_td_info	Obtém informações sobre o ambiente do servidor TouchDesigner.
get_td_module_help	Obtém a documentação help() do Python para módulos/classes do TouchDesigner.
get_td_node_errors	Verifica erros e avisos em um nó e seus descendentes. Arquivos ausentes, referências pendentes e falhas de shader são avisos, portanto, ausência de erros não significa que está saudável.
get_td_node_parameters	Obtém os parâmetros de um nó específico.
get_td_nodes	Obtém nós sob um caminho pai, com filtragem opcional.
get_top_image	Captura a saída atual de um nó TOP como imagem.
update_td_node_parameters	Atualiza os parâmetros de um nó específico.

Prompts

Os prompts fornecem instruções para agentes de IA executarem ações específicas no TouchDesigner.

Nome do Prompt	Descrição
Search node	Busca difusa por nós e recupera informações com base em nome, família ou tipo.
Node connection	Fornece instruções para conectar nós dentro do TouchDesigner.
Check node errors	Verifica erros e avisos em um nó especificado e, recursivamente, em seus descendentes.

Recursos

Não implementado.

Guia do Desenvolvedor

Procurando por configuração local, configuração de cliente, estrutura de projeto ou notas sobre o fluxo de trabalho de lançamento? Consulte o Guia do Desenvolvedor para toda a documentação voltada a desenvolvedores.

Solução de Problemas

Solução de problemas de compatibilidade de versão

O servidor MCP e o componente TouchDesigner são versionados em dois eixos independentes: a versão do pacote npm e a versão da API (o contrato entre o servidor MCP e o componente .tox). Cada versão declara a versão da API com a qual é distribuída (expectedApiVersion) e a mínima que suporta (minApiVersion, atualmente 1.3.0). A versão da API do componente conectado é comparada com esses dois valores — a versão do pacote npm em si nunca bloqueia a compatibilidade, portanto, atualizar apenas o servidor MCP nunca invalida um componente suportado.

API Server (componente)	Condição	Comportamento	Status
= versão esperada da API	Corresponde ao .tox distribuído	✅ Funciona silenciosamente	Compatível
≥ mínima, < esperada	Componente mais antigo	⚠️ Aviso "Atualização Recomendada" anexado às respostas, continua	Aviso
> esperada, mesmo MAJOR	Componente mais novo	⚠️ Aviso para atualizar o servidor MCP, continua	Aviso
MAJOR acima do esperado	Nova geração de API	❌ A execução é interrompida — atualize o servidor MCP	Erro
< mínima (ou ausente)	Muito antigo	❌ A execução é interrompida — atualize o componente	Erro

• Para resolver erros de compatibilidade:

  1. Baixe o touchdesigner-mcp-td.zip mais recente na página de versões.
  2. Exclua a pasta touchdesigner-mcp-td existente e substitua-a pelo conteúdo recém-extraído.
  3. Remova o componente mcp_webserver_base antigo do seu projeto TouchDesigner e importe o .tox da nova pasta.
  4. Reinicie o TouchDesigner e o agente de IA que executa o servidor MCP (por exemplo, Claude Desktop).

• Para desenvolvedores: Ao desenvolver localmente, execute npm run version após editar package.json (ou simplesmente use npm version ...). Isso mantém a API Python (pyproject.toml + td/modules/utils/version.py), mcpCompatibility.expectedApiVersion, o manifesto do pacote MCP e os metadados de registro sincronizados para que a verificação de compatibilidade em tempo de execução seja bem-sucedida.

Para uma análise mais aprofundada de como o servidor MCP aplica essas regras, consulte Verificação de Compatibilidade de Versão.

Solução de problemas de erros de conexão

• TouchDesignerClient armazena em cache verificações de conexão com falha por 60 segundos. Chamadas subsequentes de ferramentas reutilizam o erro em cache para evitar sobrecarregar o TouchDesigner e tentam novamente automaticamente após o TTL expirar.
• Quando o servidor MCP não consegue alcançar o TouchDesigner, você recebe mensagens de erro orientadas com correções concretas:
  • ECONNREFUSED / "conexão recusada": inicie o TouchDesigner, garanta que o WebServer DAT de mcp_webserver_base.tox esteja em execução e confirme a porta configurada (padrão 9981).
  • ETIMEDOUT / "tempo esgotado": o TouchDesigner está respondendo lentamente ou a rede está bloqueada. Reinicie o TouchDesigner/WebServer DAT ou verifique sua conexão de rede.
  • ENOTFOUND / getaddrinfo: o nome do host é inválido. Use 127.0.0.1 a menos que você o tenha alterado explicitamente.
• O texto de erro estruturado também é registrado por meio de ILogger, para que você possa verificar os logs do MCP e entender por que uma solicitação foi interrompida antes de chegar ao TouchDesigner.
• Depois que o problema subjacente for corrigido, basta executar a ferramenta novamente — o cliente limpa o erro em cache e reverifica a conexão automaticamente.

Contribuindo

Aceitamos suas contribuições!

1. Faça um fork do repositório.
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature).
3. Faça suas alterações.
4. Adicione testes e garanta que tudo funcione (npm test).
5. Faça commit das suas alterações (git commit -m 'Add some amazing feature').
6. Envie para o seu branch (git push origin feature/amazing-feature).
7. Abra um pull request.

Inclua sempre testes apropriados ao fazer alterações de implementação.

Licença

MIT