# unreal-mcp-server

Servidor MCP (Model Context Protocol) que conecta o Claude ao Unreal Engine 5.8 através da **Remote Control API** oficial do motor — sem plugin C++ customizado, sem build extra.

Este servidor roda como um processo Python externo, à parte do Editor da Unreal, e conversa com ele por HTTP usando a API que já vem embutida no motor.

## Como funciona

```
Claude  <--MCP (stdio)-->  unreal-mcp-server (Python)  <--HTTP-->  Unreal Editor (Remote Control API)
```

- O Claude fala MCP com este servidor.
- Este servidor traduz cada chamada em uma requisição HTTP para a Remote Control API do Editor (porta padrão `30010`).
- Nenhuma modificação no projeto Unreal é necessária além de habilitar o plugin nativo.

## Pré-requisitos

- Unreal Engine **5.8** (ou compatível) com o Editor aberto.
- Plugin **Remote Control API** habilitado: `Edit → Plugins → busque "Remote Control"` → marque **Remote Control API** → reinicie o Editor se solicitado.
- Confirme a porta em `Project Settings → Plugins → Web Remote Control` (padrão: `30010`).
- Python 3.10+.

## Instalação

```bash
git clone https://github.com/Jeanosasco/unreal-mcp-server.git
cd unreal-mcp-server
pip install -r requirements.txt
```

## Configuração no cliente MCP (Claude)

Adicione ao seu `mcp.json` (ou configuração equivalente do cliente):

```json
{
  "mcpServers": {
    "unreal": {
      "command": "python",
      "args": ["/caminho/completo/para/unreal-mcp-server/server.py"],
      "env": {
        "UNREAL_HOST": "127.0.0.1",
        "UNREAL_RC_PORT": "30010",
        "MESHY_API_KEY": "msy-sua-chave-aqui"
      }
    }
  }
}
```

Variáveis de ambiente (opcionais, exceto `MESHY_API_KEY` se for usar geração de modelos):

