feat: configurable exposure policy for direct, indirect and disabled tools

Introduces ExposurePolicy (option lit_mcp_exposure) deciding per ability
whether it is a direct MCP tool, only reachable via mcp-adapter's
execute-ability meta-tool, or disabled entirely (not registered with the
Abilities API at all). Ability::isDirect() remains the default when no
override applies. lit/guide can never be disabled or made indirect;
lit/media-preview and lit/media-download (image/embedded-resource results)
can never be made indirect, only direct or disabled.

AbilityRegistrar and ServerRegistrar take an optional ExposurePolicy and
use it to filter registered abilities / compute the direct tool list.
IntegrationRegistry::directAbilityNames() is removed (superseded by
ExposurePolicy::directNames()). InstructionsBuilder now also takes the
policy and lists the currently direct tools by name (lit-<name>), noting
the rest are reachable via mcp-adapter-execute-ability as lit/<name>.

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

src/Abilities/AbilityRegistrar.php

@@ -18,7 +18,7 @@ final class AbilityRegistrar
 {
     public const CATEGORY = 'lit-mcp';
 
-    public function __construct(private IntegrationRegistry $registry)
+    public function __construct(private IntegrationRegistry $registry, private ?ExposurePolicy $policy = null)
     {
     }
 
@@ -38,7 +38,8 @@ final class AbilityRegistrar
 
     public function registerAbilities(): void
     {
-        foreach ($this->registry->abilities() as $ability) {
+        $policy = $this->policy ?? new ExposurePolicy();
+        foreach ($policy->enabled($this->registry->abilities()) as $ability) {
             wp_register_ability($ability->name(), $this->argsFor($ability));
         }
     }

src/Abilities/ExposurePolicy.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Abilities;
+
+/**
+ * Decides per ability whether it is a direct MCP tool, only reachable through the
+ * adapter's meta-tools, or disabled (spec §4.3). Ability::isDirect() is the default.
+ */
+final class ExposurePolicy
+{
+    public const OPTION = 'lit_mcp_exposure';
+    public const DIRECT = 'direct';
+    public const INDIRECT = 'indirect';
+    public const DISABLED = 'disabled';
+    public const MODES = [self::DIRECT, self::INDIRECT, self::DISABLED];
+
+    /**
+     * Image/embedded-resource results only work for direct tools (ruling Q6 / task 6
+     * dispatch): lit/media-preview (ImageContent) and lit/media-download (embedded
+     * resource) can be direct or disabled, but never indirect.
+     */
+    public const DIRECT_ONLY = ['lit/media-preview', 'lit/media-download'];
+
+    /** Entry point for every conversation – must always stay a direct tool. */
+    public const REQUIRED = ['lit/guide'];
+
+    /** @param array<string, string> $overrides Ability name => mode. */
+    public function __construct(private array $overrides = [])
+    {
+    }
+
+    public static function fromOption(): self
+    {
+        return new self(self::sanitize(get_option(self::OPTION, [])));
+    }
+
+    public function mode(Ability $ability): string
+    {
+        $mode = $this->overrides[$ability->name()] ?? null;
+
+        return is_string($mode) && self::isAllowed($ability->name(), $mode) ? $mode : $this->defaultMode($ability);
+    }
+
+    public function defaultMode(Ability $ability): string
+    {
+        return $ability->isDirect() ? self::DIRECT : self::INDIRECT;
+    }
+
+    /**
+     * @param list<Ability> $abilities
+     * @return list<Ability>
+     */
+    public function enabled(array $abilities): array
+    {
+        return array_values(array_filter(
+            $abilities,
+            fn (Ability $ability): bool => $this->mode($ability) !== self::DISABLED
+        ));
+    }
+
+    /**
+     * @param list<Ability> $abilities
+     * @return list<string>
+     */
+    public function directNames(array $abilities): array
+    {
+        $names = [];
+        foreach ($abilities as $ability) {
+            if ($this->mode($ability) === self::DIRECT) {
+                $names[] = $ability->name();
+            }
+        }
+
+        return $names;
+    }
+
+    public static function isAllowed(string $name, string $mode): bool
+    {
+        if (! in_array($mode, self::MODES, true)) {
+            return false;
+        }
+
+        if (in_array($name, self::REQUIRED, true)) {
+            return $mode === self::DIRECT;
+        }
+
+        if (in_array($name, self::DIRECT_ONLY, true)) {
+            return $mode !== self::INDIRECT;
+        }
+
+        return true;
+    }
+
+    /**
+     * Settings API sanitize callback for the option.
+     *
+     * @return array<string, string>
+     */
+    public static function sanitize(mixed $input): array
+    {
+        if (! is_array($input)) {
+            return [];
+        }
+
+        $clean = [];
+        foreach ($input as $name => $mode) {
+            if (
+                is_string($name)
+                && is_string($mode)
+                && preg_match('#^[a-z0-9-]+/[a-z0-9-]+$#', $name) === 1
+                && self::isAllowed($name, $mode)
+            ) {
+                $clean[$name] = $mode;
+            }
+        }
+        ksort($clean);
+
+        return $clean;
+    }
+}

src/Guides/InstructionsBuilder.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace LIT\MCP\Guides;
 
+use LIT\MCP\Abilities\ExposurePolicy;
 use LIT\MCP\Integrations\Integration;
 use LIT\MCP\Integrations\IntegrationRegistry;
 
@@ -16,9 +17,15 @@ final class InstructionsBuilder
     /** @var (callable(): list<string>)|null */
     private $postTypeNames;
 
-    public function __construct(private IntegrationRegistry $registry, ?callable $postTypeNames = null)
+    private ExposurePolicy $policy;
-    {
+
+    public function __construct(
+        private IntegrationRegistry $registry,
+        ?callable $postTypeNames = null,
+        ?ExposurePolicy $policy = null
+    ) {
         $this->postTypeNames = $postTypeNames;
+        $this->policy = $policy ?? new ExposurePolicy();
     }
 
     public function build(): string
@@ -28,9 +35,16 @@ final class InstructionsBuilder
             $this->registry->available()
         ));
 
+        $directNames = array_map(
+            static fn (string $name): string => 'lit-' . substr($name, strlen('lit/')),
+            $this->policy->directNames($this->registry->abilities())
+        );
+
         $lines = [
             'LIT MCP pflegt diese WordPress-Website (Inhalte, Medien, Divi 5, Pods).',
             'Aktive Integrationen: ' . $active . '.',
+            'Direkt aufrufbare Tools: ' . implode(', ', $directNames) . '.',
+            'Weitere Fähigkeiten über mcp-adapter-execute-ability (Ability-Name lit/<name>).',
         ];
 
         if ($this->postTypeNames !== null) {

src/Integrations/IntegrationRegistry.php

@@ -42,17 +42,4 @@ final class IntegrationRegistry
 
         return $this->abilities;
     }
-
-    /** @return list<string> */
-    public function directAbilityNames(): array
-    {
-        $names = [];
-        foreach ($this->abilities() as $ability) {
-            if ($ability->isDirect()) {
-                $names[] = $ability->name();
-            }
-        }
-
-        return $names;
-    }
 }

