Add elicitation support for server-to-client user input requests (#228)

- Add ElicitAction enum (accept/decline/cancel)
- Add schema definitions for elicitation fields (string, number, boolean, enum)
- Add ElicitationSchema wrapper for requestedSchema
- Add ElicitRequest and ElicitResult for elicitation/create method
- Update ClientCapabilities to support elicitation capability
- Add elicit() method to ClientGateway
- Store client capabilities in session during initialization
- Add comprehensive unit tests
- Add elicitation example server with book_restaurant, confirm_action, and collect_feedback tools

src/Schema/ClientCapabilities.php

@@ -26,6 +26,7 @@ class ClientCapabilities implements \JsonSerializable
         public readonly ?bool $roots = false,
         public readonly ?bool $rootsListChanged = null,
         public readonly ?bool $sampling = null,
+        public readonly ?bool $elicitation = null,
         public readonly ?array $experimental = null,
     ) {
     }
@@ -36,6 +37,7 @@ class ClientCapabilities implements \JsonSerializable
      *         listChanged?: bool,
      *     },
      *     sampling?: bool,
+     *     elicitation?: bool,
      *     experimental?: array<string, mixed>,
      * } $data
      */
@@ -56,10 +58,16 @@ class ClientCapabilities implements \JsonSerializable
             $sampling = true;
         }
 
+        $elicitation = null;
+        if (isset($data['elicitation'])) {
+            $elicitation = true;
+        }
+
         return new self(
             $rootsEnabled,
             $rootsListChanged,
             $sampling,
+            $elicitation,
             $data['experimental'] ?? null
         );
     }
@@ -68,6 +76,7 @@ class ClientCapabilities implements \JsonSerializable
      * @return array{
      *     roots?: object,
      *     sampling?: object,
+     *     elicitation?: object,
      *     experimental?: object,
      * }
      */
@@ -85,6 +94,10 @@ class ClientCapabilities implements \JsonSerializable
             $data['sampling'] = new \stdClass();
         }
 
+        if ($this->elicitation) {
+            $data['elicitation'] = new \stdClass();
+        }
+
         if ($this->experimental) {
             $data['experimental'] = (object) $this->experimental;
         }

src/Schema/Elicitation/AbstractSchemaDefinition.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * Base class for schema definitions in elicitation requests.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+abstract class AbstractSchemaDefinition implements \JsonSerializable
+{
+    public function __construct(
+        public readonly string $title,
+        public readonly ?string $description = null,
+    ) {
+    }
+
+    /**
+     * Validate that title exists and is a string in the data array.
+     *
+     * @param array<string, mixed> $data
+     *
+     * @throws InvalidArgumentException
+     */
+    protected static function validateTitle(array $data, string $schemaType): void
+    {
+        if (!isset($data['title']) || !\is_string($data['title'])) {
+            throw new InvalidArgumentException(\sprintf('Missing or invalid "title" for %s schema definition.', $schemaType));
+        }
+    }
+
+    /**
+     * Build the base JSON structure with type, title, and optional description.
+     *
+     * @return array<string, mixed>
+     */
+    protected function buildBaseJson(string $type): array
+    {
+        $data = [
+            'type' => $type,
+            'title' => $this->title,
+        ];
+
+        if (null !== $this->description) {
+            $data['description'] = $this->description;
+        }
+
+        return $data;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    abstract public function jsonSerialize(): array;
+}

src/Schema/Elicitation/BooleanSchemaDefinition.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+/**
+ * Schema definition for boolean fields in elicitation requests.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class BooleanSchemaDefinition extends AbstractSchemaDefinition
+{
+    /**
+     * @param string      $title       Human-readable title for the field
+     * @param string|null $description Optional description/help text
+     * @param bool|null   $default     Optional default value
+     */
+    public function __construct(
+        string $title,
+        ?string $description = null,
+        public readonly ?bool $default = null,
+    ) {
+        parent::__construct($title, $description);
+    }
+
+    /**
+     * @param array{
+     *     title: string,
+     *     description?: string,
+     *     default?: bool,
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        self::validateTitle($data, 'boolean');
+
+        return new self(
+            title: $data['title'],
+            description: $data['description'] ?? null,
+            default: isset($data['default']) ? (bool) $data['default'] : null,
+        );
+    }
+
+    /**
+     * @return array{
+     *     type: string,
+     *     title: string,
+     *     description?: string,
+     *     default?: bool,
+     * }
+     */
+    public function jsonSerialize(): array
+    {
+        $data = $this->buildBaseJson('boolean');
+
+        if (null !== $this->default) {
+            $data['default'] = $this->default;
+        }
+
+        return $data;
+    }
+}

