feat: guide tool and server instructions

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7

docs/guides/overview.md

@@ -0,0 +1,23 @@
+# 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.
+
+## Verfügbare Werkzeuge (Etappe 0)
+
+- `lit-guide` – diese Anleitungen. Weitere Themen: siehe Feld `topics`.
+- `lit-site-status` – Überblick über Website, aktive Integrationen und eigene Rechte.
+
+Weitere Werkzeuge kommen mit den nächsten Ausbaustufen hinzu.

src/Guides/GuideRepository.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Guides;
+
+/**
+ * Reads guide markdown files from one directory. Topic names are restricted to
+ * lowercase slugs, so no path outside the directory can ever be read.
+ */
+final class GuideRepository
+{
+    private const TOPIC_PATTERN = '/^[a-z0-9]+(?:-[a-z0-9]+)*$/';
+
+    public function __construct(private string $directory)
+    {
+    }
+
+    /** @return list<string> */
+    public function topics(): array
+    {
+        $files = glob($this->directory . '/*.md');
+        if ($files === false) {
+            return [];
+        }
+
+        $topics = [];
+        foreach ($files as $file) {
+            $topic = basename($file, '.md');
+            if (preg_match(self::TOPIC_PATTERN, $topic) === 1) {
+                $topics[] = $topic;
+            }
+        }
+        sort($topics);
+
+        return $topics;
+    }
+
+    public function get(string $topic): ?string
+    {
+        if (preg_match(self::TOPIC_PATTERN, $topic) !== 1 || ! in_array($topic, $this->topics(), true)) {
+            return null;
+        }
+
+        $path = $this->directory . '/' . $topic . '.md';
+        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
+        $content = file_get_contents($path);
+
+        return $content === false ? null : $content;
+    }
+}

src/Guides/InstructionsBuilder.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Guides;
+
+use LIT\MCP\Integrations\Integration;
+use LIT\MCP\Integrations\IntegrationRegistry;
+
+/**
+ * Builds the short server instructions every MCP client loads on connect.
+ * Keep this text short: it occupies context in every conversation.
+ */
+final class InstructionsBuilder
+{
+    public function __construct(private IntegrationRegistry $registry)
+    {
+    }
+
+    public function build(): string
+    {
+        $active = implode(', ', array_map(
+            static fn (Integration $integration): string => $integration->id(),
+            $this->registry->available()
+        ));
+
+        return implode("\n", [
+            'LIT MCP pflegt diese WordPress-Website (Inhalte, Medien, Divi 5, Pods).',
+            'Aktive Integrationen: ' . $active . '.',
+            'Regeln:',
+            '- Vor dem ersten Arbeitsschritt lit-guide (ohne Topic) aufrufen; Details je Thema über lit-guide '
+                . 'mit topic.',
+            '- Änderungen erzeugen native Divi-Module; Variablen und Presets vor festen Werten; Code-Modul nur, '
+                . 'wenn kein natives Modul passt.',
+            '- Den Status (Entwurf/veröffentlicht) nie ändern, außer der Nutzer verlangt es ausdrücklich.',
+            '- Schreib-Tools verlangen den aktuellen rev-Wert aus dem letzten Lesevorgang.',
+            '- Fehler enthalten einen hint – ihm folgen, statt blind zu wiederholen.',
+        ]);
+    }
+}

src/Integrations/Core/GuideAbility.php

@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations\Core;
+
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\Errors;
+use LIT\MCP\Guides\GuideRepository;
+use WP_Error;
+
+final class GuideAbility implements Ability
+{
+    private const DEFAULT_TOPIC = 'overview';
+
+    public function __construct(private GuideRepository $guides)
+    {
+    }
+
+    public function name(): string
+    {
+        return 'lit/guide';
+    }
+
+    public function label(): string
+    {
+        return 'Anleitung';
+    }
+
+    public function description(): string
+    {
+        return 'Liefert Anleitungen zur Bedienung dieses MCP-Servers. Ohne topic: Übersicht und Liste aller Themen.';
+    }
+
+    public function inputSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'topic' => [
+                    'type' => 'string',
+                    'description' => 'Thema, z. B. "overview" oder "divi-shortform".',
+                ],
+            ],
+            'additionalProperties' => false,
+        ];
+    }
+
+    public function outputSchema(): ?array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'topic' => ['type' => 'string'],
+                'topics' => ['type' => 'array', 'items' => ['type' => 'string']],
+                'content' => ['type' => 'string'],
+            ],
+            'required' => ['topic', 'topics', 'content'],
+        ];
+    }
+
+    public function annotations(): array
+    {
+        return ['readonly' => true, 'destructive' => false, 'idempotent' => true];
+    }
+
+    public function isDirect(): bool
+    {
+        return true;
+    }
+
+    public function permission(array $input): bool|WP_Error
+    {
+        return true;
+    }
+
+    public function execute(array $input): mixed
+    {
+        $topic = isset($input['topic']) && is_string($input['topic']) && $input['topic'] !== ''
+            ? $input['topic']
+            : self::DEFAULT_TOPIC;
+        $topics = $this->guides->topics();
+        $content = $this->guides->get($topic);
+
+        if ($content === null) {
+            return Errors::notFound(sprintf(
+                'Unbekanntes Thema. Verfügbar: %s',
+                implode(', ', $topics)
+            ));
+        }
+
+        return ['topic' => $topic, 'topics' => $topics, 'content' => $content];
+    }
+}

