Skip to content

Commit a567732

Browse files
chr-hertelchr-hertel
committed
[Server][Capability] Let setLazyLoading() defer loading into any supplied registry
Refs #495
1 parent 66ca225 commit a567732

15 files changed

Lines changed: 686 additions & 79 deletions

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ All notable changes to `mcp/sdk` will be documented in this file.
2727
* Fix the result of a retried `resources/read` leaving out the required `ttlMs` and `cacheScope`, which the TypeScript SDK's client rejects, or keeping the hints its handler set: it now always carries `ttlMs: 0` and `cacheScope: private`.
2828
* Fix tool name validation not following the spec's rule (1 to 128 characters of `A-Z`, `a-z`, `0-9`, `_`, `-` and `.`): names of 65 to 128 characters no longer log a warning, while names with a `/` or a trailing newline now do.
2929
* [BC Break] `ReferenceHandler` resolves a string handler that is not an invokable class from the container, so a loader can register a service id as handler. The container goes first, so a function handler no longer runs if the container has an entry of the same name.
30+
* [BC Break] `Builder::setLazyLoading(true)` now also defers loading into a registry passed to `setRegistry()`, which any `RegistryInterface` supports. A registry you read directly stays empty until the server first reads it; without the call it is still loaded at build.
31+
* [BC Break] Detect the server capabilities when a request asks for them, so `initialize`, `server/discover` and `subscriptions/listen` run a pending load. The server advertises what the registry holds, and no longer every kind for a custom loader or discovery that was not loaded yet. While a load is still running, it advertises all kinds. `Configuration::$capabilities` is replaced by `Configuration::capabilities()`, and the constructor also takes a closure.
32+
* Add `DeferredRegistryInterface`, so the builder loads a custom registry without announcing the load as list changes, and no longer depends on the concrete `Registry`.
3033
* Split `RegistryInterface` by role into `ElementCatalogInterface`, `ElementResolverInterface` and `ElementWriterInterface`, which it extends. Request handlers depend on the role they use, so a handler can run against a catalog or resolver alone.
3134
* Add `Psr6SessionStore` and `Psr6NotificationBus`, which work like `Psr16SessionStore` and `Psr16NotificationBus` over a PSR-6 cache pool. `Builder::setDiscovery()` also accepts a PSR-6 pool as `$cache`.
3235
* Fix a nullable tool parameter with a default (e.g. `?string $category = 'books'`) receiving the default when the client explicitly sends `null`: `ReferenceHandler` now passes the `null` through.

‎docs/run/server-builder.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -487,8 +487,8 @@ $server = Server::builder()
487487
| `setSchemaGenerator()` | schemaGenerator | Replace the generator that builds input schemas from PHP types, see [Schema generation](../servers/schemas.md) |
488488
| `setSchemaValidator()` | schemaValidator | Replace the validator for tool arguments and structured output, see [Schema generation](../servers/schemas.md) |
489489
| `setReferenceHandler()` | referenceHandler | Replace the class that calls the handlers of tools, resources and prompts |
490-
| `setRegistry()` | registry | Use your own registry. It is loaded when the server is built |
491-
| `setLazyLoading()` | lazyLoading? | Load elements on the first registry read (default) or, with `false`, when the server is built |
490+
| `setRegistry()` | registry | Use your own registry. It is loaded when the server is built, unless you call `setLazyLoading()` |
491+
| `setLazyLoading()` | lazyLoading? | Load elements on the first registry read, which is at the latest when a client asks for the capabilities (default without `setRegistry()`), or, with `false`, when the server is built. Your own registry stays empty until the server first reads it |
492492
| `addLoader()` | loader | Add a custom loader that registers elements |
493493
| `addLoaders()` | loaders | Add several custom loaders |
494494
| `addRequestHandler()` | handler | Prepend a single custom request handler |

