convez.ai
MCP ServerDevOps & InfraestruturaAvançado
DohmBoy64Bit

Mupen64MCP

DohmBoy64Bit/Mupen64MCP

Depuração remota de N64 com Mupen64Plus via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para depuração de ROMs do Nintendo 64 via Mupen64Plus. Oferece inspeção e controle de emulação em tempo real, incluindo breakpoints, memória, registros, display lists e detecção de SO, ideal para análise de assets e reversing de jogos.

Instalação

$npx convez-ai DohmBoy64Bit/Mupen64MCP

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise de ROMs em tempo real com breakpoints e inspecção de memória
  • Reversing de assets e estruturas de dados de jogos N64
  • Rotulação automatizada de estados de jogo via IA

Veredito

Ferramenta especializada e técnica para debugging profundo de emulação N64, requer conhecimento avançado de compilação (CMake, MSYS2) e depuração de baixo nível. Solução robusta para reversing e análise de ROM, mas com curva de setup elevada.

README

A tradução para o português deste README ainda está na fila.

Mupen64MCP

Nintendo 64 ROM debugging via the Model Context Protocol (MCP).

Inspect and control a running N64 ROM through Mupen64Plus's debugger API — breakpoints, memory, registers, display lists, OS detection, and more. Designed for runtime ROM analysis, asset reversing, and game-state labeling without instrumenting the binary.

Prerequisites

  • Windows (MSYS2 MINGW64 environment recommended)
  • CMake ≥ 3.16, gcc (MSYS2) or MSVC
  • Python ≥ 3.11 with uv or pip
  • pkg-config, libopcodes, libbfd (for Mupen64Plus build)

Quick Start

# 1. Start the daemon (headless, dummy plugins)
start_daemon.bat

# 2. Start the MCP server
n64-debug-mcp

# 3. Configure your AI assistant (Claude Desktop, Cursor, etc.)
# See examples/ for config files

Building

Mupen64Plus Core (with DEBUGGER)

cd build/mupen64plus/mupen64plus-core/projects/unix
make clean
make all VULKAN=0 NO_ASM=1 DEBUGGER=1
cp mupen64plus.dll ../../lib/

Flags: VULKAN=0 (avoids missing headers), NO_ASM=1 (interpreter for reliable breakpoints), DEBUGGER=1 (enables debugger API).

Native Daemon

cd native/n64_debug_daemon
cmake -B build -DMUPEN64PLUS_DIR=../../build/mupen64plus
cmake --build build

Python MCP Server

cd mcp/python
pip install -e .
# or: uv sync

Optional: Rice Video Plugin (for framebuffer capture)

Must be built in the MSYS2 MINGW64 shell — not WinLibs or any other MinGW distribution. Plugins link against MSYS2's libstdc++-6.dll at runtime; building with a different toolchain creates ABI-incompatible DLLs that crash on load.

# Run this from an MSYS2 MINGW64 shell, not cmd or PowerShell
cd build/mupen64plus/mupen64plus-video-rice/projects/unix
make all
cp mupen64plus-video-rice.dll ../../../../plugins/

All other real plugins (RSP-HLE, audio-sdl, input-sdl) must be built the same way — using make from the MSYS2 MINGW64 shell.

Usage

# Headless (dummy plugins) — best for debugging
native/n64_debug_daemon/build/n64-debug-daemon.exe ^
  --core build/mupen64plus/lib/mupen64plus.dll ^
  --rom roms/myrom.z64 ^
  --gfx dummy --audio dummy --rsp dummy ^
  --input native/n64_debug_daemon/build/mupen64plus-input-inject.dll ^
  --port 9876

# With real rendering (Rice + RSP-HLE) — for framebuffer capture
# Note: plugins must be built with MSYS2 MINGW64 toolchain (see "Rice Video Plugin" below)
native/n64_debug_daemon/build/n64-debug-daemon.exe ^
  --core build/mupen64plus/lib/mupen64plus.dll ^
  --rom roms/myrom.z64 ^
  --gfx plugins/mupen64plus-video-rice.dll ^
  --rsp plugins/mupen64plus-rsp-hle.dll ^
  --input native/n64_debug_daemon/build/mupen64plus-input-inject.dll ^
  --port 9876

Config Options

OptionDescriptionDefault
--core <path>Path to mupen64plus.dll(required)
--rom <path>ROM file to load(none)
--gfx <path>Video plugin DLLdummy
--audio <path>Audio plugin DLLdummy
--input <path>Input plugin DLLdummy
--rsp <path>RSP plugin DLLdummy
--datadir <dir>Shared data directory.
--configdir <dir>Config directory.
--port <n>JSON-RPC TCP port9876
--allow-write-memoryEnable memory writes(disabled)

AI Assistant Integration

Claude Desktop / Cursor:

{
  "mcpServers": {
    "n64-debug-mcp": {
      "command": "uv",
      "args": ["--directory", "D:\\Mupen64MCP\\mcp\\python", "run", "n64-debug-mcp"]
    }
  }
}

Status Dashboard (optional)

n64-viewer
# or: python start_viewer.py

MCP Tools (47 total)

CategoryTools
Lifecyclen64_start_daemon, n64_stop_daemon
Emulationn64_get_status, n64_load_rom, n64_close_rom, n64_pause, n64_resume, n64_step_instruction, n64_step_frame
CPUn64_get_pc, n64_get_registers
Memoryn64_read_memory, n64_write_memory, n64_dump_rdram, n64_translate_address, n64_translate_address_static
Breakpointsn64_add_breakpoint, n64_remove_breakpoint, n64_list_breakpoints, n64_scan_functions
Tracingn64_mark_game_state, n64_get_trace_events, n64_clear_trace_events, n64_trace_rom_reads, n64_wait_for_breakpoint, n64_export_trace, n64_track_struct, n64_decode_display_list, n64_trace_callchain, n64_trace_scheduler, n64_detect_os
Inputn64_set_controller
Framebuffern64_read_framebuffer, n64_set_frame_capture_interval, n64_get_frame_count, n64_get_frame_captures, n64_clear_frame_captures, n64_wait_for_frame
Assetsn64_discover_assets, n64_export_manifest
PI DMAn64_capture_pi_dma, n64_trace_pi_dma
RSP/SPn64_get_rsp_task, n64_trace_rsp_tasks, n64_read_sp_memory, n64_read_sp_registers, n64_check_rsp_health

Project Structure

D:\Mupen64MCP\
├── mcp/python/              # Python MCP server (FastMCP)
├── native/                  # C++ daemon + input inject plugin
├── build/mupen64plus/       # Mupen64Plus core + plugins source + build
├── docs/                    # Architecture, engine reverse engineering
├── examples/                # Claude/Cursor config files
└── tests/                   # Test scripts

License

MIT

See TOOLS.md for detailed MCP tool reference with parameters and return types, docs/ARCHITECTURE.md for design details, TROUBLESHOOTING.md for common issues, and ROM_TESTING.md for tested ROMs and test results.

Ver o original no GitHub

Bom para

Relacionados