durenzidu/powpow-workbuddy-connector

Guia de Uso do Conector MCP PowPop (泡泡)

PowPop é um aplicativo social baseado em localização: os usuários descobrem personagens digitais públicos, usuários reais e posts próximos em um mapa, podendo conversar com personagens digitais e participar de campanhas de check-in. Este conector encapsula essas capacidades em 9 ferramentas somente leitura.

Autenticação e Pré-requisitos

• Conteúdo público não requer login: Dados públicos como personagens digitais próximos, posts, atrações, campanhas, planos de assinatura podem ser consultados anonimamente.
• Recursos relacionados a conta exigem autorização: Se a primeira chamada retornar 401, significa que o usuário ainda não concluiu a autorização OAuth. Oriente o usuário a encontrar PowPop nas configurações do conector e concluir a autorização (a página de autorização é fornecida pelo PowPop). Após concluir, tente novamente. O estado de autorização é mantido automaticamente pela plataforma (token renova automaticamente), sem necessidade de perguntar repetidamente.
• Atenção ao sistema de coordenadas: As ferramentas que envolvem coordenadas usam uniformemente GCJ-02 (Coordenadas de Gaode/Marte). Se o usuário fornecer diretamente coordenadas GPS (WGS-84), haverá um desvio de cerca de 300-600 metros. Prefira que o usuário forneça nomes de lugares, que serão convertidos por geocode_place ou pelo parâmetro place das ferramentas.

Visão Geral das Ferramentas

Ferramenta	Finalidade	Parâmetros Chave	Cenário Típico
find_nearby	Descobrir personagens digitais, usuários reais e posts próximos	lat+lng ou place (um dos dois); radius_meters padrão 1000; types pode filtrar por tipo	"O que tem de gente/post perto de mim?"
geocode_place	Converter nome de lugar em coordenadas e reportar confiabilidade	place	Primeiro passo antes de precisar de coordenadas
get_digital_human	Perfil completo do personagem digital (persona/biografia/localização/emoção)	id (de find_nearby)	"Próximo passo" após encontrar um personagem digital
get_post_detail	Post completo + lista de comentários	post_id (de find_nearby/search_posts)	Expandir a discussão de um post
nearby_attractions	Atrações e centros comerciais próximos (por distância)	lat+lng ou place; radius_meters padrão 3000	"O que tem de legal perto daqui?"
search_posts	Buscar posts públicos por palavra-chave	keyword (corresponde ao texto, case-insensitive)	"Posts sobre a Cidade Proibida"
list_campaigns	Listar todas as campanhas públicas (com lista de pontos de check-in)	Nenhum	"Quais campanhas estão rolando?"
list_membership_plans	Preços de assinatura/pacotes	Nenhum	"Quanto custa a assinatura?"
whoami	Verificar identidade atual autorizada	Nenhum	"Quem sou eu?" "Estou logado?"

O schema dos parâmetros baseia-se no retorno em tempo real de tools/list. Acima estão listados apenas parâmetros comuns; se houver discrepância em parâmetros opcionais ou valores padrão, não discuta com o usuário — chame conforme o schema em tempo real.

Como Usar Cada Ferramenta

find_nearby — Ferramenta Principal de Descoberta Próxima

• Escolha de localização: place (nome do local, recomendado, geocodificação automática) > lat+lng (GCJ-02). Se nenhum for passado, o servidor não consegue localizar e retorna um erro.
• types pode filtrar conforme necessário: digital_humans (personagens digitais), users (usuários reais), posts (posts). Padrão: retorna todos.
• Retorna um resumo de cada tipo e a distância. Cartões de personagem digital podem ser expandidos com get_digital_human.
• Exemplo: Usuário diz "O que tem perto do Centro" → { "place": "Centro", "types": ["digital_humans"] }.

geocode_place — Geocodificação de Nome de Local + Confiança

• Retorna lat/lng, matched_name (nome do POI que o servidor realmente encontrou) e confidence (0~1).
• Quando a confiança for inferior a 0.8, você deve informar ao usuário tanto "o nome que você forneceu" quanto "o nome que realmente foi encontrado" para confirmação. Não continue a consulta com a correspondência ambígua como resposta.

