BurningTimesAi/프로젝트/수상한잡화점/시뮬레이터/04_MCP_호출_스니펫_v1.md

---
type: 설계문서
project: 수상한잡화점
subject: Unity MCP 호출 스니펫 — 기획팀장용 복붙 템플릿
version: v1
date: 2026-04-17
status: 초판
author: 개발팀장
target_users: 기획팀장, /balance, /level 에이전트
---

# Unity MCP 호출 스니펫 v1

## 1. 사용 전제

1. **Unity Editor 기동 중** (`D:/BurningTimes/FilGoodBandits/DeckBuilding` 프로젝트 열림)
2. **Unity MCP 연결 상태** (`mcp__unity-mcp__*` 도구 사용 가능)
3. **독립 시뮬 어셈블리 컴파일 완료** (`Assets/Sim/BurningTimes.Sim.asmdef`)
4. **시나리오 JSON 파일 준비** (스키마: `02_시나리오_JSON_스키마_v1.md`)

검증 방법:
```
mcp__unity-mcp__execute_code (code: "UnityEngine.Debug.Log(\"MCP OK\");")
```

## 2. 3종 템플릿

### 2-1. 단일 실행 스니펫

**용도**: 시나리오 1건 즉시 실행하여 결과 확인.

**복붙용 프롬프트** (기획팀장이 Claude/PM에게 전달):
```
Unity MCP로 아래 시나리오 1건 실행해주세요:
- 시나리오 파일: {경로 예: D:/BurningTimes/FilGoodBandits/DeckBuilding/Assets/Sim/Scenarios/anchor_stage1.json}
- 출력 모드: stdout
- 결과 요지 요청: pc_survived, pc_remaining_hp_ratio, total_turns, defence_active_ratio
```

**MCP 도구 호출** (실행자가 실제 수행):
```csharp
mcp__unity-mcp__execute_code
  code: """
  using BurningTimes.Sim;
  var runner = new SimulationRunner();
  var result = runner.Run("Assets/Sim/Scenarios/anchor_stage1.json");
  UnityEngine.Debug.Log(UnityEngine.JsonUtility.ToJson(result, true));
  """
```

**기대 결과**: Unity Console에 결과 JSON 출력 (§03 포맷 v1 준수). `read_console` 로 회수 가능.

### 2-2. 파라미터 스윕 스니펫

**용도**: 한 축 또는 여러 축 값들을 그리드 형태로 N회 반복 실행, 통계 집계.

**복붙용 프롬프트**:
```
Unity MCP로 파라미터 스윕을 실행해주세요:
- 베이스 시나리오: {경로}
- 스윕 축:
  - PCDefence_Mul: [0.2, 0.3, 0.4, 0.5]
  - monsters[0].attack_dmg: [3, 5, 7]
- 모드: cartesian
- 셀당 반복: 10회
- 결과 집계 요지 요청: 각 셀의 pc_survived_ratio + pc_remaining_hp_mean
```

**MCP 도구 호출**:
```csharp
mcp__unity-mcp__execute_code
  code: """
  using BurningTimes.Sim;
  var runner = new SimulationRunner();
  var sweep = runner.RunSweep("Assets/Sim/Scenarios/sweep_defence_mul.json");
  UnityEngine.Debug.Log(UnityEngine.JsonUtility.ToJson(sweep, true));
  """
```

**결과 해석 예시**:
```
cells[0] (Mul=0.2, dmg=3): survived=1.0, HP_mean=62.3
cells[1] (Mul=0.2, dmg=5): survived=1.0, HP_mean=34.8
cells[2] (Mul=0.2, dmg=7): survived=0.6, HP_mean=12.1
... (총 4 × 3 = 12 cells)
```

### 2-3. 배치 비교 스니펫

**용도**: 서로 다른 시나리오·전략 N개를 한 번에 실행하여 결과 비교.

**복붙용 프롬프트**:
```
Unity MCP로 전략 비교 배치 실행 해주세요:
- 배치 파일: {경로}
- 포함 시나리오: strategy_never, strategy_always, strategy_touch_hold
- 랭킹 기준: pc_remaining_hp_ratio
- 결과 요지 요청: 전략별 ranking + deltas
```

