MCP-openMSX

*"AI가 지휘하고, MCP가 해석하며, openMSX가 8비트 디바 역할을 하는 이진 오페라를 오케스트레이션합니다."

Model Context Protocol (MCP) 서버로, openMSX 에뮬레이터 인스턴스를 자동화합니다.

이 서버는 표준화된 MCP 프로토콜을 통해 MSX 소프트웨어 개발, 테스트 및 자동화를 위한 포괄적인 도구를 제공합니다.

🎁🎁 이 프로젝트가 유용하다면 기부를 고려해 주세요: PAYPAL 링크

목차

• 프로젝트 개요

• 아키텍처

• 사용 가능한 MCP 도구

• 사용 가능한 MCP 리소스

• ⚡ 빠른 시작

  • VSCode를 이용한 빠른 설치

  • Claude Desktop을 이용한 기본 설치

  • 환경 변수

• 고급 수동 사용법

• 개발

• 라이선스

• 지원

• 기여

• 🌟 더 많은 별점! 🌟

Related MCP server: MCP Toolbox for Databases

프로젝트 개요

이 프로젝트는 현대적인 AI 보조 개발(예: GitHub Copilot, Claude Desktop)과 레트로 컴퓨팅(MSX 시스템) 사이의 가교 역할을 하며 다음을 제공합니다:

• 에뮬레이터 제어: openMSX 인스턴스 실행, 구성, 관리 및 타임라인 재생.

• 미디어 관리: ROM 카트리지, 플로피 디스크 및 카세트 테이프 처리.

• BASIC 프로그래밍 지원: BASIC 언어 프로그래밍 및 개발을 용이하게 하는 도구.

• 디버깅 도구: 중단점, 메모리 검사 및 단계별 실행을 포함한 전체 CPU 디버깅.

• 비디오 제어: VDP 레지스터 조작 및 화면 캡처.

• 메모리 작업: RAM, VRAM 읽기/쓰기 및 I/O 포트 액세스.

• 자동화: 키보드 입력 시뮬레이션 및 상태 저장(savestate) 관리.

• 벡터 DB 통합: 개발 지원을 위해 MSX 리소스가 포함된 임베디드 벡터 데이터베이스 쿼리.

• 하이브리드 모드: 이 MCP 서버는 하이브리드 액세스 모드(STDIO 및 HTTP 전송)를 지원합니다.

아키텍처

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

MCP 서버는 Copilot AI의 상위 수준 자연어 명령을 TCL 명령으로 변환하여 openMSX를 제어함으로써 자동화된 MSX 소프트웨어 테스트 및 디버깅을 가능하게 합니다.

사용 가능한 MCP 도구

에뮬레이터 제어 도구

• emu_control: openMSX 에뮬레이터 제어: launch, close, powerOn, powerOff, reset, getEmulatorSpeed, setEmulatorSpeed, machineList, extensionList, wait.

• emu_replay: 에뮬레이션 타임라인 제어: start, stop, status, goBack, absoluteGoto, advanceFrame, reverseFrame, truncate, saveReplay, loadReplay.

• emu_info: 현재 에뮬레이트된 머신에 대한 정보 획득: getStatus, getSlotsMap, getIOPortsMap.

• emu_media: ROM, 디스크 및 테이프 미디어 관리: tapeInsert, tapeRewind, tapeEject, romInsert, romEject, diskInsert, diskInsertFolder, diskEject.

• emu_vdp: VDP(비디오 디스플레이 프로세서) 관리: getPalette, getRegisters, getRegisterValue, setRegisterValue, screenGetMode, screenGetFullText.

프로그래밍 도구

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

디버깅 도구

• debug_run: 실행 제어: break, isBreaked, continue, stepIn, stepOut, stepOver, stepBack, runTo.

• debug_cpu: CPU 레지스터 읽기/쓰기, CPU 정보, 스택 파일 및 코드 디스어셈블: getCpuRegisters, getRegister, setRegister, getStackPile, disassemble, getActiveCpu.

• debug_memory: RAM 메모리 작업: selectedSlots, getBlock, readByte, readWord, writeByte, writeWord, searchBytes.

• debug_vram: VRAM 작업: getBlock, readByte, writeByte, searchBytes.

• debug_breakpoints: 중단점 관리: create, remove, list.

자동화 도구

