# 안심길동무 MCP

안심길동무는 PlayMCP에 등록할 수 있는 부모님 길안심 비서형 원격 MCP 서버입니다. 지도앱이 제안한 경로를 교통약자 관점에서 다시 점검하고, 엘리베이터/리프트/도움 연락처/이동지원 대안을 알려줍니다.

## What This Server Does

- 지도앱 경로 텍스트를 입력받아 `green`, `yellow`, `red` 길안심 등급을 산출합니다.
- 역별 엘리베이터, 휠체어 리프트, 도움 연락처, 주의사항을 확인합니다.
- 대중교통이 불안한 경우 지역 이동지원센터 연락처와 예약 대안을 제안합니다.
- 보호자가 카카오톡으로 바로 공유할 수 있는 짧은 안내 문구를 만듭니다.
- API 키가 없어도 `fixture` mode로 PlayMCP 심사/데모 호출이 가능합니다.

## MCP Endpoints

- MCP endpoint: `POST /mcp`
- Health check: `GET /health`

PlayMCP 개발자 콘솔에는 배포된 HTTPS 주소의 `/mcp` endpoint를 등록합니다.

예시:

```text
https://your-service.example.com/mcp
```

## Tools

| Tool | Purpose |
| --- | --- |
| `review_route_for_parent` | 지도앱 경로를 교통약자 관점에서 검토하고 위험/대안/공유 요약을 반환 |
| `check_station_accessibility` | 특정 역의 엘리베이터, 리프트, 화장실, 도움 연락처 확인 |
| `find_safer_exit` | 목적지 주변에서 더 안전한 역/출구 후보 추천 |
| `get_mobility_support_fallback` | 대중교통이 불안할 때 이동지원센터 대안 제공 |
| `make_guardian_share_card` | 보호자에게 보낼 카카오톡용 공유 문구 생성 |

## Environment

```text
NODE_ENV=production
PORT=3000
HOST=0.0.0.0
MCP_SERVER_NAME=ansim-gil-dongmu
MCP_SERVER_VERSION=0.1.0
DATA_MODE=fixture
KAKAO_REST_API_KEY=
PUBLIC_DATA_SERVICE_KEY=
PUBLIC_DATA_SEOUL_METRO_SERVICE_KEY=
PUBLIC_DATA_MOBILITY_SERVICE_KEY=
```

`DATA_MODE=fixture`는 API 키 없이 데모/심사 가능한 기본 모드입니다. 실제 공공 API를 사용하려면 `DATA_MODE=live`, `KAKAO_REST_API_KEY`, 공공데이터 키를 설정합니다. 공공데이터포털 키가 하나면 `PUBLIC_DATA_SERVICE_KEY`만 넣고, 데이터별 키가 다르면 `PUBLIC_DATA_SEOUL_METRO_SERVICE_KEY`, `PUBLIC_DATA_MOBILITY_SERVICE_KEY`를 각각 넣습니다. live mode에서도 API 실패 시 fixture fallback으로 응답을 유지합니다.

## Local Run

```bash
npm install
npm run build
npm test
npm run mcp:smoke
npm start
```

로컬에서 서버를 띄우면 기본 주소는 `http://127.0.0.1:3000`입니다.

## PlayMCP Registration

1. 이 서버를 HTTPS로 배포합니다.
2. `GET /health`가 200으로 응답하는지 확인합니다.
3. `npm run mcp:smoke` 또는 MCP 클라이언트로 `tools/list`와 `tools/call`을 확인합니다.
4. PlayMCP 개발자 콘솔에서 MCP 서버 endpoint를 `https://<domain>/mcp`로 등록합니다.
5. 초기 공개 범위는 private/test 상태로 두고 PlayMCP AI Chat에서 starter prompt를 검증합니다.
6. 심사 요청 후 승인되면 전체 공개로 전환합니다.

등록용 설명/프롬프트는 `playmcp/server-metadata.json`에 정리되어 있습니다.

## Example Prompts

```text
엄마가 무릎이 안 좋아. 서울역에서 종로3가역 환승 후 혜화역으로 가서 서울대병원까지 도보 15분인 경로 괜찮아?
```

```text
종로3가역에서 휠체어로 이용하기 좋은 출구와 도움 연락처 알려줘.
```

```text
아버지가 혼자 이동하기 힘든데 경기에서 서울대병원 갈 때 이동지원차량 대안도 알려줘.
```

## Safety Notice

이 서버는 공공 데이터와 fixture 정보를 바탕으로 사전 점검을 돕습니다. 엘리베이터, 리프트, 보도 공사, 혼잡, 현장 운영 상태는 달라질 수 있으므로 실제 이동 전 역무실 또는 이동지원센터에 반드시 재확인해야 합니다.