src/Schema/Elicitation/ElicitationSchema.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * Schema wrapper for elicitation requestedSchema (JSON Schema object type).
+ *
+ * Represents an object schema with primitive property definitions and optional required fields.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class ElicitationSchema implements \JsonSerializable
+{
+    /**
+     * @param array<string, StringSchemaDefinition|NumberSchemaDefinition|BooleanSchemaDefinition|EnumSchemaDefinition> $properties Property definitions keyed by name
+     * @param string[]                                                                                                  $required   Array of required property names
+     */
+    public function __construct(
+        public readonly array $properties,
+        public readonly array $required = [],
+    ) {
+        if ([] === $properties) {
+            throw new InvalidArgumentException('properties array must not be empty.');
+        }
+
+        foreach ($required as $name) {
+            if (!\array_key_exists($name, $properties)) {
+                throw new InvalidArgumentException(\sprintf('Required property "%s" is not defined in properties.', $name));
+            }
+        }
+    }
+
+    /**
+     * Create an ElicitationSchema from array data.
+     *
+     * @param array{
+     *     type?: string,
+     *     properties: array<string, array{type: string, title: string, ...}>,
+     *     required?: string[],
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        if (isset($data['type']) && 'object' !== $data['type']) {
+            throw new InvalidArgumentException('ElicitationSchema type must be "object".');
+        }
+
+        if (!isset($data['properties']) || !\is_array($data['properties'])) {
+            throw new InvalidArgumentException('Missing or invalid "properties" for elicitation schema.');
+        }
+
+        $properties = [];
+        foreach ($data['properties'] as $name => $propertyData) {
+            if (!\is_array($propertyData)) {
+                throw new InvalidArgumentException(\sprintf('Property "%s" must be an array.', $name));
+            }
+            $properties[$name] = PrimitiveSchemaDefinition::fromArray($propertyData);
+        }
+
+        return new self(
+            properties: $properties,
+            required: $data['required'] ?? [],
+        );
+    }
+
+    /**
+     * @return array{
+     *     type: string,
+     *     properties: array<string, mixed>,
+     *     required?: string[],
+     * }
+     */
+    public function jsonSerialize(): array
+    {
+        $data = [
+            'type' => 'object',
+            'properties' => [],
+        ];
+
+        foreach ($this->properties as $name => $property) {
+            $data['properties'][$name] = $property->jsonSerialize();
+        }
+
+        if ([] !== $this->required) {
+            $data['required'] = $this->required;
+        }
+
+        return $data;
+    }
+}

