Add input upcasting and output normalization to property handlers

Complete the describer extension point so a registered handler can also
upcast incoming client input into an instance and normalize an instance
back to JSON, not just describe its schema.

- Split into PropertyDescriberInterface / PropertyDenormalizerInterface /
  PropertyNormalizerInterface (sharing PropertyHandlerInterface); a single
  class may implement any combination.
- Extract the is_a matching + per-class/concern memoization into a shared
  PropertyHandlerResolver used by the schema, input and output paths.
- ReferenceHandler upcasts class-typed arguments via a denormalizer and
  verifies the result is an instance of the parameter type, so a subtype
  mismatch surfaces as invalid params rather than an internal error.
- CallToolHandler normalizes a class-typed result before formatting it.
- SchemaGenerator infers a tool outputSchema from the return type, but only
  when the describer yields an object schema (an MCP outputSchema describes
  the object-typed structuredContent); ArrayLoader does the same for
  manually registered tools.
- Shipped Uuid/DateTime describers implement all three directions.

addPropertyDescriber() now also rejects being combined with
setReferenceHandler(), mirroring the existing setSchemaGenerator() guard.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: peter-si

docs/mcp-elements.md

@@ -747,35 +747,47 @@ validation requirements that cannot be achieved through the priority system.
 
 ### Custom Type Describers
 
-When a tool parameter is type-hinted with a class, the generator falls back to `{type: "object"}` — which tells the
-LLM nothing about the expected shape. For value-object types (timestamps, identifiers, money, …) you can register a
-**property describer** that maps the class to a targeted JSON Schema fragment.
-
-A describer declares the class (or base class / interface) it handles and the fragment to emit:
+When a tool parameter or return value is type-hinted with a class, the generator falls back to `{type: "object"}` and
+the SDK has no idea how to turn the client's JSON into that class (or that class back into JSON). For value-object types
+(timestamps, identifiers, money, whole DTOs, …) you register a **property handler** that teaches the SDK about the type
+in up to three directions. Each direction is its own interface, so a handler opts into only what it needs; a single
+class may implement any combination:
 
 ```php
-interface PropertyDescriberInterface
-{
-    /** @return class-string The class/interface this describer handles (subtypes match too) */
-    public static function supportedClass(): string;
+use Mcp\Capability\Discovery\PropertyDescriberInterface;
+use Mcp\Capability\Discovery\PropertyDenormalizerInterface;
+use Mcp\Capability\Discovery\PropertyNormalizerInterface;
 
-    /** @return array<string, mixed> JSON Schema fragment for the supported type */
+// All three share PropertyHandlerInterface::supportedClass(): class-string
+
+interface PropertyDescriberInterface       // type → JSON Schema (input + output schema)
+{
     public function describe(): array;
 }
+
+interface PropertyDenormalizerInterface    // client input → instance (tool arguments)
+{
+    public function denormalize(mixed $value, string $class): mixed;
+}
+
+interface PropertyNormalizerInterface      // instance → JSON (tool results)
+{
+    public function normalize(object $value): mixed;
+}
 ```
 
-A parameter is dispatched to a describer when its type is `supportedClass()` **or any subtype of it** — so a describer
-for `\DateTimeInterface` also covers `\DateTimeImmutable`, and one for `Uuid` covers `UuidV4`, `UuidV7`, etc.
+A type is dispatched to a handler when it is `supportedClass()` **or any subtype of it** — so a handler for
+`\DateTimeInterface` also covers `\DateTimeImmutable`, and one for `Uuid` covers `UuidV4`, `UuidV7`, etc. Handlers are
+consulted in **registration order**; the first whose supported class matches wins.
 
-Two describers ship with the SDK (both opt-in):
+Two handlers ship with the SDK (both opt-in), each implementing all three directions:
 
-| Describer | Handles | Emits |
-| --- | --- | --- |
-| `Mcp\Capability\Discovery\PropertyDescriber\DateTimePropertyDescriber` | any `\DateTimeInterface` | `{type: "string", format: "date-time"}` |
-| `Mcp\Capability\Discovery\PropertyDescriber\UuidPropertyDescriber` | `Symfony\Component\Uid\Uuid` (and subclasses) | `{type: "string", format: "uuid"}` |
+| Handler | Handles | Schema | Upcasts / normalizes |
+| --- | --- | --- | --- |
+| `Mcp\Capability\Discovery\PropertyDescriber\DateTimePropertyDescriber` | any `\DateTimeInterface` | `{type: "string", format: "date-time"}` | string ⇄ `\DateTime(Immutable)` (ISO-8601) |
+| `Mcp\Capability\Discovery\PropertyDescriber\UuidPropertyDescriber` | `Symfony\Component\Uid\Uuid` (and subclasses) | `{type: "string", format: "uuid"}` | string ⇄ `Uuid` (RFC 4122) |
 
