Zafiro.MasterSystem.Debug.Emulator 0.0.6

Zafiro.MasterSystem.Debug

A .NET 10 Sega Master System / Game Gear debugging MCP, in the style of the sibling Game Boy and NES servers. It runs headlessly over stdio and is fully managed: no native libraries, emulator executables, SDL, OpenGL or BIOS are required, so the same build runs on Linux, Windows and macOS. The server exposes 51 tools for Z80 debugging, conditional breakpoints, watchpoints, correlated observation, graphics and PSG/YM2413 audio capture.

The emulation core is vendored C#: the Z80, VDP and SN76489 PSG come from Essgee, and the YM2413 FM synthesizer is a C# port of emu2413 v1.5.9 that matches the C original sample for sample. Both are MIT licensed.

Install

The server is published on NuGet as the Zafiro.MasterSystem.Debug.Mcp .NET tool and requires the .NET 10 runtime. MCP clients can run it without a separate install through dnx:

{
  "mcpServers": {
    "sms_debug": {
      "command": "dnx",
      "args": ["Zafiro.MasterSystem.Debug.Mcp", "--yes"]
    }
  }
}

Or install it globally and use the zafiro-mastersystem-debug-mcp command:

dotnet tool install -g Zafiro.MasterSystem.Debug.Mcp

Diagnostics use stderr exclusively. Every request is serialized, and execution always returns to a paused machine, reporting actual frames, instructions, cycles and stop reason.

Use the emulator from .NET code

The emulation core and debug session are also published as libraries, so tests can drive ROMs headlessly in process without the MCP server:

dotnet add package Zafiro.MasterSystem.Debug.Emulator

var session = new Zafiro.MasterSystem.Debug.Emulator.SmsDebugSession();
session.LoadRomBytes(rom, system: "sms");
session.SetController("right");
session.RunFrame(60);
var ram = session.ReadMemory(0xC000, 16);
var pixels = session.ScreenPixels();

A run pays only for what it observes: with no breakpoints the program counter is not read, CPU reads are not observed without a read watchpoint, conditions are compiled once, and nothing is allocated per instruction. For test harnesses:

• RunTimeLimit (15 seconds by default) bounds the wall-clock time of one run; set it to null so a loaded CI machine cannot split a run nondeterministically.
• RunUntilScanline(line) is RunUntilCondition("SCANLINE == line") without parsing.
• TraceWritesUntilScanline(line, "vram", address, length) records every write to a range on the way to a line in one run, instead of stopping on each one as a watchpoint does.

Zafiro.MasterSystem.Debug.Core holds the shared data model (registers, VDP/PSG state, bus accesses) and the PNG/WAV encoders.

Build from source

Requires the .NET 10 SDK.

dotnet build Zafiro.MasterSystem.Debug.slnx -c Release -m:4
dotnet src/Zafiro.MasterSystem.Debug.Mcp/bin/Release/net10.0/Zafiro.MasterSystem.Debug.Mcp.dll

To validate unreleased changes, point the MCP client at the built assembly:

{
  "mcpServers": {
    "sms_debug": {
      "command": "dotnet",
      "args": ["/absolute/path/to/Zafiro.MasterSystem.Debug/src/Zafiro.MasterSystem.Debug.Mcp/bin/Release/net10.0/Zafiro.MasterSystem.Debug.Mcp.dll"]
    }
  }
}

Capabilities

SMS sessions attach a YM2413 by default, like a Japanese Master System; load with fm: false to model an export console. Game Gear has no FM chip. See tool schemas and examples; tools/list is authoritative.

Validation

dotnet test Zafiro.MasterSystem.Debug.slnx -c Release -m:4
python3 scripts/qualify_roms.py --gameplay "/path/to/roms/"*.zip

52 tests pass, including a real stdio session, FM detection and mixer behavior, FM snapshots, and a bit-exact comparison of the YM2413 port against the C original. Seventeen local ROMs passed the stdio debugger workflow, and twelve of them reached in-game play in a scripted input sequence, including GG Sonic 1 v1.1. Wonder Boy in Monster Land detects the YM2413 and plays its FM soundtrack. See evidence. ROMs and their graphics/audio artifacts remain local and are not redistributed.

Releases

Every commit on master is released by a DotnetDeployer.Fleet worker using deployer.yaml: it builds and tests the solution, versions it with GitVersion and pushes the Zafiro.MasterSystem.Debug.Mcp package to NuGet. To check packaging locally:

dnx dotnetdeployer.tool --dry-run

Scope

The tests prove the described debugger workflows, not complete game compatibility or bus-cycle accuracy. Traces carry instruction-start timestamps. Snapshots are backend-version-specific rather than portable savestates. WAV capture exports samples and does not play them through speakers. SG-1000, SC-3000, Korean mappers and peripherals such as the light phaser or paddle are not emulated.

License

MIT. Vendored Essgee and emu2413 code keep their MIT notices; see third-party notices.