MCP GameBoy Server

MCP GameBoy Server

Visão Geral

Um servidor Model Context Protocol (MCP) para serverboy, permitindo que LLMs interajam com um emulador de GameBoy. Seu LLM pode...

• Carregar ROMs
• Pressionar teclas
• Ver a tela do GameBoy
• pular quadros

Você pode...

• controlar o emulador de gameboy usando o @modelcontextprotocol/inspector
• controlar o emulador de gameboy (e enviar ROMs) usando uma interface web em http://localhost:3001/emulator
• instalar o emulador de gameboy no seu cliente MCP favorito

Recursos

• Suporta transportes stdio e SSE
• Fornece ferramentas para controles do GameBoy (up, down, left, right, A, B, start, select)
• Fornece ferramentas para carregar diferentes ROMs
• Fornece ferramentas para obter a tela atual
• Todas as ferramentas retornam um ImageContent com o quadro de tela mais recente

Instalação

Instalando via Smithery

Para instalar o GameBoy Emulator Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @mario-andreschak/mcp-gameboy --client claude

Instalando no FLUJO

1. Clique em Add Server
2. Copie e cole a URL do GitHub no FLUJO
3. Clique em Parse, Clone, Install, Build e Save.

Instalação Manual

# Clone the repository
git clone https://github.com/yourusername/mcp-gameboy.git
cd mcp-gameboy

# Install dependencies
npm install

# Build the project
npm run build

Instalando via Arquivos de Configuração

!! ATENÇÃO : Muitos clientes MCP exigem que o caminho da ROM seja especificado nas variáveis .env como um caminho absoluto

Para integrar este servidor MCP com Cline ou outros clientes MCP via arquivos de configuração:

1. Abra as configurações do Cline:

   • No VS Code, vá em File -> Preferences -> Settings
   • Pesquise por "Cline MCP Settings"
   • Clique em "Edit in settings.json"

2. Adicione a configuração do servidor ao objeto mcpServers:

   {
     "mcpServers": {
       "mcp-gameboy": {
         "command": "node",
         "args": [
           "/path/to/mcp-gameboy/dist/index.js"
         ],
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

3. Substitua /path/to/mcp-gameboy/dist/index.js pelo caminho real do arquivo index.js no diretório do seu projeto. Use barras normais (/) ou barras invertidas duplas (\\) para o caminho no Windows.

4. Salve o arquivo de configurações. O Cline deve se conectar automaticamente ao servidor.

Uso

Variáveis de Ambiente

!! ATENÇÃO : Muitos clientes MCP exigem que o caminho da ROM seja especificado nas variáveis .env como um caminho absoluto

Crie um arquivo .env no diretório raiz com as seguintes variáveis:

# Server configuration
PORT=3001

# ROM path for stdio mode
ROM_PATH=./roms/dangan.gb

Executando no Modo stdio

No modo stdio, o servidor usa o caminho da ROM especificado na variável de ambiente ROM_PATH. Ele abrirá uma janela do navegador para exibir a tela do GameBoy.

npm run start

Executando no Modo SSE

No modo SSE, o servidor inicia um servidor Express que serve uma página web para seleção de ROM.

npm run start-sse

Em seguida, abra seu navegador em http://localhost:3001 para selecionar uma ROM.

Ferramentas

O servidor fornece as seguintes ferramentas:

• press_up: Pressione o botão UP no GameBoy
• press_down: Pressione o botão DOWN no GameBoy
• press_left: Pressione o botão LEFT no GameBoy
• press_right: Pressione o botão RIGHT no GameBoy
• press_a: Pressione o botão A no GameBoy
• press_b: Pressione o botão B no GameBoy
• press_start: Pressione o botão START no GameBoy
• press_select: Pressione o botão SELECT no GameBoy
• load_rom: Carregar um arquivo ROM do GameBoy
• get_screen: Obter a tela atual do GameBoy

Todas as ferramentas retornam um ImageContent com o quadro de tela mais recente.

Detalhes de Implementação

Este servidor é construído usando o SDK TypeScript do Model Context Protocol (MCP). Ele usa:

• McpServer de @modelcontextprotocol/sdk/server/mcp.js para a implementação do servidor
• StdioServerTransport de @modelcontextprotocol/sdk/server/stdio.js para transporte stdio
• SSEServerTransport de @modelcontextprotocol/sdk/server/sse.js para transporte SSE
• serverboy para a emulação do GameBoy
• express para o servidor web no modo SSE
• canvas para renderizar a tela do GameBoy

Licença

MIT