# HotSpot MCP

Claude LLM과 HotSpot 대기확산 시뮬레이션 코드 연동을 위한 MCP(Model Context Protocol) 서버

## 개요

HotSpot은 미국 DOE NARAC/LLNL에서 개발한 대기확산 시뮬레이션 소프트웨어입니다. 이 프로젝트는 Claude LLM에서 자연어로 시뮬레이션을 요청하면 HotSpot을 자동으로 실행하고 결과를 반환하는 MCP 서버를 제공합니다.

## 주요 기능

- **run_hotspot_simulation**: 대기확산 시뮬레이션 실행
- **get_available_radionuclides**: 사용 가능한 방사성 핵종 목록 조회
- **parse_hotspot_output**: 시뮬레이션 결과 파싱
- **get_hotspot_status**: 서버 상태 확인

## 지원 모델

| 모델 | 설명 |
|------|------|
| tritium_release | 삼중수소 방출 |
| plutonium_explosion | 플루토늄 폭발 |
| plutonium_fire | 플루토늄 화재 |
| uranium_explosion | 우라늄 폭발 |
| general_plume | 일반 플룸 |
| nuclear_explosion | 핵폭발 |

## 설치

```bash
# 가상환경 생성
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r requirements.txt
```

## 프로젝트 구조

```
hotspotMCP/
├── src/
│   ├── server.py           # MCP 서버 메인
│   ├── hot_generator.py    # .hot 파일 생성
│   ├── hotspot_runner.py   # HotSpot 실행 (Mock 모드 포함)
│   ├── output_parser.py    # 결과 파싱
│   ├── exceptions.py       # 커스텀 예외
│   ├── logger.py           # 로깅 설정
│   └── models/
│       └── schemas.py      # Pydantic 데이터 모델
├── tests/
│   └── test_integration.py # 통합 테스트
├── docs/
│   ├── PRD_v2.md           # 제품 요구사항 문서
│   ├── TASKS.md            # 작업 계획서
│   └── HOTSPOT_ANALYSIS.md # HotSpot 기술 분석
├── requirements.txt
└── README.md
```

## 사용법

### Mock 모드 테스트 (macOS)

```bash
# 통합 테스트 실행
python tests/test_integration.py
```

### MCP 서버 실행

```bash
# 서버 실행
python -m src.server
```

### Claude Desktop 연동 (예정)

`claude_desktop_config.json`에 추가:
```json
{
  "mcpServers": {
    "hotspot": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/hotspotMCP"
    }
  }
}
```

## 상태

| Phase | 상태 | 진행률 |
|-------|------|--------|
| Phase 1: 환경 구축 및 HotSpot 분석 | ✅ 완료 | 100% |
| Phase 2: MCP 서버 기본 구조 구현 | ✅ 완료 | 100% |
| Phase 3: 핵심 기능 개발 | ✅ 완료 | 100% |
| Phase 4: 테스트 및 검증 | ✅ 완료 | 100% |

## Mock 모드

HotSpot은 Windows 전용 프로그램입니다. macOS/Linux에서 개발 및 테스트할 수 있도록 Mock 모드를 제공합니다.

- Mock 모드: 샘플 결과 반환 (실제 HotSpot 실행 없이)
- 실제 모드: Windows에서 HotSpot 설치 후 실행

## 참고 자료

- [HotSpot 공식 사이트](https://narac.llnl.gov/hotspot)
- [MCP 사양](https://spec.modelcontextprotocol.io)
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)

## 라이선스

이 프로젝트는 연구 및 교육 목적으로 개발되었습니다.