[Server] Allow runtime-resolved element handlers by e0ipso · Pull Request #294 · modelcontextprotocol/php-sdk

e0ipso · 2026-04-29T07:37:16Z

Summary

Adds Builder::add(Tool|ResourceDefinition|ResourceTemplate|Prompt $definition, ElementHandlerInterface $handler) for cases where an element's name, schema, or description is only known at runtime. The existing addTool/addResource/addResourceTemplate/addPrompt methods, which derive metadata from reflection, keep working unchanged.

Four handler interfaces back the new entry point:

ToolHandlerInterface::execute(array $arguments, ClientGateway $gateway)
ResourceHandlerInterface::read(string $uri, ClientGateway $gateway)
ResourceTemplateHandlerInterface::read(string $uri, array $variables, ClientGateway $gateway)
PromptHandlerInterface::get(array $arguments, ClientGateway $gateway)

All four extend an empty ElementHandlerInterface marker so Builder::add() can accept any of them through one signature. Mismatched pairings (for example a Tool with a PromptHandlerInterface) raise Mcp\Exception\InvalidArgumentException at registration.

A new ExplicitElementLoader translates these pairs into Registry entries. It is wired in Builder::build() alongside ReflectedElementLoader (renamed from ArrayLoader), so the reflection-based loader is unchanged. ReferenceHandler::handle() builds a ClientGateway from the active session and injects it into handlers that declare a ClientGateway parameter.

Motivation and Context

Reflection-based discovery does not fit config-driven integrations where parameter names, schemas, and arguments are not known at the time the code is written. Two concrete blockers:

ReferenceHandler::prepareArguments() binds incoming arguments to handler parameters by name via reflection, so the handler signature has to mirror the input schema field names.
HandlerResolver::resolve() only accepts [ClassName::class, 'method'] strings, which rules out DI-constructed handler instances with constructor arguments.

The new entry point gives those integrations a typed registration path without changing the existing one. Standalone usage with attributes or callables is unaffected.

How Has This Been Tested?

ExplicitElementLoaderTest covers tool, resource, resource template, and prompt registration through Builder::add(), plus type-mismatch failures.
ReferenceHandlerTest covers the explicit-handler dispatch branch in ReferenceHandler::handle() for all four element kinds.
Existing tests still pass.

Breaking Changes

Renamed Mcp\Schema\Resource to Mcp\Schema\ResourceDefinition. No alias.
Renamed Mcp\Capability\Registry\Loader\ArrayLoader to Mcp\Capability\Registry\Loader\ReflectedElementLoader.

Existing closure/array/string handler forms keep working through ReflectedElementLoader.

Types of changes

Bug fix
New feature (non-breaking)
Breaking change
Documentation update

Checklist

My code follows the repository style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

mglaman

I wonder if we can simplify the array loader

mglaman · 2026-04-29T16:16:34Z

Actually I was looking at \Mcp\Capability\Registry\Loader\ArrayLoader::load:

It respects everything from $data, which allows dynamic inputSchema and outputSchema if you use \Mcp\Server\Builder::addTool. The reflection is still made, but can be ignored. Do we need a new interface for this? Because the runtime information can be generated when the server is built

e0ipso · 2026-04-30T06:06:55Z

Thanks for the review @mglaman! I have updated the code based on your suggestions. I like it much better now!

Here is my answer to your question above on "what is the point of this PR?". I should have addressed that more clearly in the PR description.

Dispatch binds by parameter name, not by schema. ReferenceHandler::prepareArguments() iterates the handler's ReflectionParameters and looks up $arguments[$paramName]. Variadic is explicitly TODO. So if your tool's inputSchema is {title: string, body: string}, the handler method has to be fn(string $title, string $body). With a config-driven schema you don't know those parameter names at the time of writing the code.

Additionally HandlerResolver::resolve() requires both elements to be strings, so [$instance, 'execute'] is rejected. Only [ClassName::class, 'method'] works. For DI-constructed objects with constructor args, that doesn't work. That could be addressed differently, but this PR removes that need.

