mgba_write16

Instructions

Implementation Reference

• src/tools.ts:102-113 (schema)

  Input schema definition for the mgba_write16 tool. Defines required 'address' (integer, 2-byte aligned) and 'value' (integer 0-65535) parameters.

  {
    name: "mgba_write16",
    description: `Write a 16-bit value (little-endian) to a memory address. Address must be 2-byte aligned.\n\n${MBC_CAVEAT}`,
    inputSchema: {
      type: "object",
      required: ["address", "value"],
      properties: {
        address: { type: "integer", description: "RAM address (2-byte aligned)" },
        value:   { type: "integer", minimum: 0, maximum: 65535, description: "16-bit value (0-65535)" },
      },
    },
  },

• src/tools.ts:315-318 (handler)

  Handler for mgba_write16 tool. Calls the mGBA bridge RPC method 'write16' with address and value, then returns a success message with the formatted hex output.

  case "mgba_write16": {
    await mgba.call("write16", { address: p.address, value: p.value });
    return ok(`Wrote ${formatHex(p.value)} → 0x${(p.address as number).toString(16).toUpperCase()}`);
  }

• src/tools.ts:258-411 (registration)

  Registration function that binds the tool list and call handler to the MCP server. mgba_write16 is registered as part of the TOOLS array and handled in the switch statement.

  export function registerTools(server: Server, mgba: MgbaClient): void {
    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
  
    server.setRequestHandler(CallToolRequestSchema, async (req) => {
      const { name, arguments: args = {} } = req.params;
      const p = args as Record<string, unknown>;
  
      switch (name) {
        case "mgba_ping": {
          const r = await mgba.call<string>("ping");
          return ok(r);
        }
  
        case "mgba_get_info": {
          const r = await mgba.call<{
            title?: string;
            code?: string;
            frame?: number;
            platform?: number | string;
            capabilities?: Record<string, boolean>;
          }>("get_info");
          const lines = [
            `Title:    ${r.title ?? "(unavailable)"}`,
            `Code:     ${r.code ?? "(unavailable)"}`,
            `Platform: ${r.platform ?? "(unavailable)"}`,
            `Frame:    ${r.frame ?? "(unavailable)"}`,
          ];
          if (r.capabilities) {
            const present = Object.entries(r.capabilities).filter(([, v]) => v).map(([k]) => k);
            const missing = Object.entries(r.capabilities).filter(([, v]) => !v).map(([k]) => k);
            lines.push("");
            lines.push(`Capabilities present: ${present.length ? present.join(", ") : "(none)"}`);
            if (missing.length) lines.push(`Missing on this build: ${missing.join(", ")}`);
          }
          return ok(lines.join("\n"));
        }
  
        case "mgba_read8": {
          const v = await mgba.call<number>("read8", { address: p.address });
          return ok(`0x${(p.address as number).toString(16).toUpperCase()}: ${formatHex(v)}`);
        }
  
        case "mgba_read16": {
          const v = await mgba.call<number>("read16", { address: p.address });
          return ok(`0x${(p.address as number).toString(16).toUpperCase()}: ${formatHex(v)}`);
        }
  
        case "mgba_read32": {
          const v = await mgba.call<number>("read32", { address: p.address });
          return ok(`0x${(p.address as number).toString(16).toUpperCase()}: ${formatHex(v)}`);
        }
  
        case "mgba_write8": {
          await mgba.call("write8", { address: p.address, value: p.value });
          return ok(`Wrote ${formatHex(p.value)} → 0x${(p.address as number).toString(16).toUpperCase()}`);
        }
  
        case "mgba_write16": {
          await mgba.call("write16", { address: p.address, value: p.value });
          return ok(`Wrote ${formatHex(p.value)} → 0x${(p.address as number).toString(16).toUpperCase()}`);
        }
  
        case "mgba_write32": {
          await mgba.call("write32", { address: p.address, value: p.value });
          return ok(`Wrote ${formatHex(p.value)} → 0x${(p.address as number).toString(16).toUpperCase()}`);
        }
  
        case "mgba_read_range": {
          const bytes = await mgba.call<number[]>("read_range", {
            address: p.address,
            length:  p.length,
          });
          const hex = bytes
            .map((b) => b.toString(16).padStart(2, "0").toUpperCase())
            .join(" ");
          const addr = (p.address as number).toString(16).toUpperCase();
          return ok(`0x${addr} [${bytes.length} bytes]:\n${hex}`);
        }
  
        case "mgba_write_range": {
          const r = await mgba.call<{ written: number }>("write_range", {
            address: p.address,
            bytes:   p.bytes,
          });
          const addr = (p.address as number).toString(16).toUpperCase();
          return ok(`Wrote ${r.written} bytes → 0x${addr}`);
        }
  
        case "mgba_press_buttons": {
          const r = await mgba.call<{ queued: boolean; queue_size: number }>("press_buttons", {
            buttons:        p.buttons,
            frames:         p.frames         ?? 1,
            release_frames: p.release_frames ?? 1,
          });
          const keys = (p.buttons as string[]).join("+");
          return ok(
            `Queued press: ${keys} ` +
            `(hold ${p.frames ?? 1}f, release ${p.release_frames ?? 1}f). ` +
            `Queue size: ${r.queue_size}`,
          );
        }
  
        case "mgba_advance_frames": {
          const frame = await mgba.call<number>("advance_frames", { count: p.count ?? 1 });
          return ok(`Advanced ${p.count ?? 1} frame(s). Current frame: ${frame}`);
        }
  
        case "mgba_pause": {
          await mgba.call("pause");
          return ok("Emulation paused");
        }
  
        case "mgba_unpause": {
          await mgba.call("unpause");
          return ok("Emulation resumed");
        }
  
        case "mgba_reset": {
          await mgba.call("reset");
          return ok("ROM reset");
        }
  
        case "mgba_screenshot": {
          const path = await mgba.call<string>("screenshot", p.path ? { path: p.path } : {});
          return ok(`Screenshot saved: ${path}`);
        }
  
        case "mgba_save_state": {
          if (p.slot === undefined && p.path === undefined) {
            throw new Error("provide either `slot` (0-9) or `path`");
          }
          const r = await mgba.call<{ slot?: number; path?: string }>("save_state", {
            ...(p.slot !== undefined ? { slot: p.slot } : {}),
            ...(p.path !== undefined ? { path: p.path } : {}),
          });
          return ok(r.path ? `Saved state to ${r.path}` : `Saved state to slot ${r.slot}`);
        }
  
        case "mgba_load_state": {
          if (p.slot === undefined && p.path === undefined) {
            throw new Error("provide either `slot` (0-9) or `path`");
          }
          const r = await mgba.call<{ slot?: number; path?: string }>("load_state", {
            ...(p.slot !== undefined ? { slot: p.slot } : {}),
            ...(p.path !== undefined ? { path: p.path } : {}),
          });
          return ok(r.path ? `Loaded state from ${r.path}` : `Loaded state from slot ${r.slot}`);
        }
  
        default:
          throw new Error(`Unknown tool: ${name}`);
      }
    });
  }

• src/tools.ts:251-254 (helper)

  Helper utility that formats a number as both decimal and hex, used in the mgba_write16 handler's response message.

  function formatHex(n: unknown): string {
    if (typeof n !== "number") return String(n);
    return `${n} (0x${n.toString(16).toUpperCase()})`;
  }