Agentes de IA e Cyango MCP

Agentes de IA e Cyango MCP

O Cyango MCP liga um assistente de IA (por exemplo Cursor, Claude Code ou outro cliente compatível com MCP) ao xr/studio enquanto edita. O assistente pode ler o estado da cena e aplicar alterações estruturadas através de ferramentas em vez de clicar em cada controlo manualmente.

Esta página explica como ligar a sua app de IA ao servidor Cyango MCP alojado e depois adicionar a skill oficial cyango-mcp para que as automações sigam as regras do Cyango. Os detalhes do protocolo estão na skill; aqui focamo-nos na configuração e nos hábitos.

O que precisa primeiro

1. Uma conta Cyango e o xr/studio com a sua história aberta. As edições MCP são aplicadas no editor em direto.
2. Uma app de IA que suporte servidores MCP remotos, por exemplo ChatGPT, Claude, Cursor ou Grok.
3. Paciência com lotes. Os agentes devem enviar poucas operações agrupadas (muitas escritas sequenciais pequenas podem sobrecarregar a ponte). A skill incluída explica o batching em profundidade.

Ligar a sua app de IA

O servidor Cyango MCP está alojado neste URL:

https://mcp.cyango.com/mcp

Na primeira ligação, a app de IA abre uma página de início de sessão da Cyango. Inicie sessão com a sua conta Cyango e selecione Allow. Não precisa de instalar nem de correr nada no seu computador.

ChatGPT

Instale o plugin Cyango a partir do diretório de plugins do ChatGPT. Também pode adicionar o servidor manualmente: abra a página de Plugins no ChatGPT, selecione Add custom MCP server e introduza o URL acima. O seu plano e as definições do workspace decidem se os servidores personalizados estão disponíveis.

Claude

• Claude Code: corra claude mcp add --transport http cyango https://mcp.cyango.com/mcp, depois corra /mcp e inicie sessão.
• Claude (web e app de desktop): adicione um conector personalizado com o URL acima.
• Plugin para Claude: instale o plugin Cyango. Adiciona o servidor e a skill cyango-mcp.

Cursor

Adicione o servidor a ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (este projeto):

{
  "mcpServers": {
    "cyango": {
      "url": "https://mcp.cyango.com/mcp"
    }
  }
}

Depois abra Settings → MCP e inicie sessão no servidor cyango.

Grok

Corra grok mcp add --transport http cyango https://mcp.cyango.com/mcp. O Grok abre a página de início de sessão no seu navegador.

Outras apps

Qualquer app que suporte servidores MCP remotos por HTTP com início de sessão OAuth pode usar o mesmo URL.

Ligar o xr/studio

Abra o xr/studio com a mesma conta Cyango, abra Story Settings → MCP Bridge e selecione Connect MCP. Depois peça ao agente para usar as ferramentas Cyango (listar cenas, alterar entidades, etc.).

Só um separador recebe as edições. Quando liga o MCP num segundo separador, esse separador fica com a ligação e o primeiro mostra Use this tab.

Ligar o xr/stores

Para o agente gerir o seu catálogo de produtos, abra o xr/stores, selecione o ícone de ligação no cabeçalho e selecione Connect MCP. O ícone fica verde quando o agente está ligado. No xr/stores o agente só trabalha nos produtos. Para editar uma história, volte a ligar o MCP no xr/studio.

Instalar a skill cyango-mcp

O Cyango publica skills de agente em @cyango-tools/skills. Instale a skill MCP no seu projeto para o assistente carregar regras automaticamente:

npx @cyango-tools/skills@latest install cyango-mcp

Isto copia a skill para .agents/skills/cyango-mcp/. O Cursor e ferramentas semelhantes descobrem normalmente skills em .agents/skills/ sem configuração extra.

Prefira instalações fixadas: use @latest (ou fixe uma versão) para o npx não reutilizar um tarball CLI antigo em cache.

Instalação manual

Se saltar a CLI, copie skills/cyango-mcp/ do pacote da skill para .agents/skills/cyango-mcp/ no seu repositório — o mesmo layout do instalador.

Atualizar

As skills distribuem-se apenas via npm, não a partir de clones Git. Volte a executar o comando de instalação quando quiser regras mais recentes:

npx @cyango-tools/skills@latest install cyango-mcp

O que a skill ensina ao agente

A skill cyango-mcp é o guia canónico para:

• Escritas em lote — criar, remover e aplicar patch a entidades e cenas com ferramentas no plural (add_entities, update_entities, remove_entities e as ferramentas de cena correspondentes). Os agentes devem evitar longas cadeias de comandos legados pontuais.
• Hierarquia e transformações — espaço world vs local, ordem de parenting e estrutura GUI vs 3D (GUI_SCREEN, GUI_CONTAINER, GROUP, …).
• Layout GUI — breakpoints desktop-first, valores seguros para o schema e leitura de gui-properties antes de editar entidades UI.
• Auxiliares de verificação — bridge_status quando surgirem problemas de ligação ou fila; validate_patch antes de patches arriscados; instantiate_prefab ao largar prefabs da biblioteca.
• XR Stores: ligar a história a uma loja ligada (set_story_ecommerce_store), ver os produtos (list_store_products) e colocar produtos ou fazer com que as suas entidades abram a página de um produto (add_product_entities, assign_products). Nas lojas Cyango o agente também cria, edita, apaga e move produtos (create_products, update_products, delete_products, move_products). Os produtos que uma história usa não são apagados nem movidos. Os produtos Shopify mantêm o nome, o preço e o stock do Shopify. Lojas e encomendas ficam no painel xr/stores.

A documentação da skill referencia famílias de entidades (luzes, panorama, modelos, ações, timeline). Indique ao agente "follow .agents/skills/cyango-mcp/SKILL.md" para qualquer tarefa de edição XR.

Como fazer prompts de forma eficaz

• Nomeie o objetivo — tipo de cena, entidades alvo ou resultado UX ("add a desktop HUD with two buttons that navigate scenes").
• Mencione a skill — "Use the cyango-mcp skill rules for GUI defaults and hierarchy."
• Escale a depuração — se o viewport parecer errado mas a ferramenta reportou sucesso, peça ao agente para inspecionar o estado com ferramentas read/list ou bridge_status em vez de repetir escritas às cegas.

Relação com outra documentação

O manual xr/studio explica como construir histórias no editor do ponto de vista do utilizador; as ferramentas MCP espelham essa mesma estrutura de cenas, entidades e ações em forma legível por máquina.