Abilities di scrittura

01Panoramica

Le ability di scrittura sono le operazioni con cui un agente AI, la CLI locale o un amministratore cambiano il sito. Ogni ability ha un nome, uno schema di input e di output, annotazioni, un'esecuzione e un controllo della capability WordPress.

Nucleo le registra nell'Abilities API di WordPress, nella categoria nucleo, con show_in_rest: true. Ogni ability controlla lo scope OAuth e, per le scritture, applica il limite di frequenza. Le ability Pro si registrano solo con la licenza Pro.

Le ability sui documenti passano dalla stessa procedura: validazione, controllo qualità, compilazione e revisione.

Per il collegamento del client e per OAuth vedi la guida Collegare un agente AI. Le ability di sola lettura sono nel capitolo Abilities di lettura.

02Meccanismi comuni

Registrazione ed edizione

Cosa fa: registra le ability all'hook di inizializzazione. Salta quelle non disponibili e, senza licenza Pro, quelle Pro. Registra solo nomi in minuscolo non ancora registrati.

Come si usa: la registrazione è automatica all'hook wp_abilities_api_init. Il nome del tool MCP è il nome dell'ability con / sostituito da -: nucleo/doc-create diventa nucleo-doc-create. Da WP-CLI il prefisso nucleo/ è facoltativo.

# esegue un'ability dalla riga di comando
wp nucleo ability run <nome> --input='<JSON>'

Parametri: nessuno.

Permessi: vedi Permessi e scope.

Edizione: le ability Pro sono doc-translate, assets-audit, css-purge, kit-apply, css-optimize, css-optimize-apply e css-optimize-off. Tutte le altre sono Free.

Limiti noti: se l'input non ha campi obbligatori, lo schema riceve default: [].

Permessi e scope

Cosa fa: il controllo dei permessi verifica prima la capability WordPress dell'ability. Poi, se la richiesta ha un token OAuth, verifica lo scope richiesto dall'ability.

Come si usa: lo scope mancante restituisce un WP_Error insufficient_scope con stato 403 e lo scope richiesto nei dati. Il server MCP controlla lo scope prima di eseguire l'ability e risponde con insufficient_scope: requires scope ... e isError: true.

Parametri: nessuno.

Permessi: gli scope delle scritture sono nucleo:write, nucleo:publish, nucleo:design e nucleo:admin. Ogni scope corrisponde a una capability di riferimento: edit_posts, publish_pages, edit_theme_options e manage_options. La capability effettiva è quella riportata in ogni sezione.

Edizione: Free

Limiti noti: lo scope base dipende dal nome dell'ability. Il requisito nucleo:publish dipende dall'input e dallo stato del post, come indicato nell'avviso.

Limite di frequenza

Cosa fa: ogni ability con readonly diverso da true conta una chiamata in una finestra fissa di 60 secondi. La chiave è l'utente corrente e il gruppo di scope dell'ability. Tutte le 33 ability di questo capitolo hanno readonly: false.

Come si usa: oltre il limite l'ability non viene eseguita e restituisce questo errore.

{"ok": false, "error": {"code": "rate_limited", "message": "...", "retryAfter": 60}}

Parametri: filtro nucleo/rate_limit, default 60 chiamate per finestra.

Permessi: non applicabile.

Edizione: Free

Limiti noti: il contatore è atomico. Il limite vale per REST, MCP e WP-CLI, perché si applica all'esecuzione dell'ability. nucleo/doc-translate richiama nucleo/doc-texts-set internamente, ma conta una sola chiamata.

Formato dell'esito

Cosa fa: le ability restituiscono un oggetto con ok e, in caso di errore, error con code e message. Alcuni controlli di forma restituiscono invece un WP_Error, di solito con codice invalid_input. Il server MCP trasforma il WP_Error in isError: true con testo <codice>: <messaggio>.

Come si usa: le ability sui documenti restituiscono {ok, postId, revision, errors, quality, error?}. Il campo quality contiene score (seo, a11y, perf), blocking e issues. I codici di errore dei documenti sono invalid_document, quality_blocking, conflict, not_found, exists, patch_failed e write_failed.

Parametri: nessuno.

Permessi: non applicabile.

Edizione: Free

Limiti noti: nucleo/kit-apply e nucleo/site-import restituiscono un report senza la chiave ok. Il server MCP considera errore solo ok: false.

Riconoscimenti (acknowledge)

Cosa fa: elenco dei problemi di qualità bloccanti accettati. Ogni voce è {rule, node, reason}, con tre stringhe obbligatorie. Il documento unisce i riconoscimenti nuovi a quelli già salvati.

