GoPeak

O servidor MCP mais abrangente para Godot Engine. Mais de 95 ferramentas para gerenciamento de cenas, GDScript LSP, depuração DAP, captura de tela, injeção de entrada e biblioteca de assets CC0.

GitHub

240

Experimente este MCPPatrocinado

Documentação

GoPeak

GoPeak Hero

GoPeak é um servidor MCP para Godot 4 que dá aos assistentes de IA um ciclo real de editar → executar → inspecionar → corrigir.

Ele é projetado para fluxos de trabalho confiáveis do Godot 4: superfície de ferramentas padrão pequena, capacidades avançadas controladas por configuração e regras de compatibilidade explícitas para nomes de ferramentas antigos/legados.

O inglês é a fonte canônica da verdade. Os READMEs localizados são visões gerais concisas e podem ficar desatualizados em relação ao README.md.

O Discord está temporariamente indisponível enquanto o link de convite é atualizado. Use GitHub Discussions por enquanto.

Início Rápido

Requisitos

Godot 4.x
Bun 1.3.3+
Cliente compatível com MCP, como Claude Desktop, Cursor, Cline ou OpenCode

1) Instalar o GoPeak

bun add -g https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz

Esse é o caminho de instalação mais rápido. Ele instala o runtime empacotado diretamente do GitHub Releases sem npm. Para uma instalação com verificação de checksum, use:

curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz
curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c gopeak-2.3.9.tgz.sha256
else
  shasum -a 256 -c gopeak-2.3.9.tgz.sha256
fi
bun add -g "$PWD/gopeak-2.3.9.tgz"

O caminho verificado confere o release baixado antes de o Bun instalá-lo globalmente. O caminho absoluto do tarball evita um bug de caminho relativo no Bun 1.3.3. O comando de checksum funciona no Linux (sha256sum) e no macOS (shasum). Para usar o instalador suportado, baixe ou clone o repositório e execute-o localmente — não canalize um script remoto para um shell:

git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
./install.sh

O arquivo de release contém o runtime empacotado. A instalação e a execução não contatam o registro npm nem exigem credenciais npm. Para uma verificação de procedência mais forte, os revisores de release também podem verificar a atestação de artefato do GitHub conforme descrito no processo de release.

Se você usou o instalador antigo, --dir, --godot e --configure permanecem aceitos com avisos até a linha 2.3.x e estão planejados para remoção em 3.0.0. Os novos mapeamentos são: use o diretório global do Bun (BUN_INSTALL) em vez de um diretório de checkout da fonte, coloque GODOT_PATH no cliente MCP env e use a configuração abaixo em vez de depender da saída do instalador. Durante a janela de compatibilidade, --godot e --configure ainda imprimem um trecho de cliente, mas nunca gravam arquivos de cliente. Consulte a política de migração para o contrato exato.

2) Adicionar configuração do cliente MCP

