docs: name tools and error codes the way the client sees them

Indirect abilities are written lit/<name> (via mcp-adapter-execute-ability) in guides, descriptions and hints, direct tools lit-<name>; guides use the client-visible codes (write_failed, partial_write) and say exactly which tools return a revision_id. ToolNamingTest keeps guides and sources consistent with Ability::isDirect() and checks the overview's direct-tool list. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7
2026-09-26 01:28:18 +02:00
parent b3c9109e47
commit fea75b03d6
19 changed files with 186 additions and 55 deletions
@@ -34,7 +34,7 @@ final class MenuAssignLocationAbility implements Ability

    public function description(): string
    {
-        return 'Weist einer Theme-Position (siehe lit-menu-list) ein Menü zu; menu_id 0 entfernt die Zuweisung. '
+        return 'Weist einer Theme-Position (siehe lit/menu-list) ein Menü zu; menu_id 0 entfernt die Zuweisung. '
            . 'Das vorher zugewiesene Menü steht in previous_menu_id.';
    }

@@ -86,7 +86,7 @@ final class MenuAssignLocationAbility implements Ability
        }

        if ($menuId > 0 && ! is_object(wp_get_nav_menu_object($menuId))) {
-            return Errors::notFound(sprintf('Menü %d nicht gefunden.', $menuId), 'Menüs über lit-menu-list abrufen.');
+            return Errors::notFound(sprintf('Menü %d nicht gefunden.', $menuId), 'Menüs über lit/menu-list abrufen.');
        }

        $previous = MenuLocations::assigned()[$location] ?? 0;
@@ -34,7 +34,7 @@ final class MenuCreateAbility implements Ability
    public function description(): string
    {
        return 'Legt ein leeres Menü an und weist es optional einer Theme-Position zu. Einträge danach mit '
-            . 'lit-menu-set-items setzen.';
+            . 'lit/menu-set-items setzen.';
    }

    public function inputSchema(): array
@@ -43,7 +43,7 @@ final class MenuCreateAbility implements Ability
            'type' => 'object',
            'properties' => [
                'name' => ['type' => 'string', 'minLength' => 1],
-                'location' => ['type' => 'string', 'description' => 'Theme-Position aus lit-menu-list.'],
+                'location' => ['type' => 'string', 'description' => 'Theme-Position aus lit/menu-list.'],
            ],
            'required' => ['name'],
            'additionalProperties' => false,
@@ -88,7 +88,7 @@ final class MenuCreateAbility implements Ability
            return Errors::invalidInput(
                'Menü konnte nicht angelegt werden: ' . $menuId->get_error_message(),
                ['name' => 'bereits vergeben oder ungültig'],
-                'Vorhandene Menüs über lit-menu-list abrufen.'
+                'Vorhandene Menüs über lit/menu-list abrufen.'
            );
        }

@@ -29,7 +29,7 @@ final class MenuGetAbility implements Ability
        return 'Liefert ein Menü als Baum (id, title, type post/taxonomy/custom, object/object_id, url, '
            . 'children). object_id und url sind bei post/taxonomy-Einträgen nur informativ (WordPress leitet '
            . 'sie aus dem verlinkten Objekt ab); nur bei custom-Einträgen ist url maßgeblich. Der Baum kann '
-            . 'bearbeitet an lit-menu-set-items zurückgegeben werden.';
+            . 'bearbeitet an lit/menu-set-items zurückgegeben werden.';
    }

    public function inputSchema(): array
@@ -78,7 +78,7 @@ final class MenuGetAbility implements Ability
        $menuId = (int) ($input['menu_id'] ?? 0);
        $menu = wp_get_nav_menu_object($menuId);
        if (! is_object($menu)) {
-            return Errors::notFound(sprintf('Menü %d nicht gefunden.', $menuId), 'Menüs über lit-menu-list abrufen.');
+            return Errors::notFound(sprintf('Menü %d nicht gefunden.', $menuId), 'Menüs über lit/menu-list abrufen.');
        }

        $items = wp_get_nav_menu_items($menuId);
@@ -44,7 +44,7 @@ final class MenuSetItemsAbility implements Ability
        return 'Setzt die Einträge eines Menüs. Entweder items = vollständiger Zielbaum oder operations = Liste aus '
            . '{op: add, item, parent_id?, position?}, {op: move, id, parent_id?, position?}, {op: remove, id} '
            . '(Kinder eines entfernten Eintrags rücken an seine Stelle; position 0-basiert, ohne = ans Ende). '
-            . 'Der Baum aus lit-menu-get kann bearbeitet unverändert zurückgegeben werden: bestehende Einträge '
+            . 'Der Baum aus lit/menu-get kann bearbeitet unverändert zurückgegeben werden: bestehende Einträge '
            . 'werden über id erkannt, type/object/object_id und bei post/taxonomy auch url sind nur informativ '
            . 'und werden ignoriert; title wird nur bei Änderung zur eigenen Beschriftung, url nur bei custom '
            . 'geändert. Neue Einträge ohne id: type post|taxonomy mit object_id oder custom mit url (/pfad, '
