claude-plugins/wordpress/skills/mcp-webp-express/SKILL.md

name, description, layer

name	description	layer
mcp-webp-express	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".	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).