wordpress/wp-fastest-cache: MCP wpfc construido e testado em producao (§16)

- estado real por site actualizado: 8 sites WP reais do bundle, nao 7
  (ccv, care, ecommerce-demo, ecommerce, e-commerce mapeados)
- pergunta em aberto sobre camada de cache em descomplicar.pt respondida:
  nenhum plugin de page-cache activo hoje, so edge Cloudflare
- achado critico documentado: options WPFC sao strings PHP planas com
  JSON dentro, nao JSON tipado do WP-CLI -- usar --format=json causa
  dupla codificacao e corrompe a option (reproduzido e corrigido)
- 18 tools testados ponta-a-ponta contra producao (descomplicar.pt, ccv)

wordpress/skills/wp-fastest-cache/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wp-fastest-cache
-description: Gestão completa do WP Fastest Cache (page cache HTML local) via WP-CLI em servidores CWP. Cobre purga de cache nativa (`wp fastest-cache clear`), diferença entre page cache (WPFC) e object cache (Redis), preload após publicar, minify HTML/CSS/gzip, exclusão de páginas/cookies/user-agents, Clearing Specific Pages, integração CDN (Cloudflare/MaxCDN/genérica) e Varnish, customização do caminho da cache, matriz Free vs Premium, estado real Premium por site (§16.1), plano do MCP `wpfc-mcp` multi-site (§16), e sequência de purga completa (WPFC + Cloudflare) após deploys ou mudanças de config. Usar quando "wp fastest cache", "wpfc", "purgar cache", "limpar cache wordpress", "cache não actualiza", "preload cache", "minify html", "combine css", "gzip wordpress", "excluir página cache", "cache timeout", "cdn wordpress", "clearing specific pages", "varnish wordpress", "wpfc mcp", "wp fastest pro".
+description: Gestão completa do WP Fastest Cache (page cache HTML local) via WP-CLI e via o MCP `wpfc` (projecto `mcp-wpfc`, multi-site, 18 tools). Cobre purga de cache nativa (`wp fastest-cache clear`), diferença entre page cache (WPFC) e object cache (Redis), preload após publicar, minify HTML/CSS/gzip, exclusão de páginas/cookies/user-agents, Clearing Specific Pages, integração CDN (Cloudflare/MaxCDN/genérica) e Varnish, customização do caminho da cache, matriz Free vs Premium, estado real Premium por site (§16.1), achado crítico sobre formato de armazenamento das options (string JSON, não JSON tipado — §16.2), e sequência de purga completa (WPFC + Cloudflare) após deploys ou mudanças de config. Usar quando "wp fastest cache", "wpfc", "purgar cache", "limpar cache wordpress", "cache não actualiza", "preload cache", "minify html", "combine css", "gzip wordpress", "excluir página cache", "cache timeout", "cdn wordpress", "clearing specific pages", "varnish wordpress", "wpfc mcp", "wp fastest pro", "mcp-wpfc".
 ---
 
 # /wp-fastest-cache — Gestão do WP Fastest Cache via WP-CLI
@@ -725,18 +725,24 @@ wp plugin list --path=$PATH --format=json | grep -i "fastest-cache"
 | Confirmar se o addon Premium está activo | `wp plugin list --format=json | grep fastest-cache` (§13) |
 | Bloquear cache de 1 página sem criar regra | Inserir `[wpfcNOT]` no conteúdo via botão do editor (§7.4) |
 
-
-## 16. MCP planeado (`wpfc-mcp`) — 19-08-2026, ainda por construir
+## 16. MCP construído (`wpfc`, projecto `mcp-wpfc`) — 19-08-2026, ao vivo
 
 ### 16.1 Estado real por site (corrige a afirmação de §13)
 
-Verificado ao vivo via `wp plugin list --format=json` em 3 sites do bundle:
+Verificado ao vivo via `wp plugin list --format=json` em 8 sites WordPress
+reais do bundle (não 7 — `care.descomplicar.pt`, `ecommerce-demo.descomplicar.pt`
+e `ecommerce.descomplicar.pt` são instalações WP reais adicionais sem WPFC):
 
 | Site | `wp-fastest-cache` | `wp-fastest-cache-premium` | Cache HTML activa? |
 |---|---|---|---|
 | `emanuelalmeida.pt` | active, v1.5.0 | não instalado | sim (Free) |
 | `starter.descomplicar.pt` | active, v1.5.0 | não instalado | sim (Free) |
+| `ccv.descomplicar.pt` | active, v1.5.0 | não instalado | sim (Free) |
 | `descomplicar.pt` (produção) | **inactive**, v1.5.0 | **inactive**, v1.7.7 | **não** — nem Free nem Premium activos |
+| `e-commerce.descomplicar.pt` | inactive, v1.5.0 | não instalado | não |
+| `care.descomplicar.pt` | não instalado | não instalado | não |
+| `ecommerce-demo.descomplicar.pt` | não instalado | não instalado | não |
+| `ecommerce.descomplicar.pt` | não instalado | não instalado | não |
 
 `descomplicar.pt` é o único site confirmado com o addon Premium **no disco**
 (1.7.7), mas está inactivo tal como o Free — a config antiga em