Come si usa: in nucleo/doc-create, nucleo/doc-patch e nucleo/doc-publish. In nucleo/site-import è un oggetto che associa il percorso del file a una lista, con reason non vuota.

Parametri: vedi le singole ability.

Permessi: quelli dell'ability.

Edizione: Free

Limiti noti: il controllo bloccante vale con publish: true e per ogni salvataggio di un post già pubblicato. Una forma non valida restituisce invalid_input.

03Riepilogo

Nessuna ability di scrittura produce un'anteprima visiva. L'URL firmato di anteprima viene da nucleo/doc-preview, descritta nel capitolo Abilities di lettura.

04Documenti

nucleo/doc-create

Cosa fa: crea una pagina, un post, un layout o una sezione da un documento Nucleo. Con postId aggancia il primo documento Nucleo a un contenuto esistente. La qualità si controlla sulla pagina composta con i layout del sito (header, footer, single o product), anche per un contenuto nuovo.

Come si usa: tool MCP nucleo-doc-create. Esempio: {"title": "Contatti", "document": {...}, "publish": false}.

Parametri:

Nessun'altra proprietà è ammessa (additionalProperties: false).

Output: {ok, postId, revision, slug, warnings?, errors, quality, error?}. slug è quello assegnato al contenuto, assente con dryRun. Con dryRun senza postId restituisce postId: 0 e revision: 0. Codici: invalid_input (WP_Error), invalid_document (con errors), quality_blocking (con quality) e write_failed. Con postId si aggiungono not_found e exists, quando il contenuto ha già un documento.

Permessi: con postId esistente edit_post su quel post; con postId inesistente edit_posts. Per nucleo_layout e nucleo_section serve edit_theme_options. Per post serve edit_posts, più publish_posts con publish: true. Per page serve edit_pages, più publish_pages con publish: true. Scope nucleo:write; con postId su un contenuto pubblicato serve anche lo scope nucleo:publish.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: sì (dryRun).

Edizione: Free

Limiti noti: per nucleo_layout il kind del documento deve essere layout o popup. Per nucleo_section deve essere section. Con postId il kind deve essere page o assente. Se root.children è vuoto e il post ha testo, il testo diventa al massimo 200 blocchi nc/text (paragrafi, titoli, voci di elenco). Immagini e altri elementi si perdono; l'originale resta nel meta _nucleo_wp_content. Un documento con "bind" viene compilato una seconda volta dopo la creazione. Ogni chiamata scrive una voce nel registro delle operazioni.

nucleo/doc-patch

Cosa fa: applica una lista di operazioni a un documento esistente, in ordine e in modo atomico. Controlla che baseRevision sia la revisione corrente.

Come si usa: tool MCP nucleo-doc-patch. Esempio: {"postId": 12, "baseRevision": 3, "ops": [{"op": "set", "id": "h1", "path": "content.text", "value": "Chi siamo"}]}.

Parametri:

Operazioni semantiche, per id di nodo:

Operazioni JSON Patch (RFC 6902, puntatori RFC 6901): add, replace, test, copy (from, path), move con from e remove con path. test fallisce se il valore è diverso o il percorso manca.

Output: {ok, postId, revision, errors, quality, error?}. Codici: invalid_input (WP_Error), not_found, conflict (revisione cambiata), patch_failed, invalid_document, quality_blocking e write_failed. patch_failed riporta nel messaggio l'indice dell'operazione (Operazione N: ...).

Permessi: edit_post su postId. Con publish: true serve anche publish_post. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: sì (dryRun).

Edizione: Free

Limiti noti: nessuna operazione sulla radice del documento. Il codice interno dell'errore di patch (invalid_op, forbidden, not_found, conflict) non esce come error.code: esce sempre patch_failed. Un post senza documento Nucleo dà patch_failed. Su un post pubblicato il controllo bloccante vale anche senza publish.

nucleo/doc-publish

Cosa fa: pubblica il documento corrente. Lo salva di nuovo con publish: true sulla revisione corrente.

Come si usa: tool MCP nucleo-doc-publish. Esempio: {"postId": 12}.

Parametri:

Output: {ok, postId, revision, errors, quality, error?}. Codici: invalid_input (WP_Error), not_found, quality_blocking, invalid_document, write_failed e conflict.

Permessi: publish_post su postId. Scope nucleo:publish.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: ogni chiamata riuscita crea una nuova revisione.

nucleo/doc-rollback

Cosa fa: ripristina una revisione precedente. Il ripristino crea una nuova revisione, quindi la cronologia resta.

Come si usa: tool MCP nucleo-doc-rollback. Il numero di revisione si legge con nucleo/doc-revisions, descritta nel capitolo Abilities di lettura.

