# 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 客户端
```

## 前置依赖

| 组件 | 版本 | 说明 |
|---|---|---|
| StarCraft | 1.16.1 | 普通版(非重制版),Battle.net 客户端免费下载 Anthology |
| BWAPI | 4.4.0 | https://github.com/bwapi/bwapi/releases/tag/v4.4.0 |
| Visual Studio | 2022 Community | 安装时勾"使用 C++ 的桌面开发" |
| uv | 0.12+ | Python 包管理器 https://astral.sh/uv |
| Chaoslauncher | (BWAPI 自带) | 注入 BWAPI.dll 到星际进程 |

## 安装步骤

### 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 编译生成:

```powershell
$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

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

输出: `cpp\build\Release\bwapi_bridge.exe`

### 4. 配置 bwapi.ini

星际目录下 `bwapi-data\bwapi.ini` 确保:

```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 配置加:

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

重启 Trae,即可调用工具。

## MCP 工具

| 工具 | 参数 | 作用 |
|---|---|---|
| `get_game_state` | 无 | 读取游戏状态(矿/气/供给/所有单位) |
| `train` | `unit_type` | 训练单位(如 `Zerg_Drone`) |
| `build` | `worker_id`, `building_type`, `tile_x`, `tile_y` | 建造建筑(自动找可建造位置) |
| `move` | `unit_id`, `x`, `y` | 移动单位到像素坐标 |
| `attack` | `unit_id`, `target_id` | 攻击目标单位 |
| `gather` | `worker_id`, `resource_id` | 采集矿物/气体 |
| `stop` | `unit_id` | 停止当前动作 |
| `hold` | `unit_id` | 原地待命 |
| `chat` | `text` | 在游戏里发消息 |

## 故障排查

- **bridge 卡在 "Game table mapping not found"**: 星际没启动,正常等待
- **bridge 连不上管道**: 退出游戏重进(之前 bridge 被强杀,BWAPI 的 connected 标志卡住)
- **build 失败**: bridge 用 `getBuildLocation` 自动找位置,确保 creep 范围内有空地
- **0 FPS**: 电脑配置不够,改 1v1 + 游戏里按 F5 降速