@@ -70,7 +70,7 @@ final class MenuSetItemsAbility implements Ability
                'items' => [
                    'type' => 'array',
                    'items' => ['type' => 'object'],
-                    'description' => 'Vollständiger Zielbaum (Knoten wie in lit-menu-get, neue Einträge ohne id).',
+                    'description' => 'Vollständiger Zielbaum (Knoten wie in lit/menu-get, neue Einträge ohne id).',
                ],
                'operations' => [
                    'type' => 'array',
@@ -132,7 +132,7 @@ final class MenuSetItemsAbility implements Ability
        $menuId = (int) ($input['menu_id'] ?? 0);
        $menu = wp_get_nav_menu_object($menuId);
        if (! is_object($menu)) {
-            return Errors::notFound(sprintf('Menü %d nicht gefunden.', $menuId), 'Menüs über lit-menu-list abrufen.');
+            return Errors::notFound(sprintf('Menü %d nicht gefunden.', $menuId), 'Menüs über lit/menu-list abrufen.');
        }

        if (array_key_exists('items', $input) === array_key_exists('operations', $input)) {
@@ -203,7 +203,7 @@ final class MenuSetItemsAbility implements Ability
        $after = FollowUp::run(
            fn () => MenuTree::build(array_values($this->currentItems($menuId))),
            $this->name() . ' re-read',
-            'Das Menü ist gespeichert, der neue Stand konnte aber nicht gelesen werden; mit lit-menu-get abrufen.',
+            'Das Menü ist gespeichert, der neue Stand konnte aber nicht gelesen werden; mit lit/menu-get abrufen.',
            $warnings
        );

@@ -462,9 +462,10 @@ class MenuWriter
            $cause,
            $detail,
            sprintf('Menü %d ist möglicherweise teilweise geändert worden.', $menuId),
-            'Den Aufruf nicht einfach wiederholen. Zuerst den aktuellen Stand mit lit-menu-get prüfen und ihn ggf. '
-                . 'mit lit-menu-set-items anhand von previous_items (Stand vorher) wiederherstellen; entfernte '
-                . 'Einträge müssen dabei neu angelegt werden. Dem Nutzer Bescheid geben.',
+            'Den Aufruf nicht einfach wiederholen. Zuerst den aktuellen Stand mit lit/menu-get prüfen und ihn ggf. '
+                . 'mit lit/menu-set-items (beide über mcp-adapter-execute-ability) anhand von previous_items (Stand '
+                . 'vorher) wiederherstellen; entfernte Einträge müssen dabei neu angelegt werden. Dem Nutzer Bescheid '
+                . 'geben.',
            ['menu_id' => $menuId, 'previous_items' => MenuTree::build(array_values($current))]
        );
    }
@@ -146,7 +146,7 @@ final class RevisionRestoreAbility implements Ability
        $revisionId = PostGuard::id($input['revision_id'] ?? null);
        $revision = $revisionId === null ? null : get_post($revisionId);
        if (! $revision instanceof WP_Post || $revision->post_type !== 'revision') {
-            return Errors::notFound('Revision nicht gefunden.', 'Revisionen über lit-revisions-list abrufen.');
+            return Errors::notFound('Revision nicht gefunden.', 'Revisionen über lit/revisions-list abrufen.');
        }

        // field 'revision_id': post_parent 0 (an orphaned revision) is the only id this
@@ -41,7 +41,7 @@ final class RevisionsListAbility implements Ability
    {
        return 'Listet die gespeicherten Revisionen eines Eintrags (neueste zuerst) mit Datum, Autor und '
            . 'Textauszug. Revisionen von Divi-Inhalten sind mit divi: true markiert; ihr excerpt ist dann '
-            . 'Shortcode-/Block-Markup, kein lesbarer Text. Wiederherstellen mit lit-revision-restore.';
+            . 'Shortcode-/Block-Markup, kein lesbarer Text. Wiederherstellen mit lit/revision-restore.';
    }

    public function inputSchema(): array
@@ -27,7 +27,7 @@ final class WpSettingsGetAbility implements Ability
    public function description(): string
    {
        return 'Liest die freigegebenen WordPress-Einstellungen (Allgemein, Lesen, Diskussion, Permalinks, '
-            . 'Website-Icon) mit Typ und Beschreibung. Ändern mit lit-wp-settings-update.';
+            . 'Website-Icon) mit Typ und Beschreibung. Ändern mit lit/wp-settings-update.';
    }

    public function inputSchema(): array
@@ -44,7 +44,7 @@ final class WpSettingsUpdateAbility implements Ability

    public function description(): string
    {
-        return 'Ändert freigegebene WordPress-Einstellungen (Schlüssel siehe lit-wp-settings-get). Alle Werte '
+        return 'Ändert freigegebene WordPress-Einstellungen (Schlüssel siehe lit/wp-settings-get). Alle Werte '
            . 'werden vorher geprüft – bei einem Fehler wird nichts gespeichert. previous enthält die alten Werte. '
            . 'Gesperrt: admin_email, users_can_register, default_role, siteurl, home.';
    }
