Skip to content

armgit / gecko

Public Imported from GitHub
0

A GameCube/Wii emulator and debugger written in Rust.

on request: super basic MCP integration

Layleecde6874fb3e
diff --git a/crates/mcp/Cargo.toml b/crates/mcp/Cargo.toml
new file mode 100644
index 0000000..a0aad36
--- /dev/null
+++ b/crates/mcp/Cargo.toml
@@ -0,0 +1,34 @@
+[package]
+name = "mcp"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+gecko = { path = "../gecko" }
+image = { path = "../image" }
+backend-wgpu = { path = "../backend-wgpu" }
+disasm = { path = "../disasm" }
+wgpu = "28.0.0"
+pollster = "0.4.0"
+png = "0.18.1"
+rmcp = { version = "1.6.0", features = [
+ "server",
+ "macros",
+ "transport-io",
+ "schemars",
+] }
+tokio = { version = "1.52.3", features = [
+ "rt-multi-thread",
+ "macros",
+ "sync",
+ "io-std",
+ "signal",
+] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.149"
+schemars = "1.2.1"
+clap = { version = "4.6.1", features = ["derive"] }
+anyhow = "1.0.102"
+tracing = "0.1.44"
+tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
+base64 = "0.22.1"
diff --git a/crates/mcp/src/boot.rs b/crates/mcp/src/boot.rs
new file mode 100644
index 0000000..63903fe
--- /dev/null
+++ b/crates/mcp/src/boot.rs
@@ -0,0 +1,65 @@
+use std::sync::{Arc, Mutex};
+
+use backend_wgpu::GxRenderer;
+use gecko::HostInput;
+use gecko::gamecube::GameCube;
+use gecko::wii::Wii;
+
+use crate::sink::{Introspection, McpSink};
+use crate::state::Backend;
+
+pub struct BootResult {
+ pub backend: Backend,
+ pub game_name: String,
+ pub game_code: String,
+}
+
+pub fn boot(
+ disc_bytes: Vec<u8>,
+ ipl: &[u8],
+ dsp_rom: &[u8],
+ coef_rom: &[u8],
+ gx: Arc<Mutex<GxRenderer>>,
+ device: wgpu::Device,
+ queue: wgpu::Queue,
+ introspect: Arc<Mutex<Introspection>>,
+) -> BootResult {
+ let dvd = image::load_dvd(disc_bytes);
+
+ let game_name = String::from_utf8_lossy(&dvd.header().game_name)
+ .trim_end_matches('\0')
+ .to_owned();
+ let game_code = String::from_utf8_lossy(&dvd.header().game_code)
+ .trim_end_matches('\0')
+ .to_owned();
+
+ let sink = Box::new(McpSink {
+ gx,
+ device,
+ queue,
+ introspect,
+ });
+
+ let backend = if dvd.header().is_wii() {
+ let mut emu = Wii::apploader_hle(dvd).build();
+ emu.dsp.load_irom(dsp_rom);
+ emu.dsp.load_coef(coef_rom);
+ emu.render_sink = sink;
+ emu.apply_host_input(&HostInput::wii_neutral());
+ Backend::Wii(emu)
+ } else {
+ let mut emu = GameCube::with_ipl(ipl, true);
+ emu.dsp.load_irom(dsp_rom);
+ emu.dsp.load_coef(coef_rom);
+ emu.render_sink = sink;
+ emu.apply_host_input(&HostInput::gc_connected());
+ emu.insert_dvd(dvd);
+ Backend::Gc(emu)
+ };
+
+ BootResult {
+ backend,
+ game_name,
+ game_code,
+ }
+}
diff --git a/crates/mcp/src/lib.rs b/crates/mcp/src/lib.rs
new file mode 100644
index 0000000..a8614f0
--- /dev/null
+++ b/crates/mcp/src/lib.rs
@@ -0,0 +1,5 @@
+pub mod boot;
+pub mod server;
+pub mod sink;
+pub mod state;
+pub mod worker;
diff --git a/crates/mcp/src/main.rs b/crates/mcp/src/main.rs
new file mode 100644
index 0000000..9e67e26
--- /dev/null
+++ b/crates/mcp/src/main.rs
@@ -0,0 +1,134 @@
+use std::path::PathBuf;
+use std::sync::{Arc, Condvar, Mutex};
+
+use anyhow::{Context, Result};
+use backend_wgpu::GxRenderer;
+use clap::Parser;
+use rmcp::ServiceExt;
+use rmcp::transport::stdio;
+use tracing_subscriber::EnvFilter;
+
+use mcp::server::McpServer;
+use mcp::sink::Introspection;
+use mcp::state::{EmuState, RunMode, Shared};
+use mcp::{boot, worker};
+
+#[derive(Parser, Debug)]
+#[command(name = "mcp", about = "MCP server exposing the gecko GameCube/Wii emulator to LLMs")]
+struct Cli {
+ #[arg(long, value_name = "PATH", help = "Disc image to load on startup (ISO/RVZ/ZIP)")]
+ dvd: Option<PathBuf>,
+
+ #[arg(long, value_name = "PATH", help = "Override the embedded GameCube IPL")]
+ ipl: Option<PathBuf>,
+
+ #[arg(long, value_name = "PATH", help = "Override the embedded DSP IROM")]
+ dsp: Option<PathBuf>,
+
+ #[arg(long, value_name = "PATH", help = "Override the embedded DSP COEF ROM")]
+ coef: Option<PathBuf>,
+
+ #[arg(long, help = "Resume the emulator immediately after loading the disc")]
+ resume: bool,
+}
+
+const DEFAULT_IPL: &[u8] = include_bytes!("../../../private/IPL.decoded.bin");
+const DEFAULT_DSP_ROM: &[u8] = include_bytes!("../../../private/dsp_rom.bin");
+const DEFAULT_COEF_ROM: &[u8] = include_bytes!("../../../private/dsp_coef.bin");
+
+fn main() -> Result<()> {
+ tracing_subscriber::fmt()
+ .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info")))
+ .with_writer(std::io::stderr)
+ .with_ansi(false)
+ .init();
+
+ let cli = Cli::parse();
+
+ let ipl = match cli.ipl {
+ Some(p) => std::fs::read(&p).with_context(|| format!("read IPL {p:?}"))?,
+ None => DEFAULT_IPL.to_vec(),
+ };
+
+ let dsp_rom = match cli.dsp {
+ Some(p) => std::fs::read(&p).with_context(|| format!("read DSP IROM {p:?}"))?,
+ None => DEFAULT_DSP_ROM.to_vec(),
+ };
+
+ let coef_rom = match cli.coef {
+ Some(p) => std::fs::read(&p).with_context(|| format!("read DSP COEF ROM {p:?}"))?,
+ None => DEFAULT_COEF_ROM.to_vec(),
+ };
+
+ let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
+ backends: wgpu::Backends::all(),
+ ..Default::default()
+ });
+ let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
+ power_preference: wgpu::PowerPreference::default(),
+ compatible_surface: None,
+ force_fallback_adapter: false,
+ }))
+ .context("no compatible wgpu adapter")?;
+ let (device, queue) = pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor::default()))
+ .context("acquire wgpu device")?;
+ let surface_format = wgpu::TextureFormat::Rgba8Unorm;
+
+ let gx = Arc::new(Mutex::new(GxRenderer::new(&device, &queue, surface_format)));
+ let introspect = Arc::new(Mutex::new(Introspection::default()));
+
+ let shared = Arc::new(Shared {
+ state: Mutex::new(EmuState::new()),
+ cv: Condvar::new(),
+ gx: gx.clone(),
+ device: device.clone(),
+ queue: queue.clone(),
+ introspect: introspect.clone(),
+ ipl,
+ dsp_rom,
+ coef_rom,
+ });
+
+ if let Some(dvd_path) = cli.dvd.as_ref() {
+ let bytes = std::fs::read(dvd_path).with_context(|| format!("read DVD {dvd_path:?}"))?;
+ let result = boot::boot(
+ bytes,
+ &shared.ipl,
+ &shared.dsp_rom,
+ &shared.coef_rom,
+ shared.gx.clone(),
+ shared.device.clone(),
+ shared.queue.clone(),
+ shared.introspect.clone(),
+ );
+
+ let mut s = shared.state.lock().unwrap();
+ s.backend = Some(result.backend);
+ s.game_name = result.game_name;
+ s.game_code = result.game_code;
+ s.run_mode = if cli.resume { RunMode::Running } else { RunMode::Paused };
+ drop(s);
+
+ shared.cv.notify_all();
+ }
+
+ let worker_shared = shared.clone();
+ std::thread::Builder::new()
+ .name("mcp-emu".into())
+ .spawn(move || worker::run(worker_shared))
+ .context("spawn emu worker")?;
+
+ let runtime = tokio::runtime::Builder::new_multi_thread()
+ .enable_all()
+ .build()
+ .context("build tokio runtime")?;
+
+ runtime.block_on(async move {
+ let server = McpServer::new(shared);
+ let service = server.serve(stdio()).await.context("rmcp serve")?;
+ service.waiting().await.context("rmcp waiting")?;
+ anyhow::Ok(())
+ })?;
+
+ Ok(())
+}
diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rs
new file mode 100644
index 0000000..2e05f95
--- /dev/null
+++ b/crates/mcp/src/server.rs
@@ -0,0 +1,718 @@
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as B64;
+use rmcp::handler::server::router::tool::ToolRouter;
+use rmcp::handler::server::wrapper::Parameters;
+use rmcp::model::{CallToolResult, Content, Implementation, ProtocolVersion, ServerCapabilities, ServerInfo};
+use rmcp::service::RequestContext;
+use rmcp::{ErrorData as McpError, RoleServer, ServerHandler, schemars, tool, tool_handler, tool_router};
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+
+use crate::boot;
+use crate::sink::Introspection;
+use crate::state::{Backend, RunMode, Shared};
+
+const MAX_READ_LEN: u32 = 1 << 20;
+const MAX_DISASM_COUNT: u32 = 4096;
+const MAX_FRAMES_PER_CALL: u32 = 600;
+const MAX_STEP_COUNT: u32 = 1 << 20;
+
+#[derive(Clone)]
+pub struct McpServer {
+ shared: Arc<Shared>,
+ #[allow(dead_code)]
+ tool_router: ToolRouter<McpServer>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct LoadGameArgs {
+ #[schemars(description = "Filesystem path to a GameCube/Wii ISO/RVZ/ZIP image")]
+ pub path: Option<String>,
+ #[schemars(description = "Base64-encoded disc image bytes (alternative to path)")]
+ pub bytes_b64: Option<String>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct StepArgs {
+ #[schemars(description = "Number of PPC instructions to step (default 1)")]
+ pub count: Option<u32>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct RunFramesArgs {
+ #[schemars(description = "Number of vsyncs to advance, 1..=600")]
+ pub count: u32,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct RunUntilPcArgs {
+ #[schemars(description = "Target program counter (virtual address)")]
+ pub pc: u32,
+ #[schemars(description = "Cycle budget; bail out and report a timeout if exceeded")]
+ pub max_cycles: Option<u64>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct ReadMemoryArgs {
+ pub addr: u32,
+ pub len: u32,
+ #[schemars(description = "Treat addr as a virtual address (default true)")]
+ pub virt: Option<bool>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct WriteMemoryArgs {
+ pub addr: u32,
+ #[schemars(description = "Base64 of bytes to write")]
+ pub bytes_b64: String,
+ pub virt: Option<bool>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct SearchBytesArgs {
+ pub addr: u32,
+ pub len: u32,
+ #[schemars(description = "Base64 of needle bytes")]
+ pub needle_b64: String,
+ #[schemars(description = "Maximum number of hits to return (default 32)")]
+ pub max_hits: Option<u32>,
+ pub virt: Option<bool>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct DisassembleArgs {
+ pub addr: u32,
+ #[schemars(description = "Number of instructions to decode (1..=4096)")]
+ pub count: u32,
+ pub virt: Option<bool>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct GetTextureArgs {
+ pub ram_addr: u32,
+ #[schemars(description = "Variant hash; 0 for non-paletted (default 0)")]
+ pub variant: Option<u32>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct SetPadArgs {
+ pub stick_x: Option<u8>,
+ pub stick_y: Option<u8>,
+ pub substick_x: Option<u8>,
+ pub substick_y: Option<u8>,
+ pub trigger_left: Option<u8>,
+ pub trigger_right: Option<u8>,
+ #[schemars(description = "GameCube pad button bitmask (A=0x100, B=0x200, START=0x1000, ...)")]
+ pub buttons: Option<u16>,
+}
+
+#[derive(Debug, Serialize)]
+struct StatusJson {
+ loaded: bool,
+ system: Option<&'static str>,
+ game_name: String,
+ game_code: String,
+ run_mode: &'static str,
+ pc: Option<u32>,
+ cycles: Option<u64>,
+ frame_index: u64,
+ last_xfb_size: (u32, u32),
+ draw_count_last_frame: u64,
+ texture_count: usize,
+}
+
+#[derive(Debug, Serialize)]
+struct RegistersJson {
+ pc: u32,
+ cia: u32,
+ nia: u32,
+ lr: u32,
+ ctr: u32,
+ msr: u32,
+ cr: u32,
+ xer: u32,
+ srr0: u32,
+ srr1: u32,
+ gprs: [u32; 32],
+ fprs: [f64; 32],
+ ps1s: [f64; 32],
+}
+
+#[derive(Debug, Serialize)]
+struct DisasmLine {
+ addr: u32,
+ raw: u32,
+ text: String,
+}
+
+#[derive(Debug, Serialize)]
+struct TextureSummary {
+ ram_addr: u32,
+ variant: u32,
+ width: u32,
+ height: u32,
+ format: &'static str,
+ last_seen_frame: u64,
+ bound_slots: Vec<u8>,
+}
+
+impl McpServer {
+ pub fn new(shared: Arc<Shared>) -> Self {
+ Self {
+ shared,
+ tool_router: Self::tool_router(),
+ }
+ }
+}
+
+#[tool_router]
+impl McpServer {
+ #[tool(
+ description = "Report whether a game is loaded plus current execution state, frame index, and texture count."
+ )]
+ async fn status(&self) -> Result<CallToolResult, McpError> {
+ let s = self.shared.state.lock().unwrap();
+ let intro = self.shared.introspect.lock().unwrap();
+ let (loaded, system, pc, cycles) = match s.backend.as_ref() {
+ None => (false, None, None, None),
+ Some(b) => {
+ let sys = match b {
+ Backend::Gc(_) => "gamecube",
+ Backend::Wii(_) => "wii",
+ };
+ (true, Some(sys), Some(b.pc()), Some(b.cycles()))
+ }
+ };
+ let json = StatusJson {
+ loaded,
+ system,
+ game_name: s.game_name.clone(),
+ game_code: s.game_code.clone(),
+ run_mode: match s.run_mode {
+ RunMode::Paused => "paused",
+ RunMode::Running => "running",
+ },
+ pc,
+ cycles,
+ frame_index: intro.frame_index,
+ last_xfb_size: intro.last_xfb_size,
+ draw_count_last_frame: intro.draw_count_this_frame,
+ texture_count: intro.textures.len(),
+ };
+ ok_json(&json)
+ }
+
+ #[tool(
+ description = "Load a GameCube or Wii disc image. Provide either a filesystem path or base64 bytes. The system kind is detected from the disc header. The emulator pauses on load; call resume or run_frames to advance."
+ )]
+ async fn load_game(&self, Parameters(args): Parameters<LoadGameArgs>) -> Result<CallToolResult, McpError> {
+ let bytes = match (args.path.as_ref(), args.bytes_b64.as_ref()) {
+ (Some(path), None) => std::fs::read(PathBuf::from(path))
+ .map_err(|e| McpError::invalid_params(format!("read disc: {e}"), None))?,
+ (None, Some(b64)) => B64
+ .decode(b64.as_bytes())
+ .map_err(|e| McpError::invalid_params(format!("decode bytes_b64: {e}"), None))?,
+ _ => {
+ return Err(McpError::invalid_params(
+ "supply exactly one of path or bytes_b64",
+ None,
+ ));
+ }
+ };
+
+ let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ boot::boot(
+ bytes,
+ &self.shared.ipl,
+ &self.shared.dsp_rom,
+ &self.shared.coef_rom,
+ self.shared.gx.clone(),
+ self.shared.device.clone(),
+ self.shared.queue.clone(),
+ self.shared.introspect.clone(),
+ )
+ }))
+ .map_err(|_| McpError::internal_error("emulator boot panicked", None))?;
+
+ let mut s = self.shared.state.lock().unwrap();
+ s.backend = Some(result.backend);
+ s.game_name = result.game_name.clone();
+ s.game_code = result.game_code.clone();
+ s.run_mode = RunMode::Paused;
+ let mut intro = self.shared.introspect.lock().unwrap();
+ *intro = Introspection::default();
+ drop(intro);
+ drop(s);
+ self.shared.cv.notify_all();
+ ok_json(&json!({ "loaded": true, "game_name": result.game_name, "game_code": result.game_code }))
+ }
+
+ #[tool(
+ description = "Switch to Running mode. The emulator advances one vsync per loop iteration on the worker thread until pause is called."
+ )]
+ async fn resume(&self) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ self.shared.set_run_mode(RunMode::Running);
+ ok_json(&json!({"run_mode": "running"}))
+ }
+
+ #[tool(
+ description = "Switch to Paused mode. Other tools (step, run_frames, run_until_pc, read_memory, ...) only work while paused."
+ )]
+ async fn pause(&self) -> Result<CallToolResult, McpError> {
+ self.shared.set_run_mode(RunMode::Paused);
+ let pc = self.shared.state.lock().unwrap().backend.as_ref().map(|b| b.pc());
+ ok_json(&json!({"run_mode": "paused", "pc": pc}))
+ }
+
+ #[tool(
+ description = "Advance the emulator by exactly N PPC instructions (no scheduler events between, just step_cpu). Requires Paused."
+ )]
+ async fn step(&self, Parameters(args): Parameters<StepArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ require_paused(&self.shared)?;
+ let count = args.count.unwrap_or(1).min(MAX_STEP_COUNT);
+ let mut s = self.shared.state.lock().unwrap();
+ let backend = s.backend.as_mut().unwrap();
+ for _ in 0..count {
+ backend.step();
+ }
+ ok_json(&json!({"stepped": count, "pc": backend.pc(), "cycles": backend.cycles()}))
+ }
+
+ #[tool(
+ description = "Advance the emulator by N full frames (vsyncs). Each frame runs the normal scheduler / GPU pipeline. Capped at 600 per call."
+ )]
+ async fn run_frames(&self, Parameters(args): Parameters<RunFramesArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ require_paused(&self.shared)?;
+ let count = args.count.clamp(1, MAX_FRAMES_PER_CALL);
+ let mut s = self.shared.state.lock().unwrap();
+ let backend = s.backend.as_mut().unwrap();
+ for _ in 0..count {
+ backend.run_until_vsync();
+ }
+ let intro = self.shared.introspect.lock().unwrap();
+ ok_json(&json!({
+ "frames": count,
+ "pc": backend.pc(),
+ "cycles": backend.cycles(),
+ "frame_index": intro.frame_index,
+ }))
+ }
+
+ #[tool(
+ description = "Step instructions until the program counter reaches `pc`, or `max_cycles` (default 100M) elapses. Reports whether the target was hit."
+ )]
+ async fn run_until_pc(&self, Parameters(args): Parameters<RunUntilPcArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ require_paused(&self.shared)?;
+ let max = args.max_cycles.unwrap_or(100_000_000);
+ let mut s = self.shared.state.lock().unwrap();
+ let backend = s.backend.as_mut().unwrap();
+ let start = backend.cycles();
+ let mut hit = false;
+ loop {
+ if backend.pc() == args.pc {
+ hit = true;
+ break;
+ }
+ if backend.cycles().wrapping_sub(start) > max {
+ break;
+ }
+ backend.step();
+ }
+ ok_json(&json!({
+ "hit": hit,
+ "pc": backend.pc(),
+ "cycles_elapsed": backend.cycles().wrapping_sub(start),
+ }))
+ }
+
+ #[tool(description = "Run the emulator until the next vsync (one frame). Convenience for run_frames(1).")]
+ async fn run_until_vsync(&self) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ require_paused(&self.shared)?;
+ let mut s = self.shared.state.lock().unwrap();
+ let backend = s.backend.as_mut().unwrap();
+ backend.run_until_vsync();
+ ok_json(&json!({"pc": backend.pc(), "cycles": backend.cycles()}))
+ }
+
+ #[tool(
+ description = "Read len bytes of GameCube/Wii memory at addr (virtual by default). Returns base64. len capped at 1 MiB."
+ )]
+ async fn read_memory(&self, Parameters(args): Parameters<ReadMemoryArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let len = args.len.min(MAX_READ_LEN) as usize;
+ let s = self.shared.state.lock().unwrap();
+ let bytes = read_bytes(s.backend.as_ref().unwrap(), args.addr, len, args.virt.unwrap_or(true))?;
+ ok_json(&json!({
+ "addr": args.addr,
+ "len": bytes.len(),
+ "bytes_b64": B64.encode(&bytes),
+ }))
+ }
+
+ #[tool(description = "Write base64 bytes to memory at addr. Use sparingly; the emulator does not validate writes.")]
+ async fn write_memory(&self, Parameters(args): Parameters<WriteMemoryArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let bytes = B64
+ .decode(args.bytes_b64.as_bytes())
+ .map_err(|e| McpError::invalid_params(format!("decode bytes_b64: {e}"), None))?;
+ let mut s = self.shared.state.lock().unwrap();
+ write_bytes(
+ s.backend.as_mut().unwrap(),
+ args.addr,
+ &bytes,
+ args.virt.unwrap_or(true),
+ )?;
+ ok_json(&json!({"addr": args.addr, "len": bytes.len()}))
+ }
+
+ #[tool(description = "Search a memory range for a needle. Returns the first N hit addresses.")]
+ async fn search_bytes(&self, Parameters(args): Parameters<SearchBytesArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let len = args.len.min(MAX_READ_LEN) as usize;
+ let needle = B64
+ .decode(args.needle_b64.as_bytes())
+ .map_err(|e| McpError::invalid_params(format!("decode needle_b64: {e}"), None))?;
+ if needle.is_empty() {
+ return Err(McpError::invalid_params("needle is empty", None));
+ }
+ let max_hits = args.max_hits.unwrap_or(32) as usize;
+ let s = self.shared.state.lock().unwrap();
+ let buf = read_bytes(s.backend.as_ref().unwrap(), args.addr, len, args.virt.unwrap_or(true))?;
+ let mut hits = Vec::new();
+ for (i, w) in buf.windows(needle.len()).enumerate() {
+ if w == needle.as_slice() {
+ hits.push(args.addr.wrapping_add(i as u32));
+ if hits.len() >= max_hits {
+ break;
+ }
+ }
+ }
+ ok_json(&json!({"hits": hits, "count": hits.len()}))
+ }
+
+ #[tool(description = "Read GPRs, FPRs, PS1s, PC/CIA/NIA, LR, CTR, MSR, CR, XER, SRR0, SRR1.")]
+ async fn get_registers(&self) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let s = self.shared.state.lock().unwrap();
+ let regs = match s.backend.as_ref().unwrap() {
+ Backend::Gc(sys) => registers_of(sys),
+ Backend::Wii(sys) => registers_of(sys),
+ };
+ ok_json(&regs)
+ }
+
+ #[tool(description = "Disassemble PowerPC instructions starting at addr. Returns [{addr, raw, text}, ...].")]
+ async fn disassemble(&self, Parameters(args): Parameters<DisassembleArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let count = args.count.min(MAX_DISASM_COUNT);
+ let virt = args.virt.unwrap_or(true);
+ let s = self.shared.state.lock().unwrap();
+ let backend = s.backend.as_ref().unwrap();
+ let mut lines = Vec::with_capacity(count as usize);
+ for i in 0..count {
+ let addr = args.addr.wrapping_add(i.wrapping_mul(4));
+ let raw = read_u32(backend, addr, virt)?;
+ let text = disasm::gekko::GekkoInstruction::decode(&raw.to_be_bytes())
+ .map(|(insn, _)| insn.to_string())
+ .unwrap_or_else(|| format!(".word {:#010X}", raw));
+ lines.push(DisasmLine { addr, raw, text });
+ }
+ ok_json(&lines)
+ }
+
+ #[tool(description = "Capture the current frame from the emulator's XFB and return it as a base64 PNG.")]
+ async fn get_view(&self) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let _ = self.shared.device.poll(wgpu::PollType::Wait {
+ submission_index: None,
+ timeout: None,
+ });
+ let captured = {
+ let gx = self.shared.gx.lock().unwrap();
+ backend_wgpu::capture::capture_texture(&self.shared.device, &self.shared.queue, &gx.xfb_texture)
+ .ok_or_else(|| McpError::internal_error("capture_texture returned None", None))?
+ };
+ let mut rgba = captured.rgba;
+ for px in rgba.chunks_exact_mut(4) {
+ px[3] = 255;
+ }
+ let png = encode_png(captured.width, captured.height, &rgba)?;
+ ok_json(&json!({
+ "width": captured.width,
+ "height": captured.height,
+ "png_b64": B64.encode(&png),
+ }))
+ }
+
+ #[tool(
+ description = "List all GX textures the emulator has uploaded so far this session, with metadata. Returns at most 1024 entries."
+ )]
+ async fn list_textures(&self) -> Result<CallToolResult, McpError> {
+ let intro = self.shared.introspect.lock().unwrap();
+ let mut out: Vec<TextureSummary> = intro
+ .textures
+ .iter()
+ .map(|(key, rec)| {
+ let mut bound_slots = Vec::new();
+ for (i, b) in intro.bound.iter().enumerate() {
+ if b.as_ref() == Some(key) {
+ bound_slots.push(i as u8);
+ }
+ }
+ TextureSummary {
+ ram_addr: key.ram_addr,
+ variant: key.variant,
+ width: rec.width,
+ height: rec.height,
+ format: format_name(rec.format),
+ last_seen_frame: rec.last_seen_frame,
+ bound_slots,
+ }
+ })
+ .collect();
+ out.sort_by_key(|t| (t.ram_addr, t.variant));
+ out.truncate(1024);
+ ok_json(&json!({"textures": out, "count": intro.textures.len()}))
+ }
+
+ #[tool(
+ description = "Return one previously uploaded GX texture as a base64 PNG. Identify by ram_addr (and variant for paletted textures)."
+ )]
+ async fn get_texture(&self, Parameters(args): Parameters<GetTextureArgs>) -> Result<CallToolResult, McpError> {
+ let intro = self.shared.introspect.lock().unwrap();
+ let key = gecko::host::TextureKey {
+ ram_addr: args.ram_addr,
+ variant: args.variant.unwrap_or(0),
+ };
+ let rec = intro.textures.get(&key).ok_or_else(|| {
+ McpError::invalid_params(
+ format!(
+ "no texture at ram_addr={:#010X} variant={:#010X}",
+ args.ram_addr,
+ args.variant.unwrap_or(0)
+ ),
+ None,
+ )
+ })?;
+ let png = encode_png(rec.width, rec.height, &rec.rgba)?;
+ ok_json(&json!({
+ "ram_addr": args.ram_addr,
+ "variant": key.variant,
+ "width": rec.width,
+ "height": rec.height,
+ "format": format_name(rec.format),
+ "png_b64": B64.encode(&png),
+ }))
+ }
+
+ #[tool(description = "Return the TextureKey currently bound to each of the 8 GX texture slots. null = unbound.")]
+ async fn list_bound_textures(&self) -> Result<CallToolResult, McpError> {
+ let intro = self.shared.introspect.lock().unwrap();
+ let bound: Vec<_> = intro
+ .bound
+ .iter()
+ .map(|b| b.map(|k| json!({"ram_addr": k.ram_addr, "variant": k.variant})))
+ .collect();
+ ok_json(&json!({"bound": bound}))
+ }
+
+ #[tool(description = "Update the GameCube controller (port 1) state. Unspecified fields stay at their last value.")]
+ async fn set_pad(&self, Parameters(args): Parameters<SetPadArgs>) -> Result<CallToolResult, McpError> {
+ require_loaded(&self.shared)?;
+ let mut pad = gecko::flipper::si::pad::PadStatus::default();
+ pad.connected = true;
+ if let Some(v) = args.stick_x {
+ pad.stick_x = v;
+ }
+ if let Some(v) = args.stick_y {
+ pad.stick_y = v;
+ }
+ if let Some(v) = args.substick_x {
+ pad.substick_x = v;
+ }
+ if let Some(v) = args.substick_y {
+ pad.substick_y = v;
+ }
+ if let Some(v) = args.trigger_left {
+ pad.trigger_left = v;
+ }
+ if let Some(v) = args.trigger_right {
+ pad.trigger_right = v;
+ }
+ if let Some(v) = args.buttons {
+ pad.buttons = v;
+ }
+ let input = gecko::HostInput::Gc(pad);
+ let mut s = self.shared.state.lock().unwrap();
+ s.backend.as_mut().unwrap().apply_host_input(&input);
+ ok_json(&json!({"applied": true}))
+ }
+}
+
+#[tool_handler]
+impl ServerHandler for McpServer {
+ fn get_info(&self) -> ServerInfo {
+ ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
+ .with_server_info(Implementation::from_build_env())
+ .with_protocol_version(ProtocolVersion::V_2024_11_05)
+ .with_instructions(
+ "Headless gecko (GameCube/Wii) emulator. Tools: load_game, status, pause/resume, step, run_frames, run_until_pc, run_until_vsync, read_memory, write_memory, search_bytes, get_registers, disassemble, get_view, list_textures, get_texture, list_bound_textures, set_pad."
+ .to_string(),
+ )
+ }
+}
+
+fn require_loaded(shared: &Shared) -> Result<(), McpError> {
+ if shared.state.lock().unwrap().backend.is_some() {
+ Ok(())
+ } else {
+ Err(McpError::invalid_request(
+ "no game is loaded; call load_game first",
+ None,
+ ))
+ }
+}
+
+fn require_paused(shared: &Shared) -> Result<(), McpError> {
+ let s = shared.state.lock().unwrap();
+ if s.run_mode == RunMode::Paused {
+ Ok(())
+ } else {
+ Err(McpError::invalid_request(
+ "the emulator is running; call pause first",
+ None,
+ ))
+ }
+}
+
+fn read_bytes(backend: &Backend, addr: u32, len: usize, virt: bool) -> Result<Vec<u8>, McpError> {
+ let mut out = Vec::with_capacity(len);
+ for i in 0..len {
+ let a = addr.wrapping_add(i as u32);
+ let byte = match backend {
+ Backend::Gc(s) => {
+ if virt {
+ s.mmio.virt_read_u8(a)
+ } else {
+ s.mmio.phys_read_u8(a)
+ }
+ }
+ Backend::Wii(s) => {
+ if virt {
+ s.mmio.virt_read_u8(a)
+ } else {
+ s.mmio.phys_read_u8(a)
+ }
+ }
+ };
+ out.push(byte);
+ }
+ Ok(out)
+}
+
+fn write_bytes(backend: &mut Backend, addr: u32, bytes: &[u8], virt: bool) -> Result<(), McpError> {
+ for (i, b) in bytes.iter().enumerate() {
+ let a = addr.wrapping_add(i as u32);
+ match backend {
+ Backend::Gc(s) => {
+ if virt {
+ s.mmio.virt_write_u8(a, *b);
+ } else {
+ s.mmio.phys_write_u8(a, *b);
+ }
+ }
+ Backend::Wii(s) => {
+ if virt {
+ s.mmio.virt_write_u8(a, *b);
+ } else {
+ s.mmio.phys_write_u8(a, *b);
+ }
+ }
+ }
+ }
+ Ok(())
+}
+
+fn read_u32(backend: &Backend, addr: u32, virt: bool) -> Result<u32, McpError> {
+ Ok(match backend {
+ Backend::Gc(s) => {
+ if virt {
+ s.mmio.virt_read_u32(addr)
+ } else {
+ s.mmio.phys_read_u32(addr)
+ }
+ }
+ Backend::Wii(s) => {
+ if virt {
+ s.mmio.virt_read_u32(addr)
+ } else {
+ s.mmio.phys_read_u32(addr)
+ }
+ }
+ })
+}
+
+fn registers_of<const SYSTEM: gecko::SystemId>(sys: &gecko::System<{ SYSTEM }>) -> RegistersJson {
+ let g = &sys.gekko;
+ RegistersJson {
+ pc: g.pc,
+ cia: g.cia,
+ nia: g.nia,
+ lr: g.spr.lr,
+ ctr: g.spr.ctr,
+ msr: g.msr.raw(),
+ cr: g.cr.raw(),
+ xer: g.spr.xer.raw(),
+ srr0: g.spr.srr0.raw(),
+ srr1: g.spr.srr1,
+ gprs: g.gprs,
+ fprs: g.fprs,
+ ps1s: g.ps1s,
+ }
+}
+
+fn format_name(fmt: gecko::flipper::gx::draw::TextureFormat) -> &'static str {
+ use gecko::flipper::gx::draw::TextureFormat as TF;
+ match fmt {
+ TF::I4 => "I4",
+ TF::I8 => "I8",
+ TF::IA4 => "IA4",
+ TF::IA8 => "IA8",
+ TF::RGB565 => "RGB565",
+ TF::RGB5A3 => "RGB5A3",
+ TF::RGBA8 => "RGBA8",
+ TF::CI4 => "CI4",
+ TF::CI8 => "CI8",
+ TF::CI14 => "CI14",
+ TF::CMPR => "CMPR",
+ }
+}
+
+fn encode_png(width: u32, height: u32, rgba: &[u8]) -> Result<Vec<u8>, McpError> {
+ let mut buf = Vec::with_capacity(rgba.len());
+ {
+ let mut encoder = png::Encoder::new(&mut buf, width, height);
+ encoder.set_color(png::ColorType::Rgba);
+ encoder.set_depth(png::BitDepth::Eight);
+ let mut writer = encoder
+ .write_header()
+ .map_err(|e| McpError::internal_error(format!("png header: {e}"), None))?;
+ writer
+ .write_image_data(rgba)
+ .map_err(|e| McpError::internal_error(format!("png write: {e}"), None))?;
+ }
+ Ok(buf)
+}
+
+fn ok_json<T: Serialize>(v: &T) -> Result<CallToolResult, McpError> {
+ let text = serde_json::to_string(v).map_err(|e| McpError::internal_error(format!("serialize: {e}"), None))?;
+ Ok(CallToolResult::success(vec![Content::text(text)]))
+}
\ No newline at end of file
diff --git a/crates/mcp/src/sink.rs b/crates/mcp/src/sink.rs
new file mode 100644
index 0000000..d29d60a
--- /dev/null
+++ b/crates/mcp/src/sink.rs
@@ -0,0 +1,77 @@
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+use backend_wgpu::GxRenderer;
+use gecko::flipper::gx::draw::TextureFormat;
+use gecko::host::{GxAction, RenderSink, TextureKey};
+
+pub struct TextureRecord {
+ pub width: u32,
+ pub height: u32,
+ pub format: TextureFormat,
+ pub rgba: std::sync::Arc<[u8]>,
+ pub last_seen_frame: u64,
+}
+
+#[derive(Default)]
+pub struct Introspection {
+ pub textures: HashMap<TextureKey, TextureRecord>,
+ pub bound: [Option<TextureKey>; 8],
+ pub last_xfb_size: (u32, u32),
+ pub draw_count_this_frame: u64,
+ pub frame_index: u64,
+}
+
+pub struct McpSink {
+ pub gx: Arc<Mutex<GxRenderer>>,
+ pub device: wgpu::Device,
+ pub queue: wgpu::Queue,
+ pub introspect: Arc<Mutex<Introspection>>,
+}
+
+impl RenderSink for McpSink {
+ fn exec(&mut self, action: GxAction) {
+ match &action {
+ GxAction::LoadTexture {
+ id,
+ width,
+ height,
+ fmt,
+ rgba,
+ } => {
+ let mut i = self.introspect.lock().unwrap();
+ let frame = i.frame_index;
+ i.textures.insert(
+ *id,
+ TextureRecord {
+ width: *width,
+ height: *height,
+ format: *fmt,
+ rgba: rgba.clone(),
+ last_seen_frame: frame,
+ },
+ );
+ }
+ GxAction::SetTexture { slot, id, .. } => {
+ let mut i = self.introspect.lock().unwrap();
+ if *slot < 8 {
+ i.bound[*slot] = Some(*id);
+ }
+ }
+ GxAction::PresentXfb { width, height, .. } => {
+ let mut i = self.introspect.lock().unwrap();
+ i.last_xfb_size = (*width, *height);
+ i.frame_index = i.frame_index.wrapping_add(1);
+ i.draw_count_this_frame = 0;
+ }
+ GxAction::Draw(_) => {
+ self.introspect.lock().unwrap().draw_count_this_frame += 1;
+ }
+ _ => {}
+ }
+ self.gx
+ .lock()
+ .unwrap()
+ .process_action(&self.device, &self.queue, &action);
+ }
+}
diff --git a/crates/mcp/src/state.rs b/crates/mcp/src/state.rs
new file mode 100644
index 0000000..1a4296a
--- /dev/null
+++ b/crates/mcp/src/state.rs
@@ -0,0 +1,107 @@
+use std::sync::{Arc, Condvar, Mutex};
+
+use backend_wgpu::GxRenderer;
+use gecko::system::{GC, System, SystemId, WII};
+
+use crate::sink::Introspection;
+
+pub enum Backend {
+ Gc(System<{ GC }>),
+ Wii(System<{ WII }>),
+}
+
+impl Backend {
+ pub fn system_id(&self) -> SystemId {
+ match self {
+ Self::Gc(_) => GC,
+ Self::Wii(_) => WII,
+ }
+ }
+
+ pub fn run_until_vsync(&mut self) {
+ match self {
+ Self::Gc(s) => s.run_until_vsync(),
+ Self::Wii(s) => s.run_until_vsync(),
+ }
+ }
+
+ pub fn step_cpu(&mut self) {
+ match self {
+ Self::Gc(s) => s.step_cpu(),
+ Self::Wii(s) => s.step_cpu(),
+ }
+ }
+
+ pub fn step(&mut self) {
+ match self {
+ Self::Gc(s) => s.step(),
+ Self::Wii(s) => s.step(),
+ }
+ }
+
+ pub fn pc(&self) -> u32 {
+ match self {
+ Self::Gc(s) => s.gekko.pc,
+ Self::Wii(s) => s.gekko.pc,
+ }
+ }
+
+ pub fn cycles(&self) -> u64 {
+ match self {
+ Self::Gc(s) => s.scheduler.cycles,
+ Self::Wii(s) => s.scheduler.cycles,
+ }
+ }
+
+ pub fn apply_host_input(&mut self, input: &gecko::HostInput) {
+ match self {
+ Self::Gc(s) => s.apply_host_input(input),
+ Self::Wii(s) => s.apply_host_input(input),
+ }
+ }
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum RunMode {
+ Paused,
+ Running,
+}
+
+pub struct EmuState {
+ pub backend: Option<Backend>,
+ pub run_mode: RunMode,
+ pub game_name: String,
+ pub game_code: String,
+ pub max_run_until_cycles: u64,
+}
+
+impl EmuState {
+ pub fn new() -> Self {
+ Self {
+ backend: None,
+ run_mode: RunMode::Paused,
+ game_name: String::new(),
+ game_code: String::new(),
+ max_run_until_cycles: 1_000_000_000,
+ }
+ }
+}
+
+pub struct Shared {
+ pub state: Mutex<EmuState>,
+ pub cv: Condvar,
+ pub gx: Arc<Mutex<GxRenderer>>,
+ pub device: wgpu::Device,
+ pub queue: wgpu::Queue,
+ pub introspect: Arc<Mutex<Introspection>>,
+ pub ipl: Vec<u8>,
+ pub dsp_rom: Vec<u8>,
+ pub coef_rom: Vec<u8>,
+}
+
+impl Shared {
+ pub fn set_run_mode(self: &Arc<Self>, mode: RunMode) {
+ self.state.lock().unwrap().run_mode = mode;
+ self.cv.notify_all();
+ }
+}
diff --git a/crates/mcp/src/worker.rs b/crates/mcp/src/worker.rs
new file mode 100644
index 0000000..baeb998
--- /dev/null
+++ b/crates/mcp/src/worker.rs
@@ -0,0 +1,24 @@
+use std::sync::Arc;
+
+use crate::state::{RunMode, Shared};
+
+pub fn run(shared: Arc<Shared>) {
+ loop {
+ let mut s = shared.state.lock().unwrap();
+ loop {
+ if s.backend.is_none() || s.run_mode == RunMode::Paused {
+ s = shared
+ .cv
+ .wait_while(s, |s| s.backend.is_none() || s.run_mode == RunMode::Paused)
+ .unwrap();
+ continue;
+ }
+ break;
+ }
+
+ if let Some(backend) = s.backend.as_mut() {
+ backend.run_until_vsync();
+ }
+ drop(s);
+ }
+}