Skip to content

Commit 483922c

Browse files
chr-hertelclaude
chr-hertel
and
claude
committed
[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>
1 parent 06917f6 commit 483922c

22 files changed

Lines changed: 785 additions & 328 deletions

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ All notable changes to `mcp/sdk` will be documented in this file.
66
-----
77

88
* Allow overriding the default name pattern for Discovery
9+
* Add `ChainLoader` to compose multiple `LoaderInterface` implementations via explicit ordering.
10+
* Add `RegistryInterface::unregisterTool()`, `unregisterResource()`, `unregisterResourceTemplate()`, `unregisterPrompt()` — idempotent removals.
11+
* `DiscoveryLoader` now refreshes only its own previously written entries; manual registrations (via `Builder::addTool()` etc. or runtime `$registry->registerTool()` calls) survive rediscovery, and a same-name manual registration takes precedence over discovery on collision.
12+
* [BC Break] Removed `ElementReference::$isManual` public property and the `bool $isManual` parameter from all `*Reference` constructors. Origin tracking is no longer carried on the element; manual-over-discovered precedence is encoded by loader execution order.
13+
* [BC Break] `RegistryInterface::registerTool()`, `registerResource()`, `registerResourceTemplate()`, `registerPrompt()` lost their trailing `bool $isManual = false` parameter. Callers using positional arguments must drop the flag.
14+
* [BC Break] Removed `RegistryInterface::clear()`, `getDiscoveryState()`, `setDiscoveryState()`. Rediscovery now goes through `DiscoveryLoader::load()` directly.
15+
* `Registry::register*()` semantics changed to plain last-write-wins (overwrites silently). The previous "discovered registration is ignored when a manual one already exists" debug-logged skip is gone — order your loaders to encode precedence instead.
916

1017
0.5.0
1118
-----

‎src/Capability/Discovery/Discoverer.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
243243
meta: $instance->meta,
244244
outputSchema: $outputSchema,
245245
);
246-
$tools[$name] = new ToolReference($tool, [$className, $methodName], false);
246+
$tools[$name] = new ToolReference($tool, [$className, $methodName]);
247247
++$discoveredCount['tools'];
248248
break;
249249

@@ -261,7 +261,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
261261
$instance->icons,
262262
$instance->meta,
263263
);
264-
$resources[$instance->uri] = new ResourceReference($resource, [$className, $methodName], false);
264+
$resources[$instance->uri] = new ResourceReference($resource, [$className, $methodName]);
265265

266266
++$discoveredCount['resources'];
267267
break;
@@ -282,7 +282,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
282282
}
283283
$prompt = new Prompt($name, $instance->title, $description, $arguments, $instance->icons, $instance->meta);
284284
$completionProviders = $this->getCompletionProviders($method);
285-
$prompts[$name] = new PromptReference($prompt, [$className, $methodName], false, $completionProviders);
285+
$prompts[$name] = new PromptReference($prompt, [$className, $methodName], $completionProviders);
286286
++$discoveredCount['prompts'];
287287
break;
288288

@@ -295,7 +295,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
295295
$meta = $instance->meta ?? null;
296296
$resourceTemplate = new ResourceTemplate($instance->uriTemplate, $name, $description, $mimeType, $annotations, $meta);
297297
$completionProviders = $this->getCompletionProviders($method);
298-
$resourceTemplates[$instance->uriTemplate] = new ResourceTemplateReference($resourceTemplate, [$className, $methodName], false, $completionProviders);
298+
$resourceTemplates[$instance->uriTemplate] = new ResourceTemplateReference($resourceTemplate, [$className, $methodName], $completionProviders);
299299
++$discoveredCount['resourceTemplates'];
300300
break;
301301
}

‎src/Capability/Registry.php‎

Lines changed: 41 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@
1111

1212
namespace Mcp\Capability;
1313

14-
use Mcp\Capability\Discovery\DiscoveryState;
1514
use Mcp\Capability\Registry\PromptReference;
1615
use Mcp\Capability\Registry\ResourceReference;
1716
use Mcp\Capability\Registry\ResourceTemplateReference;
@@ -68,44 +67,22 @@ public function __construct(
6867
) {
6968
}
7069

