claude-plugins/wordpress/skills/mcp-fluentform/SKILL.md

name, description, layer

name	description	layer
mcp-fluentform	MCP dedicado multi-site (node stdio, ligação `fluentform` em ~/.omp/agent/mcp.json) para o FluentForms 6.2.12 (WPManageNinja) em descomplicar.pt (produção) e starter.descomplicar.pt (staging) — formulários, submissions (entries), contagens por estado e settings gerais, via WP-CLI/SSH sobre a camada de serviço oficial do plugin (FormService/SubmissionService/GlobalSettingsService). Escritas limitadas a estado da entry (unread/read/spam/trashed) e favorita/star — nunca schema de formulário nem integrações de terceiros. Usar quando "fluentforms", "formulários wordpress", "entries fluentform", "submissions fluentform", "marcar entry como lida", "favoritar entry", "spam fluentform", "trash entry fluentform", "contagem de submissions", "settings fluentforms", ou qualquer execução (não estratégia) sobre o FluentForms.	wiki

/mcp-fluentform — MCP dedicado FluentForms (multi-site)

Projecto em /media/ealmeida/Dados/Dev/mcp-fluentform/ (TypeScript, SDK MCP oficial, stdio). Não existe skill de conhecimento separada sobre o FluentForms — esta skill é a ÚNICA documentação, incluindo o mapeamento de dados (tabelas/serviços) que noutros casos vive numa skill "irmã" (ver fluent-crm↔mcp-fluent-crm para esse padrão).

Achado relevante desta sessão: o FluentForms 6.2.12 já traz o seu próprio módulo MCP interno (app/Modules/MCP/, abilities fluentform/list-submissions, fluentform/update-submission-status, etc., via WP Abilities API), mas só fica acessível externamente se o site tiver o plugin mcp-adapter ou fluent-toolkit activo e o toggle "MCP" ligado nas definições do FluentForms — nenhuma das duas condições está preenchida hoje nos dois sites. Este MCP não depende disso: chama directamente a camada de serviço PHP subjacente (FormService/SubmissionService/ GlobalSettingsService), a mesma que o módulo MCP nativo do plugin também usa por baixo.

Sites conhecidos

Chamar fluentform_list_sites para a lista actual. Confirmados ao vivo 19-08-2026, FluentForms 6.2.12 active nos dois — são os únicos dois sites do bundle com o plugin activo (wp plugin list):