-Register them — and your own — on the builder. Describers are consulted in **registration order**; the first one whose
-supported class matches the parameter wins:
+Register them — and your own — on the builder:
 
 ```php
 use Mcp\Capability\Discovery\PropertyDescriber\DateTimePropertyDescriber;
@@ -788,16 +800,33 @@ $server = Server::builder()
     ->build();
 ```
 
-Now `public function schedule(\DateTimeImmutable $until)` generates `{type: "string", format: "date-time"}` for
-`$until` instead of `{type: "object"}`. Docblock descriptions, defaults and nullability are still layered on top of the
-describer's fragment.
+With these registered, a tool like:
 
-Writing a custom describer for a domain value object:
+```php
+public function getTownShopList(Uuid $id): \DateTimeImmutable
+```
+
+generates `{type: "string", format: "uuid"}` for `$id`, upcasts the client's `"id"` string into a real `Uuid` before the
+method is called, and normalizes the returned `\DateTimeImmutable` to an ISO-8601 string in the result content. Docblock
+descriptions, defaults and nullability are still layered on top of the describer's schema fragment for input parameters.
+
+**Schema vs. value — and the object rule.** A describer fragment is used directly as a tool's `outputSchema` **only when
+it is an `object` schema**, because per the MCP spec an `outputSchema` describes the object-typed `structuredContent`.
+A scalar fragment (uuid/date-time strings) is therefore *not* advertised as an output schema; such a return is
+normalized to a string and carried in the result's text `content` instead. This is what makes the **DTO** case the
+primary use of output schemas: a handler whose `describe()` returns `{type: "object", properties: {...}}` for your DTO
+class gets that emitted as the tool's `outputSchema`, while its `normalize()` produces the matching
+`structuredContent`. Note that normalization is applied to the **top-level** returned value; values nested inside a DTO
+are the registered DTO handler's responsibility (e.g. delegated to a serializer — see below).
+
+Writing a custom handler for a domain value object — implement only the directions you need:
 
 ```php
 use Mcp\Capability\Discovery\PropertyDescriberInterface;
+use Mcp\Capability\Discovery\PropertyDenormalizerInterface;
+use Mcp\Capability\Discovery\PropertyNormalizerInterface;
 
-final class MoneyPropertyDescriber implements PropertyDescriberInterface
+final class MoneyPropertyHandler implements PropertyDescriberInterface, PropertyDenormalizerInterface, PropertyNormalizerInterface
 {
     public static function supportedClass(): string
     {
@@ -808,14 +837,63 @@ final class MoneyPropertyDescriber implements PropertyDescriberInterface
     {
         return ['type' => 'string', 'pattern' => '^\d+(\.\d{2})? [A-Z]{3}$'];
     }
+
+    public function denormalize(mixed $value, string $class): \App\Money
+    {
+        return \App\Money::fromString((string) $value);
+    }
+
+    public function normalize(object $value): string
+    {
+        return (string) $value;
+    }
 }
 
-$builder->addPropertyDescriber(new MoneyPropertyDescriber());
+$builder->addPropertyDescriber(new MoneyPropertyHandler());
 ```
 