‎src/Capability/DeferredRegistryInterface.php‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the official PHP MCP SDK.
5+
*
6+
* A collaboration between Symfony and the PHP Foundation.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Mcp\Capability;
13+
14+
use Mcp\Capability\Registry\Loader\LoaderInterface;
15+
16+
/**
17+
* A registry that takes part in its own load lifecycle.
18+
*
19+
* @author Christopher Hertel <mail@christopher-hertel.de>
20+
*/
21+
interface DeferredRegistryInterface
22+
{
23+
/**
24+
* Runs a pending load, if there is one. A failed load stays pending.
25+
*/
26+
public function load(): void;
27+
28+
public function isLoaded(): bool;
29+
30+
/**
31+
* Runs $loader against this registry without announcing its writes as list changes, since they
32+
* describe the registry filling up rather than changing.
33+
*/
34+
public function loadFrom(LoaderInterface $loader): void;
35+
}

‎src/Capability/Registry.php‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
*
4141
* @author Kyrian Obikwelu <koshnawaza@gmail.com>
4242
*/
43-
final class Registry implements RegistryInterface
43+
final class Registry implements RegistryInterface, DeferredRegistryInterface
4444
{
4545
/**
4646
* @var array<string, ToolReference>
@@ -94,6 +94,11 @@ public function load(): void
9494
$this->loaded = true;
9595
}
9696

97+
public function isLoaded(): bool
98+
{
99+
return $this->loaded || null === $this->loader;
100+
}
101+
97102
/**
98103
* Runs $loader with the change events its registrations would dispatch suppressed, since they
99104
* describe the registry filling up rather than changing.

‎src/Capability/Registry/LazyRegistry.php‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the official PHP MCP SDK.
5+
*
6+
* A collaboration between Symfony and the PHP Foundation.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Mcp\Capability\Registry;
13+
14+
use Mcp\Capability\DeferredRegistryInterface;
15+
use Mcp\Capability\Registry\Loader\LoaderInterface;
16+
use Mcp\Capability\RegistryInterface;
17+
use Mcp\Schema\Page;
18+
use Mcp\Schema\Prompt;
19+
use Mcp\Schema\ResourceDefinition;
20+
use Mcp\Schema\ResourceTemplate;
21+
use Mcp\Schema\Tool;
22+
23+
/**
24+
* Defers a loader over any registry to the first read, leaving the registry itself unaware of it.
25+
*
26+
* @internal
27+
*
28+
* @author Christopher Hertel <mail@christopher-hertel.de>
29+
*/
30+
final class LazyRegistry implements RegistryInterface, DeferredRegistryInterface
31+
{
32+
private bool $loaded = false;
33+
private bool $loading = false;
34+
35+
public function __construct(
36+
private readonly RegistryInterface $registry,
37+
private readonly LoaderInterface $loader,
38+
) {
39+
}
40+
41+
public function load(): void
42+
{
43+
if ($this->loaded || $this->loading) {
44+
return;
45+
}
46+
47+
$this->loading = true;
48+
try {
49+
$this->loadFrom($this->loader);
50+
$this->loaded = true;
51+
} finally {
52+
$this->loading = false;
53+
}
54+
}
55+
56+
public function isLoaded(): bool
57+
{
58+
return $this->loaded;
59+
}
60+
61+
public function loadFrom(LoaderInterface $loader): void
62+
{
63+
if ($this->registry instanceof DeferredRegistryInterface) {
64+
$this->registry->loadFrom($loader);
65+
66+
return;
67+
}
68+
69+
$loader->load($this->registry);
70+
}
71+
72+
public function publishesListChanges(): bool
73+
{
74+
return $this->registry->publishesListChanges();
75+
}
76+
77+
public function registerTool(Tool $tool, callable|array|string $handler): ToolReference
78+
{
79+
return $this->registry->registerTool($tool, $handler);
80+
}
81+
82+
public function registerResource(ResourceDefinition $resource, callable|array|string $handler): ResourceReference
83+
{
84+
return $this->registry->registerResource($resource, $handler);
85+
}
86+
87+
public function registerResourceTemplate(ResourceTemplate $template, callable|array|string $handler, array $completionProviders = []): ResourceTemplateReference
88+
{
89+
return $this->registry->registerResourceTemplate($template, $handler, $completionProviders);
90+
}
91+
92+
public function registerPrompt(Prompt $prompt, callable|array|string $handler, array $completionProviders = []): PromptReference
93+
{
94+
return $this->registry->registerPrompt($prompt, $handler, $completionProviders);
95+
}
96+
97+
public function unregisterTool(string $name): void
98+
{
99+
$this->registry->unregisterTool($name);
100+
}
101+
102+
public function unregisterResource(string $uri): void
103+
{
104+
$this->registry->unregisterResource($uri);
105+
}
106+
107+
public function unregisterResourceTemplate(string $uriTemplate): void
108+
{
109+
$this->registry->unregisterResourceTemplate($uriTemplate);
110+
}
111+
112+
public function unregisterPrompt(string $name): void
113+
{
114+
$this->registry->unregisterPrompt($name);
115+
}
116+
117+
public function hasTool(string $name): bool
118+
{
119+
$this->load();
120+
121+
return $this->registry->hasTool($name);
122+
}
123+
124+
public function hasResource(string $uri): bool
125+
{
126+
$this->load();
127+
128+
return $this->registry->hasResource($uri);
129+
}
130+
131+
public function hasResourceTemplate(string $uriTemplate): bool
132+
{
133+
$this->load();
134+
135+
return $this->registry->hasResourceTemplate($uriTemplate);
136+
}
137+
138+
public function hasPrompt(string $name): bool
139+
{
140+
$this->load();
141+
142+
return $this->registry->hasPrompt($name);
143+
}
144+
145+
public function hasTools(): bool
146+
{
147+
$this->load();
148+
149+
return $this->registry->hasTools();
150+
}
151+
152+
public function hasResources(): bool
153+
{
154+
$this->load();
155+
156+
return $this->registry->hasResources();
157+
}
158+
159+
public function hasResourceTemplates(): bool
160+
{
161+
$this->load();
162+
163+
return $this->registry->hasResourceTemplates();
164+
}
165+
166+
public function hasPrompts(): bool
167+
{
168+
$this->load();
169+
170+
return $this->registry->hasPrompts();
171+
}
172+
173+
public function getTools(?int $limit = null, ?string $cursor = null): Page
174+
{
175+
$this->load();
176+
177+
return $this->registry->getTools($limit, $cursor);
178+
}
179+
180+
public function getResources(?int $limit = null, ?string $cursor = null): Page
181+
{
182+
$this->load();
183+
184+
return $this->registry->getResources($limit, $cursor);
185+
}
186+
187+
public function getResourceTemplates(?int $limit = null, ?string $cursor = null): Page
188+
{
189+
$this->load();
190+
191+
return $this->registry->getResourceTemplates($limit, $cursor);
192+
}
193+
194+
public function getPrompts(?int $limit = null, ?string $cursor = null): Page
195+
{
196+
$this->load();
197+
198+
return $this->registry->getPrompts($limit, $cursor);
199+
}
200+
201+
public function getTool(string $name): ToolReference
202+
{
203+
$this->load();
204+
205+
return $this->registry->getTool($name);
206+
}
207+
208+
public function getResource(string $uri, bool $includeTemplates = true): ResourceReference|ResourceTemplateReference
209+
{
210+
$this->load();
211+
212+
return $this->registry->getResource($uri, $includeTemplates);
213+
}
214+
215+
public function getResourceTemplate(string $uriTemplate): ResourceTemplateReference
216+
{
217+
$this->load();
218+
219+
return $this->registry->getResourceTemplate($uriTemplate);
220+
}
221+
222+
public function getPrompt(string $name): PromptReference
223+
{
224+
$this->load();
225+
226+
return $this->registry->getPrompt($name);
227+
}
228+
}

0 commit comments

Comments
 (0)