WP-LIT-MCP/docs/guides/overview.md

# LIT MCP – Übersicht

Dieser Server pflegt eine WordPress-Website. Alle Änderungen laufen mit den Rechten
des verbundenen WordPress-Benutzers.

## Grundregeln

1. **Divi-nativ:** Inhalte werden als echte Divi-5-Module erzeugt, damit sie im Visual
   Builder weiter bearbeitet werden können. Das Code-Modul nur verwenden, wenn kein
   natives Modul passt.
2. **Designsystem nutzen:** Globale Farben, Variablen und Presets der Website vor festen
   Werten verwenden.
3. **Status respektieren:** Entwürfe bleiben Entwürfe, veröffentlichte Inhalte bleiben
   veröffentlicht. Veröffentlichen nur auf ausdrücklichen Wunsch.
4. **Lesen vor Schreiben:** Vor Änderungen den aktuellen Stand lesen; Schreib-Tools
   verlangen den `rev` des letzten Lesevorgangs, Divi-Seiten die `tree_rev`, Änderungen am Designsystem
   die `design_rev` aus dem Probelauf.

## Werkzeuge

Direkt sichtbar: `lit-guide`, `lit-site-status`, `lit-content-types`, `lit-content-query`,
`lit-content-get`, `lit-content-create`, `lit-content-update`, `lit-post-publish`, `lit-media-search`,
`lit-media-preview`, `lit-media-download`, `lit-media-upload-from-url`, `lit-page-render-summary`,
`lit-divi-outline`, `lit-divi-node-get`, `lit-divi-catalog`, `lit-divi-design-system`, `lit-divi-insert`,
`lit-divi-update`, `lit-divi-move`, `lit-divi-delete`, `lit-library-insert`.

Die Tools sind nach Integration gruppiert (Grundlagen, WordPress, Medien, Divi, Divi-Bibliothek,
Divi Theme Builder). Jede Gruppe hat unter Einstellungen → LIT MCP → Tools eine eigene Einstellung
(direkt/indirekt/deaktiviert), die ihre Tools übernehmen („wie Gruppe“). Eine Einstellung am einzelnen Tool geht vor; die Gruppe zeigt dann „gemischt“. „nur lesen“
schaltet alle schreibenden Tools der Gruppe ab – auch solche mit eigener Einstellung. `lit-guide` bleibt immer
direkt; `lit-media-preview`/`lit-media-download` bleiben bei Gruppe „indirekt“ direkt. Ab mehr als 25 direkten
Tools warnt die Seite (Kontextkosten im Assistenten). Änderungen gelten ab der nächsten Verbindung.

Über `mcp-adapter-discover-abilities` / `mcp-adapter-execute-ability` (Ability-Namen `lit/…`; in Guides und
Hinweisen immer so geschrieben):
Status (`lit/post-unpublish`, `lit/post-schedule`, `lit/post-trash`), Kopien (`lit/post-duplicate`,
`lit/post-replace-with-copy`), Revisionen (`lit/revisions-list`, `lit/revision-restore`), Menüs
(`lit/menu-list`, `lit/menu-get`, `lit/menu-create`, `lit/menu-set-items`, `lit/menu-assign-location`),
Einstellungen (`lit/wp-settings-get`, `lit/wp-settings-update`), Medien (`lit/media-get`, `lit/media-upload`,
`lit/media-update`, `lit/media-delete`), Divi (`lit/divi-duplicate-node`, `lit/divi-replace-text`,
`lit/divi-node-copy`, `lit/divi-dynamic-sources`), Divi-Designsystem (Presets: `lit/divi-preset-get`,
`lit/divi-presets-set`, `lit/divi-presets-delete`, `lit/divi-presets-assign`, `lit/divi-design-detach`; Farben und
Variablen: `lit/divi-colors-set`, `lit/divi-variables-set`; Theme-Optionen: `lit/divi-theme-options-get`,
`lit/divi-theme-options-update`; globales CSS: `lit/divi-custom-css-get`, `lit/divi-custom-css-update`; Schriften: `lit/divi-fonts-upload`; Snapshots: `lit/divi-design-snapshots`,
`lit/divi-design-restore`; Ablauf: `lit-guide` topic `divi-design-system`), Divi-Bibliothek (`lit/library-list`, `lit/library-save`,
`lit/library-find-similar`, `lit/library-make-global`), Divi Theme Builder (`lit/tb-list`,
`lit/tb-create-template`, `lit/tb-assign`, `lit/tb-activate`).

Die `lit-divi-…`-Werkzeuge gibt es nur, wenn der Divi-5-Builder aktiv ist. Sie arbeiten auch auf Einträgen
der Divi-Bibliothek und auf Layouts des Theme Builders (ID als `post_id`); globale Module: `lit-guide` topic
`divi-library`, Vorlagen: `lit-guide` topic `theme-builder`.

Weitere Themen: `lit-guide` mit `topic` = `content-types`, `workflows`, `media`, `divi-structure`,
`divi-shortform`, `divi-attrs`, `divi-placeholders`, `divi-design-system`, `divi-library` oder
`theme-builder`.

Für den Einstieg liefert `lit-guide` mit dem Thema „all“ alle Themen in einem Aufruf.

## Rückmeldungen

