PowPop（泡泡）MCP 連接器使用指導
PowPop 是一款基於地理位置的社交應用：使用者在地圖上發現附近的公開數位人、真實使用者與貼文，可以和數位人對話、參與打卡活動。本連接器把這些能力封裝為 9 個唯讀工具。
認證與前置條件
- 公開內容無需登入：附近的數位人、貼文、景點、活動、會員方案等公開資料，匿名即可查詢。
- 帳號相關能力需要授權：首次呼叫若返回 401，表示使用者尚未完成 OAuth 授權。引導使用者在連接器設定中找到 PowPop 並完成授權（授權頁由 PowPop 提供），完成後重試即可。授權態由平台自動維護（token 自動續約），無需反覆詢問。
- 座標系注意：涉及座標的工具統一使用 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 | 檢查目前授權身份 | 無 | 「我是誰」「登入了嗎」 |
參數 schema 以
tools/list的即時回傳為準。上面只列常用參數；可選參數、預設值若有出入，不要與使用者爭論，按即時 schema 呼叫。
各工具用法要點
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 欄位的可讀錯誤（如「缺少參數」「無法解析」） | 參數缺失或輸入無效 | 按錯誤訊息修正參數後重試；不要原樣把英文錯誤丟給使用者，翻譯成 actionable 的中文提示 |
| 空結果（0 條） | 該區域/關鍵字確實沒有公開內容 | 如實告知「沒有找到」，可建議使用者換關鍵字、擴大半徑或換個地點 |
| 逾時（>30 秒） | 服務端無回應 | 不要連續重試；告知使用者稍後再試 |
高風險操作確認
本連接器全部 9 個工具均為唯讀，不存在寫操作或支付動作，無需額外確認。涉及購買會員的意向，只提供 list_membership_plans 的價格資訊，引導使用者前往 PowPop 應用內完成，不要在對話中代使用者決策。
最後同步：2026-10-18，對應 MCP server 版本 powpow-mcp 0.14.5（9 工具）。server 工具協定發生變更（新增/刪除/改參）時，需同步更新本檔案並提升連接器版本重新送審；純 server 內部修復不需要更新。