• emu_keyboard: 에뮬레이터에 텍스트 또는 키 조합 전송: sendText, sendKeyCombo.

• emu_savestates: 머신 상태 저장 및 복원: load, save, list.

• screen_shot: 에뮬레이터 화면 캡처: as_image, to_file.

• screen_dump: 화면 데이터를 BASIC BSAVE 명령으로 내보내기.

• msxdocs_resource_get: MCP 리소스를 지원하지 않는 MCP 클라이언트를 위한 MCP 리소스 검색.

문서화 도구

• vector_db_query: 벡터 DB 리소스를 쿼리하여 MSX 시스템, 카트리지 및 기타 개발 리소스에 대한 정보 획득.

• msxdocs_resource_get: MCP 리소스를 지원하지 않는 MCP 클라이언트를 위한 MCP 리소스 검색.

사용 가능한 MCP 리소스

MCP 리소스란 무엇인가요?

MCP 리소스는 MCP 서버의 기능을 확장하는 구조화된 데이터 세트, 문서 및 도우미 파일입니다. 머신 정의, 확장 목록, 미디어 템플릿 및 프로그래밍 예제와 같은 필수 정보를 제공하여 MCP-openMSX 환경 내에서 MSX 소프트웨어에 대한 더 강력한 자동화, 테스트 및 개발 워크플로우를 가능하게 합니다.

사용 가능한 리소스

60개 이상의 리소스를 사용할 수 있으며, 일부는 MCP에 직접 포함되어 있고 다른 일부는 쿼리 시 다운로드를 통해 액세스할 수 있습니다. 다음 범주로 구성되어 있습니다:

• Processors (Z80, R800)

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

• System

• Audio

• Video

• Programming (ASM, BASIC, ...)

• MSX-DOS

• MSX-UNAPI

• MSX BASIC

및 도서와 매뉴얼:

• MSX2 Technical Handbook

• The MSX Red Book

• SDCC Compiler

리소스 출처:

• 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

다양한 라이선스 하에 리소스를 제공해 주신 저자분들께 감사드립니다. 이 MCP 서버는 개발 경험을 향상시키기 위해 이러한 리소스 중 일부를 포함하고 있습니다.

빠른 시작

사전 컴파일된 NPM 패키지를 사용하여 이 MCP 서버를 기본 방식으로 사용할 수 있습니다.

VSCode를 이용한 빠른 설치

VSCode에 MCP 서버를 설치하는 단계:

1. Github Copilot 확장 설치

2. nodejs 설치 (npx 명령이 PATH에 있어야 함).

3. MCP 서버 설치:

   • 위의 Install MCP Server 버튼을 사용하여 VSCode 설정에 MCP 서버를 설치합니다.

   • 또는 작업 공간 폴더에 아래 JSON 구성으로 .vscode/mcp.json 파일을 추가합니다.

STDIO 모드 (권장)

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

스트리밍 HTTP 모드 (더 고급)

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

Claude Desktop을 이용한 기본 설치

Claude의 claude_desktop_config.json 파일에 액세스하려면 이 지침을 따르십시오.

다음 JSON 항목을 포함하도록 편집하십시오:

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

환경 변수

고급 수동 사용법

MCP 서버는 Linux, macOS 및 Windows에서 실행됩니다. 소스에서 빌드하려면 Node.js >= 18 및 TypeScript가 필요합니다.

수동 설치

npm install -g @nataliapc/mcp-openmsx

환경 변수 수동 설정

서버를 사용자 정의하려면 선택적 환경 변수를 설정하십시오:

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"

MCP 서버로 (stdio)

mcp-openmsx

HTTP 서버로

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

개발

빌드 전제 조건

• Node.js >= 18.0.0

• TypeScript

• openMSX 에뮬레이터 설치됨

빌드

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

개발 환경에서 실행

npm run dev

라이선스

GPL2 라이선스 - 자세한 내용은 LICENSE 파일을 참조하십시오.

지원

도움이 필요하거나 질문 또는 제안 사항이 있으면 GitHub Issues 페이지에서 이슈를 열거나 프로젝트 토론을 확인하십시오.

기여

기여를 환영합니다! 자유롭게 Pull Request를 제출해 주십시오.

더 많은 별점!

이 프로젝트가 마음에 드시면 GitHub에서 별점을 주십시오.

별점 기록