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
2026-09-26 03:04:14 +02:00
parent 7f136f6f4c
commit 2f8a9f0c61
11 changed files with 362 additions and 26 deletions
@@ -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)));
+    }
+}