Parametri:

Output: {ok, postId, revision, errors, quality, error?}. Codici: invalid_input (WP_Error) e not_found (documento o revisione), più quelli del salvataggio.

Permessi: edit_post su postId. Scope nucleo:write.

Annotazioni: readonly false, destructive true, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: non accetta acknowledge. Su un post pubblicato, un problema bloccante non coperto dai riconoscimenti salvati dà quality_blocking.

nucleo/doc-texts-set

Cosa fa: riscrive in blocco i testi di un documento. Struttura e altri campi non cambiano.

Come si usa: tool MCP nucleo-doc-texts-set. id e path si leggono con nucleo/doc-texts, descritta nel capitolo Abilities di lettura.

Parametri:

Output: {ok, postId, revision, errors, quality, error?}. Codici: invalid_input (WP_Error), not_found, invalid_path (campo non traducibile o nodo assente), più quelli di nucleo/doc-patch.

Permessi: edit_post su postId. Con publish: true serve anche publish_post. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: accetta solo i percorsi che nucleo/doc-texts espone. Ogni testo diventa un'operazione set di nucleo/doc-patch. Al primo percorso non ammesso non scrive nulla.

nucleo/doc-translate

Cosa fa: copia un documento in un nuovo post dello stesso tipo, applica i testi tradotti e collega la traduzione al sorgente tramite il plugin multilingua. Lingua e collegamento si assegnano alla copia in bozza, prima dei testi e della pubblicazione. Se esiste già una traduzione in quella lingua, la restituisce con existing: true senza creare né modificare nulla: i testi si aggiornano con nucleo/doc-texts-set. Se i testi non si applicano, la copia si elimina.

Come si usa: tool MCP nucleo-doc-translate. Esempio: {"postId": 12, "lang": "en", "title": "About us", "texts": [...]}.

Parametri:

Output: {ok, postId, existing?, error?}. Codici: invalid_input (WP_Error), not_found, create_failed, unknown_language (lingua non configurata nel plugin multilingua) e same_language (il sorgente è già in quella lingua), più i codici di nucleo/doc-create e nucleo/doc-texts-set.

Permessi: edit_post sul sorgente. Con publish: true serve anche publish_post sul sorgente. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Pro

Limiti noti: se i testi non si applicano, la copia si elimina e la risposta è un errore, così un nuovo tentativo non trova una traduzione a metà. Con existing: true la traduzione c'era già: non si crea né si modifica nulla. Il collegamento al gruppo di traduzioni avviene solo se il sorgente ha una lingua nel plugin multilingua. Dopo il collegamento lancia l'azione nucleo/translation_created ($newId, $sourceId, $lang).

05Design token, font e icone

nucleo/tokens-set

Cosa fa: modifica i token di design e ripubblica il CSS dei token.

Come si usa: tool MCP nucleo-tokens-set. Esempio: {"tokens": {"color": {"primary": "#1d4ed8"}, "space": {"20": 6}}}. Le regole complete sono nel capitolo Design token.

Parametri:

Output: {ok, tokens, contrast} con l'insieme completo dei token dopo la modifica e contrast, la lista dei problemi di contrasto che i nuovi token causano nei documenti pubblicati (rule, postId, node). Codici: invalid_input (WP_Error, se tokens non è un oggetto) e invalid_tokens (valore o gruppo non valido).

Permessi: edit_theme_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: i valori si uniscono a quelli salvati, gruppo per gruppo e chiave per chiave. null toglie la chiave. Un gruppo inviato come valore non oggetto sostituisce il gruppo intero. Le chiavi nuove sono in minuscolo, con cifre e -, al massimo 48 per gruppo. space e text sono in rem, text come [minRem, maxRem], container in px interi.

nucleo/fonts-import

Cosa fa: scarica una famiglia di Google Fonts in locale, come file woff2 nella libreria upload, e la rende disponibile ai token. Sostituisce la stessa famiglia già importata.

Come si usa: tool MCP nucleo-fonts-import. Esempio: {"family": "Inter", "weights": [400, 700]}.

Parametri:

Output: {ok, faces: [{family, weight, style, url}]}. Codici: invalid_input (WP_Error), invalid_family, invalid_weights, uploads_unavailable, font_format, font_host_rejected, font_network, font_too_large e font_write.

Permessi: edit_theme_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: ogni file font pesa al massimo 2 MB. Accetta solo host di font e subset ammessi. Il percorso del file sul server non esce nella risposta.

nucleo/icons-set

Cosa fa: aggiunge, sostituisce o toglie icone del sito per nc/icon. Le altre icone restano.