-To override a shipped describer, register your own for the same class **before** it — the first matching describer
-wins. Note that `addPropertyDescriber()` cannot be combined with `setSchemaGenerator()` — if you supply your own
-`SchemaGeneratorInterface`, configure the describers on that generator directly.
+#### Delegating whole DTOs to a serializer
+
+Because `describe()` may return any schema fragment and `denormalize()`/`normalize()` receive the concrete class, a
+single handler registered against a DTO base class (or marker interface) can cover **all** your DTOs by delegating to a
+serializer you already use — e.g. `symfony/serializer` — instead of the SDK reflecting your objects:
+
+```php
+use Mcp\Capability\Discovery\PropertyDenormalizerInterface;
+use Mcp\Capability\Discovery\PropertyNormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+final class SerializerDtoHandler implements PropertyDenormalizerInterface, PropertyNormalizerInterface
+{
+    public function __construct(private NormalizerInterface&DenormalizerInterface $serializer)
+    {
+    }
+
+    public static function supportedClass(): string
+    {
+        return \App\Dto\AbstractDto::class;
+    }
+
+    public function denormalize(mixed $value, string $class): object
+    {
+        return $this->serializer->denormalize($value, $class);
+    }
+
+    public function normalize(object $value): mixed
+    {
+        return $this->serializer->normalize($value);
+    }
+}
+```
+
+(For the output **schema** of such DTOs, also implement `PropertyDescriberInterface` and return the nested schema —
+assembled however you like, e.g. via `symfony/property-info` or `api-platform/json-schema`. The SDK itself does not
+reflect class properties.)
+
+To override a shipped handler, register your own for the same class **before** it — the first match wins. Note that
+`addPropertyDescriber()` cannot be combined with `setSchemaGenerator()` (configure describers on your own generator
+instead) nor with `setReferenceHandler()` (wire the handlers onto your own reference handler instead).
 
 ## Discovery vs Manual Registration
 

docs/server-builder.md

@@ -619,5 +619,5 @@ $server = Server::builder()
 | `addResource()` | handler, uri, name?, description?, mimeType?, size?, annotations? | Register resource |
 | `addResourceTemplate()` | handler, uriTemplate, name?, description?, mimeType?, annotations? | Register resource template |
 | `addPrompt()` | handler, name?, description? | Register prompt |