src/Schema/Elicitation/EnumSchemaDefinition.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * Schema definition for string enum fields in elicitation requests.
+ *
+ * Provides a list of allowed values with optional human-readable labels.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class EnumSchemaDefinition extends AbstractSchemaDefinition
+{
+    /**
+     * @param string        $title       Human-readable title for the field
+     * @param string[]      $enum        Array of allowed string values
+     * @param string|null   $description Optional description/help text
+     * @param string|null   $default     Optional default value (must be in enum)
+     * @param string[]|null $enumNames   Optional human-readable labels for each enum value
+     */
+    public function __construct(
+        string $title,
+        public readonly array $enum,
+        ?string $description = null,
+        public readonly ?string $default = null,
+        public readonly ?array $enumNames = null,
+    ) {
+        parent::__construct($title, $description);
+
+        if ([] === $enum) {
+            throw new InvalidArgumentException('enum array must not be empty.');
+        }
+
+        foreach ($enum as $value) {
+            if (!\is_string($value)) {
+                throw new InvalidArgumentException('All enum values must be strings.');
+            }
+        }
+
+        if (null !== $enumNames && \count($enumNames) !== \count($enum)) {
+            throw new InvalidArgumentException('enumNames length must match enum length.');
+        }
+
+        if (null !== $default && !\in_array($default, $enum, true)) {
+            throw new InvalidArgumentException(\sprintf('Default value "%s" is not in the enum array.', $default));
+        }
+    }
+
+    /**
+     * @param array{
+     *     title: string,
+     *     enum: string[],
+     *     description?: string,
+     *     default?: string,
+     *     enumNames?: string[],
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        self::validateTitle($data, 'enum');
+
+        if (!isset($data['enum']) || !\is_array($data['enum'])) {
+            throw new InvalidArgumentException('Missing or invalid "enum" for enum schema definition.');
+        }
+
+        return new self(
+            title: $data['title'],
+            enum: $data['enum'],
+            description: $data['description'] ?? null,
+            default: $data['default'] ?? null,
+            enumNames: $data['enumNames'] ?? null,
+        );
+    }
+
+    /**
+     * @return array{
+     *     type: string,
+     *     title: string,
+     *     enum: string[],
+     *     description?: string,
+     *     default?: string,
+     *     enumNames?: string[],
+     * }
+     */
+    public function jsonSerialize(): array
+    {
+        $data = [
+            'type' => 'string',
+            'title' => $this->title,
+            'enum' => $this->enum,
+        ];
+
+        if (null !== $this->description) {
+            $data['description'] = $this->description;
+        }
+
+        if (null !== $this->default) {
+            $data['default'] = $this->default;
+        }
+
+        if (null !== $this->enumNames) {
+            $data['enumNames'] = $this->enumNames;
+        }
+
+        return $data;
+    }
+}

src/Schema/Elicitation/NumberSchemaDefinition.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * Schema definition for number/integer fields in elicitation requests.
+ *
+ * Supports minimum and maximum value constraints.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class NumberSchemaDefinition extends AbstractSchemaDefinition
+{
+    /**
+     * @param string         $title       Human-readable title for the field
+     * @param bool           $integerOnly Whether to restrict to integer values only
+     * @param string|null    $description Optional description/help text
+     * @param int|float|null $default     Optional default value
+     * @param int|float|null $minimum     Optional minimum value (inclusive)
+     * @param int|float|null $maximum     Optional maximum value (inclusive)
+     */
+    public function __construct(
+        string $title,
+        public readonly bool $integerOnly = false,
+        ?string $description = null,
+        public readonly int|float|null $default = null,
+        public readonly int|float|null $minimum = null,
+        public readonly int|float|null $maximum = null,
+    ) {
+        parent::__construct($title, $description);
+
+        if (null !== $minimum && null !== $maximum && $minimum > $maximum) {
+            throw new InvalidArgumentException('minimum cannot be greater than maximum.');
+        }
+
+        if (null !== $default && null !== $minimum && $default < $minimum) {
+            throw new InvalidArgumentException('default value cannot be less than minimum.');
+        }
+
+        if (null !== $default && null !== $maximum && $default > $maximum) {
+            throw new InvalidArgumentException('default value cannot be greater than maximum.');
+        }
+
+        if ($integerOnly && null !== $default && $default !== (int) $default) {
+            throw new InvalidArgumentException('default value must be an integer when integerOnly is true.');
+        }
+    }
+
+    /**
+     * @param array{
+     *     type: string,
+     *     title: string,
+     *     description?: string,
+     *     default?: int|float,
+     *     minimum?: int|float,
+     *     maximum?: int|float,
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        self::validateTitle($data, 'number');
+
+        $type = $data['type'] ?? 'number';
+        $integerOnly = 'integer' === $type;
+
+        return new self(
+            title: $data['title'],
+            integerOnly: $integerOnly,
+            description: $data['description'] ?? null,
+            default: $data['default'] ?? null,
+            minimum: $data['minimum'] ?? null,
+            maximum: $data['maximum'] ?? null,
+        );
+    }
+
+    /**
+     * @return array{
+     *     type: string,
+     *     title: string,
+     *     description?: string,
+     *     default?: int|float,
+     *     minimum?: int|float,
+     *     maximum?: int|float,
+     * }
+     */
+    public function jsonSerialize(): array
+    {
+        $data = $this->buildBaseJson($this->integerOnly ? 'integer' : 'number');
+
+        if (null !== $this->default) {
+            $data['default'] = $this->default;
+        }
+
+        if (null !== $this->minimum) {
+            $data['minimum'] = $this->minimum;
+        }
+
+        if (null !== $this->maximum) {
+            $data['maximum'] = $this->maximum;
+        }
+
+        return $data;
+    }
+}

