WeatherSafetyOS MCP — 카카오 PlayMCP 제출용

위치·직업·연령 기반 개인 기상안전 도우미 MCP 서버. 기상청 실시간 데이터로 "지금 당신에게" 위험한지와 무엇을 해야 하는지를 알려준다.

별도 트랙: 메인 산출물(../sentinel-demo, 기상청 실증 코어)과 분리된 얇은 MCP 인터페이스. 코어는 건드리지 않고 배포된 공개 Worker API만 호출한다. 기상청/재난안전 API 키는 코어 Worker만 보유 — 이 MCP는 키를 갖지 않는다(유출 표면 0, 카카오 규칙 §4 개인정보/인증정보 반려 회피).

규격 준수 (카카오 PlayMCP 규칙 01)

항목	상태
전송	✅ Streamable HTTP (SDK StreamableHTTPServerTransport), stateless(no session)
버전	✅ SDK 협상(2025-06-18 등, 허용범위 내)
서버/툴명 kakao 금지	✅ 빌드 전 네이밍 린트가 강제
툴 개수 3~10	✅ 5개
annotations 5종	✅ title·readOnlyHint·destructiveHint·openWorldHint·idempotentHint
description 영문·≤1024·서비스명	✅ "… Part of WeatherSafetyOS(웨더세이프티OS)."
응답 Markdown·≤24k·TextContent	✅ 선택지 칩 푸터 포함, 24k 가드
p99 3s	✅ 외부호출 2.8s 타임아웃 + 코어 병렬화·KV 캐시
광고·리워드·개인정보 6종	✅ 없음
LLM 웹검색 불가 고유가치	✅ 실시간 공식경보·낙뢰관측·쉼터DB·결정론 위험엔진·공식 영향예보

제공 툴 (5)

툴	용도
assess_weather_risk(lat, lon)	지금 이 좌표의 개인 기상위험 판정 + 행동요령 + 최근접 쉼터 (실시간)
simulate_weather_risk(occupation, ageBand, …)	"만약 이런 날씨에 이런 사람이라면?" what-if — 같은 기상, 직업·연령별 차등
find_nearest_shelter(lat, lon, kind)	행안부 공식 무더위/한파 쉼터 6만여 곳 중 최근접
official_impact_forecast(lat, lon, sector)	기상청 공식 영향예보(직업 분야별 등급) — "농업 경고 vs 일반인 주의"
resolve_location(lat, lon)	GPS → 기상청 4체계 위치 변환

로컬 실행·검증

npm install
npm run build          # 네이밍 린트 + tsc → dist/
npm start              # Express 서버 :8080  (POST /mcp)
npm run smoke          # 5툴 핸들러 직접 호출(라이브 코어)
# 실제 MCP 프로토콜 검증: (서버 켠 상태에서) tsx scripts/client-smoke.ts
npm run inspect        # MCP Inspector (제출 전 필수 점검)
npm run stdio          # 로컬/Claude Desktop용 stdio 전송

PlayMCP in KC 배포 (Kev 액션)

KC는 Git 소스 빌드(루트 Dockerfile) 또는 컨테이너 이미지(linux/amd64)만 받는다. 절차:

1. 이 폴더(mcp-server/)를 공개 Git repo로 푸시 (루트에 Dockerfile 있음, 브랜치 main).
   • 로컬 도커 확인(선택): docker build --platform linux/amd64 -t weathersafetyos-mcp . && docker run -p 8080:8080 weathersafetyos-mcp
2. KC(playmcp.kakaocloud.io) → PlayMCP in KC 서버 생성: 서버명 weathersafetyos-mcp, Git URL·브랜치 main·Dockerfile 경로 Dockerfile → 빌드 → Active → Endpoint URL 복사.
3. PlayMCP 임시 등록: Endpoint URL 입력 → "정보 불러오기" 성공 확인 → 도구함 추가 → AI채팅 테스트.
4. 대화 예시 3개 입력(아래) → 심사 요청(≤7/7 권장) → 승인 → 전체 공개 → 상세 URL 확보.
5. 공모전 비즈폼 "Player 예선 참여"(≤7/14, 1회, 최대 2개 — 슬롯2로 제출).

등록용 대화 예시 3개

1. "택배 일 하는데 지금 대구 밖에 나가도 될까?" → assess_weather_risk(place=대구, occupation=delivery) — 실시간 체감온도·특보 + 심각도별 행동요령 + 법정 근거(산업안전보건규칙 §559 옥외작업 기준) + 최근접 무더위쉼터. 지명만으로 동작(좌표 불필요), 관측 지연 시에도 절대 500 없이 안내.

2. "폭염경보 속, 밭일 하시는 78세 아버지랑 사무실에 있는 20대는 위험이 얼마나 달라?" — (핵심: 동일 재난, 다른 운명) → simulate_weather_risk를 프로필만 바꿔 2회 → **같은 체감 38℃**가 78세 농업(야외)엔 🔴 위급(즉시 대피), 20대 사무(실내)엔 🔵 생활 안내로 4단계나 갈린다. 위급 카드엔 법정 기준(§559) + 최근접 쉼터, 그리고 기상청 공식 영향예보도 "농업 경고 vs 일반인 주의"로 직업마다 다름을 나란히 → "구역 등급을 넘어 그 자리의 당신에게".

3. "광주 지금 위험해? 가까운 쉼터도 알려줘." — (편의성·안전 UX) → 지명이 헷갈리면(광주광역시 vs 경기도 광주시) 되물어 확정 → assess_weather_risk 실시간 위험 → find_nearest_shelter로 행안부 공식 6만 곳 중 최근접 쉼터 + 지도 링크. 애매하면 묻고, GPS 좌표를 주면 즉시 정확.

구조

mcp-server/
├─ Dockerfile          ← KC Git-소스 빌드(linux/amd64, node:22, dist/server.js)
├─ src/tools.ts        ← 툴 5종(zod·annotations·영문desc·Markdown+칩), 코어 Worker 호출
├─ src/server.ts       ← Express 5 + SDK StreamableHTTPServerTransport(stateless)
├─ src/stdio.ts        ← stdio 전송(로컬/Claude)
├─ src/naming.ts       ← kakao 네이밍 금지 강제
└─ scripts/            ← lint-naming · smoke · client-smoke