MCP GameBoy Server

Instructions

Implementation Reference

• src/tools.ts:40-51 (registration)

  Registers the wait_frames tool with the MCP server. Includes inline Zod input schema, description, and the handler function that executes emulatorService.waitFrames and returns the resulting screen as ImageContent.

  server.tool(
    'wait_frames',
    'Wait for a specified number of frames',
    {
      duration_frames: z.number().int().positive().describe('Number of frames to wait').default(100)
    },
    async ({ duration_frames }): Promise<CallToolResult> => {
      // Wait for frames using the service
      const screen = emulatorService.waitFrames(duration_frames);
      return { content: [screen] };
    }
  );

• src/types.ts:26-28 (schema)

  TypeScript interface defining the expected input parameters for the wait_frames tool.

  export interface WaitFramesToolSchema {
    duration_frames: number;
  }

• src/emulatorService.ts:88-99 (helper)

  Core implementation of frame waiting in EmulatorService class. Advances the emulator for the specified number of frames by calling doFrame() in a loop and returns the current screen.

  waitFrames(durationFrames: number): ImageContent {
    log.debug(`Waiting for ${durationFrames} frames`);
    if (!this.isRomLoaded()) {
      log.warn('Attempted to wait frames with no ROM loaded');
      throw new Error('No ROM loaded');
    }
    for (let i = 0; i < durationFrames; i++) {
      this.emulator.doFrame();
    }
    log.verbose(`Waited ${durationFrames} frames`, JSON.stringify({ frames: durationFrames }));
    return this.getScreen();
  }