Come si usa: tool MCP nucleo-icons-set. Esempio: {"set": {"phone": "<svg viewBox=\"0 0 24 24\">...</svg>"}, "remove": ["old"]}.

Parametri:

Output: {ok, icons, builtin}, cioè i nomi delle icone del sito dopo la modifica e i nomi delle icone interne. Codice: invalid_input.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: al massimo 300 icone, di 20000 byte ciascuna. L'SVG deve avere viewBox e almeno un elemento. Restano solo gli elementi svg, g, path, circle, ellipse, rect, line, polyline e polygon. I colori diventano currentColor. Il nome di un'icona interna (per esempio phone) la sostituisce ovunque, anche in nc/menu e nc/list.

06Media

nucleo/media-import

Cosa fa: scarica un'immagine pubblica da un URL https e la aggiunge alla libreria media, con testo alternativo.

Come si usa: tool MCP nucleo-media-import. Esempio: {"url": "https://esempio.it/foto.jpg", "alt": "Facciata del negozio"}.

Parametri:

Output: {ok, id, url, width, height}. Codici: invalid_input (WP_Error), invalid_url, download_failed (rete, HTTP diverso da 200, file vuoto o oltre 10 MB, salvataggio fallito) e unsupported_type.

Permessi: upload_files. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: timeout di 15 secondi. Tipi ammessi: jpeg, png, webp, gif e avif, controllati sul contenuto reale. Non riconosce i duplicati: ogni chiamata crea un allegato.

nucleo/media-upload

Cosa fa: carica nella libreria media un'immagine inviata in base64, con testo alternativo. Se trova un file identico già caricato, lo restituisce senza ricaricarlo.

Come si usa: tool MCP nucleo-media-upload. Esempio: {"file": "logo.png", "data": "<base64>", "alt": "Logo"}.

Parametri:

Output: {ok, id, url, width, height, file, sha1, existing}. Codici: invalid_input (WP_Error), invalid_data (base64 non valido o vuoto), unsupported_type e download_failed (oltre 10 MB o salvataggio fallito).

Permessi: upload_files. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: il duplicato si riconosce dallo SHA-1 e dal nome del file originale, anche con suffisso -1, -2. Tipi ammessi: jpeg, png, webp, gif e avif.

nucleo/media-formats

Cosa fa: genera i formati moderni (avif, webp) attivi nelle opzioni del sito per immagini già caricate, originali e dimensioni intermedie.

Come si usa: tool MCP nucleo-media-formats. Esempio: {"missing": true, "limit": 50}. I formati si attivano con imageFormats di nucleo/site-options-set.

Parametri:

Output: {ok, done: [{id, formats}], enabled, supported, remaining}. remaining conta gli allegati immagine ancora senza formati. Codice: formats_disabled (nessun formato attivo).

Permessi: upload_files. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: senza ids lavora in ordine di ID. supported elenca i formati che l'editor di immagini del server sa scrivere.

07Menu, opzioni del sito e impostazioni

nucleo/menu-set

Cosa fa: crea o aggiorna un menu di navigazione per slug e ne sostituisce tutte le voci.

Come si usa: tool MCP nucleo-menu-set. Esempio: {"slug": "principale", "items": [{"label": "Home", "ref": "home"}, {"label": "Servizi", "page": "servizi", "children": [...]}]}.

Parametri:

Ogni voce ha label non vuota ed esattamente uno tra page (slug di pagina pubblicata), post (slug di articolo pubblicato), url (link esterno) e ref. Valori di ref: home, archive:<post-type>, <post-type>:<slug> (slug gerarchici come percorso) e term:<taxonomy>/<slug>. ref non accetta un'ancora #.

Output: {ok, id, slug, count}. count include le voci figlie. Codici: invalid_input, invalid_items, menu_failed e menu_target_missing.

Permessi: edit_theme_options. Scope nucleo:design.

Annotazioni: readonly false, destructive true, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: al massimo 3 livelli di annidamento. Le voci si validano prima di toccare il menu. Il menu si crea prima di risolvere i bersagli: se un bersaglio manca, un menu nuovo resta vuoto e uno esistente resta com'è. Dopo la scrittura i layout in coda si ricompilano subito.

nucleo/site-options-set

Cosa fa: salva titolo, motto, homepage, pagina degli articoli, formati di data e ora, attività commerciale per i dati strutturati, icone, favicon e formati immagine moderni.

Come si usa: tool MCP nucleo-site-options-set. Esempio: {"title": "Officina Rossi", "homepage": "home", "imageFormats": ["avif", "webp"]}.

Parametri:

Output: {ok, site} con title, tagline, homepage, postsPage, language, dateFormat, timeFormat, business, icons e imageFormats. Codici: invalid_input, page_not_found e same_page.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: controlla ogni valore prima di scrivere. Il JSON-LD di business non si stampa con Yoast o Rank Math attivi. language non è nello schema di input: si imposta con nucleo/site-import.

nucleo/settings-set

Cosa fa: salva le impostazioni di Nucleo in modo parziale. Valida tutto prima di scrivere.

Come si usa: tool MCP nucleo-settings-set. Esempio: {"settings": {"captcha": {"provider": "turnstile", "siteKey": "...", "secret": "..."}}}.

Parametri: settings (object, obbligatorio) con questi gruppi, tutti facoltativi:

Output: {ok, settings} nella forma di nucleo/settings-get, senza integrazioni. Codice: invalid_input, anche per un gruppo sconosciuto.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: al primo valore non valido restituisce l'errore e non scrive nulla. La chiave del servizio e il segreto del captcha non tornano mai nella risposta.

08Contenuti e termini

nucleo/content-upsert

Cosa fa: crea o aggiorna elementi di contenuto per tipo e slug. Cestina gli elementi con status: "trash". Un elemento con errori non scrive nulla, mentre gli altri proseguono.

Come si usa: tool MCP nucleo-content-upsert. Il formato degli elementi è nel capitolo Dati dinamici.

Parametri:

Output: {ok, created, updated, unchanged, trashed, results, errors}. ok è vero se errors è vuoto. results contiene {index, slug, action, id, hash}, con action created, updated, unchanged o trashed. Un elemento identico a quello salvato non si riscrive: unchanged, e post_modified resta com'è; hash è la nuova base, assente con dryRun. errors contiene {index, slug, type, path, code, message}. Codici per elemento: conflict, invalid_input, unknown_field, required, unknown_type, invalid_value, duplicate, ambiguous_slug, slug_conflict, forbidden, managed_by_document, not_found, protected, unknown_taxonomy e error, più quelli dei campi. Errore generale invalid_input con 0 o più di 100 elementi.

Permessi: edit_posts. Per elemento: edit_posts del tipo, edit_post sull'elemento esistente, publish_posts del tipo per publish, future e private, delete_post per trash, assign_terms per ogni tassonomia. Scope nucleo:write.

Annotazioni: readonly false, destructive true, idempotent false.

Dry-run: sì (dryRun).

Edizione: Free

Limiti noti: body di un elemento con documento Nucleo dà managed_by_document. Le pagine protette del sistema non si cestinano (protected).

nucleo/terms-set

Cosa fa: crea o aggiorna i termini di una tassonomia per slug, in modo parziale. Non cancella termini.

Come si usa: tool MCP nucleo-terms-set. Esempio: {"taxonomy": "area", "terms": [{"slug": "nutrizione", "name": "Nutrizione"}]}.

Parametri:

Output: {ok, created, updated, unchanged, results, errors}. results contiene {index, slug, action, id, hash}, con action created, updated o unchanged (termine identico a quello salvato, non riscritto). Codici per termine: conflict, invalid_input, duplicate, unknown_taxonomy, invalid_value, required, not_found, forbidden e error, più quelli dei campi. Errore generale invalid_input.

Permessi: manage_terms della tassonomia. Per termine: edit_terms alla creazione, edit_term sul termine esistente. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: sì (dryRun).

Edizione: Free

Limiti noti: un termine con errori non scrive nulla, mentre gli altri proseguono. Una tassonomia inesistente non supera il controllo dei permessi.

09Modello dei contenuti e campi

nucleo/model-set

Cosa fa: salva il modello dei contenuti, cioè tipi, tassonomie e gruppi di campi. Valida e calcola il diff prima di scrivere.

Come si usa: tool MCP nucleo-model-set. Il formato è nel capitolo Dati dinamici.

Parametri:

Output: {ok, diff, kept}. kept elenca le parti non inviate. Errori: {ok: false, errors} con gli errori di validazione, {ok: false, error: {code: "destructive"}, diff} per le modifiche distruttive non confermate, e invalid_input.

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: sì (dryRun).

Edizione: Free, con parti Pro.

Limiti noti: slug dei tipi di al massimo 20 caratteri, slug delle tassonomie di al massimo 32. Gli slug di WordPress e i tipi registrati da altri plugin o dal tema danno reserved_slug. Un repeater non contiene un altro repeater. Se cambiano tipi o tassonomie, il sito registra di nuovo i tipi e svuota le regole di riscrittura. L'annotazione destructive è false anche quando, con confirm, la chiamata toglie tipi o campi.

nucleo/fields-set