src/Schema/Elicitation/PrimitiveSchemaDefinition.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * Factory class for creating primitive schema definitions from array data.
+ *
+ * Dispatches to the correct schema definition class based on the "type" field.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class PrimitiveSchemaDefinition
+{
+    /**
+     * Create a schema definition from array data.
+     *
+     * @param array{
+     *     type: string,
+     *     title: string,
+     *     description?: string,
+     *     default?: mixed,
+     *     enum?: string[],
+     *     enumNames?: string[],
+     *     format?: string,
+     *     minLength?: int,
+     *     maxLength?: int,
+     *     minimum?: int|float,
+     *     maximum?: int|float,
+     * } $data
+     */
+    public static function fromArray(array $data): StringSchemaDefinition|NumberSchemaDefinition|BooleanSchemaDefinition|EnumSchemaDefinition
+    {
+        if (!isset($data['type']) || !\is_string($data['type'])) {
+            throw new InvalidArgumentException('Missing or invalid "type" for primitive schema definition.');
+        }
+
+        return match ($data['type']) {
+            'string' => isset($data['enum']) ? EnumSchemaDefinition::fromArray($data) : StringSchemaDefinition::fromArray($data),
+            'integer', 'number' => NumberSchemaDefinition::fromArray($data),
+            'boolean' => BooleanSchemaDefinition::fromArray($data),
+            default => throw new InvalidArgumentException(\sprintf('Unsupported primitive type "%s". Supported types are: string, integer, number, boolean.', $data['type'])),
+        };
+    }
+}

src/Schema/Elicitation/StringSchemaDefinition.php

@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Elicitation;
+
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * Schema definition for string fields in elicitation requests.
+ *
+ * Supports optional format validation (date, date-time, email, uri) and length constraints.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class StringSchemaDefinition extends AbstractSchemaDefinition
+{
+    private const VALID_FORMATS = ['date', 'date-time', 'email', 'uri'];
+
+    /**
+     * @param string      $title       Human-readable title for the field
+     * @param string|null $description Optional description/help text
+     * @param string|null $default     Optional default value
+     * @param string|null $format      Optional format constraint (date, date-time, email, uri)
+     * @param int|null    $minLength   Optional minimum string length
+     * @param int|null    $maxLength   Optional maximum string length
+     */
+    public function __construct(
+        string $title,
+        ?string $description = null,
+        public readonly ?string $default = null,
+        public readonly ?string $format = null,
+        public readonly ?int $minLength = null,
+        public readonly ?int $maxLength = null,
+    ) {
+        parent::__construct($title, $description);
+
+        if (null !== $format && !\in_array($format, self::VALID_FORMATS, true)) {
+            throw new InvalidArgumentException(\sprintf('Invalid format "%s". Valid formats are: %s.', $format, implode(', ', self::VALID_FORMATS)));
+        }
+
+        if (null !== $minLength && $minLength < 0) {
+            throw new InvalidArgumentException('minLength must be non-negative.');
+        }
+
+        if (null !== $maxLength && $maxLength < 0) {
+            throw new InvalidArgumentException('maxLength must be non-negative.');
+        }
+
+        if (null !== $minLength && null !== $maxLength && $minLength > $maxLength) {
+            throw new InvalidArgumentException('minLength cannot be greater than maxLength.');
+        }
+    }
+
+    /**
+     * @param array{
+     *     title: string,
+     *     description?: string,
+     *     default?: string,
+     *     format?: string,
+     *     minLength?: int,
+     *     maxLength?: int,
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        self::validateTitle($data, 'string');
+
+        return new self(
+            title: $data['title'],
+            description: $data['description'] ?? null,
+            default: $data['default'] ?? null,
+            format: $data['format'] ?? null,
+            minLength: isset($data['minLength']) ? (int) $data['minLength'] : null,
+            maxLength: isset($data['maxLength']) ? (int) $data['maxLength'] : null,
+        );
+    }
+
+    /**
+     * @return array{
+     *     type: string,
+     *     title: string,
+     *     description?: string,
+     *     default?: string,
+     *     format?: string,
+     *     minLength?: int,
+     *     maxLength?: int,
+     * }
+     */
+    public function jsonSerialize(): array
+    {
+        $data = $this->buildBaseJson('string');
+
+        if (null !== $this->default) {
+            $data['default'] = $this->default;
+        }
+
+        if (null !== $this->format) {
+            $data['format'] = $this->format;
+        }
+
+        if (null !== $this->minLength) {
+            $data['minLength'] = $this->minLength;
+        }
+
+        if (null !== $this->maxLength) {
+            $data['maxLength'] = $this->maxLength;
+        }
+
+        return $data;
+    }
+}

