MCP GameBoy Server

Instructions

Implementation Reference

• src/tools.ts:28-35 (handler)

  The inline handler function for the press_up tool (dynamically generated when button='UP'). It presses the UP button for the specified duration_frames and returns the current screen as ImageContent.

  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/tools.ts:26-27 (schema)

  Input schema for the press_up tool: duration_frames as positive integer (default 1 or 25).

    duration_frames: z.number().int().positive().optional().default(1).describe('Number of frames to hold the button').default(25)
  },

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

  Dynamic registration of press_up tool via loop over GameBoyButton values (includes 'UP'), using server.tool() with name `press_${button.toLowerCase()}`

  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/types.ts:9-18 (helper)

  GameBoyButton enum providing the 'UP' value used to generate the 'press_up' tool name.

  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)

  Supporting pressButton method in EmulatorService called by the tool handler to perform the actual button press.

  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();
  }