MCP-openMSX

„Orchestrierung einer binären Oper, bei der die KI dirigiert, MCP interpretiert und openMSX als 8-Bit-Diva agiert.“

Ein Model Context Protocol (MCP)-Server zur Automatisierung von openMSX-Emulator-Instanzen.

Dieser Server bietet umfassende Werkzeuge für die MSX-Softwareentwicklung, das Testen und die Automatisierung durch standardisierte MCP-Protokolle.

🎁🎁 Wenn Sie dieses Projekt nützlich finden, ziehen Sie bitte eine Spende in Betracht: PAYPAL Link

Inhaltsverzeichnis

• Projektübersicht

• Architektur

• Verfügbare MCP-Werkzeuge

• Verfügbare MCP-Ressourcen

• ⚡ Schnellstart

  • Schnellinstallation mit VSCode

  • Grundlegende Installation mit Claude Desktop

  • Umgebungsvariablen

• Erweiterte manuelle Nutzung

• Entwicklung

• Lizenz

• Support

• Mitwirken

• 🌟 Mehr Sterne! 🌟

Related MCP server: MCP Toolbox for Databases

Projektübersicht

Dieses Projekt schlägt eine Brücke zwischen moderner KI-gestützter Entwicklung (z. B. GitHub Copilot, Claude Desktop) und Retro-Computing (MSX-Systeme), indem es Folgendes bereitstellt:

• Emulator-Steuerung: Starten, Konfigurieren, Verwalten von openMSX-Instanzen und Wiedergeben von Zeitachsen.

• Medienverwaltung: Handhabung von ROM-Cartridges, Disketten und Kassetten.

• BASIC-Programmierunterstützung: Werkzeuge zur Erleichterung der Programmierung und Entwicklung in BASIC.

• Debugging-Werkzeuge: Vollständiges CPU-Debugging mit Breakpoints, Speicherinspektion und Einzelschrittausführung.

• Videosteuerung: VDP-Registermanipulation und Bildschirmaufnahme.

• Speicheroperationen: Lesen/Schreiben von RAM, VRAM und Zugriff auf E/A-Ports.

• Automatisierung: Simulation von Tastatureingaben und Verwaltung von Speicherständen (Savestates).

• Vektor-DB-Integration: Abfrage einer eingebetteten Vektordatenbank mit MSX-Ressourcen zur Entwicklungsunterstützung.

• Hybrid-Modus: Dieser MCP-Server unterstützt den hybriden Zugriffsmodus (STDIO und HTTP-Transporte).

Architektur

flowchart TB
  %%{init: {'flowchart': {'curve':'monotoneX' }}}%%

  subgraph yourComputerGroup[" "]
    HOST["Your AI dev companion<br>(MCP Client support)"]
    EMU["openMSX emulator<br>(local instance)"]

    subgraph mcpGroup["**mcp-openmsx**"]
      MCP["MCP Server<br>stdio / http"]
      TOOLS["MCP Tools"]
      VECTORDB[("Embeddings RAG<br>(Vector Database)")]
      RESOURCES["MCP Resources"]
      LOCALDATA["Local data<br>(inner documentation)"]
    end
    EXTDATA["External data<br>(webpages)"]

    HOST <--"_MCP<br> protocol _"--> MCP
    MCP <--> TOOLS & RESOURCES
    TOOLS <--"_ Query _"--> VECTORDB
    TOOLS <--"_ Console commands _"---> EMU
    RESOURCES <--_ http _---> EXTDATA
    RESOURCES <--> LOCALDATA
  end

  HOST@{ shape: rounded }
  MCP@{ shape: rounded }
  EMU@{ shape: rounded }
  LOCALDATA@{ shape: docs }
  EXTDATA@{ shape: docs }
  style yourComputerGroup color:#fff,fill:#4444,text-align:left
  style mcpGroup color:#fff,fill:#4444
  style HOST color:#000000,fill:#BBDEFB,stroke-width:4px,stroke-dasharray:0
  style MCP color:#000000,fill:#FFF9C4
  style EMU color:#FFFFFF,fill:#0000FF,stroke-width:4px,stroke-dasharray:0