src/Schema/Enum/ElicitAction.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Enum;
+
+/**
+ * Action taken by the user in response to an elicitation request.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+enum ElicitAction: string
+{
+    case Accept = 'accept';
+    case Decline = 'decline';
+    case Cancel = 'cancel';
+}

src/Schema/Request/ElicitRequest.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Request;
+
+use Mcp\Exception\InvalidArgumentException;
+use Mcp\Schema\Elicitation\ElicitationSchema;
+use Mcp\Schema\JsonRpc\Request;
+
+/**
+ * A request from the server to elicit additional information from the user.
+ *
+ * The client will present the message and requested schema to the user, allowing them
+ * to provide the requested information, decline, or cancel the operation.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class ElicitRequest extends Request
+{
+    /**
+     * @param string            $message         A human-readable message describing what information is needed
+     * @param ElicitationSchema $requestedSchema The schema defining the fields to elicit from the user
+     */
+    public function __construct(
+        public readonly string $message,
+        public readonly ElicitationSchema $requestedSchema,
+    ) {
+    }
+
+    public static function getMethod(): string
+    {
+        return 'elicitation/create';
+    }
+
+    protected static function fromParams(?array $params): static
+    {
+        if (!isset($params['message']) || !\is_string($params['message'])) {
+            throw new InvalidArgumentException('Missing or invalid "message" parameter for elicitation/create.');
+        }
+
+        if (!isset($params['requestedSchema']) || !\is_array($params['requestedSchema'])) {
+            throw new InvalidArgumentException('Missing or invalid "requestedSchema" parameter for elicitation/create.');
+        }
+
+        return new self(
+            $params['message'],
+            ElicitationSchema::fromArray($params['requestedSchema']),
+        );
+    }
+
+    /**
+     * @return array{
+     *     message: string,
+     *     requestedSchema: ElicitationSchema,
+     * }
+     */
+    protected function getParams(): array
+    {
+        return [
+            'message' => $this->message,
+            'requestedSchema' => $this->requestedSchema,
+        ];
+    }
+}

src/Schema/Result/ElicitResult.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Result;
+
+use Mcp\Exception\InvalidArgumentException;
+use Mcp\Schema\Enum\ElicitAction;
+use Mcp\Schema\JsonRpc\ResultInterface;
+
+/**
+ * The client's response to an elicitation/create request from the server.
+ *
+ * Contains the user's action (accept, decline, or cancel) and the content
+ * they provided when accepting.
+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+final class ElicitResult implements ResultInterface
+{
+    /**
+     * @param ElicitAction              $action  The user's action in response to the elicitation
+     * @param array<string, mixed>|null $content The content provided by the user (only present when action is "accept")
+     */
+    public function __construct(
+        public readonly ElicitAction $action,
+        public readonly ?array $content = null,
+    ) {
+    }
+
+    /**
+     * @param array{action: string, content?: array<string, mixed>} $data
+     */
+    public static function fromArray(array $data): self
+    {
+        if (!isset($data['action']) || !\is_string($data['action'])) {
+            throw new InvalidArgumentException('Missing or invalid "action" in ElicitResult data.');
+        }
+
+        $action = ElicitAction::from($data['action']);
+        $content = isset($data['content']) && \is_array($data['content']) ? $data['content'] : null;
+
+        if (ElicitAction::Accept === $action && null === $content) {
+            throw new InvalidArgumentException('Content must be provided when action is "accept".');
+        }
+
+        return new self($action, $content);
+    }
+
+    public function isAccepted(): bool
+    {
+        return ElicitAction::Accept === $this->action;
+    }
+
+    public function isDeclined(): bool
+    {
+        return ElicitAction::Decline === $this->action;
+    }
+
+    public function isCancelled(): bool
+    {
+        return ElicitAction::Cancel === $this->action;
+    }
+
+    /**
+     * @return array{action: string, content?: array<string, mixed>}
+     */
+    public function jsonSerialize(): array
+    {
+        $result = [
+            'action' => $this->action->value,
+        ];
+
+        if (null !== $this->content) {
+            $result['content'] = $this->content;
+        }
+
+        return $result;
+    }
+}

