MCP를 통한 DOOM

DOOM을 실행할 수 있나요? 네 - 여러분의 AI 코딩 어시스턴트가 DOOM을 실행할 수 있습니다.

Claude Code, Cursor 또는 MCP 호환 클라이언트에서 DOOM을 플레이하세요. AI가 게임을 보고, 악마와 싸우고, 레벨을 탐험하며, 상황을 보고합니다 - 또는 여러분이 한 동작씩 지시할 수도 있습니다.

> Let's play DOOM!

  Starting E1M1 on medium difficulty...

  HP:100 Armor:0 | Pistol (key:2) | Ammo: 50b 0s 0r 0c | Kills:0 | E1M1
  No enemies in sight. Exploring the corridor ahead.

> Go forward and find some enemies

  Sprinting down the hallway... I can see an opening ahead.

  HP:100 Armor:0 | Pistol (key:2) | Ammo: 50b 0s 0r 0c | Kills:0 | E1M1
  ENEMIES IN SIGHT (aim for angle~0 then fire): Imp (HP:60) to your left (turn_left ~9) nearby

  There's an Imp to the left! Turning to face it...

> Shoot it!

  Aimed and firing!

  HP:100 Armor:0 | Pistol (key:2) | Ammo: 47b 0s 0r 0c | Kills:0 | E1M1
  ENEMIES IN SIGHT (aim for angle~0 then fire): Imp (HP:15) AHEAD close

  Hit! The Imp is wounded (HP:15). One more burst should finish it.

  HP:95 Armor:0 | Pistol (key:2) | Ammo: 44b 0s 0r 0c | Kills:1 | E1M1
  ITEMS: Stimpack (+10 HP) slightly to your right (turn_right ~4) point-blank (~3 ticks fwd+run to reach)
  1 kill! Want to see a screenshot?

전체 스토리는 블로그 게시물에서 읽어보세요.

목차

• 작동 방식

• 빠른 시작

• 플레이 모드

• 도구 참조

• 구성

• FAQ

• 아키텍처

• 개발

• 크레딧

• 라이선스

Related MCP server: local-agent-context

작동 방식

Rust MCP 서버가 실제 DOOM 엔진(doomgeneric)을 FFI를 통해 직접 내장합니다. 에뮬레이션도, 하위 프로세스도 없습니다. 각 도구 호출은 게임을 여러 틱만큼 진행시키고 다음을 반환합니다:

1. 게임 상태 - HP, 방어구, 탄약, 킬 수, 위치, 현재 무기

2. 적 정보 - 사람이 읽을 수 있는 방향, 거리, HP가 포함된 보이는 적

3. 근처 아이템 - 획득 범위 내의 체력, 탄약, 방어구, 무기

4. 문과 스위치 - 범위 내에서 감지된 상호작용 가능한 linedef

5. 프레임 이미지 - AI의 시야를 위한 작은 PNG 썸네일

AI는 이 정보를 사용하여 탐색하고, 싸우고, 탐험합니다. 여러분이 지시하거나 AI가 자율적으로 플레이하게 둘 수 있습니다.

graph LR
    A[MCP Client] -->|doom_start| B[doom-mcp binary]
    A -->|doom_action| B
    A -->|doom_screenshot| B
    B -->|FFI| C[doomgeneric C engine]
    C -->|frame buffer| B
    B -->|game state + PNG| A

빠른 시작

1. MCP 클라이언트에 등록

Claude Code:

claude mcp add doom --scope user -- npx -y doom-mcp

Cursor, Windsurf 또는 기타 MCP 클라이언트 - .mcp.json에 추가:

{
  "mcpServers": {
    "doom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doom-mcp"]
    }
  }
}

2. 플레이

새 세션을 열고 말하세요:

"DOOM 플레이하자"

AI가 원하는 모드를 물어보고, E1M1에서 게임을 시작하고, 플레이를 시작합니다.

플레이 모드

도구 참조

doom_start

DOOM을 시작하거나 재시작합니다. 언제든 호출해도 안전합니다 — 이미 게임이 실행 중이면 새 세션 없이 깨끗하게 재시작합니다.

doom_action

게임을 진행합니다. 나열된 모든 동작은 틱 지속 시간 동안 동시에 유지됩니다.

게임플레이 참고:

• fire는 전체 지속 시간 동안 방아쇠를 유지합니다. 권총은 약 10틱마다 자동 발사됩니다.

• 회전과 발사는 별도의 동작이어야 합니다 (회전하면서 발사하면 탄약이 낭비됩니다).

• use는 문을 열고 스위치를 활성화합니다.

• 무기 키: 1=주먹, 2=권총, 3=샷건, 4=체인건, 5=로켓 런처, 6=플라즈마, 7=BFG.

doom_screenshot

전체 해상도 320x200 스크린샷을 시스템 임시 디렉토리에 저장하고 기본 이미지 뷰어로 엽니다. 게임을 진행하지 않습니다 (프레임이 안정화되도록 잠시 멈추는 것 외에는).

구성

번들된 Freedoom WAD는 기본적으로 작동하지만, 원본 DOOM 셰어웨어 WAD가 더 나은 레벨과 스프라이트를 제공합니다. 사용하려면:

1. doomworld.com/classicdoom/info/shareware.php에서 DOOM1.WAD 다운로드 (합법, 무료)

2. MCP 구성에서 DOOM_WAD_PATH 설정:

{
  "mcpServers": {
    "doom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doom-mcp"],
      "env": {
        "DOOM_WAD_PATH": "/path/to/DOOM1.WAD"
      }
    }
  }
}

DOOM 또는 DOOM 2를 소유하고 있다면 해당 WAD도 같은 방식으로 사용할 수 있습니다. 사용자 정의 WAD를 사용하려면:

{
  "mcpServers": {
    "doom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doom-mcp"],
      "env": {
        "DOOM_WAD_PATH": "/path/to/DOOM.WAD"
      }
    }
  }
}

FAQ

Windows에서 작동하나요? 네. npm 패키지에는 Windows x64 바이너리가 포함되어 있습니다. macOS/Linux와 같은 방식으로 등록하세요.

자신의 DOOM WAD(DOOM.WAD, DOOM2.WAD)를 사용할 수 있나요? 네. MCP 구성에서 DOOM_WAD_PATH를 설정하세요. 셰어웨어 DOOM1.WAD는 doomworld.com에서 무료로 다운로드할 수 있으며 번들된 Freedoom보다 훨씬 나은 레벨을 제공합니다. 자세한 내용은 구성 섹션을 참조하세요.

API 토큰 비용은 얼마인가요? 각 doom_action 호출은 약 1-2KB의 텍스트(게임 상태 + 적 정보)와 약 6KB PNG 썸네일을 반환합니다. 동작당 약 1,500-2,500 토큰입니다. 50개 동작의 일반적인 게임플레이 세션은 약 75,000-125,000 토큰을 사용합니다.

AI가 실제로 DOOM을 잘 플레이할 수 있나요? 레벨 탐색, 적 찾기, 조준, 전투가 가능합니다. 보통 난이도의 E1M1에서 세션당 약 5-10킬을 기록합니다. 부분적으로 엄폐된 적과 복잡한 문 시퀀스 탐색에는 어려움을 겪습니다. 여러분이 지시하면 더 나아집니다.

특정 레벨을 플레이할 수 있나요? 네. doom_start에 episode 및 map 매개변수를 전달하세요. 예를 들어, 에피소드 1 맵 3은 episode:1, map:3이 됩니다.

죽으면 어떻게 되나요? 엔진이 HP:0을 보고하고 죽음 화면의 스크린샷을 제공합니다. 현재 세션 내 재시작 기능은 없습니다 - 다시 플레이하려면 새 대화를 시작하세요.

멀티플레이어를 지원하나요? 아직 아닙니다. DOOM의 멀티플레이어 프로토콜은 이론적으로 다중 에이전트 플레이를 지원할 수 있지만 구현되지 않았습니다.

AI가 치트를 쓰나요? 벽을 볼 수 있나요? 아니요. 적 감지는 DOOM의 기본 시야 확인(P_CheckSight)을 사용합니다. AI는 화면에 보이는 적만 볼 수 있습니다. 아이템은 근접성으로 감지되지만 AI는 여전히 그 위를 걸어가서 획득해야 합니다.

아키텍처

src/main.rs         MCP JSON-RPC server over stdio
src/doom.rs         Engine FFI wrapper: init, tick, frame capture, state extraction
src/renderer.rs     PNG rendering (216-color palette thumbnails for MCP, full RGB for screenshots)
src/paths.rs        WAD file discovery across platforms
src/log.rs          Debug logging to file
build.rs            Compiles doomgeneric C sources via cc crate (whitelist approach)
csrc/platform.c     DG_ callbacks, virtual time, key injection, enemy/item/door detection

바이너리는 컴파일 시 doomgeneric C 엔진을 링크합니다. 런타임에는 하위 프로세스를 생성하지 않는 단일 프로세스입니다. 프레임은 공유 화면 버퍼에서 읽고 키 입력은 FFI를 통해 주입됩니다.

가상 시간 - 엔진의 클록은 실제 시간과 분리됩니다. 각 doomgeneric_Tick()은 실제 경과 시간과 관계없이 정확히 하나의 게임 틱(1/35초)을 진행합니다. 이로 인해 게임플레이가 결정적이며 틱이 건너뛰지 않습니다.

적 및 아이템 감지 - 서버는 엔진의 내부 객체 목록(thinker_t 체인)을 반복하여 근처의 적과 획득 가능한 아이템을 찾습니다. 시야 확인은 Doom의 기본 P_CheckSight()를 사용합니다. "월핵" 치트를 방지하기 위해 보이는 적만 보고됩니다.

개발

필요 사항: Rust 툴체인, GCC, Make, Git, curl, unzip.

git clone https://github.com/gunnargrosch/doom-mcp.git
cd doom-mcp
bash scripts/setup.sh      # clones engines, downloads Freedoom WAD
cargo build --release       # compiles everything into a single binary
cargo test                  # runs unit + integration tests

테스트를 위해 로컬 빌드 등록:

claude mcp add doom --scope user -- ./target/release/doom-mcp

디버그 로깅 활성화:

claude mcp add doom --scope user -e DOOM_MCP_DEBUG=1 -- ./target/release/doom-mcp
tail -f /tmp/doom-mcp.log   # Linux/macOS (Windows: %TEMP%\doom-mcp.log)

npm 패키지

npm 패키지를 로컬에서 빌드:

bash scripts/build-npm.sh   # copies binary + WAD into npm/
cd npm && npm pack           # creates doom-mcp-0.1.2.tgz

게시 (npm 계정 + CI용 NPM_TOKEN 필요):

cd npm && npm publish

크레딧

• doomgeneric by ozkl - 휴대용 DOOM 엔진

• Freedoom - 오픈소스 IWAD 파일

• id Software - 원본 DOOM (GPL-2.0)

변경 로그

자세한 변경 사항 목록은 CHANGELOG.md를 참조하세요.

라이선스

이 저장소의 MCP 서버 코드는 MIT 라이선스입니다.

doomgeneric은 GPL-2.0 라이선스이며 빌드 시 복제됩니다(벤더링되지 않음). Freedoom WAD는 BSD 스타일 라이선스로 배포됩니다.