Der MCP-Server übersetzt hochsprachliche Befehle Ihrer Copilot-KI in TCL-Befehle zur Steuerung von openMSX, was automatisierte MSX-Softwaretests und Debugging ermöglicht.

Verfügbare MCP-Werkzeuge

Emulator-Steuerungswerkzeuge

• emu_control: Steuert einen openMSX-Emulator: launch, close, powerOn, powerOff, reset, getEmulatorSpeed, setEmulatorSpeed, machineList, extensionList, wait.

• emu_replay: Steuert die Emulationszeitachse: start, stop, status, goBack, absoluteGoto, advanceFrame, reverseFrame, truncate, saveReplay, loadReplay.

• emu_info: Erhält Informationen über die aktuell emulierte Maschine: getStatus, getSlotsMap, getIOPortsMap.

• emu_media: Verwaltet ROM-, Disk- und Bandmedien: tapeInsert, tapeRewind, tapeEject, romInsert, romEject, diskInsert, diskInsertFolder, diskEject.

• emu_vdp: Verwaltet den VDP (Video Display Processor): getPalette, getRegisters, getRegisterValue, setRegisterValue, screenGetMode, screenGetFullText.

Programmierwerkzeuge

• basic_programming: BASIC-Werkzeuge: isBasicAvailable, newProgram, runProgram, setProgram, getFullProgram, getFullProgramAdvanced, listProgramLines, deleteProgramLines.

Debugging-Werkzeuge

• debug_run: Steuert die Ausführung: break, isBreaked, continue, stepIn, stepOut, stepOver, stepBack, runTo.

• debug_cpu: Lesen/Schreiben von CPU-Registern, CPU-Info, Stack-Pile und Disassemblieren von Code: getCpuRegisters, getRegister, setRegister, getStackPile, disassemble, getActiveCpu.

• debug_memory: RAM-Speicheroperationen: selectedSlots, getBlock, readByte, readWord, writeByte, writeWord, searchBytes.

• debug_vram: VRAM-Operationen: getBlock, readByte, writeByte, searchBytes.

• debug_breakpoints: Breakpoint-Verwaltung: create, remove, list.

Automatisierungswerkzeuge

• emu_keyboard: Sendet Text oder Tastenkombinationen an den Emulator: sendText, sendKeyCombo.

• emu_savestates: Speichert und stellt Maschinenzustände wieder her: load, save, list.

• screen_shot: Erfasst den Emulator-Bildschirm: as_image, to_file.

• screen_dump: Exportiert Bildschirmdaten als BASIC-BSAVE-Anweisung.

• msxdocs_resource_get: Ruft MCP-Ressourcen für MCP-Clients ab, die keine MCP-Ressourcen unterstützen.

Dokumentationswerkzeuge

• vector_db_query: Fragt die Vektor-DB-Ressourcen ab, um Informationen über MSX-Systeme, Cartridges und andere Entwicklungsressourcen zu erhalten.

• msxdocs_resource_get: Ruft MCP-Ressourcen für MCP-Clients ab, die keine MCP-Ressourcen unterstützen.

Verfügbare MCP-Ressourcen

Was sind MCP-Ressourcen?

MCP-Ressourcen sind strukturierte Datensätze, Dokumentationen und Hilfsdateien, die die Fähigkeiten des MCP-Servers erweitern. Sie bieten wesentliche Informationen wie Maschinendefinitionen, Erweiterungslisten, Medienvorlagen und Programmierbeispiele, was leistungsfähigere Automatisierungs-, Test- und Entwicklungsworkflows für MSX-Software innerhalb der MCP-openMSX-Umgebung ermöglicht.

Verfügbare Ressourcen

Es sind mehr als 60 Ressourcen verfügbar, einige sind direkt im MCP enthalten und andere sind nach Abfrage per Download zugänglich. Sie sind in folgende Kategorien unterteilt:

• Processors (Z80, R800)

• Bios (Bios ROM, DOS ROM, SUBROM, ...)

• System

• Audio

• Video

• Programming (ASM, BASIC, ...)

• MSX-DOS

• MSX-UNAPI

