durenzidu/powpow-workbuddy-connector

Guía de uso del conector PowPop MCP

PowPop es una aplicación social basada en ubicación: los usuarios descubren humanos digitales públicos, usuarios reales y publicaciones cercanas en un mapa, pueden chatear con humanos digitales y participar en eventos de check-in. Este conector encapsula estas capacidades en 9 herramientas de solo lectura.

Autenticación y requisitos previos

• El contenido público no requiere inicio de sesión: los datos públicos como humanos digitales cercanos, publicaciones, atracciones, eventos y planes de membresía se pueden consultar de forma anónima.
• Las capacidades relacionadas con la cuenta requieren autorización: si la primera llamada devuelve un 401, significa que el usuario aún no ha completado la autorización OAuth. Guíe al usuario para que encuentre PowPop en la configuración del conector y complete la autorización (la página de autorización es proporcionada por PowPop). Una vez completada, reintente. El estado de autorización se mantiene automáticamente por la plataforma (renovación automática del token), no es necesario preguntar repetidamente.
• Atención al sistema de coordenadas: las herramientas que involucran coordenadas usan uniformemente GCJ-02 (coordenadas de Gaode/Marte). Si el usuario proporciona directamente latitud/longitud GPS (WGS-84), puede haber un error de 300–600 metros; priorice permitir que el usuario proporcione un nombre de lugar, y use geocode_place o el parámetro place de la herramienta para la conversión.

Resumen de herramientas

Herramienta	Uso	Parámetros clave	Escenario típico
find_nearby	Descubrir humanos digitales, usuarios reales y publicaciones cercanas	lat+lng o place (elegir uno); radius_meters por defecto 1000; types para filtrar por tipo	«¿Qué personas/publicaciones hay cerca de mí?»
geocode_place	Convertir nombre de lugar a latitud/longitud e informar confianza de coincidencia	place	Primer paso antes de necesitar coordenadas
get_digital_human	Perfil completo de un humano digital (personalidad/biografía/ubicación/estado de ánimo)	id (de find_nearby)	Siguiente paso después de encontrar un humano digital
get_post_detail	Texto completo de la publicación + lista de comentarios	post_id (de find_nearby/search_posts)	Expandir la discusión de una publicación
nearby_attractions	Atracciones y zonas comerciales cercanas (por distancia)	lat+lng o place; radius_meters por defecto 3000	«¿Qué lugares interesantes hay cerca?»
search_posts	Buscar publicaciones públicas por palabra clave	keyword (coincide con el texto, sin distinción de mayúsculas/minúsculas)	«Publicaciones sobre la Ciudad Prohibida»
list_campaigns	Listar todos los eventos públicos (incluye lista de puntos de check-in)	Ninguno	«¿Qué eventos hay ahora?»
list_membership_plans	Precios de membresías/paquetes	Ninguno	«¿Cuánto cuesta la membresía?»
whoami	Verificar la identidad autorizada actual	Ninguno	«¿Quién soy?», «¿Estoy autenticado?»

El esquema de parámetros se basa en la respuesta en tiempo real de tools/list. Arriba solo se enumeran los parámetros comunes; si hay diferencias con los parámetros opcionales o valores predeterminados, no discuta con el usuario, simplemente llame según el esquema en tiempo real.

Puntos clave de uso de cada herramienta

find_nearby — Herramienta principal de descubrimiento cercano

• Ubicación: elija una de tres: place (nombre de lugar, recomendado, codificación automática) > lat+lng (GCJ-02). Si no se proporciona ninguna, el servidor no puede ubicar y devolverá un error.
• types puede filtrar según sea necesario: digital_humans (humanos digitales) / users (usuarios reales) / posts (publicaciones), por defecto devuelve todos.
• La respuesta incluye un resumen de cada tipo y la distancia; las tarjetas de humanos digitales se pueden expandir con get_digital_human.
• Ejemplo: el usuario dice «¿Qué personas hay cerca de Guomao?» → { "place": "Guomao", "types": ["digital_humans"] }.

geocode_place — Codificación de nombres de lugares + confianza