Cosa fa: salva i valori dei campi di un contenuto o di un termine, in modo parziale. Un valore vuoto svuota il campo.

Come si usa: tool MCP nucleo-fields-set. Esempio: {"postId": 34, "values": {"prezzo": 120}}.

Parametri:

Output: {ok, hash?, errors?}, con hash nuova base dopo il salvataggio, ed errori {code, path, message}, per esempio unknown_field, required, invalid_value, too_many e too_few. Codici generali: invalid_input, conflict e not_found, quando non esiste un tipo o una tassonomia con campi per quell'ID.

Permessi: edit_post su postId o edit_term su termId. Senza uno dei due, o con entrambi, il permesso è negato. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: controlla ogni valore prima di scrivere. Scrive solo i campi del modello Nucleo, non quelli di altri plugin.

10Layout

nucleo/layout-conditions-set

Cosa fa: sostituisce le condizioni include, exclude e priority di un layout. Il resto del documento non cambia. Il salvataggio ricompila la mappa dei layout.

Come si usa: tool MCP nucleo-layout-conditions-set. Esempio: {"postId": 7, "conditions": {"include": [{"type": "post_type", "value": "prodotto"}]}}. I tipi di condizione sono nel capitolo Compilatore e runtime.

Parametri:

Output: {ok, postId, revision, errors, quality, error?}. Codici: invalid_input (WP_Error), not_found, not_layout, conflict e invalid_document. Le condizioni non valide sono in errors con codice layout_condition.

Permessi: edit_post su postId. Scope nucleo:design; su un layout pubblicato serve anche lo scope nucleo:publish.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: il post deve essere nucleo_layout con kind layout o popup. Lo stato del post non cambia.

11Asset, CSS e critical CSS

Il funzionamento di regole, audit, riduzione e critical CSS è descritto nel capitolo Ottimizzatore e asset.

nucleo/assets-audit

Cosa fa: pianifica l'audit degli asset caricati dai template campione del sito. Ogni template è un job in background. Sostituisce il piano precedente.

Come si usa: tool MCP nucleo-assets-audit. Il report si legge con nucleo/assets-report, descritta nel capitolo Abilities di lettura.

Parametri:

Output: {ok, jobs}. Codici: invalid_input (WP_Error) e no_templates.

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Pro

Limiti noti: i job partono con un evento cron singolo.

nucleo/assets-rules-set

Cosa fa: sostituisce le regole asset dell'utente (dequeue, defer, replace) e ripubblica la tabella delle regole.

Come si usa: tool MCP nucleo-assets-rules-set. Esempio: {"rules": [{"action": "dequeue", "handle": "contact-form-7", "templates": ["page"]}]}.

Parametri:

Output: {ok, count, warnings}, dove warnings è una lista di testi di avviso. Codice: invalid_input (WP_Error).

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: le regole non valide si ignorano in compilazione, ma restano salvate. count è il numero di regole inviate, non quello delle regole valide.

nucleo/css-purge

Cosa fa: riduce il CSS di terzi per un tipo di template usando una pagina campione del sito. Restituisce le dimensioni prima e dopo e l'URL della variante.

Come si usa: tool MCP nucleo-css-purge. Esempio: {"template": "page", "handles": [{"handle": "elementor-frontend", "src": "https://..."}]}.

Parametri:

Output: {ok, results: [{handle, before, after, url}]}. Codici: invalid_input (WP_Error), dir_unwritable, write_failed e sample_unreachable.

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Pro

Limiti noti: la riduzione gira nella stessa richiesta, non in background.

nucleo/critical-set

Cosa fa: salva il critical CSS di un template.

Come si usa: tool MCP nucleo-critical-set. Lo chiama la CLI o il servizio esterno dopo nucleo/critical-request.

Parametri:

Output: {ok, bytes}. Codici: invalid_input e invalid_critical_css (entrambi WP_Error).

Permessi: edit_theme_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: rimuove </style dal CSS. Il massimo è 51200 byte (50 KB) dopo la pulizia.

nucleo/critical-request

Cosa fa: chiede a un servizio esterno il calcolo del critical CSS dei template. Il risultato torna con nucleo/critical-set.

Come si usa: tool MCP nucleo-critical-request. URL e chiave del servizio si impostano con nucleo/settings-set, gruppo service.

Parametri:

Output: {ok, job}. Codici (WP_Error): invalid_input, service_not_configured, service_unreachable e service_error.

Permessi: edit_theme_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: richiede URL https e chiave del servizio, impostati nelle impostazioni di Nucleo.

nucleo/css-optimize

Cosa fa: calcola un candidato di ottimizzazione CSS per un tipo di template, dal DOM misurato nel browser: fogli di terzi ridotti e critical CSS della prima schermata. Non pubblica il candidato.

