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 programaticamente o TouchDesigner por meio de scripts Python

Instalação

Consulte o Guia de Instalação.

Se você 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 Python help() para módulos/classes do TouchDesigner.
get_td_node_errors	Verifica erros em um nó especificado e seus filhos.
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	Pesquisa 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 no TouchDesigner.
Check node errors	Verifica erros em um nó especificado e, recursivamente, em seus filhos.

Recursos

Não implementado.

Guia do Desenvolvedor

Procurando por configuração local, configuração do cliente, estrutura do 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.

Servidor de API (componente)	Condição	Comportamento	Status
= versão de API esperada	Corresponde ao .tox distribuído	✅ Funciona silenciosamente	Compatível
≥ mínimo, < esperado	Componente mais antigo	⚠️ Aviso "Atualização Recomendada" anexado às respostas, continua	Aviso
> esperado, 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ínimo (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 da 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 do 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

• 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ê agora recebe mensagens de erro orientadas com correções concretas:
  • ECONNREFUSED / "connect refused": inicie o TouchDesigner, certifique-se de que o WebServer DAT do mcp_webserver_base.tox esteja em execução e confirme a porta configurada (padrão 9981).
  • ETIMEDOUT / "timeout": 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 do 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

Agradecemos 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 adequados ao fazer alterações de implementação.

Licença

MIT