@@ -745,46 +751,102 @@ a chave Premium `wpFastestCacheGoogleFonts: "on"` (só tem efeito com
 `WpFastestCachePowerfulHtml` a existir, ou seja, nunca teve efeito real desde
 que o Premium está inactivo).
 
-### 16.2 Decisão de âmbito
+**Pergunta em aberto de §16.2 (versão anterior) respondida:** `descomplicar.pt`
+não tem NENHUM plugin de HTML page-cache activo hoje (confirmado via
+`wp plugin list` — nem WPFC Free/Premium, nem outro concorrente; `webp-express`
+é o único plugin de optimização activo). Também sem drop-in
+`object-cache.php` (Redis inactivo) e sem headers `cache-control`/`x-cache`
+na resposta ao vivo — o site depende só da edge Cloudflare (proxy laranja)
+para qualquer camada de cache. **Conclusão: seguro construir e testar o MCP
+em produção; activar o Premium continua por decidir à parte** (fora do
+âmbito desta sessão — activação de plugin já é coberta pelo `emcp-tools
+activate-plugin` genérico, não precisa deste MCP).
 
-- **Multi-site**: o MCP terá parâmetro `site` (não uma ligação fixa por
-  site como `element-pack`/`rank-math-mcp`) — WPFC está espalhado pelos 7
-  sites do bundle com estados diferentes, ao contrário do Element Pack Pro
-  (só descomplicar.pt) ou do Rank Math (licença bundle, mas MCP oficial
-  por site).
-- **Activar o Premium em `descomplicar.pt`**: decisão tomada, ainda por
-  executar — implica activar `wp-fastest-cache-premium` num site de
-  produção, o que muda comportamento real (possível colisão com WP Meteor
-  §2.5 do ecossistema, Redis Object Cache, App for Cloudflare® — ver §3
-  desta skill sobre as 3 camadas). **Validar antes de activar**: confirmar
-  que não há outro plugin de HTML page-cache já activo em `descomplicar.pt`
-  agora que se sabe que WPFC lá está desligado (o que está a servir cache
-  HTML nesse site hoje, se é que algo está?) — pergunta em aberto, por
-  responder antes da activação.
+### 16.2 Achado crítico de implementação: formato de armazenamento das options
 
-### 16.3 Catálogo de tools previsto (derivado de §1-13 desta skill)
+**As 7 options WPFC (`WpFastestCache`, `WpFastestCacheExclude`,
+`WpFastestCacheCSP`, `WpFastestCacheCDN`, `WpFastestCacheVarnish`,
+`WpFastestCachePathSettings`, `WpFastestCacheToolbarSettings`) são strings
+PHP planas cujo conteúdo é texto JSON — NÃO são options JSON tipadas do
+WP-CLI.** Confirmado via `wp option get WpFastestCache` (sem `--format=json`):
+devolve um array PHP `{0 => '{', 1 => '"', 2 => 'w', ...}` — ou seja, o
+*valor* já é uma string de caracteres, e o WP-CLI está a mostrar essa string
+char a char porque o plugin fez `json_encode($array)` ao gravar, não
+`update_option()` sobre um array PHP nativo.
 
-Leitura (8): status geral (master switch + premium instalado/activo +
-versão), config principal (`WpFastestCache` completa), regras de exclusão
-(§7), regras CSP (§9), config CDN (§10.1), config Varnish (§10.3),
-definições de caminho (§11), definições de toolbar (§12.2).
+**Bug reproduzido e corrigido durante o build:** a primeira versão do MCP
+usava `wp option get/update --format=json` (o padrão copiado de
+`mcp-element-pack`, correcto lá porque as options do Element Pack Pro são
+arrays PHP nativos). Em `WpFastestCache` isto causa **dupla codificação**:
 
-Escrita (10): purgar cache (`all` / `all and minified` / por `post_id`,
-§2), definir/remover 1 chave da config principal — cobre tanto chaves Free
-como Premium (Lazy Load, Minify JS, Delay JS, etc., §1.1), já que ambas
-vivem na mesma option `WpFastestCache`; adicionar/remover regra de
-exclusão; adicionar/remover regra CSP; definir config CDN; definir config
-Varnish; definir caminho de cache; definir toolbar settings.
+1. Leitura com `--format=json` de uma string já-JSON devolve essa string
+   **entre aspas** (`"{\"wpFastestCacheStatus\": \"on\", ...}"`). Um único
+   `JSON.parse()` do lado do cliente devolve uma **string**, não um objecto.
+2. `{...string, ...novasChaves}` em JavaScript faz *spread* de uma string
+   como se fosse um array de caracteres — produz um objecto `{0: '{', 1: '"',
+   2: 'w', ...}` com as novas chaves misturadas.
+3. Escrever esse objecto de volta com `--format=json` grava um array PHP
+   indexado por número na base de dados — **corrompe a option**, o plugin
+   deixa de conseguir lê-la (`json_decode()` falha silenciosamente,
+   `getOption()` volta a defaults).
 
