# 다정키 (Dajungkey)

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

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

## 실행 방법

```bash
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`](docs/TOOL_SCHEMA.md).

## 데이터 정책 (요약)

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

## 검증

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