fix: replace Handler type alias with explicit PHPDoc types

Remove @phpstan-import-type Handler and replace @param Handler
annotations with explicit types:
- callable|array{0: class-string|object, 1: string}|string for tools
- \Closure|array{0: class-string|object, 1: string}|string for others

This fixes PHPStan errors where the Handler type alias didn't match
the native parameter types, and resolves missingType.iterableValue
errors by specifying the array structure.

Author: e0ipso

src/Capability/Registry/ElementReference.php

@@ -14,15 +14,13 @@
 /**
  * Base class for element references with default passthrough argument preparation.
  *
- * @phpstan-type Handler \Closure|array{0: object|string, 1: string}|string|object
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 class ElementReference implements ArgumentPreparationInterface
 {
     /**
-     * @param Handler $handler The handler can be a Closure, array method reference,
-     *                         string function/class name, or a callable object (implementing __invoke)
+     * @param object|array{0: class-string|object, 1: string}|string $handler The handler can be a Closure, array method reference,
+     *                                                                        string function/class name, or a callable object (implementing __invoke)
      */
     public function __construct(
         public readonly object|array|string $handler,

src/Capability/Registry/Loader/ArrayLoader.php

@@ -18,7 +18,6 @@
 use Mcp\Capability\Discovery\DocBlockParser;
 use Mcp\Capability\Discovery\HandlerResolver;
 use Mcp\Capability\Discovery\SchemaGenerator;
-use Mcp\Capability\Registry\ElementReference;
 use Mcp\Capability\RegistryInterface;
 use Mcp\Exception\ConfigurationException;
 use Mcp\Schema\Annotations;
@@ -35,22 +34,20 @@
 
 /**
  * @author Antoine Bluchet <soyuka@gmail.com>
- *
- * @phpstan-import-type Handler from ElementReference
  */
 final class ArrayLoader implements LoaderInterface
 {
     /**
      * @param array{
-     *     handler: Handler,
+     *     handler: callable|array{0: class-string|object, 1: string}|string,
      *     name: ?string,
      *     description: ?string,
      *     annotations: ?ToolAnnotations,
      *     icons: ?Icon[],
      *     meta: ?array<string, mixed>
      * }[] $tools
      * @param array{
-     *     handler: Handler,
+     *     handler: \Closure|array{0: class-string|object, 1: string}|string,
      *     uri: string,
      *     name: ?string,
      *     description: ?string,
@@ -61,7 +58,7 @@ final class ArrayLoader implements LoaderInterface
      *     meta: ?array<string, mixed>
      * }[] $resources
      * @param array{
-     *     handler: Handler,
+     *     handler: \Closure|array{0: class-string|object, 1: string}|string,
      *     uriTemplate: string,
      *     name: ?string,
      *     description: ?string,
@@ -70,7 +67,7 @@ final class ArrayLoader implements LoaderInterface
      *     meta: ?array<string, mixed>
      * }[] $resourceTemplates
      * @param array{
-     *     handler: Handler,
+     *     handler: \Closure|array{0: class-string|object, 1: string}|string,
      *     name: ?string,
      *     description: ?string,
      *     icons: ?Icon[],
@@ -271,7 +268,7 @@ public function load(RegistryInterface $registry): void
     }
 
     /**
-     * @param Handler $handler
+     * @param \Closure|array{0: class-string|object, 1: string}|string $handler
      */
     private function getHandlerDescription(\Closure|array|string $handler): string
     {

src/Capability/Registry/PromptReference.php

@@ -16,17 +16,15 @@
 use Mcp\Schema\Prompt;
 
 /**
- * @phpstan-import-type Handler from ElementReference
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 class PromptReference extends ElementReference
 {
     use ReflectionArgumentPreparationTrait;
 
     /**
-     * @param Handler                            $handler
-     * @param array<string, class-string|object> $completionProviders
+     * @param \Closure|array{0: class-string|object, 1: string}|string $handler
+     * @param array<string, class-string|object>                       $completionProviders
      */
     public function __construct(
         public readonly Prompt $prompt,

src/Capability/Registry/ReferenceHandler.php

@@ -61,6 +61,8 @@ public function handle(ElementReference $reference, array $arguments): mixed
     /**
      * Resolves a handler to a callable, optionally returning an instance.
      *
+     * @param \Closure|array{0: class-string|object, 1: string}|string $handler
+     *
      * @return array{0: callable, 1: ?object}
      */
     private function resolveHandler(\Closure|array|string $handler): array

src/Capability/Registry/ResourceReference.php

@@ -16,16 +16,14 @@
 use Mcp\Schema\Resource;
 
 /**
- * @phpstan-import-type Handler from ElementReference
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 class ResourceReference extends ElementReference
 {
     use ReflectionArgumentPreparationTrait;
 
     /**
-     * @param Handler $handler
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
      */
     public function __construct(
         public readonly Resource $schema,

src/Capability/Registry/ResourceTemplateReference.php

@@ -16,8 +16,6 @@
 use Mcp\Schema\ResourceTemplate;
 
 /**
- * @phpstan-import-type Handler from ElementReference
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 class ResourceTemplateReference extends ElementReference
@@ -27,8 +25,8 @@ class ResourceTemplateReference extends ElementReference
     private readonly UriTemplateMatcher $uriTemplateMatcher;
 
     /**
-     * @param Handler                            $handler
-     * @param array<string, class-string|object> $completionProviders
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
+     * @param array<string, class-string|object>                       $completionProviders
      */
     public function __construct(
         public readonly ResourceTemplate $resourceTemplate,

src/Capability/Registry/ToolReference.php

@@ -17,16 +17,14 @@
 use Mcp\Schema\Tool;
 
 /**
- * @phpstan-import-type Handler from ElementReference
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 class ToolReference extends ElementReference
 {
     use ReflectionArgumentPreparationTrait;
 
     /**
-     * @param Handler $handler
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
      */
     public function __construct(
         public readonly Tool $tool,

src/Capability/RegistryInterface.php

@@ -20,7 +20,6 @@
 use Mcp\Capability\Registry\DynamicResourceReference;
 use Mcp\Capability\Registry\DynamicResourceTemplateReference;
 use Mcp\Capability\Registry\DynamicToolReference;
-use Mcp\Capability\Registry\ElementReference;
 use Mcp\Capability\Registry\PromptReference;
 use Mcp\Capability\Registry\ResourceReference;
 use Mcp\Capability\Registry\ResourceTemplateReference;
@@ -35,8 +34,6 @@
 use Mcp\Schema\Tool;
 
 /**
- * @phpstan-import-type Handler from ElementReference
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  * @author Christopher Hertel <mail@christopher-hertel.de>
  */
@@ -45,22 +42,22 @@ interface RegistryInterface
     /**
      * Registers a tool with its handler.
      *
-     * @param Handler $handler
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
      */
     public function registerTool(Tool $tool, callable|array|string $handler, bool $isManual = false): void;
 
     /**
      * Registers a resource with its handler.
      *
-     * @param Handler $handler
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
      */
     public function registerResource(Resource $resource, callable|array|string $handler, bool $isManual = false): void;
 
     /**
      * Registers a resource template with its handler and completion providers.
      *
-     * @param Handler                            $handler
-     * @param array<string, class-string|object> $completionProviders
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
+     * @param array<string, class-string|object>                       $completionProviders
      */
     public function registerResourceTemplate(
         ResourceTemplate $template,
@@ -72,8 +69,8 @@ public function registerResourceTemplate(
     /**
      * Registers a prompt with its handler and completion providers.
      *
-     * @param Handler                            $handler
-     * @param array<string, class-string|object> $completionProviders
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
+     * @param array<string, class-string|object>                       $completionProviders
      */
     public function registerPrompt(
         Prompt $prompt,

src/Server/Builder.php

@@ -17,7 +17,6 @@
 use Mcp\Capability\Provider\DynamicToolProviderInterface;
 use Mcp\Capability\Registry;
 use Mcp\Capability\Registry\Container;
-use Mcp\Capability\Registry\ElementReference;
 use Mcp\Capability\Registry\Loader\ArrayLoader;
 use Mcp\Capability\Registry\Loader\DiscoveryLoader;
 use Mcp\Capability\Registry\Loader\LoaderInterface;
@@ -44,8 +43,6 @@
 use Psr\SimpleCache\CacheInterface;
 
 /**
- * @phpstan-import-type Handler from ElementReference
- *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
 final class Builder
@@ -86,7 +83,7 @@ final class Builder
 
     /**
      * @var array{
-     *     handler: Handler,
+     *     handler: callable|array{0: class-string|object, 1: string}|string,
      *     name: ?string,
      *     description: ?string,
      *     annotations: ?ToolAnnotations,
@@ -98,7 +95,7 @@ final class Builder
 
     /**
      * @var array{
-     *     handler: Handler,
+     *     handler: \Closure|array{0: class-string|object, 1: string}|string,
      *     uri: string,
      *     name: ?string,
      *     description: ?string,
@@ -113,7 +110,7 @@ final class Builder
 
     /**
      * @var array{
-     *     handler: Handler,
+     *     handler: \Closure|array{0: class-string|object, 1: string}|string,
      *     uriTemplate: string,
      *     name: ?string,
      *     description: ?string,
@@ -126,7 +123,7 @@ final class Builder
 
     /**
      * @var array{
-     *     handler: Handler,
+     *     handler: \Closure|array{0: class-string|object, 1: string}|string,
      *     name: ?string,
      *     description: ?string,
      *     icons: ?Icon[],
@@ -350,10 +347,10 @@ public function setProtocolVersion(ProtocolVersion $protocolVersion): self
     /**
      * Manually registers a tool handler.
      *
-     * @param Handler                   $handler
-     * @param array<string, mixed>|null $inputSchema
-     * @param ?Icon[]                   $icons
-     * @param array<string, mixed>|null $meta
+     * @param callable|array{0: class-string|object, 1: string}|string $handler
+     * @param array<string, mixed>|null                                $inputSchema
+     * @param ?Icon[]                                                  $icons
+     * @param array<string, mixed>|null                                $meta
      */
     public function addTool(
         callable|array|string $handler,
@@ -380,9 +377,9 @@ public function addTool(
     /**
      * Manually registers a resource handler.
      *
-     * @param Handler                   $handler
-     * @param ?Icon[]                   $icons
-     * @param array<string, mixed>|null $meta
+     * @param \Closure|array{0: class-string|object, 1: string}|string $handler
+     * @param ?Icon[]                                                  $icons
+     * @param array<string, mixed>|null                                $meta
      */
     public function addResource(
         \Closure|array|string $handler,
@@ -413,8 +410,8 @@ public function addResource(
     /**
      * Manually registers a resource template handler.
      *
-     * @param Handler                   $handler
-     * @param array<string, mixed>|null $meta
+     * @param \Closure|array{0: class-string|object, 1: string}|string $handler
+     * @param array<string, mixed>|null                                $meta
      */
     public function addResourceTemplate(
         \Closure|array|string $handler,
@@ -441,9 +438,9 @@ public function addResourceTemplate(
     /**
      * Manually registers a prompt handler.
      *
-     * @param Handler                   $handler
-     * @param ?Icon[]                   $icons
-     * @param array<string, mixed>|null $meta
+     * @param \Closure|array{0: class-string|object, 1: string}|string $handler
+     * @param ?Icon[]                                                  $icons
+     * @param array<string, mixed>|null                                $meta
      */
     public function addPrompt(
         \Closure|array|string $handler,