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

Medien

Werkzeugnamen: lit-… sind direkt aufrufbare Tools; lit/… sind Abilities, die über mcp-adapter-execute-ability (Name in ability_name, Eingaben in parameters) aufgerufen werden. Welche Tools direkt sichtbar sind, lässt sich unter Einstellungen → LIT MCP → Tools ändern (siehe overview); lit-media-preview und lit-media-download lassen sich dort nur auf „direkt“ oder „deaktiviert“ stellen, nie auf „indirekt“ – ihr Bild- bzw. Dateiergebnis wird nur bei direktem Aufruf zu einem sichtbaren Inhalt.

Suchen und ansehen

• lit-media-search: Text (Titel, Dateiname, Beschreibung), mime (z. B. image oder application/pdf), Zeitraum (date_after/date_before), missing_alt: true (Bilder ohne Alt-Text; mime muss dabei leer oder ein Bild-Typ sein) und unused: true (keine gefundene Verwendung). Geliefert werden nur reguläre Mediathek-Einträge (kein Papierkorb), die der Nutzer bearbeiten darf. unused prüft je Aufruf höchstens 20 Medien; wird die Prüfung dadurch unterbrochen, folgt eine Warnung und mit next_cursor geht es weiter – „keine Verwendung gefunden“ ist dabei keine Garantie (Details je Medium über lit/media-get).
• lit-media-preview: verkleinertes Bild ansehen (längste Kante max_size, Standard 512 px) – z. B. um passende Alt-Texte zu schreiben.
• lit/media-get: alle Metadaten, Bildgrößen und Verwendungsorte (Beitragsbild, Inhalte inkl. Divi, Bildfelder, Website-Icon, Logo, Header-/Hintergrundbild, Widgets). certainty: „sicher“ = per ID eingebunden, „möglicherweise“ = nur die Datei-URL gefunden (kann zu einer anderen Kopie der Datei gehören). Einträge, die der Nutzer nicht lesen darf, erscheinen als „(nicht lesbar)“. usages_complete: false heißt, die Inhaltssuche wurde begrenzt – weitere Verwendungen sind möglich; usages_truncated: true heißt, es gibt mehr Verwendungen als gelistet.

Hochladen

• lit-media-upload-from-url (direkt): lädt eine öffentlich erreichbare http(s)-Datei; interne oder lokale Adressen werden abgelehnt.
• lit/media-upload (indirekt): lädt eine Datei als Base64.
• Beide: optional title, alt, post_id (Eintrag, dem das Medium zugeordnet wird – braucht Bearbeitungsrecht); erlaubte Dateitypen jpg, png, gif, webp, avif, pdf, mp4, mp3; Größenlimit siehe die Tool-Beschreibung (Standard 5 MB, einstellbar unter Einstellungen → LIT MCP → Limits). Beide legen bei jedem Aufruf ein neues Medium an (nicht idempotent).

Ändern, herunterladen, löschen

• lit/media-update: Alt-Text, Titel, Bildunterschrift, Beschreibung für bis zu 50 Medien in einem Aufruf – alles oder nichts: Ist ein Eintrag ungültig (unbekannte ID, keine Berechtigung, Papierkorb, zu lang, nichts zu ändern, veraltetes modified), wird nichts gespeichert und failures nennt jeden fehlerhaften Eintrag. Optional pro Eintrag modified (Wert aus lit/media-get oder lit-media-search) als Schutz vor parallelen Änderungen mitsenden – modified ändert sich bei Titel, Bildunterschrift und Beschreibung, nicht bei einer reinen Alt-Text-Änderung. Bei Erfolg meldet results jeden Eintrag einzeln (mit neuem modified).
• lit-media-download: Datei (Original oder eine Bildgröße aus sizes in lit/media-get) als eingebettete Ressource, nur bis zum Upload-Limit – darüber die URL aus lit/media-get verwenden.
• lit/media-delete: nur nach Rückfrage (confirm: true). Wird das Medium verwendet (auch nur „möglicherweise“), kommt in_use mit der Liste der Verwendungen – erst nach ausdrücklicher Zustimmung des Nutzers mit force: true löschen. Medien im Papierkorb werden nicht gelöscht. Ohne aktivierten Medien-Papierkorb (WordPress-Standard) ist das Löschen endgültig und nicht rückgängig zu machen. Die Verwendungsprüfung findet NICHT: Term-Meta, Benutzer-Meta, Pods-Tabellen (pods_*, podsrel), ACF-Felder (außer als Bildfeld im Schema mit einer ID pro Meta-Eintrag), serialisierte oder kommagetrennte ID-Listen in Meta-Feldern und Optionen anderer Plugins – im Zweifel den Nutzer fragen, statt sich auf „keine Verwendung gefunden“ zu verlassen.

Alt-Texte beschreiben den Bildinhalt knapp und sachlich (keine „Bild von …“-Floskeln).

Wenn ein Schreibvorgang fehlschlägt

Wie bei Inhalten (siehe overview): code = write_failed (alles wurde zurückgenommen) oder partial_write (die Rücknahme war unvollständig, hint folgen statt zu wiederholen).