name: mcp-ai-engine description: MCP dedicado (node stdio, ligação `ai-engine` em ~/.omp/agent/mcp.json) para gerir o AI Engine (Meow Apps, slug `ai-engine`) multi-site (bundle Descomplicar) via WP-CLI/SSH — estado/versão, fornecedores de IA e de embeddings/vector DB configurados (chave API SEMPRE mascarada), modelos/ambientes por omissão por tipo de tarefa, módulos/feature-toggles, chatbots/assistentes configurados, estatísticas de uso agregadas (tokens/custos por modelo/mês/dia, sem PII), add-ons, limites de utilização. Escrita: activar/desactivar um módulo, actualizar modelo/instruções de um chatbot. Usar quando "ai engine", "mwai", "meow apps", "chatbot wordpress", "mwai_options", "mwai_chatbots", "chave API openai wordpress", "fornecedor de IA configurado", "estatísticas de uso IA wordpress", "assistente de IA wordpress". layer: wiki

/mcp-ai-engine — MCP dedicado ao AI Engine (Meow Apps)

Projecto em /media/ealmeida/Dados/Dev/mcp-ai-engine/ (TypeScript, SDK MCP oficial, stdio). Cada tool executa wp option get/patch via WP-CLI já instalado em server.descomplicar.pt. Escritas viajam em base64 por stdin (base64 -d | wp option patch update ...), nunca interpoladas na linha de comando remota.

Não há skill de conhecimento separada para o AI Engine — esta skill é a única documentação, incluindo o mapeamento completo de armazenamento (abaixo).

Âmbito

Estado/configuração/estatísticas do plugin: fornecedores de IA e as suas capacidades, chatbots configurados, módulos activos, defaults por tipo de tarefa, uso agregado (tokens/custos), add-ons, limites. Nunca chaves API em claro. Fora do âmbito (excluído estruturalmente, não por falta de tempo): histórico de conversas/discussões de visitantes (tabela wp_mwai_chats — PII, e nem sequer existe ainda nos sites verificados porque o módulo chatbot_discussions está desligado em todos), ficheiros enviados (wp_mwai_files), tarefas agendadas (wp_mwai_tasks), qualquer escrita em apikey/apiKey (por desenho — ver Segurança).

Sites conhecidos

Confirmado por wp plugin list --format=csv em todos os 8 sites reais do bundle (19-08-2026):

Site	Estado AI Engine	Notas
`starter` (starter.descomplicar.pt)	ACTIVO, 3.7.1	Chatbot "Default" (`botId: default`) configurado, providers OpenAI + Claude registados sem chave API. Site principal de teste deste MCP.
`ccv` (ccv.descomplicar.pt)	Instalado, inactivo, 3.7.1	Config (`mwai_options`/`mwai_chatbots`) persiste na BD mesmo com o plugin desactivado — continua legível/editável via WP-CLI.
`ecommerce-demo` (ecommerce-demo.descomplicar.pt)	Instalado, inactivo, 3.7.1	Sem chatbots configurados (`mwai_chatbots` nunca chegou a ser gravada).
`ecommerce` (ecommerce.descomplicar.pt)	Instalado, inactivo, 3.7.1	—
`descomplicar` (produção)	NÃO instalado	Apesar de referido como "activo" num briefing anterior — confirmado por leitura directa `wp plugin list` que NÃO está no site.
`emanuelalmeida`, `care`, `e-commerce`	NÃO instalado	—

ai_engine_list_sites devolve esta lista com as notas; qualquer tool aceita também um path absoluto directo para uma instalação futura noutro site.

Mapeamento de armazenamento (confirmado por leitura do código-fonte do plugin)

O AI Engine guarda arrays PHP nativos (não strings com JSON lá dentro) em 2 options — confirmado ao vivo com wp eval "echo gettype(get_option('mwai_options'));" → array. Por isso --format=json é seguro tanto para leitura como para escrita (ao contrário do WP Fastest Cache ou do TablePress, que serializam JSON como string plana — ver mcp-wpfc/mcp-tablepress).