Come si usa: tool MCP nucleo-css-optimize. Il candidato si pubblica con nucleo/css-optimize-apply.

Parametri:

Output: {ok, candidate: {sheets, before, after, critical: {bytes, error}, samples, classes}}. Codici: invalid_input (WP_Error), no_stylesheets, dir_unwritable e write_failed.

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no. Il candidato stesso è un'anteprima non pubblicata.

Edizione: Pro

Limiti noti: un campione su un altro host invalida tutta la richiesta.

nucleo/css-optimize-apply

Cosa fa: pubblica le parti del candidato che hanno passato il controllo nel browser: fogli ridotti e critical CSS. Toglie il candidato e restituisce la voce di stato salvata.

Come si usa: tool MCP nucleo-css-optimize-apply. Esempio: {"template": "page", "candidateId": "<id da nucleo/css-optimize>", "purge": true, "critical": false, "check": {"elements": 812, "diffs": []}}.

Parametri:

Output: {ok, status}. Codici: invalid_input (WP_Error), no_candidate (eseguire prima nucleo/css-optimize), candidate_changed (il candidato salvato è un altro), candidate_stale (il sito è cambiato dopo la misura: un documento salvato, la coda di ricostruzione o i token; eseguire di nuovo nucleo/css-optimize), critical_too_big (critical CSS oltre il limite) e gli altri codici di CssOptimizeState::apply().

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Pro

Limiti noti: senza un candidato salvato dà no_candidate. Il critical CSS oltre 50 KB dà critical_too_big.

nucleo/css-optimize-off

Cosa fa: spegne l'ottimizzazione CSS di un tipo di template. Toglie fogli ridotti e critical CSS. La voce di stato resta con stato off.

Come si usa: tool MCP nucleo-css-optimize-off. Esempio: {"template": "page"}.

Parametri:

Output: {ok}. Codice: invalid_input (WP_Error).

Permessi: manage_options. Scope nucleo:design.

Annotazioni: readonly false, destructive true, idempotent true.

Dry-run: no.

Edizione: Pro

Limiti noti: nessuno rilevato.

12Kit

nucleo/kit-apply

Cosa fa: applica un kit di avvio con lo stesso import dei siti: crea o aggiorna token, sezioni, pagine e layout.

Come si usa: tool MCP nucleo-kit-apply. I kit si elencano con nucleo/kit-list, descritta nel capitolo Abilities di lettura. Dettagli nel capitolo Kit.

Parametri:

Output: report dell'import: {created, updated, unchanged, errors, warnings, ids, base, tokensBase}, senza ok. Codici (WP_Error): invalid_input, kit_unknown e requires_missing (con missing nei dati).

Permessi: edit_theme_options. Scope nucleo:design.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: sì (dryRun).

Edizione: Pro

Limiti noti: l'unico requisito riconosciuto è woocommerce. Un requisito sconosciuto non è mai soddisfatto. Se il sito mostra gli articoli in home e il kit ha page:home, quella pagina diventa la pagina iniziale.

13Import ed export

nucleo/site-import

Cosa fa: importa i file prodotti da nucleo/site-export. Crea o aggiorna per slug token, sezioni, pagine, post, layout, regole, media, menu e impostazioni del sito (titolo, motto, homepage, lingua). La qualità si controlla sulla pagina composta con i layout del sito, anche per le pagine nuove. Pagine e post si importano prima dei layout, perché le condizioni dei layout li referenziano (page:<slug>).

Come si usa: tool MCP nucleo-site-import. La CLI locale lo usa per nucleo push. Dettagli nel capitolo Import, export e sync.

Parametri:

Output: {created, updated, unchanged, errors, warnings, ids, base, tokensBase}, senza ok. Ogni voce di errors contiene {file, message, code, guide}, con code tra error, conflict, duplicate, not_json, invalid_document e quality_blocking. Codice generale: invalid_input (WP_Error).

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: sì (dryRun).

Edizione: Free

Limiti noti: un codice di errore interno non in elenco diventa error, con il codice originale nel messaggio. base e tokensBase sono le nuove impronte da scrivere in site.json.

14Cache

nucleo/cache-rebuild

Cosa fa: ricompila i documenti indicati o tutti, senza creare nuove revisioni. Ripubblica dal database token, regole asset, layout e modello dei contenuti.

Come si usa: tool MCP nucleo-cache-rebuild. Serve quando nucleo/site-describe segnala la cache Nucleo vuota.

Parametri:

