feat(wordpress): nova skill mcp-bit-social - MCP dedicado BitSocial/BitSocial Pro
Cobre: contas sociais ligadas (+ activar/desactivar), schedules de auto-post e Share Now, logs de publicacao, resumo de falhas por plataforma, analytics, estado da licenca Pro. 12 tools, testado ponta-a-ponta em producao 19-08-2026. references/data-model.md com o schema completo wpah_bit_social_* e references/diagnostics.md com o playbook de investigacao de falhas (inclui o caso real recorrente do Pinterest sem imagem).
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: mcp-bit-social
|
||||
description: 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".
|
||||
layer: 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.
|
||||
Reference in New Issue
Block a user