@@ -98,7 +98,7 @@ final class WpSettingsUpdateAbility implements Ability
            return Errors::invalidInput(
                'Einstellungen ungültig; nichts wurde gespeichert.',
                $errors,
-                'Werte gemäß fields korrigieren; aktuelle Werte über lit-wp-settings-get.'
+                'Werte gemäß fields korrigieren; aktuelle Werte über lit/wp-settings-get.'
            );
        }

@@ -255,7 +255,8 @@ final class WpSettingsUpdateAbility implements Ability
            $cause,
            $cause->getMessage() . '; not restored: ' . implode(', ', $stuck),
            sprintf('Möglicherweise auf dem neuen, nicht vollständigen Stand: %s.', implode(', ', $stuck)),
-            'Aktuelle Werte über lit/wp-settings-get prüfen und ggf. erneut auf die gewünschten Werte setzen.',
+            'Aktuelle Werte über lit/wp-settings-get (mcp-adapter-execute-ability) prüfen und ggf. erneut auf die '
+                . 'gewünschten Werte setzen.',
            ['keys' => $stuck]
        );
    }
@@ -41,7 +41,7 @@ final class PostDuplicateAbility implements Ability
    {
        return 'Legt eine Entwurfskopie eines Eintrags an (Inhalt, Felder/Meta, Begriffe, Beitragsbild, Template, '
            . 'Divi-Einstellungen). Typischer Ablauf: Kopie bearbeiten, prüfen, dann mit '
-            . 'lit-post-replace-with-copy ins Original übernehmen – so bleibt die veröffentlichte Seite bis dahin '
+            . 'lit/post-replace-with-copy ins Original übernehmen – so bleibt die veröffentlichte Seite bis dahin '
            . 'unverändert. Die Antwort enthält die rev der Kopie für lit-content-update.';
    }

@@ -60,7 +60,7 @@ final class PostReplaceWithCopyAbility implements Ability

    public function description(): string
    {
-        return 'Übernimmt Titel, Inhalt, Felder/Meta und Begriffe einer mit lit-post-duplicate erstellten Kopie '
+        return 'Übernimmt Titel, Inhalt, Felder/Meta und Begriffe einer mit lit/post-duplicate erstellten Kopie '
            . 'ins Original. ID, URL, Status und Menüeinträge des Originals bleiben; vorher entsteht eine '
            . 'Revision und eine vollständige Sicherung des Originals (im Papierkorb, backup_id), die Kopie kommt '
            . 'danach in den Papierkorb. Die Kopie muss Entwurf oder ausstehend sein. rev des Originals aus '
@@ -165,8 +165,8 @@ final class PostReplaceWithCopyAbility implements Ability
        if ($copy->post_type !== $original->post_type || $copyOf !== $originalId || $copyId === $originalId) {
            return Errors::invalidInput(
                'Die Kopie gehört nicht zu diesem Original.',
-                ['copy_id' => sprintf('keine mit lit-post-duplicate erstellte Kopie von %d', $originalId)],
-                'Kopie mit lit-post-duplicate aus diesem Original erstellen.'
+                ['copy_id' => sprintf('keine mit lit/post-duplicate erstellte Kopie von %d', $originalId)],
+                'Kopie mit lit/post-duplicate aus diesem Original erstellen.'
            );
        }

@@ -174,7 +174,7 @@ final class PostReplaceWithCopyAbility implements Ability
            return Errors::invalidInput(
                sprintf('Die Kopie hat den Status "%s"; übernommen wird nur ein Entwurf.', $copy->post_status),
                ['copy_id' => 'Kopie muss Entwurf oder ausstehend sein'],
-                'Mit lit-post-duplicate eine neue Kopie erstellen (bzw. die Kopie in WordPress wiederherstellen).'
+                'Mit lit/post-duplicate eine neue Kopie erstellen (bzw. die Kopie in WordPress wiederherstellen).'
            );
        }

@@ -290,9 +290,9 @@ final class PostReplaceWithCopyAbility implements Ability
                    $backupId
                ),
                'Den Aufruf nicht einfach wiederholen. Zuerst den Stand mit lit-content-get prüfen; Titel, Inhalt '
-                    . 'und Auszug lassen sich mit lit/revision-restore (revision_id) zurückholen, Felder/Meta und '
-                    . 'Begriffe stehen in der Sicherung backup_id (in WordPress aus dem Papierkorb holen). Dem '
-                    . 'Nutzer Bescheid geben.',
+                    . 'und Auszug lassen sich mit lit/revision-restore (revision_id, über '
+                    . 'mcp-adapter-execute-ability) zurückholen, Felder/Meta und Begriffe stehen in der Sicherung '
+                    . 'backup_id (in WordPress aus dem Papierkorb holen). Dem Nutzer Bescheid geben.',
                $details
            );
        }