[Server] Elicitation Support for PHP MCP SDK

[e0ipso]

Is your feature request related to a problem? Please describe.

The PHP MCP SDK supports sampling but lacks elicitation. Without this, servers cannot ask for confirmations, collect configuration, or gather credentials through secure flows.

Describe the solution you'd like

Implement elicitation per MCP spec (2025-11-25) with two modes:

• Form Mode: Collect JSON Schema-validated input directly through the client
• URL Mode: Redirect to external URLs for sensitive data (OAuth, SSO)

Relationship to MCP Sampling

Elicitation mirrors sampling architecturally—both are server-initiated requests to the client that suspend execution via Fibers until a response arrives.

Aspect	Sampling	Elicitation
Purpose	Request LLM completion	Request user input
Gateway method	sample()	elicit(), elicitUrl()
Request class	CreateSamplingMessageRequest	CreateElicitationRequest
Result class	CreateSamplingMessageResult	CreateElicitationResult
Capability	ClientCapabilities->sampling	ClientCapabilities->elicitation
Trait exposure	ClientAwareTrait::sample()	ClientAwareTrait::elicit()

Abstractions

Leveraged (no changes):

• ClientGateway::request() — Fiber-based request/response handling
• ClientAwareTrait pattern — composition-based tool integration
• MessageFactory registration — message type discovery
• Schema base classes — Request, ResultInterface, Notification

Newly Introduced 🆕:

• ElicitationCapabilities — nested capability object (form/url granularity)
• ElicitationAction enum — accept/decline/cancel responses
• ElicitationMode enum — form vs url mode selection

Architecture

graph TB
    subgraph Schema["Schema Layer"]
        Request["Request/Result Schemas"]
        Enums["Action & Mode Enums"]
    end

    subgraph Server["Server Layer"]
        Gateway["ClientGateway<br/>elicit() / elicitUrl()"]
        Trait["ClientAwareTrait"]
    end

    subgraph Infra["Infrastructure Layer"]
        Capabilities["ClientCapabilities.elicitation<br/>(form, url)"]
        Factory["MessageFactory"]
    end

    Schema --> Gateway
    Gateway --> Trait
    Trait --> Infra

Loading

Opportunities

• Interactive tool workflows (wizards, confirmations)
• Secure credential collection via URL mode
• Schema-validated input before tool code runs

Describe alternatives you've considered

None.

Additional context

• Form schemas limited to flat objects with primitives (per spec)
• Actions: accept, decline, cancel — all must be handled
• Form mode: no sensitive data; URL mode: no credentials in URLs
• Error -32042 signals URL mode required before retry