docs: skill mcp-click-to-chat — MCP Click to Chat for WhatsApp (número, mensagem, toggle, posição/estilo)

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/<site>`) 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.