Finally, prompts/templates have their PromptArguments built from reflection only. There is no field in the manual-prompt array for arguments or completion providers.

I am not saying the interface isn't the only way, but it is typically the way to write a contract for code integration.

mglaman · 2026-04-30T19:35:21Z

So if your tool's inputSchema is {title: string, body: string}, the handler method has to be fn(string $title, string $body). With a config-driven schema you don't know those parameter names at the time of writing the code.

Perfect, that's what I was missing. Handler signature must match the schema. But in my opinion that would always be the case. I guess it's just hard for me to visualize the contract of something using this. The tests and docs don't cover array $arguments.

I still don't understand what a "from configuration" tool would look like. I know Drupal does fancy stuff but I am failing to visualize an example of the code to help me grok this change. I am still on the "I'd have a plugin that maps Drupalisms to the SDK"

chr-hertel · 2026-04-30T20:50:14Z

Hi @e0ipso, interesting approach and quite valid use case I understand.
I'm not sure I get what's the benefit of reusing the ArrayLoader?

With api-platform/mcp @soyuka had quite a similar problem - that's why we have that loader extension point IIRC. however, he needed to go with an extra handler as well and I feel like it is desirable to solve that use case on SDK level already 🤔

Maybe we can even think of inverting the default - for standalone usage the discovery feature is great, but in most other cases i saw, it's basically worked around - those RuntimeXyzInterface implementation feel similarly to me, WDYT?

Edit, second thought:
It could be convenient to have a Builder::add(new Prompt(...), new MyPromptHandler() implements PromptHandlerInterface) maybe

e0ipso · 2026-05-01T05:07:52Z

@chr-hertel if I understand correctly your preference is:

We add a new helper Builder::add(ElementInterface $element, ElementHandlerInterface $handler) that is documented as the primary registration.
The reflection-based method is documented as sugar syntax.
This Builder::add(...) registers using a dedicated, and new, loader. This leaves the ArrayLoader alone (instead of branching inside and sniffing interfaces).

chr-hertel · 2026-05-01T07:19:25Z

Might be worth exploring if working, but would like to have more opinions here @soyuka @Nyholm @CodeWithKyrian

e0ipso · 2026-05-01T11:03:12Z

@chr-hertel I think implemented your suggestion. I learned more about the project in the process ☺️

e0ipso · 2026-05-01T11:10:23Z

@chr-hertel I had an LLM update the PR description to reflect the conversation so far, and the new direction. I'm notifying you in case you want to revise your 👍

mglaman

This seems much better

e0ipso · 2026-05-08T08:06:36Z

@chr-hertel @Nyholm et al. Please let me know if you prefer that I take this in a different direction instead.

chr-hertel · 2026-05-08T08:11:58Z

Will come back to this in a minute 👍 first sorting small stuff right now, thanks already!

chr-hertel

I like this very much already - switched to nit-pick-mode while reviewing - first round of comments tho. Thanks @e0ipso!

chr-hertel · 2026-05-08T09:35:54Z

Also needs a CHANGELOG.md entry please 👍

Uuid::v7() was added in symfony/uid 6.2 and breaks the Symfony 5.4 matrix job. Match the convention used elsewhere in the suite.

Extract per-element preparation into dedicated private prepare* methods for tools, resources, templates, and prompts. Factor the shared required-field assertion and reflected name/description resolution into helpers.

Drop nullable return types on RuntimeToolHandlerInterface:: getInputSchema(), RuntimePromptHandlerInterface:: getPromptArguments()/getCompletionProviders(), and RuntimeResourceTemplateHandlerInterface:: getCompletionProviders() in favor of plain arrays. ArrayLoader no longer needs the null-coalescing fallbacks, and NullSchemaToolHandler plus its ConfigurationException test become redundant.

Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

Introduce a new `Builder::add(...)` pattern for a more generic runtime handler.