-| `addPropertyDescriber()` | describer | Register a [property describer](mcp-elements.md#custom-type-describers) for class-typed parameters |
+| `addPropertyDescriber()` | handler | Register a [property handler](mcp-elements.md#custom-type-describers) (schema / input upcasting / output normalization) for a class-typed value object |
 | `build()` | - | Create the server instance |

src/Capability/Discovery/PropertyDenormalizerInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Capability\Discovery;
+
+/**
+ * Upcasts an incoming client value into a class-typed argument.
+ *
+ * The counterpart to {@see PropertyDescriberInterface}: where the describer
+ * teaches the schema what a class type looks like on the wire, the
+ * denormalizer turns the value the client actually sent back into a PHP
+ * instance of that type before it is passed to the tool method. Without it, a
+ * tool like `getTownShopList(Uuid $id)` would receive the raw string and fail.
+ */
+interface PropertyDenormalizerInterface extends PropertyHandlerInterface
+{
+    /**
+     * @param mixed        $value the JSON-decoded value received from the client
+     * @param class-string $class the concrete parameter type to produce (the class
+     *                            itself or a subtype of {@see self::supportedClass()})
+     *
+     * @return mixed an instance of $class
+     */
+    public function denormalize(mixed $value, string $class): mixed;
+}

src/Capability/Discovery/PropertyDescriber/DateTimePropertyDescriber.php

@@ -11,13 +11,17 @@
 
 namespace Mcp\Capability\Discovery\PropertyDescriber;
 
+use Mcp\Capability\Discovery\PropertyDenormalizerInterface;
 use Mcp\Capability\Discovery\PropertyDescriberInterface;
+use Mcp\Capability\Discovery\PropertyNormalizerInterface;
 
 /**
- * Describes any {@see \DateTimeInterface} implementation as an ISO-8601
- * date-time string.
+ * Handles any {@see \DateTimeInterface} implementation: describes it as an
+ * ISO-8601 date-time string, parses an incoming string into a date-time
+ * instance (honoring a concrete `\DateTime` vs `\DateTimeImmutable` target),
+ * and renders a returned instance back to an ISO-8601 string.
  */
-final class DateTimePropertyDescriber implements PropertyDescriberInterface
+final class DateTimePropertyDescriber implements PropertyDescriberInterface, PropertyDenormalizerInterface, PropertyNormalizerInterface
 {
     public static function supportedClass(): string
     {
@@ -28,4 +32,22 @@ public function describe(): array
     {
         return ['type' => 'string', 'format' => 'date-time'];
     }
+
+    public function denormalize(mixed $value, string $class): \DateTimeInterface
+    {
+        if ($value instanceof \DateTimeInterface) {
+            return $value;
+        }
+
+        return \DateTime::class === $class
+            ? new \DateTime((string) $value)
+            : new \DateTimeImmutable((string) $value);
+    }
+
+    public function normalize(object $value): string
+    {
+        \assert($value instanceof \DateTimeInterface);
+
+        return $value->format(\DateTimeInterface::ATOM);
+    }
 }

src/Capability/Discovery/PropertyDescriber/UuidPropertyDescriber.php

@@ -11,14 +11,18 @@
 
 namespace Mcp\Capability\Discovery\PropertyDescriber;
 
+use Mcp\Capability\Discovery\PropertyDenormalizerInterface;
 use Mcp\Capability\Discovery\PropertyDescriberInterface;
+use Mcp\Capability\Discovery\PropertyNormalizerInterface;
 use Symfony\Component\Uid\Uuid;
 
 /**
- * Describes Symfony UID {@see Uuid} (and subclasses like `UuidV4`, `UuidV7`)
- * as a uuid-format string.
+ * Handles Symfony UID {@see Uuid} (and subclasses like `UuidV4`, `UuidV7`):
+ * describes it as a uuid-format string, upcasts an incoming string into a
+ * {@see Uuid} instance, and renders a returned instance back to its RFC 4122
+ * string form.
  */
-final class UuidPropertyDescriber implements PropertyDescriberInterface
+final class UuidPropertyDescriber implements PropertyDescriberInterface, PropertyDenormalizerInterface, PropertyNormalizerInterface
 {
     public static function supportedClass(): string
     {
@@ -29,4 +33,21 @@ public function describe(): array
     {
         return ['type' => 'string', 'format' => 'uuid'];
     }
+
+    public function denormalize(mixed $value, string $class): Uuid
+    {
+        if ($value instanceof Uuid) {
+            return $value;
+        }
+
+        // Uuid::fromString detects the version and returns the matching subtype.
+        return Uuid::fromString((string) $value);
+    }
+
+    public function normalize(object $value): string
+    {
+        \assert($value instanceof Uuid);
+
+        return (string) $value;
+    }
 }

src/Capability/Discovery/PropertyDescriberInterface.php

@@ -15,23 +15,15 @@
  * Translates a PHP class type into a JSON Schema fragment.
  *
  * A describer declares the class (or base class/interface) it handles via
- * {@see self::supportedClass()}. The {@see SchemaGenerator} matches a
- * parameter's concrete class against that type — directly or through its
- * parents and interfaces — and, when several describers are registered,
- * consults them in priority order. Implementations let callers teach the
- * generator about value-object types (DateTime, Uuid, etc.) whose JSON Schema
- * representation is more specific than a generic `{type: "object"}`.
+ * {@see PropertyHandlerInterface::supportedClass()}. The {@see SchemaGenerator}
+ * matches a parameter's or return type's concrete class against that type —
+ * directly or through its parents and interfaces — and, when several describers
+ * are registered, consults them in priority order. Implementations let callers
+ * teach the generator about value-object types (DateTime, Uuid, etc.) whose JSON
+ * Schema representation is more specific than a generic `{type: "object"}`.
  */
-interface PropertyDescriberInterface
+interface PropertyDescriberInterface extends PropertyHandlerInterface
 {
-    /**
-     * The class or interface this describer handles. Parameters whose type is
-     * the class itself or any subtype of it are dispatched to this describer.
-     *
-     * @return class-string
-     */
-    public static function supportedClass(): string;
-
     /**
      * @return array<string, mixed> Schema fragment for the supported type
      */

src/Capability/Discovery/PropertyHandlerInterface.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Capability\Discovery;
+
+/**
+ * Base contract for handlers that teach the SDK about a specific PHP class type.
+ *
+ * A handler declares the class (or base class / interface) it handles via
+ * {@see self::supportedClass()}; a parameter, property or return type is
+ * dispatched to it when its type is that class or any subtype of it. The
+ * concern-specific behaviour lives in the sub-interfaces:
+ * {@see PropertyDescriberInterface} (type → JSON Schema),
+ * {@see PropertyDenormalizerInterface} (client input → instance) and
+ * {@see PropertyNormalizerInterface} (instance → JSON output). A single class
+ * may implement any combination of them.
+ */
+interface PropertyHandlerInterface
+{
+    /**
+     * The class or interface this handler covers. Types that are the class
+     * itself or any subtype of it are dispatched to this handler.
+     *
+     * @return class-string
+     */
+    public static function supportedClass(): string;
+}