---
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.