feat(wordpress): playbooks de uso para mcp-jetengine
Adiciona references/playbooks.md (7 fluxos: ler antes de criar, modulos opcionais, CPT+taxonomia+meta-box, CCT, glossario, query builder+listing, levantar contexto) + indice curto em SKILL.md + keywords de trigger. Documenta 2 gotchas confirmados contra o schema nativo (tools/list 19-08-2026, nao exercidos como writes em producao): CCT exige o modulo 'custom-content-types' activo (so 'booking-forms' estava activo); query_type 'custom-content-type' aparece na descricao de tool-add-query mas nao no enum real - usar 'posts' com post_type 'slug/name'.
This commit is contained in:
Claude Code
@@ -0,0 +1,152 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user