MCP-openMSX

"Orquestando una ópera binaria donde la IA dirige, el MCP interpreta y openMSX actúa como la diva de 8 bits."

Un servidor de Model Context Protocol (MCP) para automatizar instancias del emulador openMSX.

Este servidor proporciona herramientas integrales para el desarrollo, pruebas y automatización de software MSX a través de protocolos MCP estandarizados.

🎁🎁 Si encuentras útil este proyecto, considera hacer una donación: Enlace a PAYPAL

Tabla de contenidos

• Descripción del proyecto

• Arquitectura

• Herramientas MCP disponibles

• Recursos MCP disponibles

• ⚡ Inicio rápido

  • Instalación rápida con VSCode

  • Instalación básica con Claude Desktop

  • Variables de entorno

• Uso manual avanzado

• Desarrollo

• Licencia

• Soporte

• Contribución

• 🌟 ¡Más estrellas! 🌟

Related MCP server: MCP Toolbox for Databases

Descripción del proyecto

Este proyecto crea un puente entre el desarrollo moderno asistido por IA (p. ej., GitHub Copilot, Claude Desktop) y la informática retro (sistemas MSX) proporcionando:

• Control del emulador: Iniciar, configurar, gestionar instancias de openMSX y reproducir líneas de tiempo.

• Gestión de medios: Manejo de cartuchos ROM, disquetes y cintas de casete.

• Soporte de programación BASIC: Herramientas para facilitar la programación y el desarrollo en lenguaje BASIC.

• Herramientas de depuración: Depuración completa de CPU con puntos de interrupción, inspección de memoria y ejecución paso a paso.

• Control de vídeo: Manipulación de registros VDP y captura de pantalla.

• Operaciones de memoria: Lectura/escritura de RAM, VRAM y acceso a puertos de E/S.

• Automatización: Simulación de entrada de teclado y gestión de estados guardados (savestates).

• Integración con base de datos vectorial: Consultar una base de datos vectorial integrada con recursos MSX para soporte de desarrollo.

• Modo híbrido: Este servidor MCP admite modo de acceso híbrido (transportes STDIO y HTTP).

Arquitectura

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

El servidor MCP traduce comandos de lenguaje natural de alto nivel de tu IA Copilot a comandos TCL para controlar openMSX, permitiendo pruebas y depuración automatizadas de software MSX.

Herramientas MCP disponibles

Herramientas de control del emulador

• emu_control: Controla un emulador openMSX: launch, close, powerOn, powerOff, reset, getEmulatorSpeed, setEmulatorSpeed, machineList, extensionList, wait.

• emu_replay: Controla la línea de tiempo de emulación: start, stop, status, goBack, absoluteGoto, advanceFrame, reverseFrame, truncate, saveReplay, loadReplay.

• emu_info: Obtiene información sobre la máquina emulada actual: getStatus, getSlotsMap, getIOPortsMap.

• emu_media: Gestiona medios ROM, disco y cinta: tapeInsert, tapeRewind, tapeEject, romInsert, romEject, diskInsert, diskInsertFolder, diskEject.

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

Herramientas de programación

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

Herramientas de depuración

• debug_run: Controla la ejecución: break, isBreaked, continue, stepIn, stepOut, stepOver, stepBack, runTo.

• debug_cpu: Lee/escribe registros de CPU, información de CPU, pila y desensambla código: getCpuRegisters, getRegister, setRegister, getStackPile, disassemble, getActiveCpu.

• debug_memory: Operaciones de memoria RAM: selectedSlots, getBlock, readByte, readWord, writeByte, writeWord, searchBytes.

• debug_vram: Operaciones de VRAM: getBlock, readByte, writeByte, searchBytes.

• debug_breakpoints: Gestión de puntos de interrupción: create, remove, list.

Herramientas de automatización

• emu_keyboard: Envía texto o combinaciones de teclas al emulador: sendText, sendKeyCombo.

• emu_savestates: Guarda y restaura estados de la máquina: load, save, list.

• screen_shot: Captura la pantalla del emulador: as_image, to_file.

• screen_dump: Exporta datos de pantalla como instrucción BASIC BSAVE.

• msxdocs_resource_get: Recupera recursos MCP para clientes MCP que no admiten recursos MCP.

Herramientas de documentación

• vector_db_query: Consulta los recursos de la base de datos vectorial para obtener información sobre sistemas MSX, cartuchos y otros recursos de desarrollo.

• msxdocs_resource_get: Recupera recursos MCP para clientes MCP que no admiten recursos MCP.

Recursos MCP disponibles

¿Qué son los recursos MCP?

Los recursos MCP son conjuntos de datos estructurados, documentación y archivos de ayuda que amplían las capacidades del servidor MCP. Proporcionan información esencial como definiciones de máquinas, listas de extensiones, plantillas de medios y ejemplos de programación, permitiendo flujos de trabajo de automatización, pruebas y desarrollo más potentes para software MSX dentro del entorno MCP-openMSX.

Recursos disponibles

Hay más de 60 recursos disponibles, algunos incluidos directamente en el MCP y otros accesibles mediante descarga cuando se consultan. Están organizados en las siguientes categorías:

• Processors (Z80, R800)

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

• System

• Audio

• Video

• Programming (ASM, BASIC, ...)

• MSX-DOS

• MSX-UNAPI

• MSX BASIC

Y libros y manuales:

• MSX2 Technical Handbook

• The MSX Red Book

• SDCC Compiler

Recursos de:

• 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

Gracias a los autores de estos recursos, quienes los han puesto a disposición bajo varias licencias. Este servidor MCP incluye algunos de estos recursos para mejorar la experiencia de desarrollo.

Inicio rápido

Puedes usar este servidor MCP de esta manera básica con el paquete NPM precompilado.

Instalación rápida con VSCode

Pasos para instalar el servidor MCP en VSCode:

1. Instala la extensión Github Copilot

2. Instala nodejs (el comando npx debe estar disponible en tu PATH).

3. Instala el servidor MCP:

   • Usa el botón Install MCP Server de arriba para instalar el servidor MCP en tu configuración de VSCode.

   • O añade a tu carpeta de espacio de trabajo un archivo llamado .vscode/mcp.json con la configuración JSON a continuación.

Modo STDIO (recomendado)

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

Modo HTTP transmitido (más avanzado)

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

Instalación básica con Claude Desktop

Sigue estas instrucciones para acceder al archivo claude_desktop_config.json de Claude.

Edítalo para incluir la siguiente entrada JSON:

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

Variables de entorno

Uso manual avanzado

El servidor MCP funciona en Linux, macOS y Windows. Construir desde el código fuente requiere Node.js >= 18 y TypeScript.

Instalación manual

npm install -g @nataliapc/mcp-openmsx

Conjunto manual de variables de entorno

Establece variables de entorno opcionales para personalizar el servidor:

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"

Como servidor MCP (stdio)

mcp-openmsx

Como servidor HTTP

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

Desarrollo

Requisitos previos para construir

• Node.js >= 18.0.0

• TypeScript

• Emulador openMSX instalado

Construcción

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

Ejecución en desarrollo

npm run dev

Licencia

Licencia GPL2 - consulta el archivo LICENSE para más detalles.

Soporte

Si necesitas ayuda, o tienes preguntas o sugerencias, por favor abre un issue en la página de GitHub Issues o consulta las discusiones del proyecto.

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

¡Más estrellas!

Por favor, danos una estrella en GitHub si te gusta este proyecto.

Historial de estrellas