sc-bwapi-mcp

MCP(Model Context Protocol)를 통해 AI 어시스턴트(예: Trae/Claude)가 스타크래프트 1의 BWAPI 브리지를 조작할 수 있게 합니다.

아키텍처

星际1 (1.16.1) ← BWAPI 4.4.0 注入 (Chaoslauncher)
      ↕ 共享内存 + 命名管道
bwapi_bridge.exe (C++, TCP 12345)
      ↕ JSON over TCP
sc-bwapi-mcp (Python MCP server)
      ↕ MCP stdio
Trae / Claude / 任意 MCP 客户端

Related MCP server: defcon-mcp-server

사전 요구 사항

설치 단계

1. 스타크래프트 1 + BWAPI 설치

1. Battle.net 클라이언트에서 StarCraft Anthology(무료)를 다운로드하고, 공백 없는 경로(예: C:\Games\Starcraft)에 설치합니다.

2. BWAPI 4.4.0을 다운로드하고, 공백 없는 경로(예: C:\libraries\BWAPI_440)에 설치합니다.

3. 환경 변수 BWAPI_DIR = C:\libraries\BWAPI_440로 설정합니다.

4. BWAPI 설치 폴더의 StarCraft\와 Windows\ 내용을 스타크래프트 폴더로 복사합니다.

2. BWAPI 라이브러리 컴파일(최초 필수)

BWAPI 4.4.0의 .lib 파일은 VS2022로 컴파일해야 생성됩니다:

$msbuild = "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
$env:BWAPI_DIR = "C:\libraries\BWAPI_440"

# 编译 BWAPILIB + BWAPIClient (Release x86)
& $msbuild "$env:BWAPI_DIR\BWAPILIB\BWAPILIB.vcxproj" /p:Configuration=Release /p:Platform=Win32 /m
& $msbuild "$env:BWAPI_DIR\BWAPIClient\BWAPIClient.vcxproj" /p:Configuration=Release /p:Platform=Win32 /m

# 编译 ExampleAIModule.dll (BWAPI 4.4.0 需要一个 AI 模块才能触发 onStart)
& $msbuild "$env:BWAPI_DIR\ExampleAIModule\ExampleAIModule.vcxproj" /p:Configuration=Release /p:Platform=Win32 /p:OutDir="<星际目录>\bwapi-data\AI\" /m

3. bridge 컴파일

cd <项目目录>
scripts\build_bridge.bat

출력: cpp\build\Release\bwapi_bridge.exe

4. bwapi.ini 설정

스타크래프트 폴더의 bwapi-data\bwapi.ini에서 다음을 확인하세요:

[ai]
ai = bwapi-data/AI/ExampleAIModule.dll
[auto_menu]
auto_menu = OFF

사용 방법

시작 순서(중요!)

1. 관리자 권한으로 Chaoslauncher 실행 → "BWAPI Injector 4.4.0 [RELEASE]" 체크 → 아직 Start를 클릭하지 마세요

2. bridge 실행: scripts\run_bridge.bat 실행 (BWAPI 서버를 기다립니다)

3. Chaoslauncher에서 Start 클릭 → 스타크래프트 진입 → Single Player → Expansion → Play Custom → 맵 선택 → 시작

4. 게임 화면에 진입하면 bridge가 자동으로 연결되고 상태를 전송합니다.

MCP 클라이언트 설정

Trae의 MCP 설정에 다음을 추가합니다:

{
  "mcpServers": {
    "sc-bwapi": {
      "command": "C:\\Users\\<你>\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "<项目路径>", "sc-bwapi-mcp"]
    }
  }
}

Trae를 재시작하면 도구를 호출할 수 있습니다.

MCP 도구

문제 해결

• bridge가 "Game table mapping not found"에서 멈춰 있음: 스타크래프트가 시작되지 않은 경우, 정상적으로 대기합니다.

• bridge가 파이프에 연결되지 못함: 게임을 종료하고 다시 들어가세요(이전에 bridge가 강제 종료되어 BWAPI의 connected 플래그가 멈춰 있음)

• build 실패: bridge가 getBuildLocation으로 위치를 자동으로 찾습니다. creep 범위 내에 빈 이 있는지 확입하세요.

• 0 FPS: 컴퓨터 사양이 부족함. 1v1로 바꾸고 게임에서 F5를 눌러 속도를 낮추세요.