src/Plugin.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace LIT\MCP;
 
 use LIT\MCP\Abilities\AbilityRegistrar;
+use LIT\MCP\Abilities\ExposurePolicy;
 use LIT\MCP\ChangeLog\ChangeLog;
 use LIT\MCP\ChangeLog\ChangeLogCleanup;
 use LIT\MCP\ChangeLog\ChangeLogInstaller;
@@ -54,10 +55,15 @@ final class Plugin
             new MediaIntegration($schema, $changeLog, $limits)
         );
 
-        (new AbilityRegistrar($registry))->register();
+        $policy = ExposurePolicy::fromOption();
+        (new AbilityRegistrar($registry, $policy))->register();
         (new ServerRegistrar(
             $registry,
-            new InstructionsBuilder($registry, static fn (): array => $schema->postTypeNames())
+            new InstructionsBuilder($registry, static fn (): array => $schema->postTypeNames(), $policy),
+            null,
+            null,
+            null,
+            $policy
         ))->register();
 
         \WPMedia\MCP\OAuth\Bootstrap::instance();

src/Server/ServerRegistrar.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace LIT\MCP\Server;
 
+use LIT\MCP\Abilities\ExposurePolicy;
 use LIT\MCP\Guides\InstructionsBuilder;
 use LIT\MCP\Integrations\IntegrationRegistry;
 use LIT\MCP\Plugin;
@@ -48,13 +49,17 @@ final class ServerRegistrar
     /** @var callable(string): bool */
     private $classExists;
 