-Chaves Premium só têm efeito real depois de 16.2 estar resolvido — o tool
-de escrita da config principal deve confirmar `wp-fastest-cache-premium`
-activo antes de aceitar uma chave Premium, devolvendo erro accionável em
-vez de gravar um no-op silencioso (mesmo padrão de guarda usado em
-`mcp-element-pack` para a licença).
+Isto **corrompeu de facto `WpFastestCache` em `descomplicar.pt`** durante o
+teste (verificado via `wp option get` sem `--format=json`, mostrando o array
+de caracteres). Restaurado imediatamente a partir do valor exacto capturado
+antes do bug (`wp option get --format=json` da leitura de diagnóstico
+original desta sessão) — confirmado idêntico ao original, só difere um `\n`
+final inofensivo.
 
-**Por fazer:** validar a pergunta em aberto de §16.2, construir o projecto
-(`~/.omp/agent/mcp.json` → `wpfc-mcp`), testar leitura+escrita ao vivo,
-registar em `ECOSSISTEMA-WORDPRESS.md`.
+**Correcção aplicada:** `getOption`/`setOption` do MCP nunca usam
+`--format=json`. Leitura: `wp option get '<key>' --path=... --allow-root`
+(raw), depois `JSON.parse()` uma única vez no cliente. Escrita: o valor
+JavaScript é `JSON.stringify()`-ado e enviado como string crua (via base64
+em stdin) para `wp option update '<key>' --path=... --allow-root` (sem
+`--format=json`), replicando exactamente o que o próprio plugin faz.
+
+**Lição para MCPs futuros que envolvam `wp option`:** nunca assumir que
+`--format=json` é seguro só porque o valor "parece JSON" no `get` — testar
+sempre `wp option get <key>` **sem** a flag primeiro, para confirmar se o
+tipo real na BD é uma string-com-JSON-dentro (como aqui) ou um array PHP
+nativo (como no Element Pack Pro, `element_pack_active_modules` etc.) antes
+de escolher o padrão de leitura/escrita.
+
+### 16.3 Sites cobertos e tools (18)
+
+Projecto `/media/ealmeida/Dados/Dev/mcp-wpfc`, registado em
+`~/.omp/agent/mcp.json` como `wpfc`. Parâmetro `site` em cada tool (alias
+conhecido de §16.1 ou path absoluto) — cobre os 8 sites reais do bundle
+numa só ligação, ao contrário de `element-pack`/`rank-math-mcp` (uma
+ligação fixa por site).
+
+- `wpfc_list_sites` — sites conhecidos com path e nota de estado.
+- `wpfc_get_status` — instalado/activo/versão, Free e Premium.
+- `wpfc_get_config` / `wpfc_set_config` — option `WpFastestCache` completa;
+  `wpfc_set_config` faz merge (read-modify-write) e **recusa gravar
+  qualquer chave só-Premium** (lista em `PREMIUM_ONLY_CONFIG_KEYS`,
+  §1.1 desta skill) a menos que confirme `wp-fastest-cache-premium` activo
+  ou receba `force_premium: true`.
+- `wpfc_purge_cache` — `all` / `all_minified` / `post` (`--post_id`).
+- `wpfc_get_exclude` / `wpfc_set_exclude` — `WpFastestCacheExclude` (§7).
+- `wpfc_get_csp` / `wpfc_set_csp` — `WpFastestCacheCSP` (§9).
+- `wpfc_get_cdn` / `wpfc_set_cdn` — `WpFastestCacheCDN` (§10.1).
+- `wpfc_get_varnish` / `wpfc_set_varnish` — `WpFastestCacheVarnish` (§10.3).
+- `wpfc_get_pathSettings` / `wpfc_set_pathSettings` — `WpFastestCachePathSettings` (§11).
+- `wpfc_get_toolbarSettings` / `wpfc_set_toolbarSettings` — `WpFastestCacheToolbarSettings` (§12.2).
+
+As 6 options estruturadas (`set_exclude`/`csp`/`cdn`/`varnish`/`pathSettings`/`toolbarSettings`)
+são **substituição completa**, não merge — enviar sempre a lista/objecto
+desejado por inteiro.
+
+**Testado ponta-a-ponta contra produção (19-08-2026):** `wpfc_get_status`
+em `descomplicar` e `ccv` confirmou os dados reais de §16.1;
+`wpfc_set_config` com uma chave Premium (`wpFastestCacheGoogleFonts`) foi
+correctamente recusado em `descomplicar` (Premium inactivo); com uma chave
+Free (`wpFastestCacheDisableEmojis: "on"`, já `"on"` — sem alterar
+comportamento) escreveu e releu correctamente, confirmado por leitura SSH
+directa fora do MCP; `wpfc_get_exclude`/`wpfc_set_exclude` testado em
+`ccv` (fallback `[]` → escrita `[]` → releitura `[]`); `wpfc_purge_cache`
+executado com sucesso em `ccv` (`Success: The cache has been cleared!`).
 
 ---