MCP GameBoy 服务器

关键词

GameBoy模拟器LLM互动游戏控制复古游戏人工智能游戏

该项目实现了一个 Model Context Protocol (MCP) 服务器，用于通过 LLM 客户端与 GameBoy 模拟器进行交互。它将模拟器的操作（如按键、加载游戏）暴露为 MCP 工具，并将屏幕画面作为工具调用的结果返回。

项目简介

MCP GameBoy 服务器利用 MCP 框架，使得 LLM 能够“玩”GameBoy 游戏。服务器管理 GameBoy 模拟器实例，并提供了标准的 MCP 接口供 LLM 客户端连接和使用。

主要功能点

  • 模拟器控制: 通过 MCP 工具调用，可以控制 GameBoy 的所有按键 (上、下、左、右、A、B、Start、Select)，并支持按键持续一定帧数。
  • 游戏加载: 可以加载不同的 GameBoy ('.gb', '.gbc') ROM 文件。
  • 获取屏幕: 获取当前模拟器画面的 PNG 图像数据。
  • 状态查询: 可以检查当前是否有 ROM 加载以及加载的是哪个 ROM。
  • ROM 管理: 可以列出服务器本地 'roms' 目录下的所有 ROM 文件。
  • 多种传输: 支持 Stdio (标准输入输出) 和 SSE (Server-Sent Events) 两种 MCP 传输协议。
  • 可视化界面: 在 SSE 模式下提供一个 Web 界面，可以手动选择 ROM 和控制模拟器，方便调试和演示。

安装步骤

该服务器是一个 Node.js 应用。请确保您已安装 Node.js 和 npm。

  1. 克隆仓库: 
    git clone https://github.com/mario-andreschak/mcp-gameboy.git
cd mcp-gameboy
  2. 安装依赖: 
    npm install
  3. 构建项目: 
    npm run build

服务器配置 (供 MCP 客户端使用)

MCP 客户端（如 VS Code 的 Cline 扩展）需要知道如何启动并连接到这个服务器。通常，这通过在客户端配置中指定服务器的启动命令和参数来实现。

例如，在一个 MCP 客户端的配置中，您可能需要添加类似以下的信息，告诉客户端如何启动 'mcp-gameboy' 服务器进程：

  • 服务器名称: 'mcp-gameboy' (客户端配置中用于识别该服务器的名称)
  • 启动命令 (command): 'node' (执行 Node.js 环境)
  • 命令参数 (args): '/path/to/mcp-gameboy/dist/index.js' (服务器主程序的入口文件路径)，通常还需要 '--stdio' 或 '--sse' 参数来指定启动模式。例如：
    • Stdio 模式: '/path/to/mcp-gameboy/dist/index.js', '--stdio'
    • SSE 模式: '/path/to/mcp-gameboy/dist/index.js', '--sse'
  • 路径注意: '/path/to/mcp-gameboy/dist/index.js' 必须替换为您实际构建后 'index.js' 文件的绝对路径。在 Windows 上使用正斜杠 '/' 或双反斜杠 '\\'。

基本使用方法

在运行服务器之前，您可能需要配置一些环境变量。在项目根目录创建一个 '.env' 文件：

# 服务器配置
# 在 SSE 模式下，这是 Web UI 的端口
PORT=3001 

# Stdio 模式下默认加载的 ROM 路径
# !! ATTENTION !! Many MCP Clients require this to be an ABSOLUTE path
# ROM_PATH=./roms/dangan.gb 
# 示例 (使用绝对路径):
ROM_PATH=/home/user/mcp-gameboy/roms/dangan.gb

注意：'ROM_PATH' 在 Stdio 模式启动时是必须的，并且许多客户端要求其为绝对路径。在 SSE 模式下，服务器提供 Web UI 供选择 ROM。

  • 在 Stdio 模式下运行: Stdio 模式通常用于通过标准输入输出直接与 MCP 客户端连接。 
    npm run start # 或 npm start -- --stdio
    此模式下，如果配置了 'ROM_PATH'，服务器会尝试加载该 ROM 并启动一个 Web 界面显示模拟器画面（监听 'PORT' 环境变量指定的端口，默认为 3000）。
  • 在 SSE 模式下运行: SSE 模式通过 HTTP/SSE 连接与 MCP 客户端通信，并提供一个独立的 Web 界面。 
    npm run start-sse # 或 npm start -- --sse
    此模式下，服务器将监听 'PORT' 环境变量指定的端口（默认为 3001）处理 MCP SSE 请求，并通过同一端口提供 Web UI (访问 'http://localhost:PORT')，您可以在 Web UI 中选择 ROM。

一旦服务器运行，兼容的 MCP 客户端即可连接并开始与 GameBoy 模拟器进行互动，例如调用 'press_a' 工具来模拟按下 A 键，或调用 'get_screen' 获取当前游戏画面。

服务器信息

访问项目