Improve elicitation SDK design and documentation

Move supportsElicitation() capability check from example code to the
ClientGateway class as a public method, making it part of the official
SDK API. This eliminates code duplication and provides a consistent way
for all tools to check client capabilities.

- Add ClientGateway::supportsElicitation() public method
- Remove duplicate capability check from ElicitationHandlers example
- Update all example tools to use SDK method via ClientGateway
- Add @author tags to all 6 elicitation schema classes
- Remove inline comments from example server (keep header doc)
- Add comprehensive elicitation section to examples.md with usage
  examples, important notes, and tool descriptions

Author: wachterjohannes

docs/examples.md

@@ -276,3 +276,80 @@ public function formatText(
     string $format = 'sentence'
 ): array
 ```
+
+### Elicitation
+
+**File**: `examples/server/elicitation/`
+
+**What it demonstrates:**
+- Server-to-client elicitation requests
+- Interactive user input during tool execution
+- Multi-field form schemas with validation
+- Boolean confirmation dialogs
+- Enum fields with human-readable labels
+- Handling accept/decline/cancel responses
+- Session persistence requirement for server-initiated requests
+
+**Key Features:**
+```php
+// Check client support before eliciting
+if (!$context->getClientGateway()->supportsElicitation()) {
+    return ['status' => 'error', 'message' => 'Client does not support elicitation'];
+}
+
+// Build schema with multiple field types
+$schema = new ElicitationSchema(
+    properties: [
+        'party_size' => new NumberSchemaDefinition(
+            title: 'Party Size',
+            integerOnly: true,
+            minimum: 1,
+            maximum: 20
+        ),
+        'date' => new StringSchemaDefinition(
+            title: 'Reservation Date',
+            format: 'date'
+        ),
+        'dietary' => new EnumSchemaDefinition(
+            title: 'Dietary Restrictions',
+            enum: ['none', 'vegetarian', 'vegan'],
+            enumNames: ['None', 'Vegetarian', 'Vegan']
+        ),
+    ],
+    required: ['party_size', 'date']
+);
+
+// Send elicitation request
+$result = $client->elicit(
+    message: 'Please provide your reservation details',
+    requestedSchema: $schema
+);
+
+// Handle response
+if ($result->isAccepted()) {
+    $data = $result->content; // User-provided data
+} elseif ($result->isDeclined() || $result->isCancelled()) {
+    // User declined or cancelled
+}
+```
+
+**Important Notes:**
+- Elicitation requires a session store (e.g., `FileSessionStore`)
+- Check client capabilities with `supportsElicitation()` before sending requests
+- Schema supports primitive types: string, number/integer, boolean, enum
+- String fields support format validation: date, date-time, email, uri
+- Users can accept (providing data), decline, or cancel requests
+
+**Usage:**
+```bash
+# Interactive testing with MCP client that supports elicitation
+npx @modelcontextprotocol/inspector php examples/server/elicitation/server.php
+
+# Test with Goose (confirmed working by reviewer)
+# Or configure in Claude Desktop or other MCP clients
+```
+
+**Example Tools:**
+1. **book_restaurant** - Multi-field reservation form with number, date, and enum fields
+2. **confirm_action** - Simple boolean confirmation dialog
+3. **collect_feedback** - Rating and comments form with optional fields

examples/server/elicitation/ElicitationHandlers.php

@@ -37,17 +37,6 @@ public function __construct(
         $this->logger->info('ElicitationHandlers instantiated.');
     }
 
-    /**
-     * Check if the client supports elicitation.
-     */
-    private function clientSupportsElicitation(RequestContext $context): bool
-    {
-        $capabilities = $context->getSession()->get('client_capabilities', []);
-
-        // MCP spec: capability presence indicates support (value is typically {} or [])
-        return \array_key_exists('elicitation', $capabilities);
-    }
-
     /**
      * Book a restaurant reservation with user elicitation.
      *
@@ -61,7 +50,7 @@ private function clientSupportsElicitation(RequestContext $context): bool
     #[McpTool('book_restaurant', 'Book a restaurant reservation, collecting details via elicitation.')]
     public function bookRestaurant(RequestContext $context, string $restaurantName): array
     {
-        if (!$this->clientSupportsElicitation($context)) {
+        if (!$context->getClientGateway()->supportsElicitation()) {
             return [
                 'status' => 'error',
                 'message' => 'Client does not support elicitation. Please provide reservation details (party_size, date, dietary) as tool parameters instead.',
@@ -160,7 +149,7 @@ enumNames: ['None', 'Vegetarian', 'Vegan', 'Gluten-Free', 'Halal', 'Kosher'],
     #[McpTool('confirm_action', 'Request user confirmation before proceeding with an action.')]
     public function confirmAction(RequestContext $context, string $actionDescription): array
     {
-        if (!$this->clientSupportsElicitation($context)) {
+        if (!$context->getClientGateway()->supportsElicitation()) {
             return [
                 'status' => 'error',
                 'message' => 'Client does not support elicitation. Please confirm the action explicitly in your request.',
@@ -219,7 +208,7 @@ public function confirmAction(RequestContext $context, string $actionDescription
     #[McpTool('collect_feedback', 'Collect user feedback via elicitation form.')]
     public function collectFeedback(RequestContext $context, string $topic): array
     {
-        if (!$this->clientSupportsElicitation($context)) {
+        if (!$context->getClientGateway()->supportsElicitation()) {
             return [
                 'status' => 'error',
                 'message' => 'Client does not support elicitation. Please provide feedback (rating 1-5, comments) as tool parameters instead.',

examples/server/elicitation/server.php

@@ -13,29 +13,10 @@
  */
 
 /**
- * MCP Elicitation Example Server
+ * MCP Elicitation Example Server.
  *
- * This example demonstrates the elicitation feature which allows servers to
- * request additional information from users during tool execution.
- *
- * Elicitation enables interactive workflows where the server can:
- * - Ask for user preferences or choices
- * - Collect form data with validated fields
- * - Request confirmation before actions
- *
- * The server provides three example tools:
- * 1. book_restaurant - Multi-field form with number, date, and enum fields
- * 2. confirm_action - Simple boolean confirmation dialog
- * 3. collect_feedback - Rating and comments form with optional fields
- *
- * IMPORTANT: Elicitation requires:
- * - A session store (FileSessionStore is used here)
- * - Client support for elicitation (check client capabilities)
- *
- * Usage:
- *   php server.php
- *
- * The server will start in stdio mode and wait for MCP client connections.
+ * Demonstrates server-to-client elicitation for interactive user input during tool execution.
+ * See docs/examples.md for detailed documentation and usage examples.
  */
 
 require_once dirname(__DIR__).'/bootstrap.php';
@@ -49,10 +30,8 @@
     ->setServerInfo('Elicitation Demo', '1.0.0')
     ->setLogger(logger())
     ->setContainer(container())
-    // Session store is REQUIRED for server-to-client requests like elicitation
     ->setSession(new FileSessionStore(__DIR__.'/sessions'))
     ->setCapabilities(new ServerCapabilities(logging: true, tools: true))
-    // Auto-discover tools from ElicitationHandlers class
     ->setDiscovery(__DIR__)
     ->build();
 

src/Schema/Elicitation/BooleanSchemaDefinition.php

@@ -18,7 +18,7 @@
 /**
  * Schema definition for boolean fields in elicitation requests.
  *
- * @author
+ * @author Johannes Wachter <johannes@sulu.io>
  */
 final class BooleanSchemaDefinition implements \JsonSerializable
 {

src/Schema/Elicitation/ElicitationSchema.php

@@ -20,7 +20,7 @@
  *
  * Represents an object schema with primitive property definitions and optional required fields.
  *
- * @author
+ * @author Johannes Wachter <johannes@sulu.io>
  */
 final class ElicitationSchema implements \JsonSerializable
 {
@@ -38,10 +38,7 @@ public function __construct(
 
         foreach ($required as $name) {
             if (!\array_key_exists($name, $properties)) {
-                throw new InvalidArgumentException(\sprintf(
-                    'Required property "%s" is not defined in properties.',
-                    $name
-                ));
+                throw new InvalidArgumentException(\sprintf('Required property "%s" is not defined in properties.', $name));
             }
         }
     }
@@ -68,10 +65,7 @@ public static function fromArray(array $data): self
         $properties = [];
         foreach ($data['properties'] as $name => $propertyData) {
             if (!\is_array($propertyData)) {
-                throw new InvalidArgumentException(\sprintf(
-                    'Property "%s" must be an array.',
-                    $name
-                ));
+                throw new InvalidArgumentException(\sprintf('Property "%s" must be an array.', $name));
             }
             $properties[$name] = PrimitiveSchemaDefinition::fromArray($propertyData);
         }

src/Schema/Elicitation/EnumSchemaDefinition.php

@@ -20,7 +20,7 @@
  *
  * Provides a list of allowed values with optional human-readable labels.
  *
- * @author
+ * @author Johannes Wachter <johannes@sulu.io>
  */
 final class EnumSchemaDefinition implements \JsonSerializable
 {
@@ -53,10 +53,7 @@ public function __construct(
         }
 
         if (null !== $default && !\in_array($default, $enum, true)) {
-            throw new InvalidArgumentException(\sprintf(
-                'Default value "%s" is not in the enum array.',
-                $default
-            ));
+            throw new InvalidArgumentException(\sprintf('Default value "%s" is not in the enum array.', $default));
         }
     }
 

src/Schema/Elicitation/NumberSchemaDefinition.php

@@ -20,17 +20,17 @@
  *
  * Supports minimum and maximum value constraints.
  *
- * @author
+ * @author Johannes Wachter <johannes@sulu.io>
  */
 final class NumberSchemaDefinition implements \JsonSerializable
 {
     /**
-     * @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)
+     * @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(
         public readonly string $title,

src/Schema/Elicitation/PrimitiveSchemaDefinition.php

@@ -20,7 +20,7 @@
  *
  * Dispatches to the correct schema definition class based on the "type" field.
  *
- * @author
+ * @author Johannes Wachter <johannes@sulu.io>
  */
 final class PrimitiveSchemaDefinition
 {
@@ -40,8 +40,6 @@ final class PrimitiveSchemaDefinition
      *     minimum?: int|float,
      *     maximum?: int|float,
      * } $data
-     *
-     * @return StringSchemaDefinition|NumberSchemaDefinition|BooleanSchemaDefinition|EnumSchemaDefinition
      */
     public static function fromArray(array $data): StringSchemaDefinition|NumberSchemaDefinition|BooleanSchemaDefinition|EnumSchemaDefinition
     {
@@ -53,10 +51,7 @@ public static function fromArray(array $data): StringSchemaDefinition|NumberSche
             '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']
-            )),
+            default => throw new InvalidArgumentException(\sprintf('Unsupported primitive type "%s". Supported types are: string, integer, number, boolean.', $data['type'])),
         };
     }
 }

src/Schema/Elicitation/StringSchemaDefinition.php

@@ -20,7 +20,7 @@
  *
  * Supports optional format validation (date, date-time, email, uri) and length constraints.
  *
- * @author
+ * @author Johannes Wachter <johannes@sulu.io>
  */
 final class StringSchemaDefinition implements \JsonSerializable
 {
@@ -43,11 +43,7 @@ public function __construct(
         public readonly ?int $maxLength = null,
     ) {
         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)
-            ));
+            throw new InvalidArgumentException(\sprintf('Invalid format "%s". Valid formats are: %s.', $format, implode(', ', self::VALID_FORMATS)));
         }
 
         if (null !== $minLength && $minLength < 0) {

src/Schema/Enum/ElicitAction.php

@@ -2,6 +2,15 @@
 
 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;
 
 /**