[Capability] Do not announce an externally loaded registry as changed

`Registry` suppresses its `*ListChangedEvent`s while it is loading — `dispatch()`
returns early on the `loading` guard, so the elements a loader registers are the
registry's initial contents rather than a change to them.
`testListChangedEventsAreSuppressedDuringTheDeferredLoad` pins that.

The guard only covers `Registry::load()`, which needs the loader the constructor
took. A registry the caller built cannot be given one that way, so
`Builder::resolve()` loads it from the outside instead — by calling
`$chainLoader->load($registry)` directly, which never sets the guard. Every
element then dispatches on the way in.

With a notification bus configured that is not quiet. `PublishingEventDispatcher`
turns each event into a published notification, so every `build()` puts one
`list_changed` per element on the bus for a registry that did not change. Under
PHP-FPM, where the server is built per request and `Psr16NotificationBus` is
shared and persistent, every request broadcasts its whole element list to every
open `subscriptions/listen` stream and consumes the 256-entry backlog — after
which a reader that fell behind silently skips real notifications.

Split the guarded body of `load()` into `loadFrom(LoaderInterface $loader)` and
route the custom-registry branch through it. `RegistryInterface` declares no
`load()`, so this stays on the concrete `Registry`, and a third-party
implementation keeps the path it has today.

Author: chr-hertel

src/Capability/Registry.php

@@ -84,13 +84,31 @@ public function __construct(
      */
     public function load(): void
     {
-        if ($this->loaded || $this->loading || null === $this->loader) {
+        if (null === $this->loader) {
+            return;
+        }
+
+        $this->loadFrom($this->loader);
+    }
+
+    /**
+     * Runs a loader supplied from outside, under the same guard {@see load()} uses.
+     *
+     * A registry the caller constructed cannot be given a loader through the constructor, so
+     * {@see \Mcp\Server\Builder} loads it from the outside instead. Doing that by calling the
+     * loader directly skips the guard, and then every element registered during the load is
+     * announced as a change — which on a configured notification bus is a burst of `list_changed`
+     * notifications on every build, for a registry that did not change.
+     */
+    public function loadFrom(LoaderInterface $loader): void
+    {
+        if ($this->loaded || $this->loading) {
             return;
         }
 
         $this->loading = true;
         try {
-            $this->loader->load($this);
+            $loader->load($this);
             $this->loaded = true;
         } finally {
             $this->loading = false;

src/Server/Builder.php

@@ -1045,8 +1045,10 @@ private function resolve(): array
 
         if ($this->hasCustomRegistry) {
             // Builder can't inject the loader into an already-constructed instance, so load it eagerly.
+            // Through loadFrom() where possible: loading a registry from the outside otherwise skips the
+            // guard that keeps the load itself from being announced as a change.
             $registry = $this->registry;
-            $chainLoader->load($registry);
+            $registry instanceof Registry ? $registry->loadFrom($chainLoader) : $chainLoader->load($registry);
             $eagerlyLoaded = true;
         } else {
             $registry = new Registry($eventDispatcher, $logger, loader: $chainLoader);

tests/Unit/Capability/RegistryTest.php

@@ -753,6 +753,34 @@ public function load(RegistryInterface $registry): void
         $this->assertTrue($registry->hasPrompts());
     }
 
+    public function testListChangedEventsAreSuppressedWhenTheLoaderIsSuppliedFromOutside(): void
+    {
+        // A registry the caller constructed cannot take a loader through the constructor, so
+        // Builder loads it from the outside. That has to be as quiet as the deferred load above:
+        // the elements arriving are the registry's initial contents, not a change to them.
+        $eventDispatcher = $this->createMock(EventDispatcherInterface::class);
+        $eventDispatcher->expects($this->never())->method('dispatch');
+
+        $registry = new Registry($eventDispatcher, $this->logger);
+        $registry->loadFrom($this->toolLoader($this->createValidTool('loaded')));
+
+        $this->assertTrue($registry->hasTool('loaded'));
+    }
+
+    public function testARuntimeRegistrationAfterAnExternalLoadIsStillDispatched(): void
+    {
+        $eventDispatcher = $this->createMock(EventDispatcherInterface::class);
+        $eventDispatcher->expects($this->once())
+            ->method('dispatch')
+            ->with($this->isInstanceOf(ToolListChangedEvent::class))
+            ->willReturnArgument(0);
+
+        $registry = new Registry($eventDispatcher, $this->logger);
+        $registry->loadFrom($this->toolLoader($this->createValidTool('loaded')));
+
+        $registry->registerTool($this->createValidTool('runtime'), 'handler');
+    }
+
     public function testListChangedEventsAreStillDispatchedForRuntimeRegistrations(): void
     {
         $eventDispatcher = $this->createMock(EventDispatcherInterface::class);

tests/Unit/Server/BuilderTest.php

@@ -32,6 +32,8 @@
 use Mcp\Server\Protocol;
 use Mcp\Server\Session\SessionInterface;
 use Mcp\Server\Stateless\StatelessProtocol;
+use Mcp\Server\Subscription\InMemoryNotificationBus;
+use Mcp\Server\Subscription\PublishingEventDispatcher;
 use Mcp\Tests\Unit\Server\Extension\ThingExtension;
 use Mcp\Tests\Unit\Server\Extension\ThingListHandler;
 use Mcp\Tests\Unit\Server\Extension\ThingListRequest;
@@ -404,6 +406,31 @@ private function callTool(Server $server, string $toolName): mixed
 
         $this->fail('CallToolHandler not found in request handlers');
     }
+
+    public function testBuildingWithASuppliedRegistryDoesNotAnnounceTheLoadAsAChange(): void
+    {
+        // The registry a caller supplies carries its own dispatcher, which the Builder has no
+        // handle on — so the load has to be quiet at the registry, or every build publishes one
+        // list_changed per element. On a shared bus that is a burst per process, for no change.
+        $bus = new InMemoryNotificationBus();
+        $registry = new Registry(new PublishingEventDispatcher($bus));
+
+        Server::builder()
+            ->setRegistry($registry)
+            ->setNotificationBus($bus)
+            ->addTool(static fn (): string => 'ok', 'alpha')
+            ->addTool(static fn (): string => 'ok', 'beta')
+            ->build();
+
+        $this->assertSame(0, $bus->cursor());
+        $this->assertTrue($registry->hasTool('alpha'));
+        $this->assertTrue($registry->hasTool('beta'));
+
+        // What the bus is for still works: a change after the build is published.
+        $registry->unregisterTool('alpha');
+
+        $this->assertSame(1, $bus->cursor());
+    }
 }
 
 /**