feat(wordpress): nova skill mcp-webp-express + doc MCP webpx na skill webp-express
Skill mcp-webp-express: MCP dedicado (webpx) para WebP Express multi-site via WP-CLI/SSH, mesmo padrao mcp-wpfc. webp-express/SKILL.md: nova seccao 14 documentando o MCP construido e testado ao vivo em emanuelalmeida.pt.
This commit is contained in:
Claude Code
@@ -0,0 +1,92 @@
|
||||
---
|
||||
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).
|
||||
Reference in New Issue
Block a user