Move per-interface handler dispatch from ReferenceHandler into ExplicitElementLoader by wrapping each ElementHandlerInterface in a Closure that satisfies the existing callable contract, revert the *Reference / Registry handler-type widening PR 294 introduced, throw Mcp\Exception\InvalidArgumentException (not \TypeError) on mismatched Builder::add() pairings, and rename two classes for clarity: * Mcp\Capability\Registry\Loader\ArrayLoader -> ReflectedElementLoader * Mcp\Schema\Resource -> Mcp\Schema\ResourceDefinition (no alias) ReferenceHandler::prepareArguments() now injects ClientGateway by type and binds an `array $arguments` / `array $variables` closure parameter from the leftover inbound arguments. This addresses Antoine's coupling concern (ReferenceHandler no longer knows about the four handler interfaces) and Chris's package-exception preference, and clears the phpdoc reserved-word collision Antoine flagged on the resource schema class. Existing tests are re-targeted to exercise the closure path through ExplicitElementLoader / ReferenceHandler.

Apply Chris's line-level suggestions on docs/server-builder.md (rewrap to 120 chars, smoothed Drupal mcp module name-drop in the explicit-element registration section, exception name reads Mcp\Exception\InvalidArgumentException), rewrap docs/mcp-elements.md to 120 chars, and add 0.6.0 CHANGELOG entries covering the Builder::add() entry point, the new handler interfaces, the new ExplicitElementLoader, plus three BC breaks (Resource -> ResourceDefinition rename, ArrayLoader -> ReflectedElementLoader rename, mismatched-pairing exception swap).

* CHANGELOG: drop spurious [BC Break] entry for the exception type Builder::add() raises (method is new in this PR). * docs/server-builder: revert wrap-only edits to pre-existing main content; keep 120ch wrapping only for new sections. * ExplicitElementLoader: trim verbose class docblock. * ReferenceHandler: rename SPLAT_PARAMETER_NAMES constant to ARGUMENT_BAG_PARAMETERS.

e0ipso · 2026-05-20T14:13:24Z

I think this should be pretty close. The Drupal implementation is quite clean when using this patch, I am so happy about this one!!

e0ipso · 2026-05-20T14:13:57Z

+            } elseif (
+                $type instanceof \ReflectionNamedType
+                && 'array' === $type->getName()
+                && \in_array($paramName, self::ARGUMENT_BAG_PARAMETERS, true)
+            ) {
+                $skipKeys = array_merge(
+                    self::RESERVED_ARGUMENT_KEYS,
+                    array_values(array_diff($allParamNames, [$paramName])),
+                );
+                $finalArgs[$paramPosition] = array_diff_key($arguments, array_flip($skipKeys));


This is the ugly part. I am open to suggestions.

i'm a bit worried about the impact to tools, that actually have array $argument, but we don't know at this level if we're dealing with an interface implementation, right?

just copying your concern i guess ... 🤔

chr-hertel

Nit pick level, only the "ugly part" got me thinking as well ...
Need to let that sink in, but those small items is actionable already.
Thanks @e0ipso!

chr-hertel · 2026-05-20T19:22:45Z

+            $registry->registerResourceTemplate(
+                $entry['definition'],
+                static fn (string $uri, array $variables, ClientGateway $client) => $handler->read($uri, $variables, $client),
+            );


Third argument completionProviders basically lost, not sure how to tackle that - would accept that for now. Same for prompts below.

can't we just add the completionProvider? there'd be a feature gap between the two loaders if not?

was my thought as well, but we only have add(Prompt, PromptHandler) at the moment.

i don't think it should be part of the Mcp\Schema\Prompt instance, so it could be an optional third argument?
add(Prompt, PromptHandler, ?CompletionProvider)

chr-hertel · 2026-05-20T19:24:36Z


-        // ArrayLoader runs before DiscoveryLoader so manual entries are seen first; DiscoveryLoader's
-        // identity check then preserves them against same-name discovered entries.
+        // ReflectedElementLoader runs before DiscoveryLoader so manual entries are seen first;


Suggested change

// ReflectedElementLoader runs before DiscoveryLoader so manual entries are seen first;

// ExplicitElementLoader and ReflectedElementLoader run before DiscoveryLoader so manual entries are seen first;

chr-hertel · 2026-05-20T20:36:07Z


+### Explicit element registration
+
+When an element's name, schema, or description is only known at runtime (for example, the Drupal `mcp` module exposing


Let's move the Drupal reference to README section "PHP Libraries Using the MCP SDK"

chr-hertel · 2026-05-20T20:48:07Z

+            } elseif (
+                $type instanceof \ReflectionNamedType
+                && 'array' === $type->getName()
+                && \in_array($paramName, self::ARGUMENT_BAG_PARAMETERS, true)
+            ) {
+                $skipKeys = array_merge(
+                    self::RESERVED_ARGUMENT_KEYS,
+                    array_values(array_diff($allParamNames, [$paramName])),
+                );
+                $finalArgs[$paramPosition] = array_diff_key($arguments, array_flip($skipKeys));


i'm a bit worried about the impact to tools, that actually have array $argument, but we don't know at this level if we're dealing with an interface implementation, right?

just copying your concern i guess ... 🤔

soyuka · 2026-05-21T09:49:51Z

+                    self::RESERVED_ARGUMENT_KEYS,
+                    array_values(array_diff($allParamNames, [$paramName])),
+                );
+                $finalArgs[$paramPosition] = array_diff_key($arguments, array_flip($skipKeys));


