<p align="center">
  <img src="logo.png" width="160" alt="마음길잡이 로고" />
</p>

<h1 align="center">마음길잡이 MCP</h1>

<p align="center">
  카카오 PlayMCP용 정신건강·복지 안내 MCP 서버<br/>
  "요즘 힘든데 근처 상담할 곳 있을까?" 한 마디로 상담기관과 복지제도를 연결합니다.
</p>

<p align="center">
  <a href="https://playmcp.kakao.com"><img src="https://img.shields.io/badge/카카오_PlayMCP-등록완료-FFCD00?style=flat-square&logo=kakao&logoColor=000" alt="PlayMCP"/></a>
  <a href="https://mind-guide-mcp.onrender.com/mcp"><img src="https://img.shields.io/badge/Render-배포중-46E3B7?style=flat-square&logo=render&logoColor=000" alt="Render"/></a>
  <img src="https://img.shields.io/badge/Python-FastMCP-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"/>
</p>

---

## 무엇을 하는 서버인가

마음길잡이는 **상담하는 봇이 아닌, 연결해주는 봇**입니다.

사용자가 카카오톡에서 지역과 상황을 말로 전달하면:
- 전국 정신건강복지센터 연락처·운영시간 안내 (공공데이터 기반, **163개 기관**)
- 산재·청년·장애·노인·아이돌봄 등 맞춤 복지제도 추천 (실데이터 **367종**)
- 위기 신호 감지 시 자살예방상담전화(109) 등 즉시 연락처 우선 안내

대화 내역을 읽거나 개인정보를 수집하지 않습니다. 사용자가 직접 입력한 내용만으로 동작합니다.

---

## 도구 (MCP Tools)

| 도구 | 설명 | 데이터 |
|------|------|--------|
| `crisis_resources` | 위기 시 즉시 연락처 안내 | 보건복지부 공식 5개 번호 |
| `find_counseling_centers` | 지역·상황별 정신건강복지센터 추천 | 공공데이터 163개 기관 |
| `recommend_welfare` | 상황·나이·가구형태별 복지제도 추천 | 복지로 실데이터 367종 |

> 모든 추천 도구는 위기 신호를 먼저 감지해, 신호가 있으면 추천보다 위기 연락처를 앞에 안내합니다.

---

## 이용 방법

카카오 AI 채팅(카카오톡)에서 마음길잡이 MCP가 연결된 상태로 자유롭게 말을 걸면 됩니다.

### 이런 말로 시작해보세요

| 상황 | 예시 말 |
|------|---------|
| 그냥 힘들 때 | "요즘 너무 지쳐요" · "아무것도 하기 싫어요" |
| 상담 기관 찾을 때 | "서울에서 상담받을 수 있는 곳 알고 싶어요" |
| 복지 제도 궁금할 때 | "청년인데 받을 수 있는 지원이 있나요?" |
| 직장·가족 스트레스 | "직장 때문에 너무 힘들어요" · "육아가 너무 버거워요" |
| 산후 우울 | "출산 후 감정 기복이 너무 심해요" |
| 위기 상황 | 즉시 자살예방상담전화(109) 등 연락처를 먼저 안내합니다 |

### 대화 예시

```
사용자: 요즘 너무 지쳐서 아무것도 못 하겠어요
마음길잡이: 많이 지치셨겠어요. 어떤 일이 있으셨는지 조금 더 얘기해주실 수 있어요?

사용자: 직장 스트레스가 너무 심해서요
마음길잡이: 정말 힘드셨겠다 싶어요. 혼자 버텨오신 거잖아요.
           가까운 상담 기관을 찾아드릴까요? 부담 없이 한 번 연락해볼 수 있어요.

사용자: 네, 서울이에요
마음길잡이: [도구 호출 → 서울 정신건강복지센터 안내]
           처음 연락할 때 "상담받고 싶어서요, 처음인데 어떻게 하면 될까요?"
           라고 말하면 친절히 안내해줄 거예요.
           마음이 힘든 건 감기 걸린 것과 같아요. 치료받는 게 당연한 거예요.
```

### 이용 가능한 채널

