7 bugs que encontrei no meu servidor MCP antes de publicar

Enviei elementor-mcp-agent v1.0 hoje — um servidor de Modelo de Contexto de Protocolo de código aberto que permite que Claude (e qualquer cliente MCP) controle o WordPress Elementor em muitos sites de clientes. É MIT, no npm como elementor-mcp-agent, listado no Registro oficial do MCP.

Repositório: github.com/Mogacode-ma/elementor-mcp-agent

O que eu quero escrever não é sobre a arquitetura — é sobre os 7 bugs que encontrei apenas porque me forcei a testar de ponta a ponta contra uma instalação real do WordPress antes de publicar. Três deles teriam corrompido silenciosamente dados em um site de cliente em produção. Os outros apenas pareceriam quebrados. Todos eles teriam sido um pesadelo para o suporte ao cliente.

Este post é a lista de bugs, com contexto. Se você está construindo um servidor MCP (ou qualquer automação contra um SaaS opinativo), esses padrões se aplicam.

A configuração

Eu administro uma pequena agência. Gerenciamos ~50 sites WordPress + Elementor Pro para clientes na Bélgica, França, Luxemburgo e Marrocos. As operações do dia a dia são previsíveis: atualizações de texto, trocas de imagem, sincronização de modelos, atualizações de plugins, backups. Cumulativamente doloroso.

MCP parecia ter a forma certa para isso: ferramentas com verificação de tipo, efeitos colaterais explícitos, dança de confirmação para operações destrutivas. Eu construí 24 ferramentas em 7 categorias (sites, páginas, widgets, modelos, WP-CLI, capturas de tela, versões da frota).

Minha v0.1 passou npm run build, npm test, ESLint, tsc --noEmit. Eu quase publiquei sem tocar em uma instalação real do Elementor.

Estou feliz por não ter feito isso.

Bug #1 — A API REST do WordPress descarta silenciosamente gravações em chaves de postmeta não registradas

O sintoma: implementei backups automatizados escrevendo o _elementor_data atual em uma chave de postmeta com timestamp (_elementor_data_backup_2026-05-22T04-35-37-847Z) via PUT /wp-json/wp/v2/pages/{id}. A API retornou 200 OK. Meu código marcou o backup como bem-sucedido. O subsequente elementor_find_replace foi aplicado com confiança.

Quando tentei verificar via wp post meta list 8 | grep backup, o resultado estava vazio.

A causa raiz: A API REST do WordPress requer register_meta() com show_in_rest: true para que uma chave de postmeta possa ser gravada através do REST. Plugins como Elementor registram suas chaves canônicas (_elementor_data, _elementor_page_settings). Chaves personalizadas que você inventa em tempo de execução são silenciosamente descartadas pelo REST.

200 OK. Sem aviso. Sem erro.

A correção: mudei o backup para WP-CLI via SSH (sempre funciona). Arquivo JSON local como fallback quando o SSH não está configurado. O REST não é mais confiável para gravações não canônicas.

A lição: qualquer API REST que requer registro de esquema para campos semelhantes a meta irá silenciosamente engolir suas gravações quando o esquema não estiver presente. Teste se o valor realmente persiste. Não confie no código de resposta.

Bug #2 — O binário wp não está no PATH SSH não interativo

Depois de corrigir o #1, tentei novamente. Novo erro:

/bin/bash: line 1: wp: comando não encontrado

Eu estava testando no meu terminal local onde wp estava aliasado. Em hosts WordPress gerenciados (Infomaniak, neste caso), wp-cli geralmente é instalado em ~/bin/wp.phar e invocado como php ~/bin/wp.phar. O shell não interativo que ssh user@host "comando" usa tem um PATH reduzido que não inclui ~/bin.

A correção: detecção automática na primeira conexão SSH — probe command -v wp, fallback para ~/bin/wp.phar, depois ~/wp-cli.phar. Cache por site. Permitir substituição explícita via campo de configuração ssh.wp_cli_path.

A lição: sessões SSH não interativas têm um PATH diferente das interativas. Se sua ferramenta gera comandos remotos, nunca assuma que um binário está no PATH. Prove ou aceite um caminho explícito.

Bug #3 — O banner SSH polui stderr e corrompe a análise de saída

A OpenSSH recentemente começou a imprimir um aviso em conexões que não usam um algoritmo de troca de chave pós-quântica:

** AVISO: a conexão não está usando um algoritmo de troca de chave pós-quântica.
** Esta sessão pode estar vulnerável a ataques de "armazenar agora, descriptografar depois".
** O servidor pode precisar ser atualizado. Veja https://openssh.com/pq.html

Isso vai para stderr. Meu código capturou stderr e concatenou na mensagem de erro. Assim, uma chamada bem-sucedida de wp post meta get ainda apresentaria esse aviso como se fosse um erro.

A correção: filtrar linhas benignas conhecidas de stderr após a captura. Colocar na lista branca por substring (post-quantum, openssh.com/pq, decrypt later, etc.) antes de decidir que a operação falhou.

A lição: stderr não é sinônimo de "erro". Ferramentas que canalizam stderr em caminhos de tratamento de erro precisam filtrar banners benignos.

Bug #4 — "Kit Padrão" retornado como um widget nos filtros template_type=widget

A consulta /wp-json/wp/v2/elementor_library?meta_key=_elementor_template_type&meta_value=widget deveria retornar os widgets globais em um site. Ela retornou o Kit Padrão (tokens de design em todo o site do Elementor) que tem _elementor_template_type=kit, não widget.

A causa raiz: A filtragem de meta_value da API REST do WordPress é pouco confiável para chaves de meta que não estão register_meta-declaradas. Na prática, ela recai em uma verificação de presença de meta_key, ignorando o valor.

A correção: buscar todas as entradas de elementor_library (sem filtro de meta_value), depois filtrar do lado do cliente em meta._elementor_template_type === 'widget'.

A lição: não confie em filtros do lado do servidor em meta não registrada. Sempre valide se a estrutura da resposta corresponde à sua intenção.

Bug #5 — _elementor_page_settings é um objeto via REST, uma string via WP-CLI

Quando adicionei duplicate_elementor_page, o caminho de cópia fez:

ler fonte → copiar dados + configurações da página → escrever na nova página via REST PUT

Falhou com:

"O parâmetro meta._elementor_page_settings não é do tipo objeto." 

A causa: GET /wp-json/wp/v2/pages/{id}?context=edit retorna meta._elementor_page_settings como um objeto analisado (o Elementor o registra dessa forma). wp post meta get o retorna como uma string JSON serializada. Meu código o tipou como string em todos os lugares, então quando o REST retornou um objeto e eu o passei de volta via REST PUT (esperando a serialização da string JSON em meu template), a API rejeitou a incompatibilidade de tipo.

A correção: normalizar na leitura. Se você obteve uma string, JSON.parse() antes de escrever no REST. Se você obteve um objeto, JSON.stringify() antes de escrever no WP-CLI. Não assuma que a representação de um transporte corresponde ao outro.

A lição: não confie em representações de dados entre diferentes transportes. Sempre normalize os dados ao ler e escrever.