MCP GameBoy Server

Instructions

Implementation Reference

• src/tools.ts:60-64 (handler)

  The MCP tool handler function for 'load_rom'. It invokes emulatorService.loadRom(romPath) and returns the resulting screen as ImageContent.

  async ({ romPath }): Promise<CallToolResult> => {
    // Load ROM using the service (already advances initial frames)
    const screen = emulatorService.loadRom(romPath);
    return { content: [screen] };
  }

• src/tools.ts:57-59 (schema)

  Zod input schema for the 'load_rom' tool, defining the required 'romPath' parameter.

  {
    romPath: z.string().describe('Path to the ROM file')
  },

• src/tools.ts:54-65 (registration)

  Registration of the 'load_rom' MCP tool on the server using server.tool(), including description, schema, and handler.

  server.tool(
    'load_rom',
    'Load a GameBoy ROM file',
    {
      romPath: z.string().describe('Path to the ROM file')
    },
    async ({ romPath }): Promise<CallToolResult> => {
      // Load ROM using the service (already advances initial frames)
      const screen = emulatorService.loadRom(romPath);
      return { content: [screen] };
    }
  );

• src/types.ts:30-32 (schema)

  TypeScript interface LoadRomToolSchema defining the input shape for the load_rom tool.

  export interface LoadRomToolSchema {
    romPath: string;
  }

• src/emulatorService.ts:41-63 (helper)

  EmulatorService.loadRom method: validates ROM file existence, loads it via the underlying emulator, advances initial frames, and returns the screen image.

  loadRom(romPath: string): ImageContent {
    log.info(`Attempting to load ROM: ${romPath}`);
    if (!fs.existsSync(romPath)) {
      log.error(`ROM file not found: ${romPath}`);
      throw new Error(`ROM file not found: ${romPath}`);
    }
  
    try {
      this.emulator.loadRom(romPath);
      log.info(`ROM loaded successfully: ${path.basename(romPath)}`);
  
      // Advance a few frames to initialize the screen
      for (let i = 0; i < 5; i++) {
        this.emulator.doFrame();
      }
      log.verbose('Advanced initial frames after ROM load');
  
      return this.getScreen();
    } catch (error) {
      log.error(`Error loading ROM: ${romPath}`, error instanceof Error ? error.message : String(error));
      throw new Error(`Failed to load ROM: ${romPath}. Reason: ${error instanceof Error ? error.message : String(error)}`);
    }
  }