MCP GameBoy Server

Instructions

Implementation Reference

• src/tools.ts:20-37 (registration)

  Dynamic registration of the 'press_select' tool (and other press_* buttons) with inline input schema, description, and handler function. The handler presses the SELECT button via EmulatorService and returns the screen image.

  // Register button press tools
  Object.values(GameBoyButton).forEach(button => {
    server.tool(
      `press_${button.toLowerCase()}`,
      `Press the ${button} button on the GameBoy`,
      {
        duration_frames: z.number().int().positive().optional().default(1).describe('Number of frames to hold the button').default(25)
      },
      async ({ duration_frames }): Promise<CallToolResult> => {
        // Press the button using the service (advances one frame)
        emulatorService.pressButton(button, duration_frames);
  
        // Return the current screen using the service
        const screen = emulatorService.getScreen();
        return { content: [screen] };
      }
    );
  });

• src/server/server.ts:24-26 (registration)

  Invokes registerGameBoyTools which registers the press_select tool among others.

  // Register GameBoy tools
  registerGameBoyTools(server, emulatorService); // Pass emulatorService

• src/types.ts:9-18 (helper)

  GameBoyButton enum defining SELECT button used in dynamic tool registration.

  export enum GameBoyButton {
    UP = 'UP',
    DOWN = 'DOWN',
    LEFT = 'LEFT',
    RIGHT = 'RIGHT',
    A = 'A',
    B = 'B',
    START = 'START',
    SELECT = 'SELECT'
  }

• src/emulatorService.ts:72-80 (helper)

  EmulatorService.pressButton method called by the press_select tool handler. Delegates to GameBoyEmulator and returns screen.

  pressButton(button: GameBoyButton, durationFrames: number): ImageContent {
    log.debug(`Pressing button: ${button}`);
    if (!this.isRomLoaded()) {
      log.warn('Attempted to press button with no ROM loaded');
      throw new Error('No ROM loaded');
    }
    this.emulator.pressButton(button, durationFrames); // This advances one frame
    return this.getScreen();
  }

• src/gameboy.ts:43-67 (helper)

  Low-level GameBoyEmulator.pressButton implementation that maps SELECT to keycode, presses for duration_frames, and advances emulation frames.

  public pressButton(button: GameBoyButton, durationFrames: number = 1): void {
    if (!this.romLoaded) {
      throw new Error('No ROM loaded');
    }
  
    // Map our button enum to serverboy's keymap
    const buttonMap: Record<GameBoyButton, number> = {
      [GameBoyButton.UP]: Gameboy.KEYMAP.UP,
      [GameBoyButton.DOWN]: Gameboy.KEYMAP.DOWN,
      [GameBoyButton.LEFT]: Gameboy.KEYMAP.LEFT,
      [GameBoyButton.RIGHT]: Gameboy.KEYMAP.RIGHT,
      [GameBoyButton.A]: Gameboy.KEYMAP.A,
      [GameBoyButton.B]: Gameboy.KEYMAP.B,
      [GameBoyButton.START]: Gameboy.KEYMAP.START,
      [GameBoyButton.SELECT]: Gameboy.KEYMAP.SELECT
    };
  
    for (let i=0; i < durationFrames; i++) {
      this.gameboy.pressKeys([buttonMap[button]]);
      this.gameboy.doFrame();
    }
  
    // for now: advance one frame so we dont "hold" the button all the time.
    this.gameboy.doFrame();
  }