# 사이(SAY) — 가족 안내 도우미 MCP 서버

카카오 AGENTIC PLAYER 10 출품작. 가족이 받은 어려운 안내문(병원/검진, 관공서/복지, 보험/카드/납부,
택배/스미싱)을 행동 카드로 바꿔, 확인된 사실과 아직 비어 있는 확인 필요 항목을 분리하고
가족이 함께 확인·완료까지 닫도록 돕는 MCP 서버입니다.

## 설계 원칙

이 서버는 **LLM을 한 번도 직접 호출하지 않습니다.** 호스트(Kakao Tools/PlayMCP AI 채팅 등)의
LLM이 안내문을 읽고 텍스트로 전사·추출하면, 이 서버는 그 결과를 결정적(deterministic) 규칙으로
검증하고 정리합니다.

- **근거 게이트**: 호스트가 추출한 값은 원문 인용(quote)과 대조해 원문에 실제로 있으면 "확정",
  없으면 "추정(확인 필요)"으로 분리됩니다. 원문에 없는 내용을 단정하지 않습니다.
- **외부 의존 없음**: 서버는 API 키도, 외부 DB도 쓰지 않습니다. 인메모리 저장 + 주기적 JSON
  스냅샷만 사용해 응답이 빠르고 장애점이 없습니다.
- **닫힘 추적**: 안내문을 "행동 카드"로 만들고, 카드 코드(`SAY-XXXXXX`)를 가족과 공유해 각자
  항목 상태(내가 확인할게요/가족에게 물어봤어요/완료 등)를 바꾸며 닫아갑니다.

설계 배경은 `SAY` 저장소의 `SAY-mcp-design-blueprint.md`를 참고하세요.

## 제공 도구 (6종)

| 도구 | 역할 |
|---|---|
| `analyze_notice` | 안내문 원문(또는 캡처 전사 텍스트)을 행동 카드로 변환 — 확정/확인필요 사실, 위험 신호, 카드 코드 발급 |
| `check_scam_signals` | 스미싱/사기 위험 신호만 빠르게 검사 (카드를 만들지 않음) |
| `get_card` | 카드 코드로 현재 카드 상태 조회 |
| `update_item_status` | 항목 상태 변경 ("내가 확인할게요", "완료로 표시" 등) |
| `make_family_message` | 카드 기반 가족 전달 문안 조립 (템플릿 기반, 자유 생성 없음) |
| `list_open_items` | 카드 코드(들)의 아직 닫히지 않은 항목 조회 |

## 로컬 실행

```bash
npm install
npm run dev        # tsx watch, http://localhost:8080/mcp
```

빌드/실행:

```bash
npm run build
npm start
```

테스트:

```bash
npm test
```

## MCP Inspector로 검증

```bash
# 서버가 로컬에서 떠 있다고 가정 (PORT=8080)
npx @modelcontextprotocol/inspector --cli http://localhost:8080/mcp --transport http --method tools/list

npx @modelcontextprotocol/inspector --cli http://localhost:8080/mcp --transport http \
  --method tools/call --tool-name analyze_notice \
  --tool-arg raw_text="건강검진 안내입니다. 내일 오전 8시까지 오세요. 오늘 밤 10시부터 금식입니다."
```

UI 모드로 직접 조작하려면:

```bash
npx @modelcontextprotocol/inspector
# 브라우저에서 Transport: Streamable HTTP, URL: http://localhost:8080/mcp
```

## 배포 (PlayMCP in KC)

이 저장소 루트의 `Dockerfile`을 그대로 사용해 "Git 소스 빌드"로 등록합니다.

- MCP 서버 이름(KC): `say-family-notice`
- Endpoint: `https://{서버이름}.playmcp-endpoint.kakaocloud.io/mcp`
- Transport: Streamable HTTP (stateless, `/mcp` 단일 엔드포인트)
- 서버 자체는 비밀키를 전혀 사용하지 않으므로 저장소를 public으로 유지해도 안전합니다.

## 데이터/프라이버시

- 안내문 원문(raw_text)은 저장하지 않습니다 — 분석 호출 동안만 메모리에 존재합니다.
- 카드에는 파생 결과(확정/추정 사실, 항목, 위험 신호)와 근거 인용(최대 120자)만 남습니다.
- 카드는 마지막 접근 후 7일 뒤 자동 삭제됩니다.
- 사용자 인증(OAuth) 없이, 카드 코드 공유만으로 가족이 카드를 함께 봅니다.

## 안전 원칙

의료·법률·금융 판단을 하지 않습니다. 원문에 없는 내용은 "확인 필요"로 남기고, 스미싱은 100%
단정하지 않으며 위험 신호와 안전한 다음 행동만 안내합니다.