Proposed fix pushed at soyuka/php-sdk@c214a5d.

The idea is to bind ExplicitElementLoader closures to ReferenceHandler::class as their closure scope. ReferenceHandler::handle() short-circuits when getClosureScopeClass()?->getName() === self::class and invokes the closure with the raw argument bag. This drops the magic-name heuristic (array $arguments / array $variables matched by parameter name) and the RESERVED_ARGUMENT_KEYS / ARGUMENT_BAG_PARAMETERS consts.

An alternative would be a wrapper class + widening, but its really nitpicking and probably not worth it.

Feel free to cherry-pick the commit.

soyuka · 2026-05-21T09:51:57Z

Nice I like this implementation better! We could've left the Resource rename in another PR to lower the diff but we should've taken care of that anyways...

docs: mention ExplicitElementLoader in comment docs: move Drupal reference to README list docs: drop implementation-only changelog entry docs: revert rewrap noise from mcp-elements.md

chr-hertel

Thanks @e0ipso - works for me like this 👍

soyuka · 2026-05-29T05:18:00Z

Thanks!

e0ipso · 2026-05-29T06:19:25Z

Thank you!

e0ipso · 2026-05-29T09:01:34Z

Crossing fingers for a v0.6.0 soon 🤞

e0ipso requested review from CodeWithKyrian, Nyholm, chr-hertel and soyuka as code owners April 29, 2026 07:37

mglaman reviewed Apr 29, 2026

View reviewed changes

Comment thread src/Capability/Registry/Loader/ArrayLoader.php Outdated

chr-hertel reviewed Apr 30, 2026

View reviewed changes

Comment thread docs/server-builder.md Outdated

e0ipso commented May 1, 2026

View reviewed changes

Comment thread src/Capability/Registry/ElementReference.php Outdated

e0ipso commented May 1, 2026

View reviewed changes

Comment thread src/Capability/Registry/ReferenceHandler.php

e0ipso commented May 1, 2026

View reviewed changes

Comment thread src/Capability/Registry/Loader/ExplicitElementLoader.php

mglaman reviewed May 4, 2026

View reviewed changes

Comment thread src/Server/Handler/ElementHandlerInterface.php

chr-hertel added Server Issues & PRs related to the Server component enhancement Request for a new feature that's not currently supported labels May 8, 2026

chr-hertel added this to the 0.6.0 milestone May 8, 2026

chr-hertel requested changes May 8, 2026

View reviewed changes

Comment thread docs/mcp-elements.md Outdated

Comment thread docs/server-builder.md Outdated

Comment thread docs/server-builder.md