src/Server/ClientGateway.php

@@ -19,6 +19,7 @@ use Mcp\Schema\Content\Content;
 use Mcp\Schema\Content\ImageContent;
 use Mcp\Schema\Content\SamplingMessage;
 use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Elicitation\ElicitationSchema;
 use Mcp\Schema\Enum\LoggingLevel;
 use Mcp\Schema\Enum\Role;
 use Mcp\Schema\Enum\SamplingContext;
@@ -30,7 +31,9 @@ use Mcp\Schema\ModelPreferences;
 use Mcp\Schema\Notification\LoggingMessageNotification;
 use Mcp\Schema\Notification\ProgressNotification;
 use Mcp\Schema\Request\CreateSamplingMessageRequest;
+use Mcp\Schema\Request\ElicitRequest;
 use Mcp\Schema\Result\CreateSamplingMessageResult;
+use Mcp\Schema\Result\ElicitResult;
 use Mcp\Server\Session\SessionInterface;
 
 /**
@@ -158,6 +161,50 @@ class ClientGateway
         return CreateSamplingMessageResult::fromArray($response->result);
     }
 
+    /**
+     * Convenience method for elicitation requests.
+     *
+     * Requests additional information from the user via the client. The user can
+     * accept (providing the requested data), decline, or cancel the request.
+     *
+     * @param string            $message         A human-readable message describing what information is needed
+     * @param ElicitationSchema $requestedSchema The schema defining the fields to elicit from the user
+     * @param int               $timeout         The timeout in seconds
+     *
+     * @return ElicitResult The elicitation response containing the user's action and any provided content
+     *
+     * @throws ClientException if the client request results in an error message
+     */
+    public function elicit(string $message, ElicitationSchema $requestedSchema, int $timeout = 120): ElicitResult
+    {
+        $request = new ElicitRequest($message, $requestedSchema);
+
+        $response = $this->request($request, $timeout);
+
+        if ($response instanceof Error) {
+            throw new ClientException($response);
+        }
+
+        return ElicitResult::fromArray($response->result);
+    }
+
+    /**
+     * Check if the connected client supports elicitation.
+     *
+     * Elicitation allows servers to request additional information from users
+     * during tool execution. This method checks the client's advertised capabilities
+     * to determine if elicitation/create requests are supported.
+     *
+     * @return bool True if the client supports elicitation, false otherwise
+     */
+    public function supportsElicitation(): bool
+    {
+        $capabilities = $this->session->get('client_capabilities', []);
+
+        // MCP spec: capability presence indicates support (value is typically {} or [])
+        return \array_key_exists('elicitation', $capabilities);
+    }
+
     /**
      * Send a request to the client and wait for a response (blocking).
      *

src/Server/Handler/Request/InitializeHandler.php

@@ -45,6 +45,7 @@ final class InitializeHandler implements RequestHandlerInterface
         \assert($request instanceof InitializeRequest);
 
         $session->set('client_info', $request->clientInfo->jsonSerialize());
+        $session->set('client_capabilities', $request->capabilities->jsonSerialize());
 
         return new Response(
             $request->getId(),

src/Server/Session/Session.php

@@ -25,6 +25,7 @@ class Session implements SessionInterface
      * Official keys are:
      * - initialized: bool
      * - client_info: array|null
+     * - client_capabilities: array|null
      * - protocol_version: string|null
      * - log_level: string|null
      *