ealmeida
70b2866edf
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).
82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
---
|
||
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.
|