feat: ability and integration infrastructure

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

src/Abilities/Ability.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Abilities;
+
+use WP_Error;
+
+/**
+ * One capability of the MCP server, registered with the WordPress Abilities API.
+ */
+interface Ability
+{
+    /** Ability name, e.g. "lit/guide". */
+    public function name(): string;
+
+    public function label(): string;
+
+    public function description(): string;
+
+    /** @return array<string, mixed> JSON Schema of the input. */
+    public function inputSchema(): array;
+
+    /** @return array<string, mixed>|null JSON Schema of the output, null for image results. */
+    public function outputSchema(): ?array;
+
+    /** @return array{readonly?: bool, destructive?: bool, idempotent?: bool} */
+    public function annotations(): array;
+
+    /** Whether the ability is listed as its own MCP tool (otherwise only via meta-tools). */
+    public function isDirect(): bool;
+
+    /** @param array<string, mixed> $input */
+    public function permission(array $input): bool|WP_Error;
+
+    /** @param array<string, mixed> $input */
+    public function execute(array $input): mixed;
+}

src/Abilities/AbilityRegistrar.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Abilities;
+
+use LIT\MCP\Access;
+use LIT\MCP\Integrations\IntegrationRegistry;
+use Throwable;
+use WP_Error;
+
+/**
+ * Registers all abilities of available integrations with the Abilities API and
+ * wraps them with the role gate and neutral error handling.
+ */
+final class AbilityRegistrar
+{
+    public const CATEGORY = 'lit-mcp';
+
+    public function __construct(private IntegrationRegistry $registry)
+    {
+    }
+
+    public function register(): void
+    {
+        add_action('wp_abilities_api_categories_init', [$this, 'registerCategory']);
+        add_action('wp_abilities_api_init', [$this, 'registerAbilities']);
+    }
+
+    public function registerCategory(): void
+    {
+        wp_register_ability_category(self::CATEGORY, [
+            'label' => 'LIT MCP',
+            'description' => 'Website-Pflege für WordPress, Divi und Pods über MCP.',
+        ]);
+    }
+
+    public function registerAbilities(): void
+    {
+        foreach ($this->registry->abilities() as $ability) {
+            wp_register_ability($ability->name(), $this->argsFor($ability));
+        }
+    }
+
+    /** @return array<string, mixed> */
+    public function argsFor(Ability $ability): array
+    {
+        $args = [
+            'label' => $ability->label(),
+            'description' => $ability->description(),
+            'category' => self::CATEGORY,
+            'input_schema' => $ability->inputSchema(),
+            'permission_callback' => static function (mixed $input = null) use ($ability): bool|WP_Error {
+                if (! Access::currentUserMayUse()) {
+                    return Errors::forbidden('Dein Benutzerkonto ist für LIT MCP nicht freigegeben.');
+                }
+
+                return $ability->permission(is_array($input) ? $input : []);
+            },
+            'execute_callback' => static function (mixed $input = null) use ($ability): mixed {
+                try {
+                    return $ability->execute(is_array($input) ? $input : []);
+                } catch (Throwable $e) {
+                    $message = sprintf('[wp-lit-mcp] %s failed: %s', $ability->name(), $e);
+                    error_log($message); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
+                    return Errors::internal();
+                }
+            },
+            'meta' => [
+                'annotations' => $ability->annotations(),
+                'show_in_rest' => false,
+                'mcp' => ['public' => true, 'type' => 'tool'],
+            ],
+        ];
+
+        $output = $ability->outputSchema();
+        if ($output !== null) {
+            $args['output_schema'] = $output;
+        }
+
+        return $args;
+    }
+}

src/Abilities/Errors.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Abilities;
+
+use WP_Error;
+
+/**
+ * Factory for the error objects abilities return. The MCP adapter turns them
+ * into tool results with isError: true.
+ */
+final class Errors
+{
+    public static function forbidden(string $message): WP_Error
+    {
+        return new WP_Error('lit_forbidden', $message, ['status' => 403]);
+    }
+
+    /** @param array<string, string> $fields */
+    public static function invalidInput(string $message, array $fields = []): WP_Error
+    {
+        return new WP_Error('lit_validation_failed', $message, ['status' => 400, 'fields' => $fields]);
+    }
+
+    public static function notFound(string $message): WP_Error
+    {
+        return new WP_Error('lit_not_found', $message, ['status' => 404]);
+    }
+
+    public static function internal(): WP_Error
+    {
+        return new WP_Error(
+            'lit_internal_error',
+            'Interner Fehler bei der Ausführung. Details stehen im PHP-Error-Log der Website.',
+            ['status' => 500]
+        );
+    }
+}

src/Integrations/Integration.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations;
+
+use LIT\MCP\Abilities\Ability;
+
+/**
+ * A group of abilities that is only registered when its theme/plugin is active.
+ */
+interface Integration
+{
+    public function id(): string;
+
+    public function isAvailable(): bool;
+
+    /** @return list<Ability> */
+    public function abilities(): array;
+}

src/Integrations/IntegrationRegistry.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Integrations;
+
+use LIT\MCP\Abilities\Ability;
+
+final class IntegrationRegistry
+{
+    /** @var list<Integration> */
+    private array $integrations;
+
+    public function __construct(Integration ...$integrations)
+    {
+        $this->integrations = array_values($integrations);
+    }
+
+    /** @return list<Integration> */
+    public function available(): array
+    {
+        return array_values(array_filter(
+            $this->integrations,
+            static fn (Integration $integration): bool => $integration->isAvailable()
+        ));
+    }
+
+    /** @return list<Ability> */
+    public function abilities(): array
+    {
+        $abilities = [];
+        foreach ($this->available() as $integration) {
+            array_push($abilities, ...$integration->abilities());
+        }
+
+        return $abilities;
+    }
+
+    /** @return list<string> */
+    public function directAbilityNames(): array
+    {
+        $names = [];
+        foreach ($this->abilities() as $ability) {
+            if ($ability->isDirect()) {
+                $names[] = $ability->name();
+            }
+        }
+
+        return $names;
+    }
+}