get_digital_human — Detalhes do Personagem Digital

• O id deve vir do ID do personagem digital retornado por find_nearby ou outras ferramentas. Não invente.
• Retorna persona (personalidade), biografia, localização e emoção atual. Adequado para apresentar primeiro e depois guiar o usuário para uma conversa.

get_post_detail — Detalhes do Post

• post_id vem do retorno de find_nearby ou search_posts.
• Apenas posts públicos (is_public) podem ser consultados. Posts não públicos retornam um erro legível; informe o usuário exatamente como está.

nearby_attractions — Atrações e Centros Comerciais

• Compartilha as mesmas regras de parâmetros de localização que find_nearby (place ou lat+lng, GCJ-02), raio padrão de 3000 metros.
• Retorna dois grupos: atrações e centros comerciais, cada um com distância. Pode ser combinado em respostas do tipo "recomendações próximas".

search_posts — Busca de Posts por Palavra-chave

• keyword faz uma correspondência difusa case-insensitive no corpo do post.
• Os resultados incluem resumo, localização e link da imagem de capa. Ao citar um post específico, inclua sua localização para uma resposta mais completa.
• Exemplo: "Buscar posts sobre outono" → { "keyword": "outono" }.

list_campaigns — Lista de Campanhas

• Sem parâmetros. Retorna todas as campanhas públicas (ex.: campanha de check-in "100 museus de Pequim"), cada uma com sua lista de pontos de check-in (acts).
• Quando o usuário perguntar "O que tem de campanha/check-in?", priorize chamar esta ferramenta.

list_membership_plans — Planos de Assinatura

• Sem parâmetros. Retorna preços agrupados por canal: pacotes por tempo do Alipay e assinaturas do PayPal/Huawei.
• Chame quando o usuário perguntar sobre preços, assinatura ou pacotes. Repasse os preços fielmente, sem tomar decisões de compra pelo usuário.

whoami — Verificação de Identidade

• Sem parâmetros. Quando autorizado, retorna informações da conta PowPop (apelido, número de emblemas, status de assinatura). Quando não autorizado, indica como conectar.
• Antes de executar qualquer ação "como usuário" ou quando o usuário perguntar sobre identidade/status de login, chame esta ferramenta primeiro.

Tratamento de Erros e Recuperação

Fenômeno	Causa	Ação
401 / Não autorizado	OAuth não concluído ou expirado	Oriente o usuário a reautorizar o PowPop nas configurações do conector e tente novamente
Erro legível no campo error (ex.: "Parâmetro ausente", "Não foi possível analisar")	Parâmetro ausente ou entrada inválida	Corrija os parâmetros conforme a mensagem de erro e tente novamente. Não repasse o erro em inglês para o usuário; traduza para uma dica acionável em português
Resultado vazio (0 itens)	Não há conteúdo público na área/palavra-chave	Informe honestamente "Nada encontrado". Sugira trocar de palavra-chave, aumentar o raio ou mudar de local
Timeout (>30 segundos)	Servidor sem resposta	Não tente novamente repetidamente. Informe o usuário para tentar mais tarde

Confirmação de Operações de Alto Risco

Todas as 9 ferramentas deste conector são somente leitura, não envolvendo operações de escrita ou pagamento, portanto não exigem confirmação adicional. Para intenções de compra de assinatura, forneça apenas as informações de preço de list_membership_plans e oriente o usuário a concluir a compra dentro do aplicativo PowPop. Não tome decisões em nome do usuário durante a conversa.

---

Última sincronização: 18/10/2026, correspondente à versão do servidor MCP powpop-mcp 0.14.5 (9 ferramentas). Quando o contrato da ferramenta do servidor sofrer alterações (adição/remoção/alteração de parâmetros), este arquivo deve ser atualizado e a versão do conector enviada para nova revisão. Correções puramente internas no servidor não exigem atualização.