Option	Conteúdo	Formato
`mwai_options` (`classes/core.php`, `$option_name`)	Config principal: `ai_envs` (fornecedores de IA), `embeddings_envs` (fornecedores de embeddings/vector DB), `module_`/`workspace_`/`chatbot_`/`speech_`/`mcp_` (feature toggles), `ai__default_env`/`ai_*_default_model` (defaults por tipo de tarefa: texto, fast, visão, imagens, áudio, JSON, embeddings), `ai_usage`/`ai_usage_daily` (estatísticas de uso agregadas), `addons`, `limits`/`default_limits`, `chatbot_defaults`, `logs_path`, etc.	Array PHP nativo
`mwai_chatbots` (`$chatbots_option_name`)	Array de chatbots/assistentes: `botId`, `name`, `model`, `instructions` (prompt de sistema), `temperature`, `maxMessages`, `maxTokens`, `apiKey` (override opcional por chatbot), tema/UI, `functions`, `mcpServers`, `crossSite`.	Array PHP nativo
`mwai_themes` (`$themes_option_name`)	Temas visuais custom do widget de chat. Vazio/`false` em todos os sites verificados — fora do âmbito deste MCP (não é config de IA).	Array PHP nativo (ou `false` quando nunca gravada)

Gotcha confirmado ao vivo: a option mwai_options lida por wp option get inclui campos que o próprio plugin trata como "dinâmicos" no seu código (populate_dynamic_options() em core.php:1404, chamado só pelo acessor interno get_all_options(), nunca pelo WordPress core get_option()) — nomeadamente addons (com enabled calculado) e ai_engines (catálogo enorme e estático de modelos por fornecedor). Na prática estes campos já estão persistidos na BD em todos os sites verificados, porque o painel admin (React) faz round-trip do objecto completo que recebe via REST (que já vem enriquecido) de volta para update_option() na gravação. Ou seja: não é um artefacto deste MCP, é o estado real da BD — ai_engine_list_addons lê exactamente isso. Para não agravar este "bloat" nem arriscar persistir uma cópia desactualizada do catálogo ai_engines (que é grande e evolui com cada release do plugin), nenhuma tool de escrita deste MCP relê e regrava a option inteira — todas usam wp option patch update <option> <key-path...>, que grava só o caminho aninhado pedido dentro do array já existente na BD.

Não existe comando WP-CLI custom (wp help mwai/wp help ai-engine confirmam "not a registered command" na v3.7.1) — todo o acesso é via wp option get/patch.

Tools (12)

Tool	Read-only	Uso
`ai_engine_list_sites`	sim	Aliases conhecidos, path WP, nota de estado do AI Engine
`ai_engine_get_status`	sim	Instalado/activo/versão — `wp plugin list` filtrado a `ai-engine`
`ai_engine_list_providers`	sim	`ai_envs` (OpenAI, Claude, Azure, Google, OpenRouter, Replicate, Mistral, etc.) — chave API mascarada
`ai_engine_list_embeddings_providers`	sim	`embeddings_envs` (Internal/WordPress DB, OpenAI Vector Store, Pinecone, etc.) — chave API mascarada
`ai_engine_get_defaults`	sim	Modelo/ambiente por omissão por tipo de tarefa (texto, fast, visão, imagens, áudio, JSON, embeddings)
`ai_engine_list_modules`	sim	Todas as chaves booleanas de `mwai_options` (descoberta dinâmica — `module_`, `workspace_`, `chatbot_`, `speech_`, `mcp_*`, flags soltas)
`ai_engine_list_chatbots`	sim	Chatbots/assistentes configurados (nome, modelo, instruções, limites) — `apiKey` mascarada
`ai_engine_get_usage`	sim	`ai_usage`/`ai_usage_daily` — tokens/custos agregados por modelo/mês/dia, sem PII
`ai_engine_list_addons`	sim	Add-ons oficiais do AI Engine e se estão `enabled`
`ai_engine_get_limits`	sim	Quotas de créditos/queries por período (visitantes/utilizadores/sistema)
`ai_engine_set_module`	não	Activa/desactiva 1 chave booleana já existente em `mwai_options` (valida dinamicamente que existe e é booleana antes de escrever)
`ai_engine_set_chatbot_field`	não	Actualiza `model` ou `instructions` de 1 chatbot (por `botId`) — allowlist rígida de 2 campos, nunca `apiKey`/`functions`/`mcpServers`