71-
public function registerTool(Tool $tool, callable|array|string $handler, bool $isManual = false): void
70+
public function registerTool(Tool $tool, callable|array|string $handler): void
7271
{
73-
$toolName = $tool->name;
74-
$existing = $this->tools[$toolName] ?? null;
75-
76-
if ($existing && !$isManual && $existing->isManual) {
77-
$this->logger->debug(
78-
\sprintf('Ignoring discovered tool "%s" as it conflicts with a manually registered one.', $toolName),
79-
);
80-
81-
return;
82-
}
83-
84-
if (!$this->nameValidator->isValid($toolName)) {
72+
if (!$this->nameValidator->isValid($tool->name)) {
8573
$this->logger->warning(
86-
\sprintf('Tool name "%s" is invalid. Tool names should only contain letters (a-z, A-Z), numbers, dots, hyphens, underscores, and forward slashes.', $toolName),
74+
\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),
8775
);
8876
}
8977

90-
$this->tools[$toolName] = new ToolReference($tool, $handler, $isManual);
78+
$this->tools[$tool->name] = new ToolReference($tool, $handler);
9179

9280
$this->eventDispatcher?->dispatch(new ToolListChangedEvent());
9381
}
9482

95-
public function registerResource(Resource $resource, callable|array|string $handler, bool $isManual = false): void
83+
public function registerResource(Resource $resource, callable|array|string $handler): void
9684
{
97-
$uri = $resource->uri;
98-
$existing = $this->resources[$uri] ?? null;
99-
100-
if ($existing && !$isManual && $existing->isManual) {
101-
$this->logger->debug(
102-
\sprintf('Ignoring discovered resource "%s" as it conflicts with a manually registered one.', $uri),
103-
);
104-
105-
return;
106-
}
107-
108-
$this->resources[$uri] = new ResourceReference($resource, $handler, $isManual);
85+
$this->resources[$resource->uri] = new ResourceReference($resource, $handler);
10986

11087
$this->eventDispatcher?->dispatch(new ResourceListChangedEvent());
11188
}
@@ -114,23 +91,10 @@ public function registerResourceTemplate(
11491
ResourceTemplate $template,
11592
callable|array|string $handler,
11693
array $completionProviders = [],
117-
bool $isManual = false,
11894
): void {
119-
$uriTemplate = $template->uriTemplate;
120-
$existing = $this->resourceTemplates[$uriTemplate] ?? null;
121-
122-
if ($existing && !$isManual && $existing->isManual) {
123-
$this->logger->debug(
124-
\sprintf('Ignoring discovered template "%s" as it conflicts with a manually registered one.', $uriTemplate),
125-
);
126-
127-
return;
128-
}
129-
130-
$this->resourceTemplates[$uriTemplate] = new ResourceTemplateReference(
95+
$this->resourceTemplates[$template->uriTemplate] = new ResourceTemplateReference(
13196
$template,
13297
$handler,
133-
$isManual,
13498
$completionProviders,
13599
);
136100

@@ -141,56 +105,54 @@ public function registerPrompt(
141105
Prompt $prompt,
142106
callable|array|string $handler,
143107
array $completionProviders = [],
144-
bool $isManual = false,
145108
): void {
146-
$promptName = $prompt->name;
147-
$existing = $this->prompts[$promptName] ?? null;
109+
$this->prompts[$prompt->name] = new PromptReference($prompt, $handler, $completionProviders);
148110

149-
if ($existing && !$isManual && $existing->isManual) {
150-
$this->logger->debug(
151-
\sprintf('Ignoring discovered prompt "%s" as it conflicts with a manually registered one.', $promptName),
152-
);
111+
$this->eventDispatcher?->dispatch(new PromptListChangedEvent());
112+
}
153113

114+
public function unregisterTool(string $name): void
115+
{
116+
if (!isset($this->tools[$name])) {
154117
return;
155118
}
156119

157-
$this->prompts[$promptName] = new PromptReference($prompt, $handler, $isManual, $completionProviders);
120+
unset($this->tools[$name]);
158121

159-
$this->eventDispatcher?->dispatch(new PromptListChangedEvent());
122+
$this->eventDispatcher?->dispatch(new ToolListChangedEvent());
160123
}
161124

162-
public function clear(): void
125+
public function unregisterResource(string $uri): void
163126
{
164-
$clearCount = 0;
165-
166-
foreach ($this->tools as $name => $tool) {
167-
if (!$tool->isManual) {
168-
unset($this->tools[$name]);
169-
++$clearCount;
170-
}
171-
}
172-
foreach ($this->resources as $uri => $resource) {
173-
if (!$resource->isManual) {
174-
unset($this->resources[$uri]);
175-
++$clearCount;
176-
}
177-
}
178-
foreach ($this->prompts as $name => $prompt) {
179-
if (!$prompt->isManual) {
180-
unset($this->prompts[$name]);
181-
++$clearCount;
182-
}
127+
if (!isset($this->resources[$uri])) {
128+
return;
183129
}
184-
foreach ($this->resourceTemplates as $uriTemplate => $template) {
185-
if (!$template->isManual) {
186-
unset($this->resourceTemplates[$uriTemplate]);
187-
++$clearCount;
188-
}
130+
131+
unset($this->resources[$uri]);
132+
133+
$this->eventDispatcher?->dispatch(new ResourceListChangedEvent());
134+
}
135+
136+
public function unregisterResourceTemplate(string $uriTemplate): void
137+
{
138+
if (!isset($this->resourceTemplates[$uriTemplate])) {
139+
return;
189140
}
190141

191-
if ($clearCount > 0) {
192-
$this->logger->debug(\sprintf('Removed %d discovered elements from internal registry.', $clearCount));
142+
unset($this->resourceTemplates[$uriTemplate]);
143+
144+
$this->eventDispatcher?->dispatch(new ResourceTemplateListChangedEvent());
145+
}
146+
147+
public function unregisterPrompt(string $name): void
148+
{
149+
if (!isset($this->prompts[$name])) {
150+
return;
193151
}
152+
153+
unset($this->prompts[$name]);
154+
155+
$this->eventDispatcher?->dispatch(new PromptListChangedEvent());
194156
}
195157

196158
public function hasTools(): bool
@@ -338,59 +300,6 @@ public function getPrompt(string $name): PromptReference
338300
return $this->prompts[$name] ?? throw new PromptNotFoundException($name);
339301
}
340302

341-
/**
342-
* Get the current discovery state (only discovered elements, not manual ones).
343-
*/
344-
public function getDiscoveryState(): DiscoveryState
345-
{
346-
return new DiscoveryState(
347-
tools: array_filter($this->tools, static fn ($tool) => !$tool->isManual),
348-
resources: array_filter($this->resources, static fn ($resource) => !$resource->isManual),
349-
prompts: array_filter($this->prompts, static fn ($prompt) => !$prompt->isManual),
350-
resourceTemplates: array_filter($this->resourceTemplates, static fn ($template) => !$template->isManual),
351-
);
352-
}
353-
354-
/**
355-
* Set the discovery state, replacing all discovered elements.
356-
* Manual elements are preserved.
357-
*/
358-
public function setDiscoveryState(DiscoveryState $state): void
359-
{
360-
// Clear existing discovered elements
361-
$this->clear();
362-
363-
// Import new discovered elements
364-
foreach ($state->getTools() as $name => $tool) {
365-
$this->tools[$name] = $tool;
366-
}
367-
368-
foreach ($state->getResources() as $uri => $resource) {
369-
$this->resources[$uri] = $resource;
370-
}
371-
372-
foreach ($state->getPrompts() as $name => $prompt) {
373-
$this->prompts[$name] = $prompt;
374-
}
375-
376-
foreach ($state->getResourceTemplates() as $uriTemplate => $template) {
377-
$this->resourceTemplates[$uriTemplate] = $template;
378-
}
379-
380-
// Dispatch events for the imported elements
381-
if ($this->eventDispatcher instanceof EventDispatcherInterface) {
382-
if (!empty($state->getTools())) {
383-
$this->eventDispatcher->dispatch(new ToolListChangedEvent());
384-
}
385-
if (!empty($state->getResources()) || !empty($state->getResourceTemplates())) {
386-
$this->eventDispatcher->dispatch(new ResourceListChangedEvent());
387-
}
388-
if (!empty($state->getPrompts())) {
389-
$this->eventDispatcher->dispatch(new PromptListChangedEvent());
390-
}
391-
}
392-
}
393-
394303
/**
395304
* Calculate next cursor for pagination.
396305
*

‎src/Capability/Registry/ElementReference.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ class ElementReference
2323
*/
2424
public function __construct(
2525
public readonly \Closure|array|string $handler,
26-
public readonly bool $isManual = false,
2726
) {
2827
}
2928
}

‎src/Capability/Registry/Loader/ArrayLoader.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ public function load(RegistryInterface $registry): void
124124
meta: $data['meta'] ?? null,
125125
outputSchema: $data['outputSchema'] ?? null,
126126
);
127-
$registry->registerTool($tool, $data['handler'], true);
127+
$registry->registerTool($tool, $data['handler']);
128128

129129
$handlerDesc = $this->getHandlerDescription($data['handler']);
130130
$this->logger->debug("Registered manual tool {$name} from handler {$handlerDesc}");
@@ -164,7 +164,7 @@ public function load(RegistryInterface $registry): void
164164
icons: $data['icons'] ?? null,
165165
meta: $data['meta'] ?? null,
166166
);
167-
$registry->registerResource($resource, $data['handler'], true);
167+
$registry->registerResource($resource, $data['handler']);
168168

169169
$handlerDesc = $this->getHandlerDescription($data['handler']);
170170
$this->logger->debug("Registered manual resource {$name} from handler {$handlerDesc}");
@@ -203,7 +203,7 @@ public function load(RegistryInterface $registry): void
203203
meta: $data['meta'] ?? null,
204204
);
205205
$completionProviders = $this->getCompletionProviders($reflection);
206-
$registry->registerResourceTemplate($template, $data['handler'], $completionProviders, true);
206+
$registry->registerResourceTemplate($template, $data['handler'], $completionProviders);
207207

208208
$handlerDesc = $this->getHandlerDescription($data['handler']);
209209
$this->logger->debug("Registered manual template {$name} from handler {$handlerDesc}");
@@ -261,7 +261,7 @@ public function load(RegistryInterface $registry): void
261261
meta: $data['meta'] ?? null
262262
);
263263
$completionProviders = $this->getCompletionProviders($reflection);
264-
$registry->registerPrompt($prompt, $data['handler'], $completionProviders, true);
264+
$registry->registerPrompt($prompt, $data['handler'], $completionProviders);
265265

266266
$handlerDesc = $this->getHandlerDescription($data['handler']);
267267
$this->logger->debug("Registered manual prompt {$name} from handler {$handlerDesc}");

‎src/Capability/Registry/Loader/ChainLoader.php‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
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\Loader;
13+
14+
use Mcp\Capability\RegistryInterface;
15+
16+
/**
17+
* Composes multiple loaders into a single one. Child loaders run in the order they were given;
18+
* for conflicting keys, the loader that runs later wins (last-write-wins).
19+
*
20+
* @author Christopher Hertel <mail@christopher-hertel.de>
21+
*/
22+
final class ChainLoader implements LoaderInterface
23+
{
24+
/**
25+
* @param LoaderInterface[] $loaders
26+
*/
27+
public function __construct(
28+
private readonly array $loaders,
29+
) {
30+
}
31+
32+
public function load(RegistryInterface $registry): void
33+
{
34+
foreach ($this->loaders as $loader) {
35+
$loader->load($registry);
36+
}
37+
}
38+
}

0 commit comments

Comments
 (0)