[Server] Untangle origin tracking from Registry

Drop the isManual flag from ElementReference and the discovery-state methods
from RegistryInterface. The Registry becomes a flat last-write-wins map;
DiscoveryLoader owns its own owned-set bookkeeping so re-running discovery
only removes elements it itself contributed. Adds ChainLoader for explicit
composition. Manual-over-discovered precedence is preserved via loader
ordering, not a flag on the reference.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chr-hertel

src/Capability/Discovery/Discoverer.php

@@ -243,7 +243,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
                         meta: $instance->meta,
                         outputSchema: $outputSchema,
                     );
-                    $tools[$name] = new ToolReference($tool, [$className, $methodName], false);
+                    $tools[$name] = new ToolReference($tool, [$className, $methodName]);
                     ++$discoveredCount['tools'];
                     break;
 
@@ -261,7 +261,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
                         $instance->icons,
                         $instance->meta,
                     );
-                    $resources[$instance->uri] = new ResourceReference($resource, [$className, $methodName], false);
+                    $resources[$instance->uri] = new ResourceReference($resource, [$className, $methodName]);
 
                     ++$discoveredCount['resources'];
                     break;
@@ -282,7 +282,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
                     }
                     $prompt = new Prompt($name, $instance->title, $description, $arguments, $instance->icons, $instance->meta);
                     $completionProviders = $this->getCompletionProviders($method);
-                    $prompts[$name] = new PromptReference($prompt, [$className, $methodName], false, $completionProviders);
+                    $prompts[$name] = new PromptReference($prompt, [$className, $methodName], $completionProviders);
                     ++$discoveredCount['prompts'];
                     break;
 
@@ -295,7 +295,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
                     $meta = $instance->meta ?? null;
                     $resourceTemplate = new ResourceTemplate($instance->uriTemplate, $name, $description, $mimeType, $annotations, $meta);
                     $completionProviders = $this->getCompletionProviders($method);
-                    $resourceTemplates[$instance->uriTemplate] = new ResourceTemplateReference($resourceTemplate, [$className, $methodName], false, $completionProviders);
+                    $resourceTemplates[$instance->uriTemplate] = new ResourceTemplateReference($resourceTemplate, [$className, $methodName], $completionProviders);
                     ++$discoveredCount['resourceTemplates'];
                     break;
             }

src/Capability/Registry.php

@@ -11,7 +11,6 @@
 
 namespace Mcp\Capability;
 
-use Mcp\Capability\Discovery\DiscoveryState;
 use Mcp\Capability\Registry\PromptReference;
 use Mcp\Capability\Registry\ResourceReference;
 use Mcp\Capability\Registry\ResourceTemplateReference;
@@ -68,44 +67,22 @@ public function __construct(
     ) {
     }
 
-    public function registerTool(Tool $tool, callable|array|string $handler, bool $isManual = false): void
+    public function registerTool(Tool $tool, callable|array|string $handler): void
     {
-        $toolName = $tool->name;
-        $existing = $this->tools[$toolName] ?? null;
-
-        if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug(
-                \sprintf('Ignoring discovered tool "%s" as it conflicts with a manually registered one.', $toolName),
-            );
-
-            return;
-        }
-
-        if (!$this->nameValidator->isValid($toolName)) {
+        if (!$this->nameValidator->isValid($tool->name)) {
             $this->logger->warning(
-                \sprintf('Tool name "%s" is invalid. Tool names should only contain letters (a-z, A-Z), numbers, dots, hyphens, underscores, and forward slashes.', $toolName),
+                \sprintf('Tool name "%s" is invalid. Tool names should only contain letters (a-z, A-Z), numbers, dots, hyphens, underscores, and forward slashes.', $tool->name),
             );
         }
 
-        $this->tools[$toolName] = new ToolReference($tool, $handler, $isManual);
+        $this->tools[$tool->name] = new ToolReference($tool, $handler);
 
         $this->eventDispatcher?->dispatch(new ToolListChangedEvent());
     }
 
