diff --git a/wordpress/skills/mcp-click-to-chat/SKILL.md b/wordpress/skills/mcp-click-to-chat/SKILL.md new file mode 100644 index 0000000..ae900ce --- /dev/null +++ b/wordpress/skills/mcp-click-to-chat/SKILL.md @@ -0,0 +1,109 @@ +--- +name: mcp-click-to-chat +description: MCP dedicado multi-site (node stdio, ligação `click-to-chat` em ~/.omp/agent/mcp.json) para gerir o Click to Chat for WhatsApp (HoliThemes) em qualquer site do bundle Descomplicar® via WP-CLI/SSH — estado do plugin, config completa, número de WhatsApp, mensagem pré-preenchida, call-to-action, activar/desactivar o widget globalmente, posição e estilo do botão flutuante. Site é um parâmetro em cada tool, não uma ligação fixa. Usar quando "click to chat mcp", "número whatsapp site", "widget whatsapp wordpress", "botão flutuante whatsapp", "mensagem pré-preenchida whatsapp", "ht_ctc_chat_options", "desactivar botão whatsapp", "posição botão whatsapp". +layer: wiki +--- + +# /mcp-click-to-chat — MCP dedicado multi-site ao Click to Chat for WhatsApp + +Projecto em `/media/ealmeida/Dados/Dev/mcp-click-to-chat/` (TypeScript, SDK MCP oficial, stdio). +Sem código PHP novo no WordPress — cada tool executa `wp option get/update --format=json` via +`ssh server` sobre o WP-CLI já instalado. **`site` é um parâmetro em cada tool**, não uma ligação +fixa: o plugin está espalhado por vários sites reais do bundle com dados diferentes por site. + +Não existe skill de conhecimento separada para este plugin — esta skill É a documentação +completa, incluindo o mapeamento de options. O plugin tem duas interfaces internas ("new" 2019+ e +"prev" legada, ver `common/class-ht-ctc-switch.php`); **todos os sites do bundle usam a interface +"new"** (a legada só se activa se a option `ccw_options` tiver a chave `number`, o que não +acontece em nenhum site verificado) — por isso este MCP só lê/escreve as options `ht_ctc_*`. + +## Âmbito + +Config do widget flutuante de WhatsApp (versão **Free** — nenhum site do bundle tem o addon PRO +`click-to-chat-pro.php` instalado, por isso não há múltiplos agentes/departamentos, apenas um +número principal). Não cobre: activação/desactivação do próprio plugin (`emcp-tools +activate-plugin`/`deactivate-plugin` cobre isso genericamente), estilos de cor detalhados por +variante (`ht_ctc_s1`..`ht_ctc_s9` — cosméticos por `style_desktop`/`style_mobile` escolhido, fora +do âmbito deste MCP), integração de Analytics/GTM/Pixel (`ht_ctc_othersettings`), Grupos de +WhatsApp ou Share button (`ht_ctc_group`/`ht_ctc_share`), WooCommerce (`ht_ctc_woo_options`). + +## Sites conhecidos + +Chamar `ctc_list_sites` para a lista actual com path e nota de estado. Verificado ao vivo +19-08-2026 (`wp plugin list` por site, slug `click-to-chat-for-whatsapp` 4.42.1, update 4.43 +disponível em todos): + +- **Activos:** `emanuelalmeida` (número real configurado, `+351919109155`), `starter` (activo mas + sem número configurado — config vazia), `ccv` (número real configurado), `ecommerce` (activo). +- **Instalado mas inactivo:** `descomplicar` (produção, `public_html`), `ecommerce-demo`. +- **Não instalado:** `care`, `e-commerce`. + +Também aceita um path absoluto directamente (`/home/ealmeida/`) para sites fora desta lista, +sem exigir rebuild do MCP. + +## Mapeamento de dados + +Option principal: **`ht_ctc_chat_options`** (array PHP nativo — ver §Segurança). Campos usados por +este MCP: + +| Campo | Tool que lê/escreve | Descrição | +|---|---|---| +| `number` | `ctc_get_number` / `ctc_update_number` | Número de WhatsApp principal, com indicativo. Legado: `cc`+`num` (interface "prev", sempre limpos por `ctc_update_number`) | +| `pre_filled` | `ctc_get_number` / `ctc_update_message` | Mensagem já escrita na conversa ao clicar | +| `call_to_action` | `ctc_get_number` / `ctc_update_message` | Texto do tooltip/balão junto ao botão | +| `display.global_display` | `ctc_get_config` / `ctc_toggle_widget` | `show`/`hide` — liga/desliga o widget em todo o site | +| `display.home`/`pages`/`posts`/`list_showon_pages`/etc. | `ctc_get_config` (só leitura) | Excepções por tipo de página ao valor global — não alteradas por este MCP | +| `style_desktop`/`style_mobile` | `ctc_get_config` / `ctc_update_position_style` | Id do estilo pré-definido do botão, `"1"`–`"9"` (paleta de cada um em `ht_ctc_s1`..`ht_ctc_s9`, fora do âmbito) | +| `side_1`/`side_1_value` | `ctc_get_config` / `ctc_update_position_style` | Lado vertical (`top`/`bottom`) + offset CSS (ex. `"15px"`) | +| `side_2`/`side_2_value` | `ctc_get_config` / `ctc_update_position_style` | Lado horizontal (`left`/`right`) + offset CSS | +| `mobile_side_*`, `same_settings` | `ctc_get_config` (só leitura) | Posição mobile — segue a desktop enquanto `same_settings` = `"1"` (comportamento nativo) | + +## Tools (8) + +| Tool | Read-only | Uso | +|---|---|---| +| `ctc_list_sites` | sim | Aliases conhecidos, path WP, nota de estado | +| `ctc_get_status` | sim | Instalado/activo, versão, update disponível — chamar antes dos outros tools | +| `ctc_get_config` | sim | Option `ht_ctc_chat_options` completa (número, mensagem, posição, estilo, regras de exibição) | +| `ctc_get_number` | sim | Só `number`, `pre_filled`, `call_to_action`, `intl_country` — resposta enxuta. Free = um único número, sem multi-agente | +| `ctc_update_number` | não | Actualiza `number` com validação (8-15 dígitos após limpeza, igual a `HT_CTC_Formatting::wa_number()` do próprio plugin). Limpa `cc`/`num` legados | +| `ctc_update_message` | não | Actualiza `pre_filled` e/ou `call_to_action` — passa só o(s) campo(s) a mudar | +| `ctc_toggle_widget` | não | `enabled: true/false` → `display.global_display` = `show`/`hide`. Não toca nas excepções por página | +| `ctc_update_position_style` | não | `style_desktop`/`style_mobile` (`"1"`-`"9"`) e/ou `side_1`/`side_1_value`/`side_2`/`side_2_value` — passa só o(s) campo(s) a mudar | + +Todas as tools de escrita fazem read-modify-write (merge), nunca substituição completa da option. +`site` é obrigatório em todas. + +## Segurança + +Allowlist fixa de 3 nomes de option `ht_ctc_*` relevantes (`src/wpcli.ts`, `OPTION_KEYS`) — nunca +`wp option update` genérico sobre uma chave arbitrária. Escritas via base64 em stdin, nunca +interpoladas no comando SSH remoto. Validação de número de WhatsApp em `ctc_update_number` +(mínimo 8, máximo 15 dígitos após remover tudo excepto dígitos). + +**Formato de armazenamento confirmado (caso seguro):** `ht_ctc_chat_options` e as restantes +options `ht_ctc_*` são gravadas pelo próprio plugin via `update_option( 'ht_ctc_xxx', $array_php +)` — array PHP nativo, não uma string com JSON lá dentro (confirmado lendo +`new/admin/db/class-ht-ctc-db.php`, e comparando ao vivo a saída de `wp option get` sem formato +vs. `--format=json` em `emanuelalmeida.pt` — ambas descodificam o mesmo array, sem dupla +codificação). Por isso `getOption`/`setOption` deste MCP usam `--format=json` directamente, ao +contrário do `mcp-wpfc` (ver essa skill para o caso inverso, o gotcha de string-com-JSON-lá-dentro +que corrompeu produção nesse plugin). + +## Verificação + +Construído e testado ponta-a-ponta contra produção 19-08-2026: `ctc_get_status`/`ctc_get_config`/ +`ctc_get_number` confirmaram os dados reais em `emanuelalmeida` (número `+351919109155`, +call-to-action "Vamos conversar?"); `ctc_update_message` (call-to-action idempotente), +`ctc_toggle_widget` (`enabled:true` idempotente) e `ctc_update_position_style` (valores +idempotentes) testados em `ccv`, cada um confirmado por leitura SSH directa antes/depois — +`ht_ctc_chat_options` ficou byte-a-byte igual, incluindo o objecto aninhado `display`; +`ctc_update_number` testado em `starter` com um número real (`+351 910 000 000` → normalizado para +`+351910000000`, confirmado por leitura SSH directa), depois restaurado ao estado original vazio +(também confirmado por leitura). + +## Skills relacionadas + +- `mcp-wpfc` — mesmo padrão de arquitectura, mas com o gotcha inverso de formato de armazenamento + (string PHP com JSON lá dentro) — ler antes de construir um MCP novo sobre outro plugin. +- `emcp-tools` — activação/desactivação genérica de plugins, fora do âmbito deste MCP.