Gearboy

Gearboy is a cross-platform Game Boy / Game Boy Color emulator. This MCP server provides access to the Gearboy emulator tooling as a service that can be run in a container. You can use it to run ROMs locally, test ROM compatibility, and leverage Gearboy's debugging features via the exposed interface. The server is intended to offer a repeatable environment for running the emulator, handling ROM loading, and providing additional controls such as boot options and debugging aids through the standard Gearboy CLI and GUI capabilities. Typical usage involves starting the container or binary, then providing a ROM file path and optional parameters through the CLI or GUI, depending on how you expose the interface in your deployment (CLI options, REST/IPC, etc.).

Once running, you can use Gearboy to load ROMs, use the built-in debugger with disassembly and breakpoints, enable portable mode, load symbol files for debugging, and access the various display options and cheats that Gearboy supports. If you plan to integrate with other tools, you can combine Gearboy’s input/output with your workflow by passing ROM paths and optional flags to the server and consuming the emulator output via its interface. The tools available include the standard Gearboy command line options (fullscreen, windowed mode, version/help) and the GUI features described in Gearboy's documentation, such as the debugger, symbol loading, and drag-and-drop ROM loading.

For scripting or automation, you can invoke Gearboy with a ROM path and optional symbol path to boot a specific game, and you can toggle options like fullscreen or windowed mode via the CLI. If you’re using the Docker-based deployment, ensure you mount ROMs and any required BIOS files into the container, and expose the appropriate ports or IPC channels for your MCP client to communicate with the emulator instance.

Prerequisites:

• Docker installed on your host (or an alternative environment to run the Gearboy container).
• Access to Gearboy ROMs and optional BIOS files as needed by your setup.

Option A: Run Gearboy via Docker (recommended in MCP setups)

1. Install Docker on your machine.
2. Pull and run the Gearboy container (adjust image name if needed):

docker pull drhelius/gearboy
docker run -it --rm -v /path/to/roms:/roms -v /path/to/bios:/bios drhelius/gearboy

3. If your MCP framework requires a specific entrypoint or port, adapt the run command accordingly (e.g., -p hostPort:containerPort, -v mounts).

Option B: Build/run Gearboy locally (from source)

1. Ensure you have a C++ toolchain installed (CMake, a compiler) and SDL2 dependencies as described in Gearboy's build notes.
2. Clone the repository and follow the build instructions in the Gearboy README (Windows/macOS/Linux as appropriate).
3. Run the built binary with optional arguments as documented in Gearboy’s command line usage.

Notes:

• If you use Docker, you may need to expose an interface (volume mounts or networking) to interact with ROMs and any saved states. Ensure the container has access to the ROM files you intend to load.

Tips and considerations:

• When using Docker, mount your ROMs directory to /roms (adjust as needed) so Gearboy can load ROMs without copying files into the container.
• If Gearboy requires a BIOS/Boot ROM, provide the path to it via a mounted volume and the appropriate command line option.
• Portable mode can be enabled by placing a portable.ini file in the application directory; in Docker, mount a writable volume to persist portable state.
• Some builds may require additional libraries (e.g., SDL2) on the host if you run Gearboy natively rather than in Docker.
• If you encounter OpenGL or GPU acceleration issues, try running in windowed mode first or enable software rendering if available.
• For debugging, leverage Gearboy’s symbols and debugger features by providing an accompanying .sym file alongside the ROM, or using the GUI to load symbol files.
• Ensure environment variables required by your MCP orchestration (e.g., PORT, ROM_PATH) are properly set in your deployment configuration.