durenzidu/powpow-workbuddy-connector

PowPop (Bubble) MCP Connector Usage Guide

PowPop is a location-based social app: users discover nearby public digital humans, real users, and posts on a map, can chat with digital humans, and participate in check-in campaigns. This connector encapsulates these capabilities into 9 read-only tools.

Authentication & Prerequisites

• Public content does not require login: Nearby digital humans, posts, attractions, campaigns, membership plans, and other public data can be queried anonymously.
• Account-related features require authorization: If the first call returns a 401, it means the user has not completed OAuth authorization. Guide the user to find PowPop in the connector settings and complete authorization (the authorization page is provided by PowPop). Retry after completion. The authorization state is maintained automatically by the platform (tokens are auto-renewed), no need to ask repeatedly.
• Coordinate system note: Tools involving coordinates uniformly use GCJ-02 (Gaode/Mars coordinate system). When the user directly provides GPS (WGS-84) latitude/longitude, there will be an offset of about 300–600 meters. Prefer to have the user provide a place name and use geocode_place or the tool's place parameter for conversion.

Tool Overview

Tool	Purpose	Key Parameters	Typical Scenario
find_nearby	Discover nearby digital humans, real users, and posts	lat + lng or place (choose one); radius_meters default 1000; types to filter by type	"What people/posts are near me"
geocode_place	Convert place name to coordinates with match confidence	place	First step before needing coordinates
get_digital_human	Full profile of a digital human (persona/bio/location/mood)	id (from find_nearby)	"Next step" after finding a digital human
get_post_detail	Full post text + comment list	post_id (from find_nearby/search_posts)	Expand discussion on a specific post
nearby_attractions	Nearby attractions and business districts (by distance)	lat + lng or place; radius_meters default 3000	"What fun things are nearby"
search_posts	Search public posts by keyword	keyword (matches body, case-insensitive)	"Posts about the Forbidden City"
list_campaigns	All public campaigns (includes check-in points)	None	"What campaigns are there now"
list_membership_plans	Membership/package prices	None	"How much is membership"
whoami	Check current authorized identity	None	"Who am I" / "Am I logged in"

The parameter schema from tools/list takes precedence. The above lists only common parameters; if optional parameters or default values differ, do not argue with the user; follow the live schema.

Usage Details for Each Tool

find_nearby — Core Nearby Discovery Tool

• Location options (choose one): place (place name, recommended, auto-geocoded) > lat + lng (GCJ-02). If none are provided, the server cannot locate and will return an error.
• types can filter as needed: digital_humans / users / posts. Default returns all.
• Returns summaries and distances for each category; digital human cards can be expanded with get_digital_human.
• Example: User says "Who's near Guomao" → { "place": "Guomao", "types": ["digital_humans"] }.

geocode_place — Place Name Geocoding + Confidence

• Returns lat/lng, matched_name (the actual POI name matched by the server), and confidence (0~1).
• When confidence is below 0.8, you must tell the user both "the place name you entered" and "the actual matched name" for confirmation; do not take a fuzzy match as the answer and continue querying.

get_digital_human — Digital Human Details

• id must come from a digital human id returned by find_nearby or similar tools. Do not fabricate it.
• Returns persona, bio, location, and current mood. Suitable for introducing the digital human then guiding the user into a conversation.

get_post_detail — Post Details

• post_id comes from the return of find_nearby or search_posts.
• Only public posts (is_public) can be queried; non-public posts will return a readable error; just relay it to the user.

nearby_attractions — Attractions & Business Districts

• Shares the location parameter convention with find_nearby (place or lat + lng, GCJ-02); default radius 3000 meters.
• Returns two sets: attractions and business_districts, each with distance. Can be combined into "nearby recommendations" responses.

search_posts — Keyword Post Search

• keyword does a case-insensitive fuzzy match on post body text.
• Results include summary, location, and cover image link. When citing a specific post, include its location info for a more complete answer.
• Example: "Search for posts about autumn" → { "keyword": "autumn" }.

list_campaigns — Campaign List

• No parameters. Returns all public campaigns (e.g., "Beijing 100 Museums" check-in campaign); each campaign includes a list of check-in points (acts).
• Call this tool first when the user asks "What campaigns/check-ins are there."

list_membership_plans — Membership Plans

• No parameters. Returns prices grouped by channel: Alipay duration packages and PayPal/Huawei subscriptions.
• Call when user asks about prices, membership, or packages; relay prices faithfully; do not make purchase recommendations for the user.

whoami — Identity Check

• No parameters. When authorized, returns PowPop account info (nickname, badge count, membership status); when not authorized, prompts how to connect.
• Call this tool before any operation "as the user" or when the user asks about identity/login status.

Error Handling & Recovery

Phenomenon	Cause	Handling
401 / Unauthorized	OAuth not completed or expired	Guide the user to re-authorize PowPop in connector settings, then retry
Readable error in error field (e.g., "missing parameter", "cannot parse")	Missing or invalid parameters	Fix parameters based on the error message and retry; do not pass raw English errors to the user; translate into actionable Chinese prompts
Empty result (0 items)	No public content in that area/keyword	Honestly say "nothing found" and suggest changing keywords, expanding radius, or switching location
Timeout (>30 seconds)	Server unresponsive	Do not retry continuously; tell the user to try again later

High-Risk Operation Confirmation

All 9 tools in this connector are read-only; there are no write operations or payment actions, so no additional confirmation is needed. Regarding membership purchase intentions, only provide price information from list_membership_plans and guide the user to complete the transaction within the PowPop app. Do not make decisions on behalf of the user during the conversation.

---

Last synced: 2026-10-18, corresponding to MCP server version powpow-mcp 0.14.5 (9 tools). When the server tool contract changes (add/delete/modify parameters), this file must be updated and the connector version bumped for resubmission; pure server internal fixes do not require an update.