-    public function registerResource(Resource $resource, callable|array|string $handler, bool $isManual = false): void
+    public function registerResource(Resource $resource, callable|array|string $handler): void
     {
-        $uri = $resource->uri;
-        $existing = $this->resources[$uri] ?? null;
-
-        if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug(
-                \sprintf('Ignoring discovered resource "%s" as it conflicts with a manually registered one.', $uri),
-            );
-
-            return;
-        }
-
-        $this->resources[$uri] = new ResourceReference($resource, $handler, $isManual);
+        $this->resources[$resource->uri] = new ResourceReference($resource, $handler);
 
         $this->eventDispatcher?->dispatch(new ResourceListChangedEvent());
     }
@@ -114,23 +91,10 @@ public function registerResourceTemplate(
         ResourceTemplate $template,
         callable|array|string $handler,
         array $completionProviders = [],
-        bool $isManual = false,
     ): void {
-        $uriTemplate = $template->uriTemplate;
-        $existing = $this->resourceTemplates[$uriTemplate] ?? null;
-
-        if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug(
-                \sprintf('Ignoring discovered template "%s" as it conflicts with a manually registered one.', $uriTemplate),
-            );
-
-            return;
-        }
-
-        $this->resourceTemplates[$uriTemplate] = new ResourceTemplateReference(
+        $this->resourceTemplates[$template->uriTemplate] = new ResourceTemplateReference(
             $template,
             $handler,
-            $isManual,
             $completionProviders,
         );
 
@@ -141,56 +105,54 @@ public function registerPrompt(
         Prompt $prompt,
         callable|array|string $handler,
         array $completionProviders = [],
-        bool $isManual = false,
     ): void {
-        $promptName = $prompt->name;
-        $existing = $this->prompts[$promptName] ?? null;
+        $this->prompts[$prompt->name] = new PromptReference($prompt, $handler, $completionProviders);
 
-        if ($existing && !$isManual && $existing->isManual) {
-            $this->logger->debug(
-                \sprintf('Ignoring discovered prompt "%s" as it conflicts with a manually registered one.', $promptName),
-            );
+        $this->eventDispatcher?->dispatch(new PromptListChangedEvent());
+    }
 
+    public function unregisterTool(string $name): void
+    {
+        if (!isset($this->tools[$name])) {
             return;
         }
 
-        $this->prompts[$promptName] = new PromptReference($prompt, $handler, $isManual, $completionProviders);
+        unset($this->tools[$name]);
 
-        $this->eventDispatcher?->dispatch(new PromptListChangedEvent());
+        $this->eventDispatcher?->dispatch(new ToolListChangedEvent());
     }
 
-    public function clear(): void
+    public function unregisterResource(string $uri): 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;
-            }
+        if (!isset($this->resources[$uri])) {
+            return;
         }
-        foreach ($this->resourceTemplates as $uriTemplate => $template) {
-            if (!$template->isManual) {
-                unset($this->resourceTemplates[$uriTemplate]);
-                ++$clearCount;
-            }
+
+        unset($this->resources[$uri]);
+
+        $this->eventDispatcher?->dispatch(new ResourceListChangedEvent());
+    }
+
+    public function unregisterResourceTemplate(string $uriTemplate): void
+    {
+        if (!isset($this->resourceTemplates[$uriTemplate])) {
+            return;
         }
 
-        if ($clearCount > 0) {
-            $this->logger->debug(\sprintf('Removed %d discovered elements from internal registry.', $clearCount));
+        unset($this->resourceTemplates[$uriTemplate]);
+
+        $this->eventDispatcher?->dispatch(new ResourceTemplateListChangedEvent());
+    }
+
+    public function unregisterPrompt(string $name): void
+    {
+        if (!isset($this->prompts[$name])) {
+            return;
         }
+
+        unset($this->prompts[$name]);
+
+        $this->eventDispatcher?->dispatch(new PromptListChangedEvent());
     }
 
     public function hasTools(): bool
@@ -338,59 +300,6 @@ public function getPrompt(string $name): PromptReference
         return $this->prompts[$name] ?? throw new PromptNotFoundException($name);
     }
 
-    /**
-     * Get the current discovery state (only discovered elements, not manual ones).
-     */
-    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),
-        );
-    }
-
-    /**
-     * Set the discovery state, replacing all discovered elements.
-     * Manual elements are preserved.
-     */
-    public function setDiscoveryState(DiscoveryState $state): void
-    {
-        // Clear existing discovered elements
-        $this->clear();
-
-        // Import new discovered elements
-        foreach ($state->getTools() as $name => $tool) {
-            $this->tools[$name] = $tool;
-        }
-
-        foreach ($state->getResources() as $uri => $resource) {
-            $this->resources[$uri] = $resource;
-        }
-
-        foreach ($state->getPrompts() as $name => $prompt) {
-            $this->prompts[$name] = $prompt;
-        }
-
-        foreach ($state->getResourceTemplates() as $uriTemplate => $template) {
-            $this->resourceTemplates[$uriTemplate] = $template;
-        }
-
-        // Dispatch events for the imported elements
-        if ($this->eventDispatcher instanceof EventDispatcherInterface) {
-            if (!empty($state->getTools())) {
-                $this->eventDispatcher->dispatch(new ToolListChangedEvent());
-            }
-            if (!empty($state->getResources()) || !empty($state->getResourceTemplates())) {
-                $this->eventDispatcher->dispatch(new ResourceListChangedEvent());
-            }
-            if (!empty($state->getPrompts())) {
-                $this->eventDispatcher->dispatch(new PromptListChangedEvent());
-            }
-        }
-    }
-
     /**
      * Calculate next cursor for pagination.
      *

src/Capability/Registry/ElementReference.php

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

src/Capability/Registry/Loader/ArrayLoader.php

@@ -124,7 +124,7 @@ public function load(RegistryInterface $registry): void
                     meta: $data['meta'] ?? null,
                     outputSchema: $data['outputSchema'] ?? null,
                 );
-                $registry->registerTool($tool, $data['handler'], true);
+                $registry->registerTool($tool, $data['handler']);
 
                 $handlerDesc = $this->getHandlerDescription($data['handler']);
                 $this->logger->debug("Registered manual tool {$name} from handler {$handlerDesc}");
@@ -164,7 +164,7 @@ public function load(RegistryInterface $registry): void
                     icons: $data['icons'] ?? null,
                     meta: $data['meta'] ?? null,
                 );
-                $registry->registerResource($resource, $data['handler'], true);
+                $registry->registerResource($resource, $data['handler']);
 
                 $handlerDesc = $this->getHandlerDescription($data['handler']);
                 $this->logger->debug("Registered manual resource {$name} from handler {$handlerDesc}");
@@ -203,7 +203,7 @@ public function load(RegistryInterface $registry): void
                     meta: $data['meta'] ?? null,
                 );
                 $completionProviders = $this->getCompletionProviders($reflection);
-                $registry->registerResourceTemplate($template, $data['handler'], $completionProviders, true);
+                $registry->registerResourceTemplate($template, $data['handler'], $completionProviders);
 
                 $handlerDesc = $this->getHandlerDescription($data['handler']);
                 $this->logger->debug("Registered manual template {$name} from handler {$handlerDesc}");
@@ -261,7 +261,7 @@ public function load(RegistryInterface $registry): void
                     meta: $data['meta'] ?? null
                 );
                 $completionProviders = $this->getCompletionProviders($reflection);
-                $registry->registerPrompt($prompt, $data['handler'], $completionProviders, true);
+                $registry->registerPrompt($prompt, $data['handler'], $completionProviders);
 
                 $handlerDesc = $this->getHandlerDescription($data['handler']);
                 $this->logger->debug("Registered manual prompt {$name} from handler {$handlerDesc}");

src/Capability/Registry/Loader/ChainLoader.php

@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Capability\Registry\Loader;
+
+use Mcp\Capability\RegistryInterface;
+
+/**
+ * Composes multiple loaders into a single one. Child loaders run in the order they were given;
+ * for conflicting keys, the loader that runs later wins (last-write-wins).
+ *
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+final class ChainLoader implements LoaderInterface
+{
+    /**
+     * @param LoaderInterface[] $loaders
+     */
+    public function __construct(
+        private readonly array $loaders,
+    ) {
+    }
+
+    public function load(RegistryInterface $registry): void
+    {
+        foreach ($this->loaders as $loader) {
+            $loader->load($registry);
+        }
+    }
+}