다정키 (Dajungkey)

커플이 싸우기 전에 말투를 한 번 더 다정하게 바꿔주는 AI 커플 말투 도구. 카카오 AGENTIC PLAYER 10 예선 제출용 remote MCP 서버 (TypeScript + @modelcontextprotocol/sdk + Streamable HTTP).

서비스 소개·데모 시나리오는 docs/SUBMISSION.md, 기획 전문은 docs/SPEC.md 참고.

실행 방법

npm install

# 개발 (파일 변경 감지)
npm run dev

# 프로덕션
npm run build
NODE_ENV=production npm start

# 테스트 (API key 불필요 — mock provider로 동작)
npm test

환경변수

.env.example을 복사해 .env를 만들고 채운다. .env는 절대 커밋하지 않는다.

변수	필수	설명
ANTHROPIC_API_KEY	아니오	Claude API key. 없으면 local fallback mode로 동작 (로컬 결정적 응답). 개발용이며, 실제 심사용 배포에서는 설정을 권장한다. fallback 응답에도 mock/디버그 문구는 사용자에게 노출되지 않는다
MODEL_NAME	key 설정 시 필수	런타임 모델명 (예: claude-opus-4-8). 코드에 하드코딩하지 않는다
PORT	아니오	서버 포트 (기본 3000)

엔드포인트

메서드·경로	용도
POST /mcp	MCP Streamable HTTP 엔드포인트 (PlayMCP 등록 대상)
GET /health	헬스 체크 ({"ok":true})

완전 무상태 서버: 세션·DB 없음, 요청마다 MCP 서버 인스턴스를 만들고 응답 후 폐기한다.

응답 지연 보호: LLM 응답이 2.5초를 넘거나 실패하면 local fallback 결과로 즉시 응답한다 (PlayMCP 툴 응답 p99 3,000ms 요건 대응).

MCP Tools

tool	역할
fight_prevention_rewrite	날카로운 문장을 감정은 유지한 채 완충 (싸움 방지모드)
warm_tone_rewrite	무뚝뚝한 문장을 다정하게
apply_couple_tonepack	애칭·이모지·선호 말투 반영 (말투팩은 매 호출 전달, 무저장)
cooldown_message	격앙된 문장을 잠깐 멈추자는 메시지로 전환

공통 출력: { rewritten, safety_action, note? } — safety_action은 none | softened | cooldown_suggested | refused. 상세 스키마는 docs/TOOL_SCHEMA.md.

데이터 정책 (요약)

• 원문·변환 결과·말투팩을 저장하지 않고 로그에도 남기지 않는다. 로그는 메타데이터만(tool명, 성공 여부, 지연시간, safety_action).
• LLM 호출 실패 시 원문을 그대로 반환하지 않는다 — 실패 안내만 반환.
• 배포 시 NODE_ENV=production 권장 (프레임워크 기본 에러 로깅 억제).
• 전문: docs/PRIVACY.md

검증

• npm test — local fallback 기반 smoke test (tool 4개 + annotations + red-team G28·G30 + 지연시간 보호 + 에러 계약)
• 배포 전 docs/GOLDEN_CASES.md의 red-team 케이스(G27~G30)를 실제 LLM으로 수동 검수한다.