MCP 服务器

Playground MCP

MCP server for Korean content mini-games, enabling AI agents to host and participate in quote guessing, word relay, actor relay, balance games, and daily challenges.

README

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

Kakao PlayMCP Agentic Player 10 공모전 출품작. AI 에이전트가 게임 진행자(MC)가 되어 혼자서도, 친구들과도 즐기는 미니게임 MCP 서버입니다. 상세 기획은 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).

실행

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          # 환경변수로 포트 지정

테스트:

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 스모크 테스트

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

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

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