Comment thread src/Capability/Registry/Loader/ExplicitElementLoader.php

Comment thread src/Capability/Registry/ReferenceHandler.php

chr-hertel reviewed May 8, 2026

View reviewed changes

Comment thread docs/server-builder.md Outdated

chr-hertel reviewed May 8, 2026

View reviewed changes

Comment thread src/Server/Builder.php Outdated

chr-hertel added needs more work Not ready to be merged yet, needs additional follow-up from the author(s). labels May 8, 2026

chr-hertel mentioned this pull request May 8, 2026

[Server] feat(capability): add dynamic provider interfaces #180

Closed

6 tasks

e0ipso and others added 10 commits May 20, 2026 15:37

test(server): use Uuid::v4 for symfony/uid 5.4 compatibility

acc3100

Uuid::v7() was added in symfony/uid 6.2 and breaks the Symfony 5.4 matrix job. Match the convention used elsewhere in the suite.

refactor(server): split ArrayLoader registration

3876e61

Extract per-element preparation into dedicated private prepare* methods for tools, resources, templates, and prompts. Factor the shared required-field assertion and reflected name/description resolution into helpers.

doc: update docs/server-builder.md

59c4163

Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

feat: peer revie feedback

a781354

Introduce a new `Builder::add(...)` pattern for a more generic runtime handler.

refactor: rename CallableHandler to Handler

e89882a

style: fix phpdoc param alignment

7fcbcdc

e0ipso force-pushed the allow-runtime-tools branch from aae7a3a to 7fcbcdc Compare May 20, 2026 13:37

refactor: inline $reference->handler access

994bd02

e0ipso requested review from chr-hertel and soyuka May 20, 2026 14:12

e0ipso commented May 20, 2026

View reviewed changes

chr-hertel reviewed May 20, 2026

View reviewed changes

soyuka reviewed May 21, 2026

View reviewed changes

e0ipso and others added 3 commits May 28, 2026 16:41

Merge branch 'main' into allow-runtime-tools

791b197

fix: maintainer review feedback

0bae832

docs: mention ExplicitElementLoader in comment docs: move Drupal reference to README list docs: drop implementation-only changelog entry docs: revert rewrap noise from mcp-elements.md

style: fix phpdoc param alignment

21c7c65

chr-hertel approved these changes May 28, 2026

View reviewed changes

chr-hertel requested a review from soyuka May 28, 2026 20:34

soyuka approved these changes May 29, 2026

View reviewed changes

soyuka merged commit 0347dc8 into modelcontextprotocol:main May 29, 2026
18 checks passed

soyuka mentioned this pull request May 29, 2026

Document v0.6.0 changes in CHANGELOG and docs #311

Open

	// ReflectedElementLoader runs before DiscoveryLoader so manual entries are seen first;
	// ExplicitElementLoader and ReflectedElementLoader run before DiscoveryLoader so manual entries are seen first;


		### Explicit element registration

		When an element's name, schema, or description is only known at runtime (for example, the Drupal `mcp` module exposing

Conversation

e0ipso commented Apr 29, 2026 • edited by chr-hertel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

mglaman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mglaman commented Apr 29, 2026

Uh oh!

e0ipso commented Apr 30, 2026

Uh oh!

mglaman commented Apr 30, 2026

Uh oh!

chr-hertel commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

e0ipso commented May 1, 2026

Uh oh!

chr-hertel commented May 1, 2026

Uh oh!

e0ipso commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

e0ipso commented May 1, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mglaman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

e0ipso commented May 8, 2026

Uh oh!

chr-hertel commented May 8, 2026

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chr-hertel commented May 8, 2026

Uh oh!

Uh oh!

Uh oh!

e0ipso commented May 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chr-hertel May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

e0ipso commented Apr 29, 2026 •

edited by chr-hertel

Loading

chr-hertel commented Apr 30, 2026 •

edited

Loading

e0ipso commented May 1, 2026 •

edited

Loading

chr-hertel May 21, 2026 •

edited

Loading