Alias	Domínio	Prefixo de tabela	Formulários	Submissions
descomplicar	descomplicar.pt (produção)	wpah_	3 (Contact Form Demo unpublished, Subscription Form unpublished, Blank Form (#3) published)	1 (form #3, status read)
starter	starter.descomplicar.pt (staging)	wpbk_	2 (Contact Form Demo, Subscription Form, ambos published)	0

Também aceita um path absoluto directamente (/home/ealmeida/<site>) para sites fora desta lista, sem exigir rebuild do MCP — mas confirmar primeiro que o FluentForms está activo lá (wp plugin list --allow-root --path=<path>).

Mapeamento de dados

FluentForms não expõe WP-CLI CRUD (wp fluentform só tem activate_license/license_status/ stats). Toda a leitura/escrita deste MCP passa pela camada de serviço PHP oficial do plugin, via wp eval — nunca SQL directo, nunca wp option update.

Tabelas custom (prefixo de tabela varia por site, ver acima; resolvido internamente pelo ORM do plugin, nunca hardcoded em TypeScript):

Tabela (sem prefixo)	Papel
fluentform_forms	formulários — title, status (published/unpublished), type, form_fields (JSON do schema), has_payment
fluentform_submissions	entries — form_id, response (JSON das respostas), status (unread/read/spam/trashed), is_favourite, serial_number, user_id, payment_*
fluentform_submission_meta	meta por submission (ex. _entry_uid_hash para link público)
fluentform_entry_details	valores desnormalizados por campo (usado por relatórios/exportação)
fluentform_form_meta	meta por formulário (settings, notificações, integrações)
fluentform_form_analytics	contadores de vistas/conversão por formulário
fluentform_logs	log de eventos por submission/formulário

Classes de serviço oficiais usadas por este MCP (FluentForm\App\Services\* + FluentForm\App\Models\*, todas instanciáveis directamente com new, sem container DI):

• Form::query() — listagem/filtro de formulários (orderBy, where('title','LIKE',...), where('status',...), ->paginate($perPage,['*'],'page',$page)).
• FormService::getInputsAndLabels($formId) — schema de campos (inputs/labels), usado por fluentform_get_form e para rotular os valores em fluentform_get_submission.
• Submission::customQuery($attrs) — o MESMO método que o wp-admin usa para a listagem de entries; aceita form_id, entry_type (nome real do parâmetro de estado — não status; 'favorites' é tratado à parte via is_favourite=1), search, date_range: [from,to], sort_by.
• SubmissionService::find($id) — detalhe completo de 1 entry. EFEITO SECUNDÁRIO REAL DO PLUGIN: marca automaticamente unread→read (mesmo comportamento de abrir a entry no wp-admin) — documentado na descrição da tool, não é bug deste MCP.
• SubmissionService::updateStatus(['entry_id'=>,'status'=>]) — unread/read/spam/trashed; dispara do_action('fluentform/after_submission_status_update', ...).
• SubmissionService::toggleIsFavorite($id) — toggle puro, devolve [mensagem, novo_estado].
• SubmissionService::resources(['form_id'=>,'counts'=>true]) → Submission::countByGroup($formId) — contagens unread/read/spam/trashed/all (exclui trashed)/favorites.
• GlobalSettingsService::get(['key'=>[...]]) — só lê chaves com prefixo fluentform_/_fluentform_/fluentform-/_fluentform- (allowlist própria do plugin); usado por fluentform_get_settings.

Arquitectura — wp eval sobre a camada de serviço, nunca SQL/WP-CLI directo

Corpo PHP fixo (nunca construído a partir de texto do chamador) + dados de entrada (JSON) viajam em base64 dentro de uma variável de ambiente remota, nunca interpolados como texto dinâmico no comando SSH — mesmo padrão de mcp-fluent-crm/src/wp-bridge.ts (runPhp()), adaptado a multi-site: o path WordPress é um parâmetro por chamada (src/sites.ts), não uma config fixa.

Gotcha de datas — não replicar sem testar primeiro: $model->created_at/updated_at não devolvem uma string — devolvem um objecto FluentForm\Framework\Support\DateTime (Carbon-like). json_encode() directo sobre esse objecto produz {"date":"...","timezone_type":3,"timezone":"..."} em vez de uma string, porque o serializeDate() custom do Model.php do plugin só é aplicado em toArray()/toJson(), nunca num json_encode() PHP nativo isolado. Corrigido em todos os pontos deste MCP com (string) $form->created_at — o DateTime do framework implementa __toString() devolvendo Y-m-d H:i:s correctamente.

Gotcha de race condition — confirmado ao vivo durante a construção: duas chamadas de escrita dependentes (ex. dois fluentform_toggle_favorite seguidos, para testar round-trip) NUNCA podem correr em paralelo — cada wp eval é um processo PHP efémero independente; disparar dois concorrentes faz ambos lerem o mesmo estado "antigo" e o resultado final fica indeterminado (visto ao vivo: 1º toggle devolveu is_favourite:true, mas a leitura SQL imediatamente a seguir mostrou 0 porque o 2º toggle, corrido em paralelo, tinha lido o 0 original em vez do true já escrito pelo 1º). Corrigido correndo sequencialmente; qualquer teste/uso futuro deste MCP com múltiplas escritas na mesma entry deve aguardar o resultado de cada chamada antes da seguinte.

Tools (9)

Tool	Read-only	Uso
fluentform_list_sites	sim	Aliases conhecidos, path WP, prefixo de tabela
fluentform_list_forms	sim	search/status(published|unpublished)/sort_by/paginação — id, título, estado, tipo, has_payment, datas
fluentform_get_form	sim	Detalhe de 1 formulário + schema de campos (key/label/element) — necessário para saber as chaves esperadas em fluentform_get_submission
fluentform_list_submissions	sim	Entries de UM formulário (form_id obrigatório) — filtros status(unread|read|spam|trashed|favorites)/search/date_from+date_to(YYYY-MM-DD)/sort_by, paginação
fluentform_get_submission	efeito secundário	Detalhe completo de 1 entry (campos rotulados). Marca unread→read automaticamente (comportamento real do plugin)
fluentform_count_submissions	sim	Contagens por estado de um formulário: unread/read/spam/trashed/all/favorites
fluentform_update_submission_status	não	unread/read/spam/trashed. trashed é soft-delete (reversível chamando de novo com outro estado)
fluentform_toggle_favorite	não	Toggle puro — chamar duas vezes seguidas (sequencialmente!) devolve ao estado original
fluentform_get_settings	sim	Options com allowlist fluentform_/_fluentform_ — por omissão: _fluentform_global_form_settings (layout/misc), fluentform_global_modules_status (integrações ligadas/desligadas, nunca credenciais), _fluentform_installed_version. Aceita keys para ler chaves específicas dentro do mesmo allowlist

Todas as tools exigem site como primeiro parâmetro.

Decisão deliberada: sem escrita de schema/integrações

Nenhuma tool cria/edita formulários, campos, notificações ou integrações de terceiros (Mailchimp/Slack/etc). Razão (do enunciado desta tarefa): risco alto, fora do âmbito de um MCP de gestão de entries — mudar form_fields/integrações parte a experiência de submissão pública do site sem forma fácil de detectar isso a partir de fora. Gerir formulários/integrações via wp-admin (FluentForms → Forms/Settings).

Segurança

• Nenhuma tool constrói SQL ou nomes de tabela a partir de input do chamador — todas as queries passam por métodos do ORM do próprio plugin (Form::query(), Submission::customQuery(), Model::find()), nunca whereRaw/interpolação directa.
• fluentform_get_settings só lê chaves com o prefixo allowlisted pelo próprio GlobalSettingsService — não há forma de ler uma option arbitrária fora do namespace FluentForms através deste MCP.
• Corpo PHP + payload sempre em base64 dentro de env var remota — nunca interpolados como texto no comando SSH (ver src/wp-bridge.ts).
• fluentform_get_submission devolve valores de campos submetidos pelo público (texto não confiável) sem qualquer fencing adicional — ao contrário do módulo MCP nativo do plugin (que aplica marcadores [[UNTRUSTED_USER_INPUT]]), porque este MCP é de uso interno da equipa, não exposto a um agente autónomo com acesso à internet pública. Reavaliar se o uso mudar.

Verificação

Construído e testado ponta-a-ponta contra produção e staging em 19-08-2026, via protocolo MCP real (stdin/stdout, não só chamadas SSH soltas):

• npm run build limpo (tsc, sem erros).
• Smoke test stdio: initialize + tools/list devolveu os 9 tools esperados.
• Leituras reais confirmadas por SQL directo fora do MCP: fluentform_list_forms em descomplicar (3 formulários) e starter (2 formulários, ambos published); fluentform_get_form no formulário #3 (descomplicar) devolveu 8 campos incluindo um campo FluentBooking (fcal_booking); fluentform_list_submissions no formulário #3 (descomplicar, 1 entry, status:read); fluentform_count_submissions no mesmo formulário ({unread:0,read:1,spam:0,trashed:0,all:1,favorites:0}); fluentform_get_settings em descomplicar devolveu _fluentform_global_form_settings/fluentform_global_modules_status/ _fluentform_installed_version correctos.
• fluentform_get_submission na entry #1 (descomplicar): 7 campos rotulados correctamente (nome, email, empresa, cargo, data de reserva FluentBooking, 2 checkboxes), datas devolvidas como string Y-m-d H:i:s (não o objecto Carbon cru).
• Escrita 1 (idempotente): fluentform_update_submission_status na entry #1 com status:"read" (valor já-corrente) — devolveu {entry_id:1,status:"read"}, confirmado por SQL directo que status/is_favourite ficaram inalterados (só updated_at mudou, efeito normal de qualquer update).
• Escrita 2 (round-trip): fluentform_toggle_favorite na entry #1 chamado sequencialmente duas vezes — 1ª chamada devolveu is_favourite:true (confirmado is_favourite=1 por SQL directo), 2ª chamada devolveu is_favourite:false (confirmado is_favourite=0 por SQL directo, estado final idêntico ao inicial).
• Tratamento de erro confirmado: fluentform_get_form com form_id:9999 devolveu isError:true com "Formulário #9999 não encontrado."; fluentform_list_forms com site:"unknown-site" devolveu isError:true listando os aliases conhecidos.

Skills relacionadas

• mcp-fluent-crm — mesmo mecanismo wp eval sobre camada de serviço oficial, para contactos e campanhas em descomplicar.pt; FluentCRM tem automações que disparam a partir de submissões FluentForm (FluentFormSubmissionTrigger).
• mcp-fluent-smtp — transporte de email usado pelas notificações de submissão do FluentForms.
• mcp-wpfc / mcp-wpmeteor — outros MCPs multi-site do mesmo bundle, padrão site como parâmetro em cada tool.