• Devuelve lat/lng, matched_name (nombre POI realmente coincidente por el servidor) y confidence (0~1).
• Cuando la confianza sea inferior a 0.8, debe informar al usuario tanto «el nombre de lugar que ingresó» como «el nombre de lugar realmente coincidente» para que confirme; no use directamente una coincidencia difusa como respuesta para continuar la consulta.

get_digital_human — Detalles del humano digital

• id debe provenir del ID del humano digital devuelto por herramientas como find_nearby, no lo invente.
• Devuelve personalidad (persona), biografía, ubicación y estado de ánimo actual; adecuado para presentar primero y luego guiar al usuario a conversar.

get_post_detail — Detalles de la publicación

• post_id proviene de la respuesta de find_nearby o search_posts.
• Solo se pueden consultar publicaciones públicas (is_public); las publicaciones no públicas devolverán un error legible, simplemente informe al usuario.

nearby_attractions — Atracciones y zonas comerciales

• Comparte las mismas convenciones de parámetros de ubicación que find_nearby (place o lat+lng, GCJ-02), radio predeterminado de 3000 metros.
• Devuelve dos grupos: atracciones (attractions) y zonas comerciales (business_districts), cada uno con distancia; se pueden combinar en respuestas de tipo «recomendaciones cercanas».

search_posts — Búsqueda de publicaciones por palabra clave

• keyword realiza una coincidencia difusa sin distinción de mayúsculas/minúsculas en el texto de la publicación.
• Los resultados incluyen resumen, ubicación y enlace de imagen de portada; al citar una publicación específica, priorice incluir su información de ubicación para una respuesta más completa.
• Ejemplo: «Buscar publicaciones sobre el otoño» → { "keyword": "otoño" }.

list_campaigns — Lista de eventos

• Sin parámetros. Devuelve todos los eventos públicos (por ejemplo, evento de check-in «100 museos de Pekín»), cada evento incluye una lista de puntos de check-in (acts).
• Cuando el usuario pregunte «¿Qué eventos/hay check-in?», priorice llamar a esta herramienta.

list_membership_plans — Planes de membresía

• Sin parámetros. Devuelve precios agrupados por canal: paquetes de duración de Alipay y suscripciones de PayPal/Huawei.
• Llámela cuando el usuario pregunte por precios, membresías o paquetes; informe los precios fielmente, no tome decisiones de compra por el usuario.

whoami — Verificación de identidad

• Sin parámetros. Cuando está autorizado, devuelve la información de la cuenta PowPop (apodo, número de insignias, estado de membresía); cuando no está autorizado, indica cómo conectar.
• Antes de realizar cualquier acción «como usuario», o cuando el usuario pregunte por su identidad/estado de inicio de sesión, llame primero a esta herramienta.

Manejo de errores y recuperación

Síntoma	Causa	Acción
401 / No autorizado	OAuth no completado o caducado	Guíe al usuario para reautorizar PowPop en la configuración del conector y luego reintente
Error legible en el campo error (p. ej., «Falta parámetro», «No se puede analizar»)	Parámetro faltante o entrada inválida	Corrija los parámetros según el mensaje de error y reintente; no muestre el error en inglés al usuario directamente, tradúzcalo a un mensaje accionable en español
Resultado vacío (0 elementos)	No hay contenido público en esa área/palabra clave	Informe honestamente «No se encontró», puede sugerir al usuario cambiar la palabra clave, ampliar el radio o cambiar de ubicación
Tiempo de espera (>30 segundos)	El servidor no responde	No reintente continuamente; informe al usuario que lo intente más tarde

Confirmación de operaciones de alto riesgo

Las 9 herramientas de este conector son todas de solo lectura, no existen operaciones de escritura ni pagos, no se necesita confirmación adicional. En cuanto a la intención de comprar una membresía, solo proporcione la información de precios de list_membership_plans y guíe al usuario a completarla dentro de la aplicación PowPop, sin tomar decisiones por el usuario en la conversación.

---

Última sincronización: 2026-10-18, correspondiente a la versión del servidor MCP powpow-mcp 0.14.5 (9 herramientas). Cuando el contrato de herramientas del servidor cambie (agregar/eliminar/modificar parámetros), este archivo debe actualizarse y la versión del conector debe aumentarse para una nueva revisión; las correcciones puramente internas del servidor no requieren actualización.