claude-plugins/wordpress/skills/mcp-jetengine/references/playbooks.md

Playbooks — mcp-jetengine

Sequências de chamadas às 11 tools nativas para tarefas reais. Todos os exemplos usam tools/call com {name, arguments} tal como o agente vê através do proxy (mcp-jetengine reencaminha verbatim). Exemplos escritos a partir do inputSchema real de cada tool (tools/list, 19-08-2026) — não exercidos contra produção nesta sessão (ver SKILL.md §Verificação); ler o inputSchema ao vivo antes de confiar cegamente num nome de campo.

0. Regra geral — ler antes de criar

Antes de registar qualquer estrutura nova, chamar resource-get-configuration (com os parts relevantes: post_types, taxonomies, meta_boxes, queries, custom_content_types, glossaries) para confirmar que o slug não existe já e para reutilizar queries/glossários existentes em vez de duplicar. Evita a classe de erro "criei um CPT com o mesmo slug de outro já existente" e mantém o site em conformidade com a regra anti-duplicação do projecto.

1. Módulos — pré-requisito antes de CCT, Mapas, REST API Listings

custom-content-types, maps-listings, rest-api-listings, gallery-grid, gallery-slider, qr-code, calendar, listing-injections, profile-builder, dynamic-visibility, data-stores, fullwidth-block-editor são módulos opcionais (JetEngine > Modules) — só booking-forms estava activo em descomplicar.pt a 19-08-2026. CPT, Taxonomias, Meta Boxes, Query Builder e Listings "normais" (não-mapa) são núcleo do plugin, sempre disponíveis, sem módulo a activar.

// 1. Confirmar estado actual
{"name": "tool-manage-modules", "arguments": {"operation": "list"}}

// 2. Activar o que falta (ex. antes de criar um CCT)
{"name": "tool-manage-modules", "arguments": {"operation": "activate", "modules": ["custom-content-types"]}}

operation: "activate"/"deactivate" aceitam vários slugs de uma vez em modules. Chamar tool-add-cct sem o módulo custom-content-types activo é o erro mais provável de quem salta este passo.

2. CPT + Taxonomia + Meta Box — conteúdo editorial estruturado

Fluxo para um tipo de conteúdo público (ex. "Casos de Estudo", "Formadores"): CPT primeiro, taxonomia associada ao CPT, depois campos.

// 1. Post Type
{"name": "tool-add-cpt", "arguments": {
  "general_settings": {"name": "Casos de Estudo", "slug": "caso-estudo"},
  "advanced_settings": {"public": true, "show_in_rest": true, "supports": ["title", "editor", "thumbnail"]}
}}

// 2. Taxonomia associada
{"name": "tool-add-taxonomy", "arguments": {
  "general_settings": {"name": "Sectores", "object_type": ["caso-estudo"]},
  "advanced_settings": {"public": true, "hierarchical": true, "show_in_rest": true}
}}

// 3. Meta Box com campos
{"name": "tool-add-meta-box", "arguments": {
  "general_settings": {"name": "Detalhes do Caso", "object_type": "post", "allowed_post_type": ["caso-estudo"]},
  "meta_fields": [
    {"name": "cliente", "type": "text", "title": "Cliente", "is_required": true},
    {"name": "resultado_percent", "type": "number", "title": "Resultado (%)"}
  ]
}}

meta_fields aceita descritores simplificados (name/type/title, como acima) OU o array JetEngine "cru" completo (object_type: "field", mesmo formato usado pela UI/references/ automation.md da skill jetengine) quando é preciso uma opção que o descritor simplificado não cobre (ex. referência a um glossário — ver §4).

3. CCT — dados de alta performance

Usar quando o volume/velocidade de leitura importa mais do que integração nativa WP (ver tabela CPT vs CCT na skill jetengine). Requer o módulo custom-content-types activo (§1).

{"name": "tool-add-cct", "arguments": {
  "name": "Leads Formulário",
  "slug": "leads_formulario",
  "fields": [
    {"field_name": "nome", "field_type": "text", "is_key_field": "yes"},
    {"field_name": "email", "field_type": "text", "is_key_field": "yes"},
    {"field_name": "criado_em", "field_type": "datetime", "save_as_timestamp": true}
  ]
}}

4. Glossário — opções reutilizáveis

Glossário = lista de pares value/label reutilizável em vários campos select/checkbox/ radio. A tool nativa só cobre o registo do glossário:

{"name": "tool-add-glossary", "arguments": {
  "name": "Estados de Proposta",
  "source": "manual",
  "fields": [
    {"value": "rascunho", "label": "Rascunho", "is_checked": true},
    {"value": "enviada", "label": "Enviada"},
    {"value": "aceite", "label": "Aceite"}
  ]
}}

Não confirmado nesta sessão: o schema simplificado de tool-add-meta-box.meta_fields não expõe uma propriedade explícita "glossário" — só options/choices inline. Ligar um campo a um glossário existente é uma funcionalidade da UI do JetEngine (campo → Options Type → Glossary); para o fazer via este MCP, passar o item do array meta_fields no formato JetEngine "cru" (object_type: "field", com a chave de opções apontando para o glossário) — confirmar a chave exacta lendo resource-get-configuration num meta box existente que já use um glossário, ou a UI, antes de replicar às cegas.

5. Query Builder + Listing — directório dinâmico

// 1. Query (posts normais)
{"name": "tool-add-query", "arguments": {
  "name": "Casos de Estudo Recentes",
  "query_type": "posts",
  "query_args": {"post_type": "caso-estudo", "posts_per_page": 12, "orderby": "date", "order": "DESC"}
}}

// 2. Listing ligado à query
{"name": "tool-add-listing", "arguments": {
  "title": "Grid Casos de Estudo",
  "query_id": 123,
  "view_type": "elementor"
}}

Gotcha de schema (JetEngine, não deste proxy): a descrição de tool-add-query menciona query_type: "custom-content-type" para consultar um CCT, mas o enum real do campo query_type não inclui esse valor — só sql, posts, terms, users, comments, repeater, current-wp-query, merged-query, relations-query. Para consultar um CCT usar query_type: "posts" com query_args.post_type no formato "<cct-slug>/<name>" (mesmo exemplo que a descrição da tool dá) — o enum é a fonte vinculativa, a descrição está desactualizada. Confirmar contra tools/list ao vivo antes de assumir que isto mudou.

Query sql exige query_args.sql não-vazio; qualquer outro tipo exige argumentos estilo WP_Query (tax_query, meta_query, etc.) — chamadas sem query_args são rejeitadas pelo plugin ("Requests without query_args are invalid").

6. Levantar contexto (macros, config, plugins activos)

{"name": "resource-get-macros", "arguments": {}}
{"name": "resource-get-website-config", "arguments": {"parts": {"post_types": true, "taxonomies": true, "active_plugins": true}}}
{"name": "resource-get-configuration", "arguments": {"parts": {"queries": true, "custom_content_types": true, "glossaries": true}}}

Útil antes de escrever texto/URLs dinâmicos num Listing Template ou numa Query — %macro% só funciona se a macro existir e aceitar os argumentos passados.