- Erfolg: `ok`, `summary`, `changed`, `warnings`, `rev`, `revision_id` (Revision mit dem Stand vorher, nur bei
  Tools, die Inhalt überschreiben, sonst `null`), `log_id`, URLs. Divi-Werkzeuge zusätzlich `tree_rev` (Stand
  des Seiteninhalts, Pflicht für die nächste Divi-Änderung) und `outline` (betroffener Abschnitt);
  `lit/divi-replace-text` nennt `tree_rev` je Seite in `results` (Probelauf: in `matches`). Bei
  Bibliothekseinträgen und Theme-Builder-Layouts kommt `restore_url` hinzu (Revisionsvergleich in WordPress) –
  `lit/revision-restore` gilt nur für Inhaltstypen.
- Fehler: JSON mit `code` (z. B. `validation_failed`, `rev_mismatch`, `write_failed`, `partial_write`),
  `message`, `hint` (und ggf. `fields`). Dem `hint` folgen. Weitere Codes: `forbidden` (ein Recht fehlt, die
  Meldung nennt es), `in_use` (ein Preset oder Eintrag wird noch verwendet; `usages` nennt die Fundstellen),
  `conflict` (eine andere Änderung am Designsystem läuft noch, oder der Name einer Schrift ist vergeben),
  `not_found` (z. B. eine unbekannte oder verdrängte `snapshot_id`), `snapshot_too_large`, `font_fetch_failed` (Schriftdatei nicht ladbar) und `font_invalid`
  (Datei passt nicht zum Format).
- `confirm_required`: Nutzer fragen, dann mit `confirm: true` wiederholen. Beim Designsystem enthält die Antwort
  die `design_rev`, die mit `confirm: true` zurückgegeben wird; `rev_mismatch` heißt dort: der Bestand hat sich
  seit dem Probelauf geändert, den Probelauf wiederholen.

## Divi-Fähigkeit nicht freigegeben

LIT MCP gibt jede Divi-Fähigkeit einzeln frei, z. B. „Seiten lesen“, „Seiten schreiben“, „Presets schreiben“,
„Farben schreiben“, „Variablen schreiben“, „Theme-Optionen schreiben“, „Schriften hochladen“ oder
„Theme Builder lesen“. Nach einem Divi-Update geschieht das automatisch, wenn alle Divi-Stellen, die eine Fähigkeit
nutzt, unverändert sind (geprüft wird die Aufrufform, nicht das Verhalten); sonst nach einer Prüfung durch einen
Administrator. Nur Werkzeuge, die eine nicht nutzbare Fähigkeit brauchen – lesende wie schreibende –, lehnen ab; alle
anderen Divi-Werkzeuge laufen weiter, ebenso `lit-content-create` ohne `divi`.

Antwortet ein Werkzeug mit `divi_untested`, ist eine Fähigkeit, die es braucht, für die installierte Divi-Version noch
nicht geprüft; bei `divi_incompatible` hat Divi Stellen geändert, die LIT MCP dafür nutzt. In beiden Fällen wurde
nichts geändert. Vorgehen:

1. Den Aufruf nicht wiederholen: er scheitert, bis ein Administrator eingreift.
2. `lit-site-status` lesen. Unter `components` → `divi` → `features` steht je Fähigkeit der Zustand (`released`,
   `untested`, `incompatible`), die Quelle (`code`, `database`, `auto`), die Probleme (`problems`) und die betroffenen
   Werkzeuge (`tools`).
3. Ein anderes Werkzeug nutzen, das die betroffene Fähigkeit nicht braucht – ist z. B. nur „Seiten schreiben“
   betroffen, funktioniert `lit-divi-outline` weiter, und der Nutzer kann die Änderung selbst im Divi-Builder machen.
4. Den Nutzer informieren: bei `divi_untested` soll ein Administrator unter Einstellungen → LIT MCP → Kompatibilität die
   Prüfung ausführen und die Version freigeben; bei `divi_incompatible` muss LIT MCP aktualisiert werden. Die Sperre
   nicht über andere Werkzeuge umgehen.
5. Dasselbe gilt für Pods: Ist eine Pods-Fähigkeit (`pods-…`) nicht nutzbar, antwortet das betroffene Werkzeug mit
   `compat_incompatible`; der Stand steht im selben Reiter „Kompatibilität“.

Seitenweite Änderungen (Optionen, Menüs und Menü-Positionen, Medien, Divi-Design, Theme Builder, globale
Bibliotheksmodule) leeren den Cache von WP Super Cache, Änderungen an einem Beitrag nur dessen Seite. Dabei leert der
Purge eines einzelnen Beitrags die Cache-Dateien unter dem Host, über den der MCP-Aufruf eingeht; bei verschiedenen
Hosts (z. B. mit und ohne `www`) bleiben die Dateien des anderen Hosts womöglich ungeleert (der Komplett-Purge ist davon
nicht betroffen). Ist der Cache dafür gesperrt, bleibt er unverändert; der Zustand steht im Reiter „Kompatibilität“
und in `lit-site-status` (`wpsc`). Der Nachlauf-Purge, der auf ein gedrosseltes Leeren des ganzen Caches folgt, braucht
WP-Cron (oder einen System-Cron, der `wp-cron.php` aufruft). Auf Divi-Seiten leert jede Prüfung im Reiter den ganzen
Cache einmal: Divi selbst leert ihn beim Anlegen und Löschen der Testseite. Wurde etwas außerhalb von LIT MCP
geändert, leert `lit/cache-clear` den Cache auf Wunsch (`scope` `all` oder `post` mit `post_id`; erst Probelauf, dann
nach Rückfrage `confirm: true`).