# 안심돌봄 조수 — 요양·재가 돌봄 기록 MCP 서버

요양보호사와 가족 돌봄자가 카카오톡 에이전트에게 말하듯 기록하면,
**어르신별 안전 제약이 자동 적용된** 보호자용 알림장·주간 리포트 초안이 만들어지는 돌봄 기록 조수.

> AGENTIC PLAYER 10 (카카오 PlayMCP 공모전) 출품용

## 한 줄 서사

**"보육은 키즈노트에서 어린이ZIP까지 왔지만, 요양은 여전히 전화와 수기입니다.
1회 대회가 어린이집 선생님의 퇴근을 앞당겼다면, 이번엔 요양 현장 차례입니다."**

패밀리노트(카카오 계열)는 알림장을 *전달*합니다. 이 도구는 알림장을 *쓰는 고통*을 해결합니다.

## 핵심 차별점: 도구 레벨 안전 제약 주입

원형 프로젝트에서 실제로 겪은 사고 — 거동 불가 와상 어르신의 알림장에 AI가
"정원 산책을 다녀오셨습니다"라는 문장을 지어낸 일 — 를 구조적으로 차단하는 설계입니다.

1. **특이사항 → 금지표현 자동 변환** (`safety.ts`)
   어르신 등록 시 와상·휠체어·연하곤란·경관영양·치매·당뇨·낙상·욕창·알레르기 등을
   "산책 묘사 절대 금지" 같은 제약 규칙으로 변환해 저장
2. **초안 재료에 제약 강제 포함**
   `draft_notice`가 반환하는 모든 재료에 안전 제약 블록이 무조건 붙어,
   문장을 쓰는 에이전트가 지어낼 수 없는 구조
3. **수치 분리** — 식사량·투약은 기록 원본 그대로 표기하도록 지시 (AI 재작성 금지)
4. **기록 없으면 초안 거부** — "기록 없이 알림장을 지어내지 않는 것이 원칙"
5. **Human-in-the-loop** — 모든 초안 끝에 "확인·수정 후 전달" 문구 강제

서버는 LLM을 호출하지 않는 결정론적 구조 (상태 관리 + 안전 제약 + 재료 반환).
문장 작성은 호출한 에이전트가 수행 → 안정성·비용·보안 모두 유리.

## 두 사용자, 하나의 도구

| 페르소나 | 시나리오 |
|---|---|
| **요양보호사 (시설)** | "김O순 어르신, 점심 반 그릇에 혈압약 드심" → 퇴근 전 "알림장 초안 만들어줘" → 3안 중 선택·수정 |
| **가족 돌봄자 (재가)** | 노부모를 돌보는 자녀가 기록 → 형제자매와 공간 코드 공유 → '오늘의 엄마 알림장'·주간 리포트를 가족 단톡방에 공유 |

재가 페르소나가 투표 모수를 요양보호사 수십만 명에서 가족 돌봄자 수백만 명으로 확장합니다.

## 도구 목록 (8개)

| 도구 | 역할 | 트리거 예시 |
|---|---|---|
| `create_care_space` | 돌봄 공간 생성 (시설/재가) + 코드 발급 | "돌봄 기록 시작할래" |
| `register_senior` | 어르신 등록 + 특이사항→안전 제약 변환 | "김O순 어르신 추가, 와상에 복숭아 알레르기" |
| `log_care` | 식사·투약·컨디션·메모 기록 (원문 보존, 과거 날짜 백필 가능) | "점심 반 그릇 드셨어" |
| `draft_notice` | 알림장 초안 재료 (안전 제약 + 기록 원본 + 3안 지침) | "알림장 초안 만들어줘" |
| `ask_senior_info` | 특이사항·오늘 기록 빠른 조회 | "김O순 어르신 알레르기 뭐였지?" |
| `weekly_report` | 최근 7일 기록 집계 + 주간 리포트 지침 | "이번 주 엄마 어땠는지 정리해줘" |
| `list_seniors` | 오늘 기록 현황 체크리스트 (미기록 어르신 표시) | "아직 기록 안 한 어르신 누구야?" |
| `view_care_diary` | 쌓인 기록을 가족이 간직하는 돌봄 일기 재료로 (최대 30일) | "엄마 돌봄 일기 보여줘" |

## 개인정보 보호 설계

- 어르신 **실명 대신 호칭·가명 등록 안내** (공간 생성·등록 시 상시 고지)
- 최소 수집: 이름·주민번호·연락처 등 식별정보 필드 없음
- 공간 코드 기반 접근 — 코드를 아는 사람만 해당 공간 조회 가능
- 의료 진단·처방 기능 없음 (기록·소통 보조로 한정, 원형 프로젝트의 의료 안전 정책 승계)

## 로컬 실행

```bash
npm install
npm run build
npm start                 # http://localhost:3000/mcp
node smoke-test.mjs       # 서버 켜둔 상태에서 전체 시나리오 검증
```

Node 22+ 필요 (내장 `node:sqlite` 사용, 네이티브 의존성 없음).

## 카카오클라우드 배포 → 접수 체크리스트

공식 가이드: **kko.to/player10**

- [ ] 카카오클라우드 인스턴스 생성, 코드 업로드, `PORT`·`DB_PATH` 설정
  - `DB_PATH`는 재시작에도 유지되는 볼륨 경로로 (기록 데이터 유실 방지)
- [ ] HTTPS 엔드포인트 확보 → `https://<도메인>/mcp` PlayMCP 등록
- [ ] **심사 요청 — 7/7(화)까지** ← 7/10 심사 완료 보장 마지노선
- [ ] 심사 통과 후 '전체 공개' 전환
- [ ] 공모전 예선 접수 (마감 7/14, 제출 1회)
- [ ] 본선 진출 시(7/30): 알림장 초안 카드·주간 리포트를 Kakao Tools Widget으로 고도화


## v0.2 개선 내역 (제출 후 품질 업데이트)

도구 목록·스키마는 심사 통과본 그대로 유지하고, 내부 품질만 개선:

1. **유연 호칭 매칭** — "김O순 어르신"으로 등록해도 "김O순"으로 찾음. 후보가 여럿이면 되물음
2. **안전 규칙 8종 → 16종** — 편마비·파킨슨·난청·시각장애·치아·신장질환·배회·혈압 추가
3. **입력 시점 모순 감지** — 와상 어르신 기록에 '산책'이 들어오면 저장은 하되 확인 요청 (출력+입력 이중 안전망)
4. **알림장 어제 기록 비교** — 사실 비교("어제 반 그릇 → 오늘 완식")까지만 허용, 원인 추정 금지 지침 포함
5. **주간 리포트 서버 집계** — 기록 일수·건수를 서버가 결정론적으로 계산해 제공
6. 공간 코드 입력 관대화(하이픈·공백 허용), 메모 1,000자 제한, 결과 텍스트 한국어 통일
7. **돌봄 일기(view_care_diary) 신설** — 쌓인 기록을 '가족이 간직하는 부모님의 하루하루'로 재구성. 기록자 관찰 시점, 메모 원문 보존, 1인칭 속마음 창작 금지

## 향후 확장

- 패밀리노트 연동 — 확정된 알림장을 전달 채널로 바로 발송 (카카오 생태계 완성 서사)
- 음성 메모 입력 (현장에서 손이 바쁜 요양보호사용)
- 장기요양기관 평가 "수급자 가족과의 소통" 항목 대응 기록 리포트
- 다국어 메모 → 한국어 알림장 (외국인 요양보호사 지원, 원형 프로젝트 기능 승계)