# 놀이터 MCP — K-콘텐츠 미니게임 파티팩

Kakao PlayMCP **Agentic Player 10** 공모전 출품작. AI 에이전트가 게임 진행자(MC)가 되어
혼자서도, 친구들과도 즐기는 미니게임 MCP 서버입니다. 상세 기획은 [plan.md](plan.md) 참고.

## 게임 5종

| game_type | 게임 | 핵심 |
|---|---|---|
| `quote` | 🎬 그 대사 뭐였지 | 명대사로 영화/드라마 맞추기. 오답마다 힌트 공개(연도→장르→주연→초성), 힌트 적게 쓸수록 고득점 |
| `word_relay` | 🔤 단어 이어 말하기 | 정해진 글자 수의 한글 단어를 번갈아 말하며 문장을 이어가고, **문장을 끝내는 사람이 패배**. 1인 플레이는 **AI가 상대 플레이어로 참전** |
| `actor` | 🎭 배우 릴레이 | 공개된 배우들이 모두 출연한 작품 맞추기. **오답이 힌트가 되는** 역추리 시그니처 게임 |
| `balance` | ⚖️ 너 뭐 골라 | 밸런스 게임 + 전체 이용자 통계 비교(다수파/소수파). 멀티 시 상대 선택 예측 모드 |
| `daily` | 📅 데일리 챌린지 | 매일 바뀌는 공통 문제 3라운드(명대사·배우·밸런스), 하루 1회 기록, 공유 카드 |

기본은 **1인 플레이**, `players` 목록을 넘기면 핫시트 멀티(자유 버저)로 동작합니다.
단어 이어 말하기만 예외로 턴제이며, 혼자 시작하면 AI(진행자)가 자동으로 상대 플레이어가 됩니다.

> 기존 "노래 재해석 퀴즈"는 2026-07-13에 제거하고 단어 이어 말하기로 교체했습니다 —
> 가사 원문의 합법적 데이터 소스가 사실상 없다는 조사 결과에 따른 결정 (plan.md 2.2).

## 실행

```bash
pip install -r requirements.txt
python server.py                    # streamable HTTP — 0.0.0.0:8000/mcp
python server.py --transport stdio  # 로컬 에이전트 테스트용
PORT=8080 python server.py          # 환경변수로 포트 지정
```

테스트:

```bash
python test_game.py                        # 엔진 단위 테스트
python server.py --port 8124 &             # E2E: 서버 띄운 뒤
python test_server_http.py                 # streamable HTTP 클라이언트로 검증
```

## MCP 도구 (12종)

`list_games`, `start_game`, `get_question`, `submit_answer`, `get_hint`,
`skip_or_reveal`, `get_scoreboard`, `end_game`, `submit_balance_choice`,
`submit_word`, `declare_sentence_end`, `get_daily_challenge`

단어 이어 말하기는 `submit_word`가 글자 수·한글·중복·차례를 결정론적으로 검증하고
한국어 종결어미를 자동 감지해 패배를 판정합니다. 휴리스틱이 놓친 문장 완성은
`declare_sentence_end`로 보완 판정합니다 (서버=심판, LLM=상대 플레이어 역할 분리).

핵심 설계 원칙 (plan.md 5.2): **정답은 어떤 도구 응답에도 포함되지 않습니다.**
판정은 서버만 수행하며, 정답 공개는 정답을 맞혔을 때와 `skip_or_reveal` 호출 시에만 일어납니다.
LLM이 스포일러를 낼 수 없는 구조가 "왜 MCP여야 하는가"에 대한 답입니다.

## 데이터 수집 정책 (중요)

모든 문제 은행은 `data/*.json` 시드 파일이며, 각 파일의 `_meta`에 출처를 명기했습니다.

| 파일 | 문항 | 수집 방식 |
|---|---|---|
| `quotes.json` | 41 | 대중적으로 널리 알려진 명대사의 **짧은 인용(1~2문장)** 자체 큐레이션 |
| `works.json` | 50 | 작품-출연진(주연급, 특별출연 제외) 자체 큐레이션. 본선 때 TMDB API로 검증·확장 예정 |
| `balance.json` | 60 | 전량 자체 창작 (저작권 free) |

단어 이어 말하기는 문제 은행이 필요 없는 게임입니다 — 서버에 내장된 한국어 종결어미
패턴 사전만 사용하므로 데이터·저작권 리스크가 없습니다.

⚠️ 모든 시드 데이터는 LLM 초안 기반이므로 **출품 전 사람 검수 필수**입니다.
특히 `works.json` 출연진 오류는 배우 릴레이 오판정으로 직결됩니다 (plan.md 10장 리스크).

## 저장소 구조

```
server.py            MCP 서버 (FastMCP, 도구 12종 + 진행자 지침)
game/engine.py       게임 엔진 (세션·라운드·점수·단어 릴레이·데일리 챌린지)
game/judge.py        정답 판정 (정규화·별칭·유사도·초성)
game/stats.py        SQLite 영속 통계 (밸런스 집계·데일리 기록)
data/*.json          문제 은행 시드 (151문항)
data/stats.db        런타임 생성 (통계 DB)
test_game.py         엔진 단위 테스트
test_server_http.py  E2E 스모크 테스트
```

## 카카오클라우드 배포 (공모전 필수 요건)

1. 카카오클라우드 VM(Ubuntu) 생성 → 보안그룹에서 서비스 포트 개방
2. `pip install -r requirements.txt` 후 `python server.py --port 8000`
   (운영 시 systemd 서비스 또는 Docker로 상시 구동 권장)
3. HTTPS 리버스 프록시(nginx + Let's Encrypt) 뒤에 `/mcp` 엔드포인트 노출
4. PlayMCP에 엔드포인트 등록 → **전체 공개** 설정 (공모전 출품 인정 조건)

세부 스펙(인증 방식 등)은 공모전 노션 가이드 확인 후 확정 — plan.md 9장 참고.