feat(mcp-gtranslate): adiciona skill do MCP dedicado ao GTranslate
- 9 tools: idiomas activos/ordem, estilo/posicao do widget, idioma de origem, estado da licenca Pro/Enterprise (read-only) - Documenta formato de armazenamento (array PHP nativo, --format=json correcto) e o gotcha de escrita idempotente do wp option patch update - Confirmado ao vivo: so descomplicar.pt tem o plugin instalado
This commit is contained in:
@@ -0,0 +1,98 @@
|
||||
---
|
||||
name: mcp-gtranslate
|
||||
description: MCP dedicado multi-site (node stdio, ligação `gtranslate` em ~/.omp/agent/mcp.json) para gerir o GTranslate (widget de tradução frontend) via WP-CLI/SSH — idiomas activos e ordem (widget principal e flutuante), estilo/posição do widget, idioma de origem, estado da licença Pro/Enterprise (read-only). Site é um parâmetro em cada tool, não uma ligação fixa. Usar quando "gtranslate mcp", "idiomas activos gtranslate", "estilo widget traducao", "widget flutuante gtranslate", "licenca pro gtranslate", "mudar idioma origem site".
|
||||
layer: wiki
|
||||
---
|
||||
|
||||
# /mcp-gtranslate — MCP dedicado multi-site ao GTranslate
|
||||
|
||||
Projecto em `/media/ealmeida/Dados/Dev/mcp-gtranslate/` (TypeScript, SDK MCP oficial, stdio). Sem
|
||||
código PHP novo no WordPress: cada tool executa `wp option get`/`wp option patch update` via
|
||||
`ssh server` sobre o WP-CLI já instalado. `site` é um parâmetro em cada tool, não uma ligação
|
||||
fixa — hoje só `descomplicar.pt` (produção) tem o GTranslate instalado, mas o MCP aceita qualquer
|
||||
alias conhecido ou path absoluto.
|
||||
|
||||
Não existe skill de conhecimento separada para o GTranslate — esta skill é a ÚNICA documentação,
|
||||
incluindo o mapeamento de dados (a única option envolvida).
|
||||
|
||||
## Âmbito
|
||||
|
||||
Toda a config do GTranslate Free vive numa única option, `GTranslate` (confirmado por grep
|
||||
completo a `get_option`/`update_option`/`add_option` em `gtranslate.php` — sem tabela custom, sem
|
||||
comando WP-CLI próprio registado). Não cobre: activação/desactivação do próprio plugin
|
||||
(`emcp-tools activate-plugin`/`deactivate-plugin` já cobre isso genericamente), a config do
|
||||
"URL Translation Addon" (`url_addon/config.php`, um ficheiro PHP editado directamente pelo plugin
|
||||
quando Pro/Enterprise está activo — fora do âmbito, o site actual é Free), nem activação de
|
||||
licença Pro/Enterprise (handshake client-side contra gtranslate.net, sem endpoint WP-CLI/SSH).
|
||||
|
||||
## Sites conhecidos
|
||||
|
||||
Chamar `gtranslate_list_sites` para a lista actual com path e nota de estado. Verificado ao vivo
|
||||
19-08-2026: **só `descomplicar.pt` (produção) tem o GTranslate instalado e activo** (v3.1.1, Free
|
||||
— `pro_version`/`enterprise_version` ambos vazios). Os outros 7 sites reais do bundle
|
||||
(`starter`, `emanuelalmeida`, `ccv`, `care`, `ecommerce-demo`, `e-commerce`, `ecommerce`) não o
|
||||
têm — todos só têm o Loco Translate instalado, um plugin de tradução de ficheiros `.po`/`.mo`
|
||||
sem qualquer relação com o GTranslate. 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 |
|
||||
|---|---|---|
|
||||
| `gtranslate_list_sites` | sim | Aliases conhecidos, path WP, nota de estado |
|
||||
| `gtranslate_get_status` | sim | Instalado/activo/versão — chamar sempre antes dos outros tools |
|
||||
| `gtranslate_get_config` | sim | Option `GTranslate` completa (array PHP nativo) |
|
||||
| `gtranslate_get_license_status` | sim | `pro_version`/`enterprise_version` normalizados a booleano + `tier` (free/pro/enterprise). Não activa licença |
|
||||
| `gtranslate_get_languages` | sim | `default_language`, `incl_langs` (widget principal), `fincl_langs` (widget flutuante), mais a lista completa dos 103 idiomas suportados |
|
||||
| `gtranslate_toggle_language` | não | Activa/desactiva 1 código de idioma em `incl_langs`/`fincl_langs`/`both`, preservando a ordem dos restantes. Recusa esvaziar uma lista |
|
||||
| `gtranslate_get_widget_style` | sim | `widget_look`, `flag_size`/`flag_style`, `globe_size`/`globe_color`, cores, `floating_language_selector` (posição do flutuante, `no` = desligado), direcções de abertura, `select_language_label`, `wrapper_selector`, `custom_css` |
|
||||
| `gtranslate_set_widget_style` | não | Grava, chave a chave via `wp option patch update`, só as chaves de estilo fornecidas. `widget_look`/`floating_language_selector`/`flag_style`/direcções validados contra os enums reais do plugin |
|
||||
| `gtranslate_set_default_language` | não | Muda `default_language` (idioma de origem/nativo do conteúdo). Não mexe em `incl_langs`/`fincl_langs` |
|
||||
|
||||
Todas as tools exigem `site` como primeiro parâmetro.
|
||||
|
||||
## Formato de armazenamento — confirmado, oposto ao WP Fastest Cache
|
||||
|
||||
`GTranslate` é um **array PHP nativo** (confirmado ao vivo: `wp option get GTranslate` sem
|
||||
`--format=json` devolve `array(...)` desenrolado, não uma string com JSON lá dentro).
|
||||
`--format=json` é portanto **correcto** aqui em leitura e escrita — mesma verificação prévia
|
||||
obrigatória que gerou o gotcha inverso no `mcp-wpfc` (ver skill `wp-fastest-cache` §16.2), mas
|
||||
com resultado oposto: aqui não há dupla codificação a evitar.
|
||||
|
||||
## Gotcha de escrita idempotente (WP-CLI)
|
||||
|
||||
`wp option patch update` quando o valor gravado é **idêntico** ao actual às vezes devolve
|
||||
`Success: ... is unchanged` (exit 0), mas foi reproduzido ao vivo a devolver
|
||||
`Error: Could not update option` (exit != 0) para o mesmo caso — `update_option()` do WordPress
|
||||
devolve `false` quando o valor não muda, e o WP-CLI nem sempre trata esse `false` como sucesso.
|
||||
`patchKey()` (`src/wpcli.ts`) relê a chave após qualquer falha e só propaga o erro se o valor no
|
||||
site continuar diferente do pretendido — evita que uma chamada idempotente (ex. desactivar um
|
||||
idioma já desactivado) rebente por um falso negativo do WP-CLI.
|
||||
|
||||
## Segurança
|
||||
|
||||
Allowlist fixa de 1 option (`GTranslate`) — nunca `wp option update` genérico sobre uma chave
|
||||
arbitrária. Escritas via base64 em stdin, nunca interpoladas no comando SSH remoto. Sem
|
||||
licença/API key para mascarar: confirmado por grep a "license"/"api_key"/"secret"/"token" em todo
|
||||
o código-fonte do plugin — `pro_version`/`enterprise_version` são flags booleanas gravadas por
|
||||
checkbox, a validação real da licença é feita client-side contra gtranslate.net pelo domínio do
|
||||
site, não por um segredo em `wp_options`.
|
||||
|
||||
## Verificação
|
||||
|
||||
Construído e testado ponta-a-ponta contra produção (`descomplicar.pt`) 19-08-2026:
|
||||
`gtranslate_get_status` confirmou v3.1.1 activo; `gtranslate_get_languages` confirmou
|
||||
`default_language: "pt"`, `incl_langs` com 10 idiomas e `fincl_langs` com 3, ambos batendo certo
|
||||
com leitura SQL/WP-CLI directa fora do MCP; `gtranslate_get_widget_style` confirmou
|
||||
`widget_look: "flags"`, `floating_language_selector: "no"`; `gtranslate_get_license_status`
|
||||
confirmou `tier: "free"`. Escrita testada com `gtranslate_toggle_language` (activou "ja" em
|
||||
`incl_langs`, confirmado por `wp option get` directo, depois desactivou — testado 3x seguidas
|
||||
incluindo o caso idempotente que expôs o gotcha do WP-CLI acima — estado final idêntico ao
|
||||
original, confirmado por leitura SSH directa); `gtranslate_set_widget_style` e
|
||||
`gtranslate_set_default_language` testados com os valores já-correntes (no-op idempotente),
|
||||
confirmado sem alteração via leitura SSH directa.
|
||||
|
||||
## Skills relacionadas
|
||||
|
||||
- `wp-fastest-cache` — o gotcha de formato inverso que motivou a verificação obrigatória aqui.
|
||||
- `mcp-wpmeteor` — mesmo padrão de option nativa + `wp option patch update` atómico.
|
||||
Reference in New Issue
Block a user