---
name: mcp-webp-express
description: MCP dedicado multi-site (node stdio, ligação `webpx` em ~/.omp/agent/mcp.json) para gerir o WebP Express em qualquer site do bundle Descomplicar® via WP-CLI/SSH — estado do plugin, ficheiro de config completo (modo de operação, qualidade jpeg/png, stack de conversores), conversão em massa, flush de webps. Site é um parâmetro em cada tool, não uma ligação fixa. Usar quando "converter webp via mcp", "webpx mcp", "config webp express mcp", "conversores webp mcp", "flush webp mcp", "convert webp mcp".
layer: wiki
---

# /mcp-webp-express — MCP dedicado multi-site ao WebP Express

Projecto em `/media/ealmeida/Dados/Dev/mcp-webp-express/` (TypeScript, SDK MCP oficial, stdio).
Mesmo padrão do `mcp-wpfc`/`mcp-element-pack`: sem código PHP novo no WordPress, cada tool executa
`wp option get`, leitura/escrita directa no ficheiro de config, ou
`wp webp-express convert|flushwebp` via `ssh server` sobre o WP-CLI já instalado. `site` é um
parâmetro em cada tool, não uma ligação fixa — WebP Express está activo nos 8 sites reais do
bundle.

**Relação com a skill `webp-express`:** essa skill é a fonte de conhecimento (mapeamento completo
de todas as chaves do ficheiro de config, modos de operação, conversores, redirection rules,
alter-html, web-service, gotchas de produção — §1-13). Esta skill é o "como executar" — qual tool
chamar para cada operação. Consultar `webp-express` para entender uma definição; usar as tools
abaixo para lê-la/escrevê-la.

## Âmbito

Config, stack de conversores, conversão em massa e limpeza do WebP Express. Não cobre:
activação/desactivação do próprio plugin (`emcp-tools activate-plugin`/`deactivate-plugin`),
optimização/compressão genérica de imagem (nenhum plugin equivalente no bundle hoje), Cloudflare
Polish (fora de âmbito — Polish está `off` no plano Free, ver §13 da skill `webp-express`).

## Sites conhecidos

Chamar `webpx_list_sites` para a lista actual com path e nota de estado. Aliases verificados ao
vivo 19-08-2026, todos com WebP Express v0.25.15 activo: `descomplicar`/`emanuelalmeida`
(`operation-mode: cdn-friendly`), `starter`/`ccv`/`care`/`ecommerce-demo`/`e-commerce`/`ecommerce`
(`operation-mode: varied-image-responses`). Também aceita um path absoluto directamente
(`/home/ealmeida/<site>`) para sites fora desta lista, sem exigir rebuild do MCP.

## Tools (9)

| Tool | Read-only | Uso |
|---|---|---|
| `webpx_list_sites` | sim | Aliases conhecidos, path WP, nota de estado |
| `webpx_get_status` | sim | Plugin instalado/activo/versão + `webp-express-state` resumido — chamar sempre antes de forçar `converter` em `webpx_convert` |
| `webpx_get_state` | sim | `webp-express-state` em bruto: `workingConverterIds`, `configured`, regras `.htaccess` gravadas |
| `webpx_get_config` / `webpx_set_config` | sim/não | Ficheiro `config.<hash>.json` completo — merge raso; recusa chaves de diagnóstico só-leitura; avisa quando a chave exige re-save manual em wp-admin para regenerar `.htaccess` |
| `webpx_get_converters` / `webpx_set_converter_options` | sim/não | `converters[]` — opções por conversor + reordenação (`position`). Nunca toca em `working` |
| `webpx_convert` | não | `wp webp-express convert [<location>] [flags]` — sem `location`, dry preview |
| `webpx_flushwebp` | não | `wp webp-express flushwebp [--only-png]` — apaga `.webp` gerados, nunca originais registados |

Todas as tools exigem `site` como primeiro parâmetro.

## Segurança

- `webpx_set_config` recusa gravar as chaves de diagnóstico
  (`environment-when-config-was-saved`, `base-htaccess-on-these-capability-tests`,
  `document-root`, `paths-used-in-htaccess`) — snapshots de ambiente gravados pelo próprio plugin,
  nunca destinados a edição manual.
- Escrita no ficheiro de config preserva owner:group:permissões originais capturados via `stat`
  antes de sobrescrever — a ligação SSH corre como root; sem isto o ficheiro ficaria `root:root`
  e o wp-admin desse site deixaria de conseguir gravar as próprias definições.
- Valor viaja sempre em base64 sobre stdin, nunca interpolado no comando SSH remoto.

**Gotcha de formato (mesma classe do já documentado em `mcp-wpfc`):** `webp-express-state` é uma
STRING JSON dentro de um wp_option (`json_encode()` gravado directamente), não um array WP-CLI
tipado — `wp option get webp-express-state --format=json` devolve JSON duplamente codificado.
`getState()` descodifica uma segunda vez. Ao contrário do WPFC, aqui a CONFIG principal nem
sequer é um wp_option — vive num ficheiro com hash no nome (`webp-express-config-hash` resolve o
caminho, nunca hardcoded).

**Gotcha de SDK:** `structuredContent` do resultado de uma tool MCP tem de ser um objecto — nunca
um array. Passar um array (ex. `converters[]`) causa `MCP error -32602: expected record, received
array`. `jsonResult()` só anexa `structuredContent` quando os dados são um objecto simples.

## Verificação

Construído e testado ponta-a-ponta contra produção (`emanuelalmeida.pt`) 19-08-2026: leitura
completa da config e da stack de conversores; escrita+releitura+reversão de `enable-logging`
(`false→true→false`) e de `gd.skip-pngs` via `webpx_set_converter_options`
(`false→true→false`), ambas confirmadas por `stat` a manter `ealmeida:ealmeida 644` antes/depois;
bloqueio confirmado ao tentar gravar `document-root`; `webpx_convert` em dry preview (0 ficheiros
por converter, config já estável). `webpx_flushwebp` e `webpx_convert` com `location`/`reconvert`
reais não foram exercidos contra produção — mesmo código-caminho (`runSsh` + construção de
comando) já validado via `convert` em dry-run.

## Skills relacionadas

- `webp-express` — mapeamento completo de todas as chaves de config, modos de operação,
  conversores, qualidade/encoding, redirection rules, alter-html, web-service, decision tree de
  comandos WP-CLI equivalentes.
- `mcp-wpfc` — MCP irmão para WP Fastest Cache, mesmo padrão arquitectural; primeira ocorrência
  documentada do gotcha de JSON duplamente codificado.
- `wp-font-perf` — cobre WebP em `background-image` CSS, que o WebP Express não converte (fora do
  âmbito deste MCP e dessa skill de origem).