PowPop（泡泡）MCP 커넥터 사용 가이드
PowPop은 위치 기반 소셜 애플리케이션입니다. 사용자가 지도에서 주변의 공개 디지털 휴먼, 실제 사용자, 게시물을 발견하고, 디지털 휴먼과 대화하거나 체크인 이벤트에 참여할 수 있습니다. 본 커넥터는 이러한 기능을 9개의 읽기 전용 도구로 캡슐화합니다.
인증 및 전제 조건
- 공개 콘텐츠는 로그인 불필요: 주변의 디지털 휴먼, 게시물, 명소, 이벤트, 멤버십 플랜 등 공개 데이터는 익명으로 조회할 수 있습니다.
- 계정 관련 기능은 인증 필요: 첫 번째 호출 시 401 오류가 발생하면 사용자가 아직 OAuth 인증을 완료하지 않은 것입니다. 사용자에게 커넥터 설정에서 PowPop을 찾아 인증을 완료하도록 안내하세요(인증 페이지는 PowPop에서 제공). 완료 후 재시도하면 됩니다. 인증 상태는 플랫폼에서 자동으로 유지되며(토큰 자동 갱신), 반복적으로 물어볼 필요가 없습니다.
- 좌표계 주의: 좌표가 필요한 도구는 모두 **GCJ-02(가오더/화성 좌표계)**를 사용합니다. 사용자가 GPS(WGS-84) 위/경도를 직접 제공하면 약 300-600미터의 오차가 발생할 수 있으므로, 사용자에게 지명을 제공하도록 요청하고
geocode_place또는 도구의place매개변수를 사용하여 변환하는 것이 좋습니다.
도구 개요
| 도구 | 용도 | 주요 매개변수 | 일반적인 시나리오 |
|---|---|---|---|
find_nearby | 주변의 디지털 휴먼, 실제 사용자, 게시물 발견 | lat+lng 또는 place(둘 중 하나); radius_meters 기본값 1000; types로 특정 유형만 반환 가능 | "내 주변에 누가/무슨 게시물이 있어?" |
geocode_place | 지명을 위/경도로 변환하고 매칭 신뢰도 보고 | place | 좌표가 필요할 때 첫 번째 단계 |
get_digital_human | 디지털 휴먼 전체 프로필(페르소나/소개/위치/감정) | id(find_nearby에서 획득) | 디지털 휴먼을 찾은 후 "다음 단계" |
get_post_detail | 게시물 전체 내용 + 댓글 목록 | post_id(find_nearby/search_posts에서 획득) | 특정 게시물의 토론 확인 |
nearby_attractions | 주변 명소 및 상권(거리순) | lat+lng 또는 place; radius_meters 기본값 3000 | "주변에 뭐 재미있는 곳 있어?" |
search_posts | 키워드로 공개 게시물 검색 | keyword(본문 매칭, 대소문자 구분 안 함) | "고궁에 관한 게시물" |
list_campaigns | 모든 공개 이벤트(체크인 장소 목록 포함) | 없음 | "지금 어떤 이벤트가 있어?" |
list_membership_plans | 멤버십/패키지 가격 | 없음 | "멤버십 얼마야?" |
whoami | 현재 인증된 신원 확인 | 없음 | "나는 누구지?" "로그인됐어?" |
매개변수 스키마는
tools/list의 실시간 반환을 기준으로 합니다. 위에는 일반적인 매개변수만 나열되어 있습니다. 선택적 매개변수, 기본값에 차이가 있더라도 사용자와 논쟁하지 말고 실시간 스키마에 따라 호출하세요.
각 도구 사용법 상세
find_nearby — 주변 탐색 핵심 도구
- 위치는 세 가지 중 하나를 선택:
place(지명, 권장, 자동 인코딩) >lat+lng(GCJ-02). 세 가지 모두 전달하지 않으면 서버에서 위치를 확인할 수 없어 오류가 반환됩니다. types로 필터링 가능:digital_humans(디지털 휴먼) /users(실제 사용자) /posts(게시물), 기본값은 모두 반환.- 각 유형의 요약과 거리를 반환하며, 디지털 휴먼 카드는
get_digital_human을 사용하여 추가 확인 가능. - 예시: 사용자가 "국무 주변에 누가 있어?" →
{ "place": "국무", "types": ["digital_humans"] }.
geocode_place — 지명 인코딩 + 신뢰도
lat/lng,matched_name(서버가 실제로 매칭한 POI 이름),confidence(0~1) 반환.- 신뢰도가 0.8 미만이면 "사용자가 입력한 지명"과 "실제 매칭된 지명"을 모두 사용자에게 알려 확인을 받아야 하며, 모호한 매칭을 그대로 답변으로 사용하지 마세요.
get_digital_human — 디지털 휴먼 상세
id는 반드시find_nearby등 도구가 반환한 디지털 휴먼의 ID여야 하며, 임의로 생성하지 마세요.- 페르소나(persona), 소개, 위치, 현재 감정을 반환하므로, 먼저 소개한 후 사용자에게 대화를 유도하는 데 적합합니다.
get_post_detail — 게시물 상세
post_id는find_nearby또는search_posts의 반환 결과에서 가져옵니다.- 공개 게시물(is_public)만 조회 가능하며, 비공개 게시물의 경우 읽을 수 있는 오류 메시지가 반환되므로 사용자에게 그대로 전달하면 됩니다.
nearby_attractions — 명소 및 상권
find_nearby와 위치 매개변수 규칙을 공유합니다(place또는lat+lng, GCJ-02). 기본 반경은 3000미터입니다.- 명소(attractions)와 상권(business_districts) 두 그룹을 반환하며, 각각 거리 정보가 포함되어 있어 "주변 추천" 유형의 답변에 통합할 수 있습니다.
search_posts — 키워드 게시물 검색
keyword는 게시물 본문에 대해 대소문자를 구분하지 않는 퍼지 매칭을 수행합니다.- 검색 결과에는 요약, 위치, 대표 이미지 링크가 포함되며, 특정 게시물을 인용할 때는 위치 정보를 함께 제공하면 더 완성도 높은 답변이 됩니다.
- 예시: "가을에 관한 게시물 검색" →
{ "keyword": "가을" }.
list_campaigns — 이벤트 목록
- 매개변수 없음. 모든 공개 이벤트(예: "베이징 100개 박물관" 체크인 이벤트)를 반환하며, 각 이벤트에는 체크인 장소(acts) 목록이 포함됩니다.
- 사용자가 "무슨 이벤트/체크인이 있어?"라고 물으면 이 도구를 우선 호출하세요.
list_membership_plans — 멤버십 플랜
- 매개변수 없음. 채널별로 그룹화된 가격을 반환합니다: 알리페이 기간제 패키지와 PayPal/화웨이 구독.
- 사용자가 가격, 멤버십, 패키지에 대해 물을 때 호출하세요. 가격을 그대로 전달하고, 사용자를 대신하여 구매 결정을 내리지 마세요.
whoami — 신원 확인
- 매개변수 없음. 인증된 경우 PowPop 계정 정보(닉네임, 배지 수, 멤버십 상태)를 반환하고, 인증되지 않은 경우 연결 방법을 안내합니다.
- "사용자 신분"으로 작업을 수행하기 전이나 사용자가 신원/로그인 상태를 물을 때 먼저 이 도구를 호출하세요.
오류 처리 및 복구
| 현상 | 원인 | 처리 |
|---|---|---|
| 401 / 인증되지 않음 | OAuth가 완료되지 않았거나 만료됨 | 사용자에게 커넥터 설정에서 PowPop을 다시 인증하도록 안내한 후 재시도 |
error 필드의 읽을 수 있는 오류 메시지(예: "매개변수 누락", "해석 불가") | 매개변수 누락 또는 입력이 유효하지 않음 | 오류 메시지에 따라 매개변수를 수정한 후 재시도, 영어 오류를 사용자에게 그대로 전달하지 말고 실행 가능한 한국어 안내로 번역 |
| 빈 결과(0개) | 해당 지역/키워드에 공개 콘텐츠가 실제로 없음 | "발견된 항목이 없습니다"라고如实告知하고, 사용자에게 키워드 변경, 반경 확대, 위치 변경 등을 제안 |
| 시간 초과(30초 이상) | 서버 응답 없음 | 연속 재시도하지 말고, 사용자에게 잠시 후 다시 시도하라고 안내 |
고위험 작업 확인
본 커넥터의 9개 도구는 모두 읽기 전용이므로 쓰기 작업이나 결제 동작이 없어 추가 확인이 필요하지 않습니다. 멤버십 구매 관련 문의가 있을 경우, list_membership_plans의 가격 정보만 제공하고 사용자가 PowPop 앱 내에서 직접 완료하도록 안내하며, 대화 중에 사용자를 대신해 결정하지 마세요.
최종 동기화: 2026-10-18, MCP 서버 버전 powpow-mcp 0.14.5(9개 도구)에 해당. 서버 도구 계약이 변경될 경우(추가/삭제/매개변수 변경) 본 파일을 업데이트하고 커넥터 버전을 올려 재심사를 받아야 함. 순수 서버 내부 수정은 업데이트 불필요.