+    private ExposurePolicy $policy;
+
     public function __construct(
         private IntegrationRegistry $registry,
         private InstructionsBuilder $instructions,
         ?callable $oauthEnabled = null,
         ?callable $createAdapterServer = null,
-        ?callable $classExists = null
+        ?callable $classExists = null,
+        ?ExposurePolicy $policy = null
     ) {
+        $this->policy = $policy ?? new ExposurePolicy();
         $this->oauthEnabled = $oauthEnabled
             ?? static fn (): bool => (new OAuthContext())->is_enabled();
         $this->classExists = $classExists
@@ -102,7 +107,7 @@ final class ServerRegistrar
             'name' => 'LIT MCP',
             'description' => $this->instructions->build(),
             'version' => Plugin::VERSION,
-            'tools' => array_merge($this->registry->directAbilityNames(), self::META_TOOLS),
+            'tools' => array_merge($this->policy->directNames($this->registry->abilities()), self::META_TOOLS),
         ];
     }
 

tests/Unit/Abilities/AbilityRegistrarTest.php

@@ -7,6 +7,7 @@ namespace LIT\MCP\Tests\Unit\Abilities;
 use Brain\Monkey\Functions;
 use LIT\MCP\Abilities\Ability;
 use LIT\MCP\Abilities\AbilityRegistrar;
+use LIT\MCP\Abilities\ExposurePolicy;
 use LIT\MCP\Abilities\WriteFailed;
 use LIT\MCP\Integrations\Integration;
 use LIT\MCP\Integrations\IntegrationRegistry;
@@ -185,4 +186,17 @@ final class AbilityRegistrarTest extends TestCase
 
         $this->registrarFor($ability)->registerAbilities();
     }
+
+    public function testDisabledAbilitiesAreNotRegistered(): void
+    {
+        $ability = $this->ability();
+        $integration = Mockery::mock(Integration::class);
+        $integration->allows('id')->andReturn('core');
+        $integration->allows('isAvailable')->andReturn(true);
+        $integration->allows('abilities')->andReturn([$ability]);
+        Functions\expect('wp_register_ability')->never();
+
+        (new AbilityRegistrar(new IntegrationRegistry($integration), new ExposurePolicy(['lit/test' => 'disabled'])))
+            ->registerAbilities();
+    }
 }

tests/Unit/Abilities/ExposurePolicyTest.php