• MSX BASIC

Sowie Bücher und Handbücher:

• MSX2 Technical Handbook

• The MSX Red Book

• SDCC Compiler

Ressourcen von:

• Grauw MSX Assembly Page

• Z80 Heaven Wiki

• The MSX Red Book

• MSX2 Technical Handbook

• Konamiman MSX-UNAPI-specification

• BiFi MSX Net

• MRC Wiki

• MSX Banzai!

• SDCC

Dank an die Autoren dieser Ressourcen, die sie unter verschiedenen Lizenzen zur Verfügung gestellt haben. Dieser MCP-Server enthält einige dieser Ressourcen, um die Entwicklungserfahrung zu verbessern.

Schnellstart

Sie können diesen MCP-Server auf diese grundlegende Weise mit dem vorcompilierten NPM-Paket verwenden.

Schnellinstallation mit VSCode

Schritte zur Installation des MCP-Servers in VSCode:

1. Installieren Sie die Github Copilot-Erweiterung

2. Installieren Sie nodejs (der npx-Befehl muss in Ihrem PATH verfügbar sein).

3. Installieren Sie den MCP-Server:

   • Verwenden Sie die Schaltfläche Install MCP Server oben, um den MCP-Server in Ihren VSCode-Einstellungen zu installieren.

   • Oder fügen Sie Ihrem Arbeitsbereichsordner eine Datei namens .vscode/mcp.json mit der unten stehenden JSON-Konfiguration hinzu.

STDIO-Modus (empfohlen)

{
  "servers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

Gestreamter HTTP-Modus (fortgeschrittener)

{
  "servers": {
    "mcp-openmsx": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { }
    }
  }
}

Grundlegende Installation mit Claude Desktop

Folgen Sie diesen Anweisungen, um auf die Datei claude_desktop_config.json von Claude zuzugreifen.

Bearbeiten Sie sie, um den folgenden JSON-Eintrag hinzuzufügen:

{
  "mcpServers": {
    "mcp-openmsx": {
      "command": "npx",
      "args": ["@nataliapc/mcp-openmsx"],
      "env": {
        "OPENMSX_SHARE_DIR": "C:\\the\\location\\of\\your\\openmsx\\share\\folder"
      }
    }
  }
}

Umgebungsvariablen

Erweiterte manuelle Nutzung

Der MCP-Server läuft unter Linux, macOS und Windows. Das Bauen aus dem Quellcode erfordert Node.js >= 18 und TypeScript.

Manuelle Installation

npm install -g @nataliapc/mcp-openmsx

Manuelle Einstellung von Umgebungsvariablen

Setzen Sie optionale Umgebungsvariablen, um den Server anzupassen:

export OPENMSX_EXECUTABLE="openmsx"
export OPENMSX_SHARE_DIR="/usr/share/openmsx"
export OPENMSX_SCREENSHOT_DIR="/my_project/screenshots"
export OPENMSX_SCREENDUMP_DIR="/my_project/screendumps"
export OPENMSX_REPLAYS_DIR="/my_project/replays"
export MCP_HTTP_PORT=3000
export MCP_ALLOWED_ORIGINS="http://localhost,http://mydomain.com"

Als MCP-Server (stdio)

mcp-openmsx

Als HTTP-Server

MCP_TRANSPORT=http mcp-openmsx
# or
mcp-openmsx http

Entwicklung

Voraussetzungen zum Bauen

• Node.js >= 18.0.0

• TypeScript

• openMSX-Emulator installiert

Bauen

git clone https://github.com/nataliapc/mcp-openmsx.git
cd mcp-openmsx/mcp-server
npm install
npm run build

Ausführen in der Entwicklung

npm run dev

Lizenz

GPL2-Lizenz - siehe LICENSE-Datei für Details.

Support

Wenn Sie Hilfe benötigen oder Fragen oder Vorschläge haben, eröffnen Sie bitte ein Issue auf der GitHub Issues-Seite oder prüfen Sie die Projektdiskussionen.

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.

Mehr Sterne!

Bitte geben Sie uns einen Stern auf [GitHub](https://github.com/nataliap