feat: structured errors with hint, ToolResult, cursor pagination

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7
2026-09-25 21:37:42 +02:00
parent 5434cb6767
commit f63d35c2f8
12 changed files with 631 additions and 14 deletions
@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Abilities;
+
+use InvalidArgumentException;
+use LIT\MCP\Abilities\ToolResult;
+use LIT\MCP\Tests\Unit\TestCase;
+
+final class ToolResultTest extends TestCase
+{
+    public function testDefaultsMatchTheSpecShape(): void
+    {
+        self::assertSame(
+            [
+                'ok' => true,
+                'summary' => 'Seite angelegt',
+                'changed' => [],
+                'outline' => null,
+                'rev' => null,
+                'warnings' => [],
+                'revision_id' => null,
+                'snapshot_id' => null,
+                'log_id' => null,
+                'preview_url' => null,
+                'edit_url' => null,
+            ],
+            ToolResult::ok('Seite angelegt')->toArray()
+        );
+    }
+
+    public function testBuilderFillsAllFieldsAndExtras(): void
+    {
+        $result = ToolResult::ok('Aktualisiert')
+            ->changed('12', 'page', 'updated', 'Startseite')
+            ->warning('Bild ohne Alt-Text')
+            ->warnings(['Zweite Warnung'])
+            ->outline('Hero')
+            ->rev('a1b2c3d4e5f6')
+            ->revisionId(812)
+            ->snapshotId('snap-1')
+            ->logId(4711)
+            ->urls('https://kunde.de/?p=12&preview=true', 'https://kunde.de/wp-admin/post.php?post=12&action=edit')
+            ->with('previous', ['blogname' => 'Alt'])
+            ->toArray();
+
+        self::assertSame([['id' => '12', 'type' => 'page', 'action' => 'updated', 'label' => 'Startseite']], $result['changed']);
+        self::assertSame(['Bild ohne Alt-Text', 'Zweite Warnung'], $result['warnings']);
+        self::assertSame('Hero', $result['outline']);
+        self::assertSame('a1b2c3d4e5f6', $result['rev']);
+        self::assertSame(812, $result['revision_id']);
+        self::assertSame('snap-1', $result['snapshot_id']);
+        self::assertSame(4711, $result['log_id']);
+        self::assertSame('https://kunde.de/?p=12&preview=true', $result['preview_url']);
+        self::assertSame(['blogname' => 'Alt'], $result['previous']);
+    }
+
+    public function testReservedKeysCannotBeOverwrittenByExtras(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        ToolResult::ok('x')->with('ok', false);
+    }
+
+    public function testSchemaRequiresCoreKeysAndAcceptsExtraProperties(): void
+    {
+        $schema = ToolResult::schema(['previous' => ['type' => 'object']], ['previous']);
+
+        self::assertSame('object', $schema['type']);
+        self::assertContains('summary', $schema['required']);
+        self::assertContains('previous', $schema['required']);
+        self::assertSame(['integer', 'null'], $schema['properties']['revision_id']['type']);
+        self::assertSame(['type' => 'object'], $schema['properties']['previous']);
+    }
+}