fix: clear() wiping dynamically registered tools by tracking discovered state on references

src/Capability/Registry.php

@@ -161,36 +161,10 @@ public function registerPrompt(
 
     public function clear(): void
     {
-        $clearCount = 0;
-
-        foreach ($this->tools as $name => $tool) {
-            if (!$tool->isManual) {
-                unset($this->tools[$name]);
-                ++$clearCount;
-            }
-        }
-        foreach ($this->resources as $uri => $resource) {
-            if (!$resource->isManual) {
-                unset($this->resources[$uri]);
-                ++$clearCount;
-            }
-        }
-        foreach ($this->prompts as $name => $prompt) {
-            if (!$prompt->isManual) {
-                unset($this->prompts[$name]);
-                ++$clearCount;
-            }
-        }
-        foreach ($this->resourceTemplates as $uriTemplate => $template) {
-            if (!$template->isManual) {
-                unset($this->resourceTemplates[$uriTemplate]);
-                ++$clearCount;
-            }
-        }
-
-        if ($clearCount > 0) {
-            $this->logger->debug(\sprintf('Removed %d discovered elements from internal registry.', $clearCount));
-        }
+        $this->tools = array_filter($this->tools, static fn ($t) => !$t->isDiscovered);
+        $this->resources = array_filter($this->resources, static fn ($r) => !$r->isDiscovered);
+        $this->prompts = array_filter($this->prompts, static fn ($p) => !$p->isDiscovered);
+        $this->resourceTemplates = array_filter($this->resourceTemplates, static fn ($t) => !$t->isDiscovered);
     }
 
     public function hasTools(): bool
@@ -344,10 +318,10 @@ public function getPrompt(string $name): PromptReference
     public function getDiscoveryState(): DiscoveryState
     {
         return new DiscoveryState(
-            tools: array_filter($this->tools, static fn ($tool) => !$tool->isManual),
-            resources: array_filter($this->resources, static fn ($resource) => !$resource->isManual),
-            prompts: array_filter($this->prompts, static fn ($prompt) => !$prompt->isManual),
-            resourceTemplates: array_filter($this->resourceTemplates, static fn ($template) => !$template->isManual),
+            tools: array_filter($this->tools, static fn ($t) => $t->isDiscovered),
+            resources: array_filter($this->resources, static fn ($r) => $r->isDiscovered),
+            prompts: array_filter($this->prompts, static fn ($p) => $p->isDiscovered),
+            resourceTemplates: array_filter($this->resourceTemplates, static fn ($t) => $t->isDiscovered),
         );
     }
 
@@ -360,21 +334,29 @@ public function setDiscoveryState(DiscoveryState $state): void
         // Clear existing discovered elements
         $this->clear();
 
-        // Import new discovered elements
+        // Import new discovered elements — skip any that conflict with manual or dynamic registrations
         foreach ($state->getTools() as $name => $tool) {
-            $this->tools[$name] = $tool;
+            if (!isset($this->tools[$name])) {
+                $this->tools[$name] = new ToolReference($tool->tool, $tool->handler, isDiscovered: true);
+            }
         }
 
         foreach ($state->getResources() as $uri => $resource) {
-            $this->resources[$uri] = $resource;
+            if (!isset($this->resources[$uri])) {
+                $this->resources[$uri] = new ResourceReference($resource->resource, $resource->handler, isDiscovered: true);
+            }
         }
 
         foreach ($state->getPrompts() as $name => $prompt) {
-            $this->prompts[$name] = $prompt;
+            if (!isset($this->prompts[$name])) {
+                $this->prompts[$name] = new PromptReference($prompt->prompt, $prompt->handler, completionProviders: $prompt->completionProviders, isDiscovered: true);
+            }
         }
 
         foreach ($state->getResourceTemplates() as $uriTemplate => $template) {
-            $this->resourceTemplates[$uriTemplate] = $template;
+            if (!isset($this->resourceTemplates[$uriTemplate])) {
+                $this->resourceTemplates[$uriTemplate] = new ResourceTemplateReference($template->resourceTemplate, $template->handler, completionProviders: $template->completionProviders, isDiscovered: true);
+            }
         }
 
         // Dispatch events for the imported elements

src/Capability/Registry/ElementReference.php

@@ -24,6 +24,7 @@ class ElementReference
     public function __construct(
         public readonly \Closure|array|string $handler,
         public readonly bool $isManual = false,
+        public readonly bool $isDiscovered = false,
     ) {
     }
 }

src/Capability/Registry/PromptReference.php