| Variável | Padrão | Descrição |
|---|---|---|
| `UNREAL_HOST` | `127.0.0.1` | Host onde o Editor está escutando |
| `UNREAL_RC_PORT` | `30010` | Porta HTTP da Remote Control API |
| `MESHY_API_KEY` | *(vazio)* | Chave da API da [Meshy](https://www.meshy.ai/api), necessária apenas para as tools de geração de modelo 3D |
| `MODEL_OUTPUT_DIR` | `./generated_models` | Pasta local onde os modelos gerados são salvos antes do import |

## Ferramentas (tools) disponíveis

### Núcleo — endpoints oficiais da Remote Control API

Estas seguem 1:1 a [documentação oficial da Unreal 5.8](https://dev.epicgames.com/documentation/unreal-engine/remote-control-api-http-reference-for-unreal-engine) e são as mais confiáveis:

| Tool | Descrição |
|---|---|
| `unreal_status` | Verifica se a API está acessível e lista as rotas expostas pelo Editor |
| `unreal_call_function` | Chama uma UFUNCTION em qualquer UObject vivo |
| `unreal_get_property` | Lê o valor de uma propriedade |
| `unreal_set_property` | Escreve o valor de uma propriedade (deve ser `EditAnywhere`, não `EditConst`) |
| `unreal_describe_object` | Lista propriedades e funções expostas em um objeto — use para descobrir o que existe antes de chamar `call_function`/`set_property` |
| `unreal_search_assets` | Busca no Asset Registry do projeto |
| `unreal_batch` | Executa múltiplas requisições em uma única chamada |

### Conveniência — construídas sobre `EditorLevelLibrary`

Estas chamam funções bem conhecidas do `EditorLevelLibrary`, mas **não fazem parte da referência oficial da Remote Control API** listada acima. Se alguma falhar no seu build do Editor, use `unreal_describe_object` em `/Script/EditorScriptingUtilities.Default__EditorLevelLibrary` para confirmar o nome exato da função/parâmetros na sua versão:

| Tool | Descrição |
|---|---|
| `unreal_list_level_actors` | Lista todos os atores no nível aberto |
| `unreal_spawn_actor` | Instancia um ator de uma classe, em uma posição/rotação |
| `unreal_destroy_actor` | Remove um ator do nível |
| `unreal_save_current_level` | Salva o nível atual |

### Geração de modelos 3D via IA (Meshy)

Estas tools **não são parte da Unreal em si** — chamam a API da [Meshy](https://www.meshy.ai) para gerar um modelo 3D a partir de texto, e depois usam a tool de import (best-effort, veja acima) para colocá-lo no projeto:

| Tool | Descrição |
|---|---|
| `unreal_generate_3d_model` | Gera um modelo 3D a partir de um prompt de texto e baixa o arquivo (`.fbx`/`.glb`/etc.) na máquina onde este servidor roda. Não mexe na Unreal. |
| `unreal_import_model` | Importa um arquivo de mesh local para o Content Browser do projeto aberto |
| `unreal_generate_and_place_model` | Fluxo completo: gera o modelo, importa no projeto, e instancia como ator no nível aberto — tudo em uma chamada |

Requer `MESHY_API_KEY` configurada. O fluxo de geração é assíncrono no lado da Meshy (preview → refine) e pode levar de 1 a 5 minutos.

## Exemplo de uso

Com o Editor aberto e o plugin habilitado, peça ao Claude algo como:

> "Verifique se a Unreal está conectada, depois liste todos os atores no nível atual."

O Claude vai chamar `unreal_status` e, em seguida, `unreal_list_level_actors`.

Ou, para gerar um modelo do zero:

> "Gere um modelo 3D de uma torre de vigia em pedra desgastada e coloque no nível."

O Claude vai chamar `unreal_generate_and_place_model`, que encadeia geração (Meshy) → import → spawn.

## Solução de problemas

- **"Could not reach the Unreal Remote Control API"** — confirme que o Editor está aberto, o plugin Remote Control API está habilitado, e a porta em `env` bate com a configurada no projeto.
- **Erro HTTP 4xx/5xx em `unreal_call_function`/`unreal_set_property`** — normalmente indica `objectPath`, `functionName` ou `propertyName` incorretos. Use `unreal_describe_object` para confirmar os nomes exatos antes de tentar de novo.
- **Propriedade não aceita escrita** — a propriedade precisa ser `EditAnywhere` e não pode ser `EditConst` na definição C++/Blueprint.
- **Firewall/rede** — a Remote Control API escuta apenas em HTTP simples; garanta que a porta não está bloqueada localmente se o servidor Python rodar em outra máquina.
- **"No Meshy API key provided"** — configure a variável `MESHY_API_KEY` no `mcp.json` ou no ambiente antes de usar `unreal_generate_3d_model`/`unreal_generate_and_place_model`.
- **`unreal_import_model` falha** — o import automatizado depende de `AutomatedAssetImportSubsystem`, que não faz parte da referência oficial da Remote Control API. Use `unreal_describe_object` em `/Script/UnrealEd.Default__AutomatedAssetImportSubsystem` para confirmar a assinatura exata na sua versão do Editor, ou arraste o arquivo manualmente para o Content Browser como alternativa.
- **Geração da Meshy demorando/travando** — o fluxo preview → refine costuma levar de 1 a 5 minutos; verifique seu saldo de créditos em https://www.meshy.ai caso a tarefa falhe com erro 402.

## Roadmap

- [ ] Suporte ao endpoint `/remote/object/event` (assinatura de eventos em tempo real via WebSocket)
- [ ] Ferramentas de alto nível para geração procedural de níveis
- [ ] Testes automatizados contra uma instância headless do Editor
- [ ] Empacotamento via `pipx`/binário standalone
- [ ] Suporte a outros provedores de geração 3D (Tripo AI, Rodin/Hyper3D) como alternativa à Meshy

## Licença

A definir.