@@ -0,0 +1,116 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LIT\MCP\Tests\Unit\Abilities;
+
+use Brain\Monkey\Functions;
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\ExposurePolicy;
+use LIT\MCP\Tests\Unit\TestCase;
+use Mockery;
+
+final class ExposurePolicyTest extends TestCase
+{
+    private function ability(string $name, bool $direct): Ability
+    {
+        $ability = Mockery::mock(Ability::class);
+        $ability->allows('name')->andReturn($name);
+        $ability->allows('isDirect')->andReturn($direct);
+
+        return $ability;
+    }
+
+    public function testDefaultFollowsIsDirect(): void
+    {
+        $policy = new ExposurePolicy();
+
+        self::assertSame('direct', $policy->mode($this->ability('lit/content-get', true)));
+        self::assertSame('indirect', $policy->mode($this->ability('lit/menu-list', false)));
+    }
+
+    public function testOverridesChangeTheMode(): void
+    {
+        $policy = new ExposurePolicy(['lit/content-get' => 'indirect', 'lit/menu-list' => 'disabled']);
+
+        self::assertSame('indirect', $policy->mode($this->ability('lit/content-get', true)));
+        self::assertSame('disabled', $policy->mode($this->ability('lit/menu-list', false)));
+    }
+
+    public function testImpossibleOrBrokenOverridesFallBackToTheDefault(): void
+    {
+        $policy = new ExposurePolicy([
+            'lit/media-preview' => 'indirect',
+            'lit/media-download' => 'indirect',
+            'lit/guide' => 'disabled',
+            'lit/content-get' => 'sometimes',
+        ]);
+
+        self::assertSame('direct', $policy->mode($this->ability('lit/media-preview', true)));
+        self::assertSame('direct', $policy->mode($this->ability('lit/media-download', true)));
+        self::assertSame('direct', $policy->mode($this->ability('lit/guide', true)));
+        self::assertSame('direct', $policy->mode($this->ability('lit/content-get', true)));
+    }
+
+    public function testGuideCanNeitherBeDisabledNorMadeIndirect(): void
+    {
+        $policy = new ExposurePolicy(['lit/guide' => 'indirect']);
+
+        self::assertSame('direct', $policy->mode($this->ability('lit/guide', true)));
+        self::assertFalse(ExposurePolicy::isAllowed('lit/guide', 'indirect'));
+        self::assertFalse(ExposurePolicy::isAllowed('lit/guide', 'disabled'));
+        self::assertTrue(ExposurePolicy::isAllowed('lit/guide', 'direct'));
+    }
+
+    public function testMediaPreviewAndDownloadMayStillBeDisabled(): void
+    {
+        $policy = new ExposurePolicy(['lit/media-preview' => 'disabled', 'lit/media-download' => 'disabled']);
+
+        self::assertSame('disabled', $policy->mode($this->ability('lit/media-preview', true)));
+        self::assertSame('disabled', $policy->mode($this->ability('lit/media-download', true)));
+    }
+
+    public function testEnabledAndDirectNamesKeepTheRegistryOrder(): void
+    {
+        $a = $this->ability('lit/a', true);
+        $b = $this->ability('lit/b', false);
+        $c = $this->ability('lit/c', true);
+        $policy = new ExposurePolicy(['lit/b' => 'direct', 'lit/c' => 'disabled']);
+
+        self::assertSame([$a, $b], $policy->enabled([$a, $b, $c]));
+        self::assertSame(['lit/a', 'lit/b'], $policy->directNames([$a, $b, $c]));
+    }
+
+    public function testSanitizeKeepsOnlyValidEntries(): void
+    {
+        self::assertSame(
+            ['lit/content-get' => 'indirect', 'lit/menu-list' => 'disabled'],
+            ExposurePolicy::sanitize([
+                'lit/menu-list' => 'disabled',
+                'lit/content-get' => 'indirect',
+                'lit/guide' => 'disabled',
+                '<script>' => 'direct',
+                'lit/x' => ['direct'],
+            ])
+        );
+        self::assertSame([], ExposurePolicy::sanitize('garbage'));
+    }
+
+    public function testSanitizeRejectsIndirectForDirectOnlyAbilities(): void
+    {
+        self::assertSame(
+            ['lit/media-preview' => 'disabled'],
+            ExposurePolicy::sanitize([
+                'lit/media-preview' => 'disabled',
+                'lit/media-download' => 'indirect',
+            ])
+        );
+    }
+
+    public function testFromOptionToleratesACorruptOption(): void
+    {
+        Functions\when('get_option')->justReturn('garbage');
+
+        self::assertSame('direct', ExposurePolicy::fromOption()->mode($this->ability('lit/a', true)));
+    }
+}

tests/Unit/Guides/InstructionsBuilderTest.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace LIT\MCP\Tests\Unit\Guides;
 
+use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\ExposurePolicy;
 use LIT\MCP\Guides\InstructionsBuilder;
 use LIT\MCP\Integrations\Integration;
 use LIT\MCP\Integrations\IntegrationRegistry;
