Skip to content

Commit f9cf392

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

8 files changed

Lines changed: 472 additions & 18 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ 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+
* Add `DeferredRegistryInterface`, so the builder loads a custom registry without announcing the load as list changes, and no longer depends on the concrete `Registry`.
3032
* 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.
3133
* 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`.
3234
* 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 (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: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
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+
34+
public function __construct(
35+
private readonly RegistryInterface $registry,
36+
private readonly LoaderInterface $loader,
37+
) {
38+
}
39+
40+
public function load(): void
41+
{
42+
if ($this->loaded) {
43+
return;
44+
}
45+
46+
$this->loadFrom($this->loader);
47+
48+
$this->loaded = true;
49+
}
50+
51+
public function isLoaded(): bool
52+
{
53+
return $this->loaded;
54+
}
55+
56+
public function loadFrom(LoaderInterface $loader): void
57+
{
58+
if ($this->registry instanceof DeferredRegistryInterface) {
59+
$this->registry->loadFrom($loader);
60+
61+
return;
62+
}
63+
64+
$loader->load($this->registry);
65+
}
66+
67+
public function publishesListChanges(): bool
68+
{
69+
return $this->registry->publishesListChanges();
70+
}
71+
72+
public function registerTool(Tool $tool, callable|array|string $handler): ToolReference
73+
{
74+
return $this->registry->registerTool($tool, $handler);
75+
}
76+
77+
public function registerResource(ResourceDefinition $resource, callable|array|string $handler): ResourceReference
78+
{
79+
return $this->registry->registerResource($resource, $handler);
80+
}
81+
82+
public function registerResourceTemplate(ResourceTemplate $template, callable|array|string $handler, array $completionProviders = []): ResourceTemplateReference
83+
{
84+
return $this->registry->registerResourceTemplate($template, $handler, $completionProviders);
85+
}
86+
87+
public function registerPrompt(Prompt $prompt, callable|array|string $handler, array $completionProviders = []): PromptReference
88+
{
89+
return $this->registry->registerPrompt($prompt, $handler, $completionProviders);
90+
}
91+
92+
public function unregisterTool(string $name): void
93+
{
94+
$this->registry->unregisterTool($name);
95+
}
96+
97+
public function unregisterResource(string $uri): void
98+
{
99+
$this->registry->unregisterResource($uri);
100+
}
101+
102+
public function unregisterResourceTemplate(string $uriTemplate): void
103+
{
104+
$this->registry->unregisterResourceTemplate($uriTemplate);
105+
}
106+
107+
public function unregisterPrompt(string $name): void
108+
{
109+
$this->registry->unregisterPrompt($name);
110+
}
111+
112+
public function hasTool(string $name): bool
113+
{
114+
$this->load();
115+
116+
return $this->registry->hasTool($name);
117+
}
118+
119+
public function hasResource(string $uri): bool
120+
{
121+
$this->load();
122+
123+
return $this->registry->hasResource($uri);
124+
}
125+
126+
public function hasResourceTemplate(string $uriTemplate): bool
127+
{
128+
$this->load();
129+
130+
return $this->registry->hasResourceTemplate($uriTemplate);
131+
}
132+
133+
public function hasPrompt(string $name): bool
134+
{
135+
$this->load();
136+
137+
return $this->registry->hasPrompt($name);
138+
}
139+
140+
public function hasTools(): bool
141+
{
142+
$this->load();
143+
144+
return $this->registry->hasTools();
145+
}
146+
147+
public function hasResources(): bool
148+
{
149+
$this->load();
150+
151+
return $this->registry->hasResources();
152+
}
153+
154+
public function hasResourceTemplates(): bool
155+
{
156+
$this->load();
157+
158+
return $this->registry->hasResourceTemplates();
159+
}
160+
161+
public function hasPrompts(): bool
162+
{
163+
$this->load();
164+
165+
return $this->registry->hasPrompts();
166+
}
167+
168+
public function getTools(?int $limit = null, ?string $cursor = null): Page
169+
{
170+
$this->load();
171+
172+
return $this->registry->getTools($limit, $cursor);
173+
}
174+
175+
public function getResources(?int $limit = null, ?string $cursor = null): Page
176+
{
177+
$this->load();
178+
179+
return $this->registry->getResources($limit, $cursor);
180+
}
181+
182+
public function getResourceTemplates(?int $limit = null, ?string $cursor = null): Page
183+
{
184+
$this->load();
185+
186+
return $this->registry->getResourceTemplates($limit, $cursor);
187+
}
188+
189+
public function getPrompts(?int $limit = null, ?string $cursor = null): Page
190+
{
191+
$this->load();
192+
193+
return $this->registry->getPrompts($limit, $cursor);
194+
}
195+
196+
public function getTool(string $name): ToolReference
197+
{
198+
$this->load();
199+
200+
return $this->registry->getTool($name);
201+
}
202+
203+
public function getResource(string $uri, bool $includeTemplates = true): ResourceReference|ResourceTemplateReference
204+
{
205+
$this->load();
206+
207+
return $this->registry->getResource($uri, $includeTemplates);
208+
}
209+
210+
public function getResourceTemplate(string $uriTemplate): ResourceTemplateReference
211+
{
212+
$this->load();
213+
214+
return $this->registry->getResourceTemplate($uriTemplate);
215+
}
216+
217+
public function getPrompt(string $name): PromptReference
218+
{
219+
$this->load();
220+
221+
return $this->registry->getPrompt($name);
222+
}
223+
}

0 commit comments

Comments
 (0)