Segurança

Chaves API nunca em claro, em nenhuma tool, em nenhuma circunstância. ai_envs[].apikey, embeddings_envs[].apikey e mwai_chatbots[].apiKey são sempre destruturados fora do objecto devolvido e substituídos por { has_key: boolean, key_hint: string | null } (src/mask.ts) — key_hint mostra só os últimos 4 caracteres prefixados de asteriscos (***abcd), ou máscara total se a chave tiver ≤4 caracteres. Nenhuma tool de escrita toca em apikey/apiKey — ai_engine_set_module só aceita chaves já-booleanas de mwai_options (rejeita ai_envs/embeddings_envs/qualquer chave não-booleana), ai_engine_set_chatbot_field só aceita field ∈ {model, instructions} (enum zod, rejeitado no schema antes mesmo de chegar ao handler).

Escritas usam wp option patch update <option> <key-path...> com o valor em base64 sobre stdin (nunca interpolado no comando SSH remoto). Gotcha herdado do mcp-gtranslate: update_option() devolve false tanto em falha real como quando o valor gravado já é igual ao actual, e o WP-CLI nem sempre reporta esse caso como sucesso — em caso de exit code != 0, patchKey relê o valor no caminho pedido e só propaga o erro se continuar diferente do pretendido.

Sem histórico de conversas de visitantes acessível por este MCP — a tabela wp_mwai_chats (módulo chatbot_discussions) não é lida por nenhuma tool, mesmo que venha a ser activada no futuro; é uma exclusão estrutural, não uma limitação de dados actualmente vazios.

Verificação

Construído e testado ponta-a-ponta (19-08-2026):

Build TypeScript limpo (npm run build), smoke test stdio (initialize + tools/list → 12 tools).
ai_engine_get_status em starter confirmou installed:true, active:true, version:"3.7.1".
ai_engine_list_providers/ai_engine_list_embeddings_providers/ai_engine_list_chatbots/ ai_engine_list_modules/ai_engine_get_defaults/ai_engine_get_usage/ai_engine_list_addons/ ai_engine_get_limits em starter: 8 leituras reais confirmadas, incluindo module_addons:true, chatbot_discussions_titling:true (typing dinâmico de booleanos correcto), 2 fornecedores de IA e 1 de embeddings (Pinecone) devolvidos com has_key:false, key_hint:null (sem chave configurada no site) e 1 chatbot ("Default") com instructions legível e apiKey mascarada.
Verificação de mascaramento com chave real (não apenas ausência de chave): gravada temporariamente uma chave de teste falsa (sk-TEST-FAKE-...abcdEND) directamente em ai_envs[0].apikey no site ccv (inactivo, baixo risco) via wp option patch fora do MCP; chamada ai_engine_list_providers devolveu has_key:true, key_hint:"***dEND" — a chave completa nunca apareceu em nenhum campo da resposta JSON-RPC. Valor restaurado a "" de imediato e confirmado por leitura directa idêntico ao original.
Também testado directamente maskSecret() isolado (chave longa → *** + últimos 4 chars; chave curta ≤4 chars → máscara total; vazio/null/undefined → has_key:false).
Escrita ai_engine_set_module: round-trip idempotente em starter — module_statistics (false→true→false), confirmado por leitura directa fora do MCP antes/ depois idêntico ao valor original.
Escrita ai_engine_set_chatbot_field: round-trip idempotente em starter — model do chatbot default (""→"gpt-4o-mini"→""), confirmado por leitura directa fora do MCP que o valor final é byte-a-byte igual ao original e que instructions (campo não tocado) permaneceu inalterado.

Skills relacionadas

Nenhuma skill de conhecimento separada existe para o AI Engine — este documento cobre tudo. Ver wp-cli para o padrão geral de gestão WordPress via WP-CLI/SSH usado por este MCP, e mcp-gtranslate/mcp-tablepress para o padrão de wp option patch com arrays nativos vs. options JSON-em-string.

12 KiB Raw Blame History