Skip to content

Commit bbfa001

Browse files
committed
[Capability] Split RegistryInterface by role
Refs #495
1 parent 0d340e1 commit bbfa001

16 files changed

Lines changed: 225 additions & 151 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
2626
* Tool, prompt and resource results and `TextContent` encode arrays and objects as compact JSON instead of pretty-printed JSON.
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.
29+
* 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.
2930
* 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`.
3031
* 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.
3132
* Fix a `subscriptions/listen` stream that can carry nothing (the server announces none of the requested types, or the client asks for none) being held open for the full subscription lifetime: it is acknowledged with an empty `notifications` filter and closed gracefully right away, instead of pinning a PHP-FPM worker. Adds `NotificationFilter::isEmpty()`.
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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\Schema\Page;
15+
use Mcp\Schema\Prompt;
16+
use Mcp\Schema\ResourceDefinition;
17+
use Mcp\Schema\ResourceTemplate;
18+
use Mcp\Schema\Tool;
19+
20+
/**
21+
* Lists the elements a server offers.
22+
*
23+
* @author Christopher Hertel <mail@christopher-hertel.de>
24+
*/
25+
interface ElementCatalogInterface
26+
{
27+
/**
28+
* Gets all registered tools.
29+
*
30+
* @return Page<Tool>
31+
*/
32+
public function getTools(?int $limit = null, ?string $cursor = null): Page;
33+
34+
/**
35+
* Gets all registered resources.
36+
*
37+
* @return Page<ResourceDefinition>
38+
*/
39+
public function getResources(?int $limit = null, ?string $cursor = null): Page;
40+
41+
/**
42+
* Gets all registered resource templates.
43+
*
44+
* @return Page<ResourceTemplate>
45+
*/
46+
public function getResourceTemplates(?int $limit = null, ?string $cursor = null): Page;
47+
48+
/**
49+
* Gets all registered prompts.
50+
*
51+
* @return Page<Prompt>
52+
*/
53+
public function getPrompts(?int $limit = null, ?string $cursor = null): Page;
54+
}
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
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\PromptReference;
15+
use Mcp\Capability\Registry\ResourceReference;
16+
use Mcp\Capability\Registry\ResourceTemplateReference;
17+
use Mcp\Capability\Registry\ToolReference;
18+
use Mcp\Exception\PromptNotFoundException;
19+
use Mcp\Exception\ResourceNotFoundException;
20+
use Mcp\Exception\ToolNotFoundException;
21+
22+
/**
23+
* Finds a single element by its name or URI, without needing the whole catalog.
24+
*
25+
* @author Christopher Hertel <mail@christopher-hertel.de>
26+
*/
27+
interface ElementResolverInterface
28+
{
29+
/**
30+
* Gets a tool reference by name.
31+
*
32+
* @throws ToolNotFoundException
33+
*/
34+
public function getTool(string $name): ToolReference;
35+
36+
/**
37+
* Gets a resource reference by URI (includes template matching if enabled).
38+
*
39+
* @throws ResourceNotFoundException
40+
*/
41+
public function getResource(string $uri, bool $includeTemplates = true): ResourceReference|ResourceTemplateReference;
42+
43+
/**
44+
* Gets a prompt reference by name.
45+
*
46+
* @throws PromptNotFoundException
47+
*/
48+
public function getPrompt(string $name): PromptReference;
49+
}
Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
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\ElementReference;
15+
use Mcp\Capability\Registry\PromptReference;
16+
use Mcp\Capability\Registry\ResourceReference;
17+
use Mcp\Capability\Registry\ResourceTemplateReference;
18+
use Mcp\Capability\Registry\ToolReference;
19+
use Mcp\Schema\Prompt;
20+
use Mcp\Schema\ResourceDefinition;
21+
use Mcp\Schema\ResourceTemplate;
22+
use Mcp\Schema\Tool;
23+
24+
/**
25+
* Adds and removes elements.
26+
*
27+
* @phpstan-import-type Handler from ElementReference
28+
*
29+
* @author Christopher Hertel <mail@christopher-hertel.de>
30+
*/
31+
interface ElementWriterInterface
32+
{
33+
/**
34+
* Registers a tool with its handler. Overwrites any prior registration of the same name.
35+
* Returns the stored reference, whose identity callers may track to detect later overwrites.
36+
*
37+
* @param Handler $handler
38+
*/
39+
public function registerTool(Tool $tool, callable|array|string $handler): ToolReference;
40+
41+
/**
42+
* Registers a resource with its handler. Overwrites any prior registration of the same URI.
43+
* Returns the stored reference, whose identity callers may track to detect later overwrites.
44+
*
45+
* @param Handler $handler
46+
*/
47+
public function registerResource(ResourceDefinition $resource, callable|array|string $handler): ResourceReference;
48+
49+
/**
50+
* Registers a resource template with its handler and completion providers.
51+
* Overwrites any prior registration of the same URI template.
52+
* Returns the stored reference, whose identity callers may track to detect later overwrites.
53+
*
54+
* @param Handler $handler
55+
* @param array<string, class-string|object> $completionProviders
56+
*/
57+
public function registerResourceTemplate(
58+
ResourceTemplate $template,
59+
callable|array|string $handler,
60+
array $completionProviders = [],
61+
): ResourceTemplateReference;
62+
63+
/**
64+
* Registers a prompt with its handler and completion providers.
65+
* Overwrites any prior registration of the same name.
66+
* Returns the stored reference, whose identity callers may track to detect later overwrites.
67+
*
68+
* @param Handler $handler
69+
* @param array<string, class-string|object> $completionProviders
70+
*/
71+
public function registerPrompt(
72+
Prompt $prompt,
73+
callable|array|string $handler,
74+
array $completionProviders = [],
75+
): PromptReference;
76+
77+
/**
78+
* Removes a tool by name. No-op if absent.
79+
*/
80+
public function unregisterTool(string $name): void;
81+
82+
/**
83+
* Removes a resource by URI. No-op if absent.
84+
*/
85+
public function unregisterResource(string $uri): void;
86+
87+
/**
88+
* Removes a resource template by URI template. No-op if absent.
89+
*/
90+
public function unregisterResourceTemplate(string $uriTemplate): void;
91+
92+
/**
93+
* Removes a prompt by name. No-op if absent.
94+
*/
95+
public function unregisterPrompt(string $name): void;
96+
}

‎src/Capability/RegistryInterface.php‎

Lines changed: 3 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -11,93 +11,16 @@
1111

1212
namespace Mcp\Capability;
1313

14-
use Mcp\Capability\Registry\ElementReference;
15-
use Mcp\Capability\Registry\PromptReference;
16-
use Mcp\Capability\Registry\ResourceReference;
1714
use Mcp\Capability\Registry\ResourceTemplateReference;
18-
use Mcp\Capability\Registry\ToolReference;
19-
use Mcp\Exception\PromptNotFoundException;
2015
use Mcp\Exception\ResourceNotFoundException;
21-
use Mcp\Exception\ToolNotFoundException;
22-
use Mcp\Schema\Page;
23-
use Mcp\Schema\Prompt;
24-
use Mcp\Schema\ResourceDefinition;
25-
use Mcp\Schema\ResourceTemplate;
26-
use Mcp\Schema\Tool;
2716
use Mcp\Server\Subscription\PublishingEventDispatcher;
2817

2918
/**
30-
* @phpstan-import-type Handler from ElementReference
31-
*
3219
* @author Kyrian Obikwelu <koshnawaza@gmail.com>
3320
* @author Christopher Hertel <mail@christopher-hertel.de>
3421
*/
35-
interface RegistryInterface
22+
interface RegistryInterface extends ElementCatalogInterface, ElementResolverInterface, ElementWriterInterface
3623
{
37-
/**
38-
* Registers a tool with its handler. Overwrites any prior registration of the same name.
39-
* Returns the stored reference, whose identity callers may track to detect later overwrites.
40-
*
41-
* @param Handler $handler
42-
*/
43-
public function registerTool(Tool $tool, callable|array|string $handler): ToolReference;
44-
45-
/**
46-
* Registers a resource with its handler. Overwrites any prior registration of the same URI.
47-
* Returns the stored reference, whose identity callers may track to detect later overwrites.
48-
*
49-
* @param Handler $handler
50-
*/
51-
public function registerResource(ResourceDefinition $resource, callable|array|string $handler): ResourceReference;
52-
53-
/**
54-
* Registers a resource template with its handler and completion providers.
55-
* Overwrites any prior registration of the same URI template.
56-
* Returns the stored reference, whose identity callers may track to detect later overwrites.
57-
*
58-
* @param Handler $handler
59-
* @param array<string, class-string|object> $completionProviders
60-
*/
61-
public function registerResourceTemplate(
62-
ResourceTemplate $template,
63-
callable|array|string $handler,
64-
array $completionProviders = [],
65-
): ResourceTemplateReference;
66-
67-
/**
68-
* Registers a prompt with its handler and completion providers.
69-
* Overwrites any prior registration of the same name.
70-
* Returns the stored reference, whose identity callers may track to detect later overwrites.
71-
*
72-
* @param Handler $handler
73-
* @param array<string, class-string|object> $completionProviders
74-
*/
75-
public function registerPrompt(
76-
Prompt $prompt,
77-
callable|array|string $handler,
78-
array $completionProviders = [],
79-
): PromptReference;
80-
81-
/**
82-
* Removes a tool by name. No-op if absent.
83-
*/
84-
public function unregisterTool(string $name): void;
85-
86-
/**
87-
* Removes a resource by URI. No-op if absent.
88-
*/
89-
public function unregisterResource(string $uri): void;
90-
91-
/**
92-
* Removes a resource template by URI template. No-op if absent.
93-
*/
94-
public function unregisterResourceTemplate(string $uriTemplate): void;
95-
96-
/**
97-
* Removes a prompt by name. No-op if absent.
98-
*/
99-
public function unregisterPrompt(string $name): void;
100-
10124
/**
10225
* Whether list changes reach a notification bus, e.g. through a {@see PublishingEventDispatcher}.
10326
* A decorator forwards the answer of the registry it wraps.
@@ -117,74 +40,25 @@ public function hasPrompt(string $name): bool;
11740
*/
11841
public function hasTools(): bool;
11942

120-
/**
121-
* Gets all registered tools.
122-
*
123-
* @return Page<Tool>
124-
*/
125-
public function getTools(?int $limit = null, ?string $cursor = null): Page;
126-
127-
/**
128-
* Gets a tool reference by name.
129-
*
130-
* @throws ToolNotFoundException
131-
*/
132-
public function getTool(string $name): ToolReference;
133-
13443
/**
13544
* @return bool true if any resources are registered
13645
*/
13746
public function hasResources(): bool;
13847

139-
/**
140-
* Gets all registered resources.
141-
*
142-
* @return Page<ResourceDefinition>
143-
*/
144-
public function getResources(?int $limit = null, ?string $cursor = null): Page;
145-
146-
/**
147-
* Gets a resource reference by URI (includes template matching if enabled).
148-
*
149-
* @throws ResourceNotFoundException
150-
*/
151-
public function getResource(string $uri, bool $includeTemplates = true): ResourceReference|ResourceTemplateReference;
152-
15348
/**
15449
* @return bool true if any resource templates are registered
15550
*/
15651
public function hasResourceTemplates(): bool;
15752

15853
/**
159-
* Gets all registered resource templates.
160-
*
161-
* @return Page<ResourceTemplate>
54+
* @return bool true if any prompts are registered
16255
*/
163-
public function getResourceTemplates(?int $limit = null, ?string $cursor = null): Page;
56+
public function hasPrompts(): bool;
16457

16558
/**
16659
* Gets a resource template reference by URI template.
16760
*
16861
* @throws ResourceNotFoundException
16962
*/
17063
public function getResourceTemplate(string $uriTemplate): ResourceTemplateReference;
171-
172-
/**
173-
* @return bool true if any prompts are registered
174-
*/
175-
public function hasPrompts(): bool;
176-
177-
/**
178-
* Gets all registered prompts.
179-
*
180-
* @return Page<Prompt>
181-
*/
182-
public function getPrompts(?int $limit = null, ?string $cursor = null): Page;
183-
184-
/**
185-
* Gets a prompt reference by name.
186-
*
187-
* @throws PromptNotFoundException
188-
*/
189-
public function getPrompt(string $name): PromptReference;
19064
}

0 commit comments

Comments
 (0)