# 🍯 HoneyMCP — 얼불춤(ADOFAI) 고퀄리티 맵 자동생성 MCP

> **"맵 만들어줘" 한마디면 유튜브급 커스텀 맵이 나옵니다.**
> A Model Context Protocol server that generates human-quality
> *A Dance of Fire and Ice* custom levels from any song.
> 노래를 주면 실제 음표에 맞춘 타일길 + 매직서클 + 카메라/조명 이펙트까지 자동으로 뽑아줍니다.

![python](https://img.shields.io/badge/python-3.10%2B-blue) ![mcp](https://img.shields.io/badge/MCP-stdio-green) ![tests](https://img.shields.io/badge/tests-11_passing-brightgreen)

## ✨ 핵심 기술 (왜 노잼이 아닌가)

| 기술 | 설명 |
|---|---|
| 🎹 **실제 음표 싱크** | ffmpeg + spectral flux로 노래의 온셋(음표) 수백 개를 2초 만에 추출. 타일을 진짜 음표 위에 배치 (싱크율 ~90%) |
| 🧲 **SetSpeed 박자 고정** | 공식 에디터 가이드의 매직쉐이프 정석. 도형은 자유롭게, 박자는 타일마다 BPM 보정으로 고정 |
| 🗺️ **겹침 제로 배치** | 전 타일 좌표 시뮬레이션 + DFS 백트래킹. 뭉개진 덩어리 원천 차단 |
| 🐇🐢 **속도비율 제한** | 타일 속도비를 기준의 0.45~2.6배로 강제. 빠름/느림 표식(토끼/거북이) 도배 + 불가능 구간 원천 차단. 빠른 음표=직선 스트림, 느린 음표=큰 도형 (고수 원칙) |
| 🌀 **프레이즈 모티프** | 8타일마다 물결→지그재그→아크→나선 순환 + 구간마다 방향 전환. 평행 고속도로 방지 |
| 🛡️ **품질 게이트** | 점수제 검증(errors/warnings). 불합격이면 시드 바꿔 최대 6회 자동 재생성 후 최고본만 저장 |
| 👆 **2/3/4키 동시치기** | 공식 가이드 multi-press 정석(0.01° 히든 미드스핀). ★5부터 코러스에 2키 자동, 수동 추가도 가능 |

## 📋 요구사항

- Python 3.10+
- **ffmpeg** (음표 추출용. 없으면 기계 그리드 폴백으로 동작)
  - Windows: `winget install ffmpeg` (또는 [ffmpeg.org](https://ffmpeg.org/download.html))
- 얼불춤 본편 (결과물 확인용. 생성 자체는 게임 없이 됨)

## 🚀 설치

```powershell
git clone https://github.com/dohunkr/HoneyMCP.git
cd HoneyMCP
pip install -e ".[dev]"
```

## 🔌 MCP 연결법 (클라이언트별)

서버 실행 명령(공통): `python -m honey_mcp.server` (stdio 방식)

> ⚠️ 설정 후 **클라이언트를 완전히 종료→재시작**해야 반영됩니다.

### opencode (`opencode.json` — 프로젝트 루트)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "honey-adofai": {
      "type": "local",
      "command": ["C:/Python310/python.exe", "-m", "honey_mcp.server"],
      "enabled": true
    }
  }
}
```
`command`의 python 경로는 본인 환경에 맞게 수정. `.venv` 사용 시 `.venv/Scripts/python.exe` 절대경로 권장.
`opencode.json.example` 참고. 연결 확인: 툴 목록에 `honey-adofai`가 보이면 OK.

### Claude Code (`.mcp.json` — 프로젝트 루트)

```json
{
  "mcpServers": {
    "honey-adofai": {
      "command": "python",
      "args": ["-m", "honey_mcp.server"],
      "cwd": "D:/Github/ADOFAI/HoneyMCP"
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "honey-adofai": {
      "command": "python",
      "args": ["-m", "honey_mcp.server"],
      "cwd": "D:/Github/ADOFAI/HoneyMCP"
    }
  }
}
```

### Antigravity / Codex

MCP 설정에 stdio 서버로 등록 (위와 동일):
command `python`, args `["-m", "honey_mcp.server"]`, cwd = 이 폴더.

## 🎮 사용법

채팅에 노래 파일 경로만 주면 됩니다:

```
D:\Music\track.ogg 로 맵 만들어줘 (★5, 화려하게)
```

AI는 자동으로 `analyze_song → generate_full_map → 품질게이트`를 수행합니다.
출력: `D:/Github/ADOFAI/HoneyMap_<곡명>/` 안에 `.adofai` + 노래 복사본 →
**얼불춤 레벨 에디터로 폴더를 열어서 F5 테스트플레이.**

MCP 없이 직접 생성도 가능:

```powershell
python tools/make_map.py --audio "C:/Music/song.ogg" --outdir "D:/Github/ADOFAI/HoneyMap_song" `
    --title "Song" --artist "Artist" --difficulty 5 --style showcase --seed 7
```

- `difficulty`: 1~10 (★5-6 권장. ★5부터 2키 동시치기, ★7부터 6개, ★9부터 3키)
- `style`: `showcase`(화려) / `clean`(깔끔) / `party`

## 🧰 MCP 도구

| 도구 | 설명 |
|---|---|
| `analyze_song(audio_path)` | BPM/오프셋/음표/구간 분석 (~2초) |
| `generate_full_map(audio_path, output_dir, title, artist, difficulty, style, seed)` | 원샷 풀맵 생성 + 품질게이트 + 자동재시도 |
| `validate_level_tool(level_path)` | 점수/에러/경고 리포트 |
| `adjust_effects(level_path, style, zoom, enable_flash)` | 타일 유지 + 이펙트만 교체 |
| `add_multipress(level_path, floor, keys)` | 2/3/4키 동시치기 수동 추가 |
| `list_patterns()` | 패턴 사전 |
| 프롬프트 `make_map` / 리소스 `adofai://spec` | AI 작업手順 + 스펙 요약 |

## 🛡️ 품질 게이트 (재발방지)

`errors` (하나라도 있으면 자동 재생성):
- 게임 enum 위반 (`Forward` 등 — 과거 로딩 크래시 원인)
- SetSpeed가 기준의 0.35~3배 초과 (불가능 구간)
- floor 범위 초과 / 타일 부족 / BPM 범위 이탈

`warnings` (점수 감점):
- 직선 7연속 고속도로 / 좌우회전 편중 / 타일 겹침 / 음표 싱크율 60% 미만

## 🗺️ 맵 출력 규칙

- 모든 맵은 `D:/Github/ADOFAI/HoneyMap_<곡명>/` 에 생성 (프로젝트 폴더와 분리)
- 예시: 도라에몽 피아노 커버 → 타일 210개, score 100, 싱크율 90%, 2키×3

## 🧪 개발

```powershell
pytest -q
```

구조: `src/honey_mcp/` — `server.py`(MCP) / `audio.py` / `onsets.py`(음표추출) /
`chart.py`(채보+배치) / `effects.py`(이펙트) / `adofai.py`(파일IO+검증+멀티프레스)

## ❓ 트러블슈팅

| 증상 | 원인/해결 |
|---|---|
| `Requested value 'Forward' was not found` | 구버전 산출물. 최신 버전으로 재생성 (게이트에서 원천 차단됨) |
| 타일에 토끼/거북이 도배 | 구버전 속도 폭주. v6+ 속도비율 제한으로 해결 |
| MCP가 노래 분석에서 멈춤 | 구 librosa 경로 문제. 현재 ffmpeg 기반으로 2초 내외 (ffmpeg 설치 확인) |
| 한글 출력 깨짐 (cp949) | `$env:PYTHONUTF8="1"` 설정 |
| MCP가 안 보임 | 클라이언트 재시작 확인 + python 절대경로 확인 |

## 📄 라이선스

MIT — 자유롭게 쓰고 고치고 공유하세요. 맵을 만들 때 사용한 노래의 저작권은 각 권리자에게 있습니다.