{
  "mcpServers": {
    "godot": {
      "command": "gopeak",
      "args": [],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

compact é o perfil padrão. Ele mantém o contexto MCP inicial pequeno e expõe grupos adicionais controlados por configuração somente quando solicitado.

3) Experimente estes prompts

"Liste projetos Godot em /your/projects e mostre informações do projeto."
"Crie scenes/Player.tscn com uma raiz CharacterBody2D e um script de movimento."
"Execute o projeto, leia a saída de depuração e corrija o erro principal."
"Use tool.catalog para encontrar ferramentas de animação e ative o grupo certo."

O Que Você Obtém

Fluxo de Trabalho	O que o GoPeak pode fazer
Controle de projeto	Encontrar projetos, iniciar o editor, executar/parar o jogo, coletar saída de depuração.
Edição de cena + script	Criar cenas, adicionar nós, editar propriedades tipadas, criar/modificar GDScript.
Fluxos de recursos	Trabalhar com recursos, materiais, shaders, imports e verificações relacionadas à exportação.
Depuração	Usar logs, diagnósticos do LSP do Godot, breakpoints/stack traces do DAP e inspeção em tempo de execução quando configurado.
Teste em tempo de execução	Capturar screenshots, inspecionar árvores ao vivo, injetar entrada e chamar métodos em tempo de execução por meio do addon.
Descoberta de ferramentas	Manter a superfície padrão compacta e ativar grupos de capacidades com `tool.catalog` ou `tool.groups`.

Portões de configuração

Algumas capacidades exigem serviços extras do lado do Godot. O GoPeak rotula essas capacidades em vez de fingir que tudo está sempre disponível:

Capacidade	Exige
Edições de cena/recurso via bridge do editor	Plugin `godot_mcp_editor` habilitado no projeto Godot.
Inspeção em tempo de execução, screenshots, injeção de entrada	Addon/socket em tempo de execução, porta padrão `7777`.
Ferramentas LSP do GDScript	LSP do Godot habilitado na porta `6005`.
Ferramentas de depuração DAP	DAP do Godot habilitado na porta `6006`.
Ferramentas de asset store/provedor	Acesso à rede e disponibilidade do provedor.

Adicionar os Plugins do Godot

Instale a partir da pasta do seu projeto Godot:

curl -sL https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.sh | bash

PowerShell:

iwr https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.ps1 -UseBasicParsing | iex

Em seguida, habilite os plugins em Project Settings → Plugins:

godot_mcp_editor para ferramentas de cena/recurso via bridge
godot_mcp_runtime para inspeção em tempo de execução, screenshots e fluxos de entrada

Hooks de shell opcionais para notificações de atualização são opt-in:

gopeak setup

gopeak setup só modifica arquivos rc suportados de bash/zsh quando você o executa explicitamente. Instalar o asset de release não adiciona hooks de shell automaticamente.

Perfis de Ferramentas

O GoPeak suporta três perfis de exposição:

Perfil	Use quando
`compact`	Padrão. Ferramentas principais confiáveis mais grupos dinâmicos ativados sob demanda.
`full`	Modo de compatibilidade/auditoria para a superfície legada completa.
`legacy`	Alias de configuração antigo com o mesmo comportamento exposto que `full`.

Defina GOPEAK_TOOL_PROFILE ou o alias de fallback MCP_TOOL_PROFILE.

Grupos dinâmicos

No modo compacto, pesquise com tool.catalog; grupos correspondentes são ativados automaticamente. Você também pode gerenciar grupos diretamente com tool.groups.

Grupos comuns:

Grupo	Status	Notas
`runtime`	opcional-runtime	Árvore de cena ao vivo, propriedades, chamadas de método, métricas. Exige addon/socket em tempo de execução.
`testing`	opcional-runtime	Screenshots, captura de viewport, injeção de entrada. Exige configuração de runtime/editor.
`lsp`	opcional-lsp	Diagnósticos, conclusão, hover, símbolos. Exige LSP do Godot na porta `6005`.
`dap`	opcional-dap	Breakpoints, stepping, stack traces. Exige DAP do Godot na porta `6006`.
`asset_store`	opcional-rede	Busca/download de assets CC0 externos. Dependente de rede/provedor.
`class_advanced`	confiável-estático	Descoberta de ClassDB/herança apoiada por metadados estáticos do motor.
`tilemap`	auditoria-exigida	Deve considerar o comportamento `TileMapLayer` do Godot 4.3+ antes da promoção.
grupos de mutação	auditoria-exigida	Grupos de cena/recurso/script/configurações/sinal/autoload/import/áudio/navegação/tema/animação precisam de evidências de fixture antes de serem comercializados como totalmente confiáveis.
`intent_tracking`	camada-de-fluxo	Ajudantes de memória/transferência de fluxo de trabalho, não uma primitiva do motor Godot. Mantenha opt-in.

Se o seu cliente MCP não atualizar após a ativação, reconecte o cliente ou chame a ferramenta recém-ativada uma vez para forçar um novo round-trip tools/list.

O GoPeak também usa paginação baseada em cursor para tools/list para que perfis grandes não sejam despejados no contexto de uma vez. Ajuste com GOPEAK_TOOLS_PAGE_SIZE quando necessário.

Valores Tipados do Godot

Ferramentas de cena via bridge, como add_node e set_node_properties, aceitam payloads vetoriais comuns para propriedades tipadas:

{
  "position": { "type": "Vector2", "x": 100, "y": 200 },
  "scale": { "type": "Vector2", "x": 2, "y": 2 }
}

{ "x": 100, "y": 200 } e [100, 200] simples também são convertidos para campos comuns de Vector2, mas valores marcados são os mais seguros entre ferramentas.

Comandos Úteis

# run the globally installed CLI
gopeak

# run from source
git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
bun ci
bun run build
bun run ./build/index.js

# local verification
bun run ci
bun run test:dynamic-groups
bun run test:metadata
bun run test:packaging

Nomes de binários CLI:

gopeak
godot-mcp

Ambiente e Portas

Nome	Finalidade	Padrão
`GOPEAK_TOOL_PROFILE`	Perfil de exposição de ferramentas: `compact`, `full`, `legacy`	`compact`
`MCP_TOOL_PROFILE`	Alias de ambiente de perfil de fallback	`compact`
`GODOT_PATH`	Caminho explícito do executável do Godot	detecção automática
`GODOT_BRIDGE_PORT`	Substituição da porta HTTP+WS do Bridge/Visualizer	`6505`
`GOPEAK_BRIDGE_HOST`	Host de bind do Bridge/Visualizer	`127.0.0.1`
`GOPEAK_TOOLS_PAGE_SIZE`	Número de ferramentas por página `tools/list`	`33`
`GOPEAK_RUNTIME_TIMEOUT_MS`	Tempo limite de comando do addon em tempo de execução em milissegundos	`10000`
`DEBUG`	Habilitar logs de depuração do servidor	`false`
`LOG_MODE`	Modo de gravação: `lite` ou `full`	`lite`

Porta	Serviço
`6505`	Servidor unificado Godot Bridge + Visualizer em loopback por padrão.
`6005`	LSP do Godot.
`6006`	DAP do Godot.
`7777`	Socket de comando do addon em tempo de execução.

Ferramentas de screenshot em tempo de execução (capture_screenshot, capture_viewport) usam um arquivo PNG temporário gerenciado pelo GoPeak quando o addon em tempo de execução suporta output_path, e então retornam conteúdo de imagem MCP normal. Addons em tempo de execução mais antigos que não recebem um output_path continuam retornando screenshots base64 inline.

Solução de Problemas

Godot não encontrado → defina GODOT_PATH.
Nenhuma ferramenta MCP visível → reinicie seu cliente MCP.
Precisa de uma ferramenta oculta → pesquise com tool.catalog ou ative um grupo com tool.groups.
Caminho do projeto inválido → confirme que project.godot existe.
Ferramentas em tempo de execução não funcionam → instale/habilite o addon em tempo de execução e verifique a porta 7777.
Screenshots em tempo de execução expiram → atualize o addon em tempo de execução para que os comandos de screenshot suportem o fluxo gerenciado output_path. Para respostas lentas em tempo de execução, aumente GOPEAK_RUNTIME_TIMEOUT_MS; addons mais antigos ainda podem expirar em screenshots base64 inline grandes.
Bridge do editor desconectado → pare servidores gopeak/MCP duplicados que possam já estar usando a porta do bridge 6505; get_editor_status relata erros de inicialização do bridge, como EADDRINUSE.

Política de Migração e Depreciação

O GoPeak trata compact como o padrão seguro e full/legacy como perfis de compatibilidade. Mudanças futuras de ocultação, remoção, renomeação ou contrato de API devem incluir:

mapeamento antigo → novo ou uma nota explícita de sem substituição;
impacto no perfil (compact, full, legacy ou grupo opt-in);
janela de alias e cronograma planejado de remoção;
atualizações de README/docs e notas de release;
verificação provando exposição tools/list e comportamento de alias;
exemplos de prompts de migração para fluxos de trabalho comuns do Godot.

Posição atual: nomes de ferramentas legados e aliases compactos permanecem suportados. Grupos externos opcionais (runtime, testing, lsp, dap, asset_store) são controlados por configuração, não comportamento principal sempre disponível.

Política completa: docs/migration-policy.md.

Mais Documentação

Licença e Créditos

MIT — veja LICENSE.

Servidor MCP original por Coding-Solo
Aprimoramentos do GoPeak por HaD0Yun
Visualizador de projeto inspirado em tomyud1/godot-mcp