MCP GameBoy Server

Instructions

Implementation Reference

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

  Async handler function executed when the 'press_b' tool is called. It presses the B button for the specified number of frames via emulatorService and returns the updated 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:25-27 (schema)

  Zod schema defining the input parameters for the press_b tool: optional duration_frames (defaults to 25).

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

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

  Loop that registers the 'press_b' tool (when button==='B') on the MCP server, including name, description, schema, and handler.

  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 registration of press_b tool (via registerGameBoyTools) on the MCP server instance.

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

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

  Supporting method called by the tool handler to press the specified button (B for press_b) and return the 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();
  }