关键词

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' 获取当前游戏画面。

信息

分类

AI与计算

访问项目