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 | 現在の認証済み ID を確認 | なし | 「私は誰？」「ログインしてる？」 |
パラメータスキーマは
tools/listのリアルタイム返却値が正しい。上記はよく使うパラメータのみを列挙しています。オプションパラメータやデフォルト値に相違がある場合は、ユーザーと議論せず、リアルタイムスキーマに従って呼び出してください。
各ツールの使い方のポイント
find_nearby —— 周辺発見の中核ツール
- 位置指定は 3 つの方法から：
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 を使用する必要があります。独自に 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）の 2 つのグループを返し、それぞれ距離が含まれます。これらを「おすすめスポット」の回答に統合できます。
search_posts —— キーワード検索
keywordは投稿本文に対して大文字小文字を区別しないあいまいマッチングを行います。- 結果には概要、位置、ヘッダー画像リンクが含まれます。特定の投稿を引用する際は、可能な限りその位置情報も含めると回答がより完全になります。
- 例：「秋に関する投稿を検索」→
{ "keyword": "秋天" }。
list_campaigns —— キャンペーン一覧
- パラメータなし。すべての公開キャンペーン（例：「北京の 100 の博物館」チェックインキャンペーン）を返し、各キャンペーンにはチェックインポイント（acts）のリストが含まれます。
- ユーザーが「どんなキャンペーン/チェックインがある？」と尋ねた場合、最初にこのツールを呼び出してください。
list_membership_plans —— 会員プラン
- パラメータなし。チャネル別にグループ化された価格を返します：Alipay の期間パックと PayPal/ Huawei のサブスクリプション。
- ユーザーが価格、会員、プランについて尋ねた場合に呼び出します。価格をそのまま伝え、ユーザーの代わりに購入の意思決定をしないでください。
whoami —— 身元確認
- パラメータなし。認証済みの場合は PowPop アカウント情報（ニックネーム、バッジ数、会員ステータス）を返します。未認証の場合は接続方法を促します。
- 「ユーザーとして」何らかの操作を実行する前、またはユーザーが身元やログイン状態を尋ねた場合に、最初にこのツールを呼び出してください。
エラーハンドリングとリカバリ
| 現象 | 原因 | 対処 |
|---|---|---|
| 401 / 未認証 | OAuth が未完了または期限切れ | コネクタ設定で PowPop を再認証するようユーザーをガイドし、再試行 |
error フィールドの読み取り可能なエラー（例：「パラメータが不足しています」「解析できません」） | パラメータ不足または入力が無効 | エラーメッセージに従ってパラメータを修正し再試行；エラーの英語をそのままユーザーに提示せず、アクション可能な日本語のヒントに翻訳 |
| 空の結果（0 件） | そのエリア/キーワードには公開コンテンツが本当にない | 「見つかりませんでした」とそのまま伝え、キーワードを変更する、半径を広げる、場所を変えるなどを提案 |
| タイムアウト（30 秒以上） | サーバーが応答しない | 連続して再試行しない；ユーザーに後で再試行するよう伝える |
リスクの高い操作の確認
このコネクタの全 9 つのツールは読み取り専用であり、書き込み操作や支払いアクションは存在しないため、追加の確認は不要です。会員購入に関する意向については、list_membership_plans の価格情報のみを提供し、ユーザーを PowPop アプリ内の購入フローに誘導してください。会話内でユーザーに代わって決定を下さないでください。
最終同期日：2026-10-18、MCP サーバーバージョン powpow-mcp 0.14.5（9 ツール）に対応。サーバーのツール契約に変更（追加/削除/パラメータ変更）があった場合、このファイルを同期して更新し、コネクタのバージョンを上げて再審査を提出する必要があります。純粋なサーバー内部の修正は更新不要です。