claude-plugins/wordpress/skills/mcp-bit-social/SKILL.md

name, description, layer

name	description	layer
mcp-bit-social	MCP dedicado (node stdio, ligação `bit-social` em ~/.omp/agent/mcp.json) para o BitSocial/BitSocial Pro (BitApps) em descomplicar.pt — a automação que publica os artigos do blog em Facebook, LinkedIn, Pinterest e Tumblr. Contas sociais ligadas, schedules de auto-post e "Share Now", logs de publicação, resumo de falhas por plataforma, analytics, estado da licença. Usar quando "bitsocial", "porque falhou a publicação no Pinterest/Facebook/LinkedIn", "contas sociais ligadas", "logs de publicação social", "auto-post settings", "schedule bitsocial", "desactivar conta social", "licença bitsocial pro".	wiki

/mcp-bit-social — MCP dedicado BitSocial / BitSocial Pro

Projecto em /media/ealmeida/Dados/Dev/mcp-bit-social/ (TypeScript, SDK MCP oficial, stdio). Independente porque as rotas HTTP do próprio plugin (backend/routes/*.php) exigem sessão wp-admin autenticada + nonce (Route::noAuth()->middleware('nonce:admin')) — sem caminho headless razoável. Sem código PHP novo no WordPress: cada tool corre wp db query/wp option get via ssh server sobre o WP-CLI já instalado, contra o schema wpah_bit_social_* e as wp_options do plugin.

Âmbito

Diagnóstico e gestão de contas, schedules e logs de publicação — o domínio onde as falhas reais acontecem (produção tem 175 schedules, 1825 logs, ~50% falha histórica em Pinterest por imagem em falta). Não cobre a UI de composição/edição de templates de post nem o fluxo OAuth de ligar uma conta nova — isso continua a fazer-se no wp-admin.

Tools (12)

Estado e analytics (read-only):

• bs_get_plugin_status — versões free/pro, db versions, licença Pro (chave mascarada), cron externo.
• bs_get_analytics — contas activas, schedules activos, publicações OK/falhadas (soma de logs).

Contas:

• bs_list_accounts (read-only) — filtra por platform/status. Nunca devolve details (contém o access_token OAuth em claro).
• bs_set_account_status — única write tool; liga/desliga uma conta (mirror 1:1 de AccountController::updateStatus, só a coluna status). Uma conta desactivada sai da rotação de auto-post/share-now sem perder a ligação OAuth.

Configuração (read-only):

• bs_list_custom_apps — apps de API próprias (nunca credential, segredo cifrado).
• bs_list_groups — grupos de contas (Pro), com as contas membro.
• bs_get_auto_post_settings — bit_social_auto_post_settings: post types/taxonomias que disparam auto-post, contas/grupos alvo, atraso de publicação.
• bs_get_social_templates — bit_social_templates_settings: template de conteúdo por plataforma (imagem destacada / link card / só texto).

Schedules e diagnóstico (read-only):

• bs_list_schedules — schedule_type=schedule_share (auto-post recorrente) e direct_share ("Share Now") vivem na mesma tabela; filtra por status/tipo/nome, paginado.
• bs_get_schedule — detalhe completo de um schedule, incluindo config (filtros de posts, contas alvo, templates) e published_post_ids.
• bs_list_logs — um log por (schedule × plataforma) tentado; details inclui o erro da plataforma em caso de falha. Ferramenta principal de diagnóstico.
• bs_get_failure_summary — falhas dos últimos N dias agrupadas por plataforma, até 5 mensagens de erro distintas por plataforma.

Segurança

Nunca selecciona accounts.details (access_token OAuth em claro) nem custom_apps.credential (segredo cifrado). bs_get_plugin_status mascara a chave de licença Pro (só os últimos 4 caracteres). Texto livre (pesquisa por nome) viaja como SQL escapado (sqlString), nunca interpolado na linha de comando SSH.

Gotcha de infra-estrutura

wp db query shella para o mysql CLI, que em modo batch re-escapa backslashes nos valores — sem a flag --raw, qualquer JSON_OBJECT/JSON_ARRAYAGG que aninhe uma coluna já-JSON (ex.: config, details) fica com JSON inválido (\" vira \\"). O MCP já corre sempre com --raw; relevante só ao escrever queries SQL BitSocial novas fora deste MCP.

Verificação

Construído e testado ponta-a-ponta contra produção 19-08-2026: as 12 tools exercitadas com dados reais (4 contas, 175 schedules, 1825 logs), incluindo o caso de falha real recorrente ("Must have image for create pin in Pinterest.", 39 ocorrências/60 dias) e um round-trip de escrita idempotente em bs_set_account_status (confirmado no updated_at da BD).

Recursos adicionais

• references/data-model.md — schema completo das tabelas wpah_bit_social_*, enums (Schedule::status/scheduleType, Account::accountType), forma dos campos JSON aninhados (config, details, bit_social_auto_post_settings, bit_social_templates_settings).
• references/diagnostics.md — playbook: investigar uma publicação falhada, pausar uma conta sem a desligar, ver o que está configurado para auto-post.