Gearsystem

Gearsystem ships with an embedded MCP server to aid debugging and tooling for emulation. The MCP server exposes execution control, memory inspection, and hardware status access to external tooling and AI-assisted debuggers. You can connect your MCP client or integration to the Gearsystem container to pause/resume execution, inspect Z80/VDP state, read and modify RAM, and trigger save states or ROM-related operations. The server is designed to be lightweight and is intended to work alongside the Gearsystem emulator binary rather than as a separate service, enabling tight integration for debugging sessions, automation, and advanced testing workflows.

Prerequisites:\n- Docker installed on the host (recommended for quick start) OR ensure you have a compatible runtime if you prefer a native build.\n- Access to Gearsystem binaries or a container image that bundles the MCP server with Gearsystem.\n\nOption A: Run with Docker (recommended)\n1. Install Docker: https://docs.docker.com/get-docker/\n2. Pull and run the Gearsystem MCP container:\n\n docker run -it --rm drhelius/gearsystem\n\n3. Attach your MCP client to the running container as per your MCP tool's documentation (address/port usually provided by the container).\n\nOption B: Build from source (if you prefer a native build)\n1. Install required build tools (C/C++ toolchain, CMake, etc.).\n2. Clone the Gearsystem repository.\n3. Follow the repository's build instructions to compile Gearsystem and enable the embedded MCP server.\n4. Run the Gearsystem binary locally and connect your MCP client to the appropriate port.\n\nNote: The MCP server is embedded in Gearsystem; ensure you enable the server or pass the correct flags if building from source.\n

Tips and common issues:\n- If you encounter connection failures, verify that the MCP server port is accessible from your client and that no firewall rules block the connection.\n- When running via Docker, ensure you expose or map the MCP port if your client runs outside the container.\n- Review Gearsystem docs for available MCP endpoints (execution control, memory inspection, VRAM/IO inspection).\n- Some features may require running in a supported platform (Windows, Linux, macOS) with appropriate permissions.\n- If using RetroArch or other front-ends, confirm compatibility with Gearsystem's MCP implementation and any version-specific quirks.\n