Add elicitation support for server-to-client user input requests

[wachterjohannes]

Motivation and Context

This PR implements the elicitation feature from the MCP specification (2025-06-18), which allows servers to request additional information from users during tool execution via the elicitation/create method.

Elicitation enables interactive workflows where the server can:

• Ask for user preferences or choices
• Collect form data with validated fields
• Request confirmation before performing actions

This is particularly useful for tools that need dynamic user input that can't be determined upfront.

How Has This Been Tested?

• Unit tests: 87 new tests covering all elicitation classes
• PHPStan: No errors at configured level
• Integration testing: Tested with OpenCode PR #8243 which adds elicitation client support
  • Verified book_restaurant tool with multi-field form (number, date, enum)
  • Verified confirm_action tool with boolean confirmation
  • Verified collect_feedback tool with rating enum and optional comments
  • Tested accept, decline, and cancel user responses

Breaking Changes

None. This is a purely additive feature.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

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

Additional context

Files added

Schema definitions (src/Schema/Elicitation/):

• StringSchemaDefinition - String fields with optional format (date, email, uri), minLength, maxLength
• NumberSchemaDefinition - Integer/number fields with min/max validation
• BooleanSchemaDefinition - Boolean checkbox fields
• EnumSchemaDefinition - String enums with optional human-readable labels (enumNames)
• PrimitiveSchemaDefinition - Factory for deserializing schema definitions
• ElicitationSchema - Wrapper for the requestedSchema object

Request/Result (src/Schema/):

• Enum/ElicitAction - User response actions (accept, decline, cancel)
• Request/ElicitRequest - The elicitation/create request
• Result/ElicitResult - The client's response with convenience methods (isAccepted(), isDeclined(), isCancelled())

Server changes:

• ClientGateway::elicit() - Convenience method for sending elicitation requests
• InitializeHandler - Now stores client capabilities in session for capability checking

Example (examples/server/elicitation/):

• Complete working example with three tools demonstrating different elicitation patterns
• Includes capability checking for graceful fallback when client doesn't support elicitation

Protocol details

Request format:

{
  "method": "elicitation/create",
  "params": {
    "message": "Please provide your reservation details:",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "party_size": { "type": "integer", "minimum": 1, "maximum": 20 },
        "date": { "type": "string", "format": "date" }
      },
      "required": ["party_size", "date"]
    }
  }
}

Response format:

{
  "action": "accept",
  "content": { "party_size": 4, "date": "2025-02-14" }
}

Link to the MCP Specification: https://modelcontextprotocol.io/specification/draft/client/elicitation

[wachterjohannes]

@chr-hertel @Nyholm i am not totally happy with the code - have to rework a bit in the next days - but maybe there is already some feedback about it :)

[chr-hertel]

Thank you @wachterjohannes for working on this! I think for a first iteration we can go ahead, especially the schema extension with nov release can be a follow up 👍

what's missing from your point of view?

[chr-hertel]

from DX point of view i think it would be great to support

enum: ['none', 'vegetarian'], // with values being name and value
// or
enum: ['None' => 'none', 'Vegetarian' => 'vegetarian'], // with index being name and values being value
// or
enum: Diet::class, // with Diet being a backed enum

follow up tho 👍

[chr-hertel]

Please have a look at the conformance scenario tools-call-elicitation, elicitation-sep1034-defaults and elicitation-sep1330-enums can be follow-ups if i get it right. requires rebase, but needed anyways.

[chr-hertel]

BTW, tested the reservation example with goose - works like a charm! 👍

[wachterjohannes]

Follow-ups (Separate PRs)

Conformance Test Scenarios - Listed in conformance-baseline.yml but implementations not yet added to tests/Conformance/server.php:

• tools-call-elicitation - Test tool execution flow with elicitation request/response handling
• elicitation-sep1034-defaults - Test default value handling in elicitation schemas per SEP-1034 specification
• elicitation-sep1330-enums - Test enum field validation and enumNames mapping per SEP-1330 specification

These conformance tests validate elicitation behavior against the MCP specification but aren't blocking since the core feature is working (demonstrated in the examples).

Enum DX Enhancement - Developer experience improvement for enum definitions:

• Support multiple enum definition approaches (e.g., associative arrays, value-label pairs)
• Make enum field creation more ergonomic and intuitive
• Maintain backward compatibility with current string array approach

This was noted as a future improvement in the initial review and doesn't impact current functionality.

[wachterjohannes]

@chr-hertel TBH totally forgotten this 😂 Now i am happy with it :)