@@ -12,11 +14,28 @@ use Mockery;
 
 final class InstructionsBuilderTest extends TestCase
 {
-    public function testNamesActiveIntegrationsAndCoreRules(): void
+    private function ability(string $name, bool $direct): Ability
+    {
+        $ability = Mockery::mock(Ability::class);
+        $ability->allows('name')->andReturn($name);
+        $ability->allows('isDirect')->andReturn($direct);
+
+        return $ability;
+    }
+
+    private function coreWith(Ability ...$abilities): Integration
     {
         $core = Mockery::mock(Integration::class);
         $core->allows('id')->andReturn('core');
         $core->allows('isAvailable')->andReturn(true);
+        $core->allows('abilities')->andReturn(array_values($abilities));
+
+        return $core;
+    }
+
+    public function testNamesActiveIntegrationsAndCoreRules(): void
+    {
+        $core = $this->coreWith($this->ability('lit/guide', true), $this->ability('lit/menu-list', false));
 
         $text = (new InstructionsBuilder(new IntegrationRegistry($core)))->build();
 
@@ -28,9 +47,7 @@ final class InstructionsBuilderTest extends TestCase
 
     public function testListsPostTypesWhenAProviderIsGiven(): void
     {
-        $core = Mockery::mock(Integration::class);
+        $core = $this->coreWith($this->ability('lit/guide', true));
-        $core->allows('id')->andReturn('core');
-        $core->allows('isAvailable')->andReturn(true);
 
         $text = (new InstructionsBuilder(new IntegrationRegistry($core), static fn (): array => ['page', 'post']))->build();
 
@@ -38,4 +55,31 @@ final class InstructionsBuilderTest extends TestCase
         self::assertStringContainsString('lit-content-types', $text);
         self::assertStringContainsString('confirm: true', $text);
     }
+
+    public function testListsTheCurrentlyDirectToolsByToolNameAndNamesTheRestNeutrally(): void
+    {
+        $core = $this->coreWith(
+            $this->ability('lit/guide', true),
+            $this->ability('lit/menu-list', false)
+        );
+
+        $text = (new InstructionsBuilder(new IntegrationRegistry($core)))->build();
+
+        self::assertStringContainsString('Direkt aufrufbare Tools: lit-guide', $text);
+        self::assertStringContainsString('mcp-adapter-execute-ability', $text);
+        self::assertStringNotContainsString('lit-menu-list', $text);
+    }
+
+    public function testDirectToolListReflectsExposurePolicyOverrides(): void
+    {
+        $core = $this->coreWith(
+            $this->ability('lit/guide', true),
+            $this->ability('lit/menu-list', false)
+        );
+        $policy = new ExposurePolicy(['lit/menu-list' => 'direct']);
+
+        $text = (new InstructionsBuilder(new IntegrationRegistry($core), null, $policy))->build();
+
+        self::assertStringContainsString('lit-menu-list', $text);
+    }
 }

tests/Unit/Integrations/IntegrationRegistryTest.php

@@ -25,7 +25,6 @@ final class IntegrationRegistryTest extends TestCase
 
         self::assertSame(['core'], array_map(static fn ($i) => $i->id(), $registry->available()));
         self::assertSame([$direct, $indirect], $registry->abilities());
-        self::assertSame(['lit/a'], $registry->directAbilityNames());
     }
 
     private function ability(string $name, bool $direct): Ability

tests/Unit/Server/ServerRegistrarTest.php

@@ -7,6 +7,7 @@ namespace LIT\MCP\Tests\Unit\Server;
 use Brain\Monkey\Filters;
 use Brain\Monkey\Functions;
 use LIT\MCP\Abilities\Ability;
+use LIT\MCP\Abilities\ExposurePolicy;
 use LIT\MCP\Guides\InstructionsBuilder;
 use LIT\MCP\Integrations\Integration;
 use LIT\MCP\Integrations\IntegrationRegistry;
@@ -61,6 +62,33 @@ final class ServerRegistrarTest extends TestCase
         self::assertNotContains('lit/rare-tool', $args['tools']);
     }
 
+    public function testExposurePolicyDecidesWhichToolsAreDirect(): void
+    {
+        // Deviation from the brief: the brief's original test demoted lit/guide to
+        // indirect, but the controller's fixed constraint for this task is that
+        // lit/guide can neither be disabled nor made indirect (see ExposurePolicy::
+        // REQUIRED / ExposurePolicyTest::testGuideCanNeitherBeDisabledNorMadeIndirect).
+        // Using a demotable direct ability here instead proves the same thing: the
+        // policy, not Ability::isDirect(), decides the tool list.
+        $optional = Mockery::mock(Ability::class);
+        $optional->allows('name')->andReturn('lit/optional-tool');
+        $optional->allows('isDirect')->andReturn(true);
+
+        $core = Mockery::mock(Integration::class);
+        $core->allows('id')->andReturn('core');
+        $core->allows('isAvailable')->andReturn(true);
+        $core->allows('abilities')->andReturn([$optional]);
+        $registry = new IntegrationRegistry($core, ...$this->registry()->available());
+
+        $policy = new ExposurePolicy(['lit/optional-tool' => 'indirect', 'lit/rare-tool' => 'direct']);
+        $registrar = new ServerRegistrar($registry, $this->instructions(), static fn () => true, null, null, $policy);
+
+        self::assertSame(
+            ['lit/guide', 'lit/rare-tool', 'mcp-adapter/discover-abilities', 'mcp-adapter/get-ability-info', 'mcp-adapter/execute-ability'],
+            $registrar->serverArguments()['tools']
+        );
+    }
+
     public function testNoServerWhenOauthIsDisabled(): void
     {
         $registrar = new ServerRegistrar($this->registry(), $this->instructions(), static fn () => false);