Unity-MCP

Uma ponte entre o motor de jogos Unity e assistentes de IA usando o Model Context Protocol (MCP).

GitHub
7

Documentação

Unity-MCP

Uma ponte entre Unity e assistentes de IA usando o Model Context Protocol (MCP).

Visão Geral

Unity-MCP é uma implementação de código aberto do Model Context Protocol para desenvolvimento de jogos em Unity. Ele permite que assistentes de IA interajam com ambientes de jogos Unity por meio de uma interface padronizada, possibilitando desenvolvimento de jogos assistido por IA, testes automatizados, análise de cenas e depuração em tempo de execução.

Arquitetura

A arquitetura foi simplificada para usar o AILogger para persistência, eliminando a necessidade de um componente de servidor separado:

AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILogger
  • Assistente de IA: Comunica-se com o Cliente STDIO Unity-MCP usando o protocolo MCP
  • Cliente STDIO Unity-MCP: Encaminha comandos para o Cliente Unity e armazena resultados no AILogger
  • Cliente Unity: Executa comandos no Unity e retorna resultados
  • AILogger: Armazena logs e resultados para recuperação posterior

O Cliente STDIO Unity-MCP comunica-se diretamente com o Cliente Unity, que fornece endpoints tanto para execução de código quanto para consultas. A ferramenta de consulta transforma consultas em execução de código, envolvendo-as em uma instrução return.

Recursos

  • Executar código C# no ambiente de execução do Unity
  • Inspecionar objetos de jogo e seus componentes
  • Analisar hierarquias e estruturas de cena
  • Executar testes e receber resultados
  • Invocar métodos em objetos de jogo e componentes
  • Modificar o estado do jogo durante a execução

Opções de Implantação

  • Extensão do Editor Unity: Uma extensão do Editor que persiste além dos ciclos de execução do jogo
  • Contêiner Docker: Uma versão conteinerizada que se comunica com o Unity pela rede
  • Pacote NPX: Um pacote Node.js que pode ser instalado e executado via NPX

Documentação

Primeiros Passos

Para começar com o Unity-MCP, siga estes passos:

  1. Clone o repositório:

    git clone https://github.com/TSavo/Unity-MCP.git
cd Unity-MCP

  2. Instale as dependências:

    npm install

  3. Compile o projeto:

    npm run build

  4. Inicie o cliente STDIO MCP:

    npm start

    Isso iniciará o cliente STDIO MCP que se comunica com o Unity e usa o AILogger para persistência.

    Observação: Certifique-se de que o AILogger esteja em execução em http://localhost:3030 ou defina a variável de ambiente AI_LOGGER_URL para apontar para sua instância do AILogger.

  5. Execute os testes:

    # Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only e2e tests
npm run test:e2e

# Run tests with a specific pattern
npm test -- --testNamePattern="should return the server manifest"
npm run test:unit -- --testNamePattern="should return the server manifest"
npm run test:e2e -- --testNamePattern="should discover the test server"

Para instruções mais detalhadas, consulte o Guia de Instalação.

Conectando a Assistentes de IA

Para conectar a ponte Unity-MCP a um assistente de IA, você precisa criar um arquivo de configuração MCP:

{
  "mcpServers": {
    "unity-ai-bridge": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Coloque este arquivo no local apropriado para o seu assistente de IA. Para o Claude, isso normalmente seria no diretório de configuração do aplicativo Claude Desktop.

Ferramentas Disponíveis

A ponte Unity-MCP fornece as seguintes ferramentas:

  1. execute_code: Executa código C# diretamente no Unity.
  2. query: Executa uma consulta usando notação de ponto para acessar objetos, propriedades e métodos.
  3. get_logs: Recupera logs do AILogger.
  4. get_log_by_name: Recupera um log específico do AILogger.

Exemplos de Uso

Executando Código no Unity

Você pode executar código C# no Unity usando a ferramenta execute_code. O código será executado no ambiente de execução do Unity, e o resultado será armazenado no AILogger para recuperação posterior.

Solicitação JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "code": "Debug.Log(\"Hello from Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
      "timeout": 5000
    }
  }
}

Resposta JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123}}"
      }
    ]
  }
}

Consultando Objetos do Unity

Você pode consultar objetos do Unity usando a ferramenta query. Isso permite acessar objetos, propriedades e métodos usando notação de ponto.

Solicitação JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "query": "Camera.main.transform.position",
      "timeout": 5000
    }
  }
}

Resposta JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
      }
    ]
  }
}

Recuperando Resultados do AILogger

Você pode recuperar os resultados de operações anteriores do AILogger usando a ferramenta get_log_by_name.

Solicitação JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_log_by_name",
    "arguments": {
      "log_name": "unity-execute-1712534400000",
      "limit": 1
    }
  }
}

Resposta JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
      }
    ]
  }
}

Exemplo de Uso

Depois que o assistente de IA tiver acesso à ferramenta Unity, você pode pedir que ele execute tarefas como:

Can you execute the following C# code in Unity?

GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);

Licença

MIT

Autor

T Savo (@TSavo)