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.tomlnew file mode 100644index 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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(®s)+ }++ #[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 filediff --git a/crates/mcp/src/sink.rs b/crates/mcp/src/sink.rsnew file mode 100644index 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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);+ }+}