**MCP 도구 호출**:
```csharp
mcp__unity-mcp__execute_code
  code: """
  using BurningTimes.Sim;
  var runner = new SimulationRunner();
  var batch = runner.RunBatch("Assets/Sim/Scenarios/strategies_compare.json");
  UnityEngine.Debug.Log(UnityEngine.JsonUtility.ToJson(batch, true));
  """
```

## 3. 파일 기반 결과 회수 (출력 모드 `file`)

시나리오 입력에 `"output_mode": "file"` 또는 호출 시 지정:

```csharp
mcp__unity-mcp__execute_code
  code: """
  using BurningTimes.Sim;
  var runner = new SimulationRunner();
  var result = runner.Run("Assets/Sim/Scenarios/anchor_stage1.json");
  ResultEmitter.EmitFile(result, "Assets/Sim/Output/anchor_stage1_result.json");
  UnityEngine.Debug.Log("saved");
  """
```

이후 Read 도구로 파일 내용 조회:
```
Read: D:/BurningTimes/FilGoodBandits/DeckBuilding/Assets/Sim/Output/anchor_stage1_result.json
```

## 4. 프로젝트 외부 저장 (기획팀 `.cache/` 등)

시뮬 결과를 Unity 외부 기획 워크스페이스에 직접 저장:

```csharp
mcp__unity-mcp__execute_code
  code: """
  using BurningTimes.Sim;
  var runner = new SimulationRunner();
  var result = runner.Run("Assets/Sim/Scenarios/anchor_stage1.json");
  ResultEmitter.EmitFile(result, @"D:/BurningTimes/BurningTimesAi/기획팀/.cache/sim_results/anchor_stage1.json");
  """
```

## 5. 에러 진단 체크리스트

### 5-1. MCP 연결 실패
- Unity Editor 상태 확인 (`manage_editor` 호출)
- MCP 서버 재시작 (Claude Code 재연결)
- Transport 모드 `stdio:6400` 확인 (교훈: 2026-04-14 Transport HTTP Local 불일치)

### 5-2. 컴파일 에러
- `Assets/Sim/*.cs` 변경 후 `refresh_unity` 호출하여 재컴파일
- Editor Console 스캔: `read_console`

### 5-3. 시나리오 파싱 실패
- 스키마 버전 확인 (`schema_version: "1.0"`)
- JSON 유효성 검사 (외부 툴 또는 `JsonUtility.FromJson` try/catch 확인)
- `ScenarioValidationException` 메시지 참조

### 5-4. 결과가 이상 (비현실적 값)
- `seed` 고정 여부 (`deterministic` 모드인지 확인)
- `global_value` 기본값 오버라이드 확인
- 상세 로그 활성화(`record_detail: true`)로 tick 추적

## 6. 실행 흐름 예시 (전체 파이프라인)

```
1. 기획팀장: 시나리오 JSON 작성
   ↓
2. PM 또는 기획팀장: Claude Code에서 본 문서 §2-1 프롬프트 전달
   ↓
3. Claude: mcp__unity-mcp__execute_code 호출
   ↓
4. Unity Editor: SimulationRunner.Run() 실행
   ↓
5. Claude: read_console 로 결과 JSON 회수
   ↓
6. 기획팀장: 결과 JSON 분석·밸런스 튜닝
   ↓
7. (반복) 시나리오·스윕 조정하여 다시 §2
```

## 7. 변경 이력
- **v1 (2026-04-17)**: 초판. MCP 연결 미확인 상태에서 작성 — 실제 실행 검증은 Unity Editor 기동 + MCP 연결 시점에 수행 (C23 정직).

## 8. 기각안
- **기각안 A**: Unity Editor 외부에서 .NET 직접 실행 → Unity 테이블 의존성·Addressable 로드 등 환경 재현 비용 과도. Editor 내 실행이 최선
- **기각안 B**: PlayMode 강제 전환 후 시뮬 → 시뮬 독립성 저해·프레임 락·기존 InGame 로직 간섭. EditMode + 독립 Runner가 깔끔
- **기각안 C**: Headless 모드 배치 빌드 실행 → 빌드·CI 파이프라인 복잡. MCP `execute_code` 즉시 실행이 기획팀 피드백 루프 최적