tests/Fixtures/guides/divi-shortform.md

@@ -0,0 +1,2 @@
+# Divi-Kurzform
+Testinhalt Kurzform.

tests/Fixtures/guides/overview.md

@@ -0,0 +1,2 @@
+# Übersicht
+Testinhalt Übersicht.

tests/Unit/Guides/GuideRepositoryTest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Guides;
+
+use LIT\MCP\Guides\GuideRepository;
+use LIT\MCP\Tests\Unit\TestCase;
+
+final class GuideRepositoryTest extends TestCase
+{
+    private GuideRepository $guides;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->guides = new GuideRepository(dirname(__DIR__, 2) . '/Fixtures/guides');
+    }
+
+    public function testListsTopicsSortedWithoutExtension(): void
+    {
+        self::assertSame(['divi-shortform', 'overview'], $this->guides->topics());
+    }
+
+    public function testReturnsMarkdownOfKnownTopic(): void
+    {
+        self::assertStringContainsString('Testinhalt Kurzform', (string) $this->guides->get('divi-shortform'));
+    }
+
+    /**
+     * @dataProvider maliciousTopics
+     */
+    public function testRejectsAnythingThatIsNotAPlainTopicName(string $topic): void
+    {
+        self::assertNull($this->guides->get($topic));
+    }
+
+    /** @return array<string, array{string}> */
+    public static function maliciousTopics(): array
+    {
+        return [
+            'traversal' => ['../../wp-config'],
+            'with extension' => ['overview.md'],
+            'empty' => [''],
+            'absolute' => ['/etc/passwd'],
+            'unknown' => ['does-not-exist'],
+            'uppercase' => ['OVERVIEW'],
+        ];
+    }
+
+    public function testMissingDirectoryYieldsNoTopics(): void
+    {
+        self::assertSame([], (new GuideRepository('/nonexistent/dir'))->topics());
+    }
+}

tests/Unit/Guides/InstructionsBuilderTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Guides;
+
+use LIT\MCP\Guides\InstructionsBuilder;
+use LIT\MCP\Integrations\Integration;
+use LIT\MCP\Integrations\IntegrationRegistry;
+use LIT\MCP\Tests\Unit\TestCase;
+use Mockery;
+
+final class InstructionsBuilderTest extends TestCase
+{
+    public function testNamesActiveIntegrationsAndCoreRules(): void
+    {
+        $core = Mockery::mock(Integration::class);
+        $core->allows('id')->andReturn('core');
+        $core->allows('isAvailable')->andReturn(true);
+
+        $text = (new InstructionsBuilder(new IntegrationRegistry($core)))->build();
+
+        self::assertStringContainsString('Aktive Integrationen: core', $text);
+        self::assertStringContainsString('lit-guide', $text);
+        self::assertStringContainsString('Status', $text);
+        self::assertLessThan(2000, strlen($text), 'Instructions must stay short – they are loaded in every conversation.');
+    }
+}

tests/Unit/Integrations/Core/GuideAbilityTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Integrations\Core;
+
+use LIT\MCP\Guides\GuideRepository;
+use LIT\MCP\Integrations\Core\GuideAbility;
+use LIT\MCP\Tests\Unit\TestCase;
+use WP_Error;
+
+final class GuideAbilityTest extends TestCase
+{
+    private GuideAbility $ability;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->ability = new GuideAbility(new GuideRepository(dirname(__DIR__, 3) . '/Fixtures/guides'));
+    }
+
+    public function testWithoutTopicReturnsOverviewAndTopicList(): void
+    {
+        $result = $this->ability->execute([]);
+
+        self::assertSame('overview', $result['topic']);
+        self::assertSame(['divi-shortform', 'overview'], $result['topics']);
+        self::assertStringContainsString('Testinhalt Übersicht', $result['content']);
+    }
+
+    public function testReturnsRequestedTopic(): void
+    {
+        $result = $this->ability->execute(['topic' => 'divi-shortform']);
+
+        self::assertStringContainsString('Testinhalt Kurzform', $result['content']);
+    }
+
+    public function testUnknownTopicIsNotFoundErrorListingTopics(): void
+    {
+        $result = $this->ability->execute(['topic' => '../../wp-config']);
+
+        self::assertInstanceOf(WP_Error::class, $result);
+        self::assertSame('lit_not_found', $result->get_error_code());
+        self::assertStringContainsString('divi-shortform', $result->get_error_message());
+    }
+
+    public function testIsDirectReadOnlyTool(): void
+    {
+        self::assertSame('lit/guide', $this->ability->name());
+        self::assertTrue($this->ability->isDirect());
+        self::assertTrue($this->ability->annotations()['readonly']);
+    }
+}