사이(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	카드 코드(들)의 아직 닫히지 않은 항목 조회

로컬 실행

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

빌드/실행:

npm run build
npm start

테스트:

npm test

MCP Inspector로 검증

# 서버가 로컬에서 떠 있다고 가정 (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 모드로 직접 조작하려면:

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% 단정하지 않으며 위험 신호와 안전한 다음 행동만 안내합니다.