# 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.

```json
// 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.

```json
// 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).

```json
{"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**:

```json
{"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

```json
// 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)

```json
{"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.