@@ -31,8 +31,9 @@ public function __construct(
         \Closure|array|string $handler,
         bool $isManual = false,
         public readonly array $completionProviders = [],
+        bool $isDiscovered = false,
     ) {
-        parent::__construct($handler, $isManual);
+        parent::__construct($handler, $isManual, $isDiscovered);
     }
 
     /**

src/Capability/Registry/ResourceReference.php

@@ -29,8 +29,9 @@ public function __construct(
         public readonly Resource $resource,
         callable|array|string $handler,
         bool $isManual = false,
+        bool $isDiscovered = false,
     ) {
-        parent::__construct($handler, $isManual);
+        parent::__construct($handler, $isManual, $isDiscovered);
     }
 
     /**

src/Capability/Registry/ResourceTemplateReference.php

@@ -38,8 +38,9 @@ public function __construct(
         callable|array|string $handler,
         bool $isManual = false,
         public readonly array $completionProviders = [],
+        bool $isDiscovered = false,
     ) {
-        parent::__construct($handler, $isManual);
+        parent::__construct($handler, $isManual, $isDiscovered);
 
         $this->compileTemplate();
     }

src/Capability/Registry/ToolReference.php

@@ -29,8 +29,9 @@ public function __construct(
         public readonly Tool $tool,
         callable|array|string $handler,
         bool $isManual = false,
+        bool $isDiscovered = false,
     ) {
-        parent::__construct($handler, $isManual);
+        parent::__construct($handler, $isManual, $isDiscovered);
     }
 
     /**

tests/Inspector/Http/snapshots/HttpCombinedRegistrationTest-resources_list.json

@@ -1,9 +1,9 @@
 {
   "resources": [
     {
-      "name": "priority_config_discovered",
+      "name": "priority_config_manual",
       "uri": "config://priority",
-      "description": "A resource discovered via attributes.\n\nThis will be overridden by a manual registration with the same URI."
+      "description": "Manually registered resource that overrides a discovered one."
     }
   ]
 }

tests/Inspector/Http/snapshots/HttpCombinedRegistrationTest-resources_read-config_priority.json

@@ -3,7 +3,7 @@
     {
       "uri": "config://priority",
       "mimeType": "text/plain",
-      "text": "Discovered Priority Config: Low"
+      "text": "Manual Priority Config: HIGH (overrides discovered)"
     }
   ]
 }

tests/Unit/Capability/RegistryTest.php

@@ -12,6 +12,7 @@
 namespace Mcp\Tests\Unit\Capability;
 
 use Mcp\Capability\Completion\EnumCompletionProvider;
+use Mcp\Capability\Discovery\DiscoveryState;
 use Mcp\Capability\Registry;
 use Mcp\Capability\Registry\PromptReference;
 use Mcp\Capability\Registry\ResourceReference;
@@ -426,42 +427,70 @@ public function testClearRemovesOnlyDiscoveredElements(): void
         $manualTemplate = $this->createValidResourceTemplate('manual://{id}');
         $discoveredTemplate = $this->createValidResourceTemplate('discovered://{id}');
 
+        // Register manual elements directly
         $this->registry->registerTool($manualTool, static fn () => 'manual', true);
-        $this->registry->registerTool($discoveredTool, static fn () => 'discovered');
         $this->registry->registerResource($manualResource, static fn () => 'manual', true);
-        $this->registry->registerResource($discoveredResource, static fn () => 'discovered');
         $this->registry->registerPrompt($manualPrompt, static fn () => [], [], true);
-        $this->registry->registerPrompt($discoveredPrompt, static fn () => []);
         $this->registry->registerResourceTemplate($manualTemplate, static fn () => 'manual', [], true);
-        $this->registry->registerResourceTemplate($discoveredTemplate, static fn () => 'discovered');
 
-        // Test that all elements exist
-        $this->registry->getTool('manual_tool');
-        $this->registry->getResource('test://manual');
-        $this->registry->getPrompt('manual_prompt');
-        $this->registry->getResourceTemplate('manual://{id}');
-        $this->registry->getTool('discovered_tool');
-        $this->registry->getResource('test://discovered');
-        $this->registry->getPrompt('discovered_prompt');
-        $this->registry->getResourceTemplate('discovered://{id}');
+        // Import discovered elements via setDiscoveryState
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            tools: ['discovered_tool' => new ToolReference($discoveredTool, static fn () => 'discovered')],
+            resources: ['test://discovered' => new ResourceReference($discoveredResource, static fn () => 'discovered')],
+            prompts: ['discovered_prompt' => new PromptReference($discoveredPrompt, static fn () => [])],
+            resourceTemplates: ['discovered://{id}' => new ResourceTemplateReference($discoveredTemplate, static fn () => 'discovered')],
+        ));
+
+        // All elements exist before clear
+        $this->assertInstanceOf(ToolReference::class, $this->registry->getTool('discovered_tool'));
 
         $this->registry->clear();
 
-        // Manual elements should still exist
-        $this->registry->getTool('manual_tool');
-        $this->registry->getResource('test://manual');
-        $this->registry->getPrompt('manual_prompt');
-        $this->registry->getResourceTemplate('manual://{id}');
+        // Manual elements survive
+        $this->assertInstanceOf(ToolReference::class, $this->registry->getTool('manual_tool'));
+        $this->assertInstanceOf(ResourceReference::class, $this->registry->getResource('test://manual'));
+        $this->assertInstanceOf(PromptReference::class, $this->registry->getPrompt('manual_prompt'));
+        $this->assertInstanceOf(ResourceTemplateReference::class, $this->registry->getResourceTemplate('manual://{id}'));
 
-        // Test that all discovered elements throw exceptions
+        // Discovered elements are gone
         $this->expectException(ToolNotFoundException::class);
         $this->registry->getTool('discovered_tool');
+    }
+
+    public function testClearRemovesDiscoveredResources(): void
+    {
+        $discoveredResource = $this->createValidResource('test://discovered');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            resources: ['test://discovered' => new ResourceReference($discoveredResource, static fn () => 'discovered')],
+        ));
+
+        $this->registry->clear();
 
         $this->expectException(ResourceNotFoundException::class);
         $this->registry->getResource('test://discovered');
+    }
+
+    public function testClearRemovesDiscoveredPrompts(): void
+    {
+        $discoveredPrompt = $this->createValidPrompt('discovered_prompt');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            prompts: ['discovered_prompt' => new PromptReference($discoveredPrompt, static fn () => [])],
+        ));
+
+        $this->registry->clear();
 
         $this->expectException(PromptNotFoundException::class);
         $this->registry->getPrompt('discovered_prompt');
+    }
+
+    public function testClearRemovesDiscoveredResourceTemplates(): void
+    {
+        $discoveredTemplate = $this->createValidResourceTemplate('discovered://{id}');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            resourceTemplates: ['discovered://{id}' => new ResourceTemplateReference($discoveredTemplate, static fn () => 'discovered')],
+        ));
+
+        $this->registry->clear();
 
         $this->expectException(ResourceNotFoundException::class);
         $this->registry->getResourceTemplate('discovered://{id}');
@@ -611,6 +640,127 @@ public function testExtractStructuredContentReturnsArrayDirectlyForArrayOutputSc
         ], $structuredContent);
     }
 
+    public function testClearPreservesDynamicallyRegisteredElements(): void
+    {
+        // 1. Register a manual tool
+        $manualTool = $this->createValidTool('manual_tool');
+        $this->registry->registerTool($manualTool, static fn () => 'manual', true);
+
+        // 2. Import discovered tools via setDiscoveryState
+        $discoveredTool = $this->createValidTool('discovered_tool');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            tools: ['discovered_tool' => new ToolReference($discoveredTool, static fn () => 'discovered')],
+        ));
+
+        // 3. Register a dynamic tool (not manual, not discovered)
+        $dynamicTool = $this->createValidTool('dynamic_tool');
+        $this->registry->registerTool($dynamicTool, static fn () => 'dynamic');
+
+        // 4. Restore discovery state again (simulates next HTTP request)
+        $discoveredTool2 = $this->createValidTool('discovered_tool_v2');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            tools: ['discovered_tool_v2' => new ToolReference($discoveredTool2, static fn () => 'discovered_v2')],
+        ));
+
+        // Manual tool survives
+        $this->assertInstanceOf(ToolReference::class, $this->registry->getTool('manual_tool'));
+        // Dynamic tool survives
+        $this->assertInstanceOf(ToolReference::class, $this->registry->getTool('dynamic_tool'));
+        // New discovered tool is present
+        $this->assertInstanceOf(ToolReference::class, $this->registry->getTool('discovered_tool_v2'));
+        // Old discovered tool is gone
+        $this->expectException(ToolNotFoundException::class);
+        $this->registry->getTool('discovered_tool');
+    }
+
+    public function testGetDiscoveryStateExcludesDynamicTools(): void
+    {
+        // Import discovered tool via setDiscoveryState
+        $discoveredTool = $this->createValidTool('discovered_tool');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            tools: ['discovered_tool' => new ToolReference($discoveredTool, static fn () => 'discovered')],
+        ));
+
+        // Register a dynamic tool
+        $dynamicTool = $this->createValidTool('dynamic_tool');
+        $this->registry->registerTool($dynamicTool, static fn () => 'dynamic');
+
+        // Register a manual tool
+        $manualTool = $this->createValidTool('manual_tool');
+        $this->registry->registerTool($manualTool, static fn () => 'manual', true);
+
+        $state = $this->registry->getDiscoveryState();
+
+        $this->assertArrayHasKey('discovered_tool', $state->getTools());
+        $this->assertArrayNotHasKey('dynamic_tool', $state->getTools());
+        $this->assertArrayNotHasKey('manual_tool', $state->getTools());
+    }
+
+    public function testSetDiscoveryStateRoundTrip(): void
+    {
+        // Import initial discovered state
+        $tool = $this->createValidTool('round_trip_tool');
+        $resource = $this->createValidResource('test://round-trip');
+        $prompt = $this->createValidPrompt('round_trip_prompt');
+        $template = $this->createValidResourceTemplate('round-trip://{id}');
+
+        $initialState = new DiscoveryState(
+            tools: ['round_trip_tool' => new ToolReference($tool, static fn () => 'result')],
+            resources: ['test://round-trip' => new ResourceReference($resource, static fn () => 'content')],
+            prompts: ['round_trip_prompt' => new PromptReference($prompt, static fn () => [])],
+            resourceTemplates: ['round-trip://{id}' => new ResourceTemplateReference($template, static fn () => 'tpl')],
+        );
+
+        $this->registry->setDiscoveryState($initialState);
+
+        // Round-trip: get and set again
+        $exportedState = $this->registry->getDiscoveryState();
+        $this->registry->setDiscoveryState($exportedState);
+
+        // All elements still present
+        $this->assertInstanceOf(ToolReference::class, $this->registry->getTool('round_trip_tool'));
+        $this->assertInstanceOf(ResourceReference::class, $this->registry->getResource('test://round-trip'));
+        $this->assertInstanceOf(PromptReference::class, $this->registry->getPrompt('round_trip_prompt'));
+        $this->assertInstanceOf(ResourceTemplateReference::class, $this->registry->getResourceTemplate('round-trip://{id}'));
+
+        // Exported state matches
+        $reExportedState = $this->registry->getDiscoveryState();
+        $this->assertCount(\count($exportedState->getTools()), $reExportedState->getTools());
+        $this->assertCount(\count($exportedState->getResources()), $reExportedState->getResources());
+        $this->assertCount(\count($exportedState->getPrompts()), $reExportedState->getPrompts());
+        $this->assertCount(\count($exportedState->getResourceTemplates()), $reExportedState->getResourceTemplates());
+    }
+
+    public function testSetDiscoveryStateDoesNotOverwriteManualOrDynamicTools(): void
+    {
+        // Register a manual tool
+        $manualTool = $this->createValidTool('conflict_tool');
+        $this->registry->registerTool($manualTool, static fn () => 'manual_result', true);
+
+        // Register a dynamic tool
+        $dynamicTool = $this->createValidTool('dynamic_conflict');
+        $this->registry->registerTool($dynamicTool, static fn () => 'dynamic_result');
+
+        // Try to import discovered tools with same names
+        $discoveredConflict = $this->createValidTool('conflict_tool');
+        $discoveredDynConflict = $this->createValidTool('dynamic_conflict');
+        $this->registry->setDiscoveryState(new DiscoveryState(
+            tools: [
+                'conflict_tool' => new ToolReference($discoveredConflict, static fn () => 'discovered_result'),
+                'dynamic_conflict' => new ToolReference($discoveredDynConflict, static fn () => 'discovered_dyn_result'),
+            ],
+        ));
+
+        // Manual tool preserved with original handler
+        $manualRef = $this->registry->getTool('conflict_tool');
+        $this->assertTrue($manualRef->isManual);
+        $this->assertEquals('manual_result', ($manualRef->handler)());
+
+        // Dynamic tool preserved with original handler
+        $dynamicRef = $this->registry->getTool('dynamic_conflict');
+        $this->assertEquals('dynamic_result', ($dynamicRef->handler)());
+    }
+
     private function createValidTool(string $name, ?array $outputSchema = null): Tool
     {
         return new Tool(