Output: {ok, rebuilt, queued, republished}. republished è false se un'altra ricostruzione tiene il lock. Codice: invalid_input (WP_Error).

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: ricompila subito al massimo 20 documenti. Il resto va in coda. Un documento che non si può ricompilare (non valido, o con problemi bloccanti su un post pubblicato) mantiene il suo output precedente: vedi nucleo/status, campi stale e failed. Senza postIds considera solo page, post, nucleo_layout e nucleo_section con il meta _nucleo_doc.

15Gap report

nucleo/gap-report

Cosa fa: registra una cosa che il design chiede e Nucleo non sa fare, con il workaround usato. La stessa coppia di blocco e bisogno incrementa un contatore.

Come si usa: tool MCP nucleo-gap-report. Le segnalazioni si leggono con nucleo/gap-list, descritta nel capitolo Abilities di lettura.

Parametri:

Output: {ok, count}. Codice: invalid_input.

Permessi: edit_pages. Scope nucleo:write.

Annotazioni: readonly false, destructive false, idempotent false.

Dry-run: no.

Edizione: Free

Limiti noti: conserva al massimo 200 segnalazioni. Le più vecchie si scartano.

16Componenti

nucleo/component-activate

Cosa fa: attiva un plugin di componenti Nucleo già presente su disco. Non installa nulla e non riceve codice.

Come si usa: tool MCP nucleo-component-activate. Esempio: {"plugin": "officina-componenti"}.

Parametri:

Output: {ok, plugin, active, already}. Codici: invalid_input (WP_Error), not_found, not_component e activation_failed.

Permessi: activate_plugins. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Free

Limiti noti: il file deve trovarsi in WP_PLUGIN_DIR/<slug>/<slug>.php, con l'intestazione Nucleo Components. Un plugin già attivo restituisce already: true.

17WooCommerce

nucleo/woo-checkout-fields-set

Cosa fa: aggiunge, sostituisce o toglie campi aggiuntivi del checkout a blocchi di WooCommerce. Nucleo li salva nell'opzione nucleo_woo_checkout_fields e li registra a ogni richiesta con l'API Additional Checkout Fields di WooCommerce (woocommerce_register_additional_checkout_field), con id nucleo/<key>. WooCommerce salva i valori sull'ordine e li mostra nell'amministrazione e nelle email.

Come si usa: tool MCP nucleo-woo-checkout-fields-set. Esempio: {"set": [{"key": "vat", "label": "Partita IVA", "location": "address", "type": "text", "required": false}], "remove": ["old"]}.

Parametri:

Output: {ok, fields}, cioè i campi dopo la modifica. Input vuoto (senza set né remove): non cambia nulla e restituisce i campi salvati. Codici: woo_missing, invalid_field, too_many_fields.

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Pro

Limiti noti: al massimo 20 campi. I campi compaiono solo nel checkout a blocchi (woo/checkout con mode blocks), non nello shortcode classico. Togliere un campo non cancella i valori già salvati sugli ordini.

nucleo/woo-checkout-parts-set

Cosa fa: mostra o nasconde parti del checkout di WooCommerce. Note d'ordine, termini e condizioni e campo coupon sono blocchi interni della pagina Checkout, che deve usare il blocco woocommerce/checkout: l'ability li toglie o li rimette al loro posto nel contenuto della pagina, che WordPress salva con una revisione (se la pagina ha un documento Nucleo, si modifica la sua copia originale). Azienda, telefono e seconda riga dell'indirizzo sono opzioni di WooCommerce (hidden, optional, required) e funzionano anche con il checkout classico. Senza parametri restituisce lo stato attuale e non conta come scrittura; su un checkout classico o senza pagina Checkout le parti a blocchi risultano null.

Come si usa: tool MCP nucleo-woo-checkout-parts-set. Esempio: {"orderNote": false, "company": "optional"}. Senza parametri restituisce lo stato attuale.

Parametri:

Output: {ok, parts, pageId}, cioè lo stato delle sei parti dopo la modifica e l'id della pagina Checkout. Codici: woo_missing, invalid_part, no_checkout_page, not_block_checkout e anchor_missing (nella pagina manca il blocco a cui agganciare la parte).

Permessi: manage_options. Scope nucleo:admin.

Annotazioni: readonly false, destructive false, idempotent true.

Dry-run: no.

Edizione: Pro

Limiti noti: serve una pagina Checkout con il blocco woocommerce/checkout. Un valore non valido non cambia nulla. Se il riepilogo dell'ordine ha la struttura vecchia della pagina creata dall'installer di WooCommerce, con i totali come figli diretti, l'ability li sposta in un checkout-order-summary-totals-block, come fa l'editor. Così l'editor non rimette il coupon tolto.