| 채널 | 방법 |
|------|------|
| 카카오 AI 채팅 | [playmcp.kakao.com](https://playmcp.kakao.com) → 마음길잡이 추가 후 카카오톡에서 대화 |
| MCP 클라이언트 | `https://mind-guide-mcp.onrender.com/mcp` 엔드포인트 직접 연결 |

---

## 대화 설계

단순한 정보 안내 봇이 아닌, 실제로 힘든 사람이 쓴다는 전제로 대화 흐름을 설계했습니다.

```
1단계 — 공감      힘들다는 말에 바로 도구를 쓰지 않고, 먼저 마음을 받아줍니다.
2단계 — 확인      "도움받을 수 있는 곳 찾아드릴까요?" 의사를 먼저 묻습니다.
3단계 — 안내      동의하면 지역·상황을 물어 상담기관 또는 복지제도를 안내합니다.
4단계 — 신청 안내 추천 후 "처음 연락할 때 이렇게 말해보세요" 스크립트를 함께 줍니다.
5단계 — 체크인    "다음에 또 얘기해요" 등으로 대화를 자연스럽게 마무리합니다.
```

**낙인 제거 메시지** — 추천할 때 아래 메시지를 자연스럽게 녹여 부담을 낮춥니다.

> "마음이 힘든 건 감기 걸린 것과 같아요. 치료받는 게 당연한 거예요."  
> "상담 받는다고 큰 문제가 있는 사람인 게 아니에요. 오히려 용기 있는 거예요."  
> "지금 연락하는 게 절대 늦지 않았어요."

---

## 설계 원칙 (안전)

1. **연결하는 봇** — 감정 진단·치료 조언 금지. 실제 기관으로 연결하는 역할만 합니다.
2. **위기 우선** — 위기 신호 감지 시 추천보다 즉시 연락처를 먼저 안내합니다.
3. **위기 수단·방법은 절대 다루지 않습니다.**
4. **AI가 사람 상담을 대체하지 않습니다.** 항상 실제 기관 연결을 권합니다.

---

## 데이터 출처

### 상담기관 (163개)

| 항목 | 내용 |
|------|------|
| 출처 | 공공데이터포털 `전국건강증진센터표준데이터` |
| 필터 | 건강증진센터구분 = 정신보건 |
| 제공 정보 | 기관명 · 주소 · 전화 · 운영시간 · 담당 업무 |
| 갱신 기준 | 2026-03 다운로드 기준 (`data/centers.json`) |

### 복지제도 (367종)

| 항목 | 내용 |
|------|------|
| 출처 | 한국사회보장정보원 `복지서비스정보` (odcloud) |
| API | `https://api.odcloud.kr/api/15083323/v1/...` |
| 제공 정보 | 서비스명 · 서비스요약 · 대표문의 · 복지로 링크 |
| 매칭 방식 | 사용자 입력 키워드 × 서비스명·요약 점수 기반 |
| 키 설정 | `.env` → `DATA_GO_KR_API_KEY` (없으면 더미 12종으로 동작) |

### 위기 연락처

보건복지부 공식 번호, 2024-01-01부터 109 통합 운영.

---

## 로컬 실행

```bash
pip install -r requirements.txt
cp .env.example .env   # DATA_GO_KR_API_KEY 입력 (없어도 동작)
python mind_guide_server.py
# → http://0.0.0.0:8000/mcp (streamable-http)
```

### 환경변수

| 변수 | 설명 | 필수 |
|------|------|------|
| `DATA_GO_KR_API_KEY` | data.go.kr 일반 인증키 | 선택 (없으면 더미 데이터) |
| `HOST` | 서버 바인딩 주소 | 선택 (기본: `0.0.0.0`) |
| `PORT` | 포트 | 선택 (기본: `8000`) |

---

## 배포

| 항목 | 값 |
|------|-----|
| 플랫폼 | Render (무료 플랜) |
| MCP 엔드포인트 | `https://mind-guide-mcp.onrender.com/mcp` |
| 전송 방식 | streamable-http (`stateless_http=True`) |
| PlayMCP | [playmcp.kakao.com](https://playmcp.kakao.com) 등록 완료 |

> Render 무료 플랜은 15분 비활성 후 슬립됩니다. 첫 요청 시 수십 초 걸릴 수 있어요.

---

## 위기 연락처

| 전화 | 번호 | 운영 |
|------|------|------|
| 자살예방상담전화 | **109** | 24시간 무료 |
| 정신건강위기상담전화 | **1577-0199** | 24시간 무료 |
| 보건복지상담센터 | **129** | 24시간 무료 |
| 청소년전화 | **1388** | 24시간 무료 |
| 응급 | **119** | 24시간 |