feat/2025-11-25: sampling, elicitation, roots (#198)

* feat: Roots implementation

* feat: added unit testing

* feat: improved unit tests and fixed NetworkTransport crash

* feat: implemented sampling and elicitation

* feat: improved sampling tests

* feat: improved elicitation tests

* feat: improved confirmance tests

* feat: improved Prompts unit tests

* feat: removed test code

* feat: updated conformance tests

Author: yehorsobko-mac

Sources/MCP/Base/Error.swift

@@ -6,6 +6,25 @@ import Foundation
     @preconcurrency import SystemPackage
 #endif
 
+/// Information about a required URL elicitation
+public struct URLElicitationInfo: Codable, Hashable, Sendable {
+    /// Elicitation mode (must be "url")
+    public var mode: String
+    /// Unique identifier for this elicitation
+    public var elicitationId: String
+    /// URL for the user to visit
+    public var url: String
+    /// Message describing the elicitation
+    public var message: String
+
+    public init(mode: String = "url", elicitationId: String, url: String, message: String) {
+        self.mode = mode
+        self.elicitationId = elicitationId
+        self.url = url
+        self.message = message
+    }
+}
+
 /// A model context protocol error.
 public enum MCPError: Swift.Error, Sendable {
     // Standard JSON-RPC 2.0 errors (-32700 to -32603)
@@ -18,6 +37,9 @@ public enum MCPError: Swift.Error, Sendable {
     // Server errors (-32000 to -32099)
     case serverError(code: Int, message: String)
 
+    // MCP specific errors
+    case urlElicitationRequired(message: String, elicitations: [URLElicitationInfo])  // -32042
+
     // Transport specific errors
     case connectionClosed
     case transportError(Swift.Error)
@@ -31,6 +53,7 @@ public enum MCPError: Swift.Error, Sendable {
         case .invalidParams: return -32602
         case .internalError: return -32603
         case .serverError(let code, _): return code
+        case .urlElicitationRequired: return -32042
         case .connectionClosed: return -32000
         case .transportError: return -32001
         }
@@ -68,6 +91,8 @@ extension MCPError: LocalizedError {
             return "Internal error" + (detail.map { ": \($0)" } ?? "")
         case .serverError(_, let message):
             return "Server error: \(message)"
+        case .urlElicitationRequired(let message, _):
+            return "URL elicitation required: \(message)"
         case .connectionClosed:
             return "Connection closed"
         case .transportError(let error):
@@ -89,6 +114,8 @@ extension MCPError: LocalizedError {
             return "Internal JSON-RPC error"
         case .serverError:
             return "Server-defined error occurred"
+        case .urlElicitationRequired:
+            return "The server requires user authentication or input via external URL"
         case .connectionClosed:
             return "The connection to the server was closed"
         case .transportError(let error):
@@ -106,6 +133,11 @@ extension MCPError: LocalizedError {
             return "Check the method name and ensure it is supported by the server"
         case .invalidParams:
             return "Verify the parameters match the method's expected parameters"
+        case .urlElicitationRequired(_, let elicitations):
+            if let first = elicitations.first {
+                return "Visit \(first.url) to complete the required authentication or input"
+            }
+            return "Complete the required URL-based elicitation"
         case .connectionClosed:
             return "Try reconnecting to the server"
         default:
@@ -154,6 +186,20 @@ extension MCPError: Codable {
         case .serverError(_, _):
             // No additional data for server errors
             break
+        case .urlElicitationRequired(_, let elicitations):
+            // Encode elicitations array as structured data
+            let elicitationsData = elicitations.map { info -> [String: Value] in
+                return [
+                    "mode": .string(info.mode),
+                    "elicitationId": .string(info.elicitationId),
+                    "url": .string(info.url),
+                    "message": .string(info.message)
+                ]
+            }
+            try container.encode(
+                ["elicitations": Value.array(elicitationsData.map { .object($0) })],
+                forKey: .data
+            )
         case .connectionClosed:
             break
         case .transportError(let error):
@@ -188,6 +234,25 @@ extension MCPError: Codable {
             self = .invalidParams(unwrapDetail(message))
         case -32603:
             self = .internalError(unwrapDetail(nil))
+        case -32042:
+            // Extract elicitations array from data
+            var elicitations: [URLElicitationInfo] = []
+            if case .array(let items) = data?["elicitations"] {
+                for item in items {
+                    if case .object(let dict) = item,
+                       case .string(let mode) = dict["mode"],
+                       case .string(let elicitationId) = dict["elicitationId"],
+                       case .string(let url) = dict["url"],
+                       case .string(let msg) = dict["message"] {
+                        elicitations.append(URLElicitationInfo(
+                            mode: mode,
+                            elicitationId: elicitationId,
+                            url: url,
+                            message: msg))
+                    }
+                }
+            }
+            self = .urlElicitationRequired(message: message, elicitations: elicitations)
         case -32000:
             self = .connectionClosed
         case -32001:
@@ -236,6 +301,9 @@ extension MCPError: Hashable {
             hasher.combine(detail)
         case .serverError(_, let message):
             hasher.combine(message)
+        case .urlElicitationRequired(let message, let elicitations):
+            hasher.combine(message)
+            hasher.combine(elicitations)
         case .connectionClosed:
             break
         case .transportError(let error):

Sources/MCP/Base/Transports/HTTPClientTransport.swift

@@ -444,25 +444,28 @@ public actor HTTPClientTransport: Transport {
             guard isConnected else { return }
 
             // Wait for session ID to be available before opening SSE stream
-            if self.sessionID == nil {
+            if self.sessionID == nil, let signalTask = self.initialSessionIDSignalTask {
                 logger.debug("⏳ Waiting for session ID to be set (timeout: \(self.sseInitializationTimeout)s)...")
 
                 let startTime = Date()
                 let timeout = self.sseInitializationTimeout
-
-                // Poll for session ID with exponential backoff
-                var attempt = 0
-                while self.sessionID == nil && !Task.isCancelled {
-                    let elapsed = Date().timeIntervalSince(startTime)
-                    if elapsed >= timeout {
-                        logger.warning("⏱️ Timeout waiting for session ID (\(timeout)s). SSE stream will proceed anyway.")
-                        break
+                do {
+                    try await withThrowingTaskGroup { group in
+                        group.addTask {
+                            try await Task.sleep(for: .seconds(timeout))
+                        }
+
+                        group.addTask {
+                            await signalTask.value
+                        }
+
+                        if let firstResult = try await group.next() {
+                            group.cancelAll()
+                            return firstResult
+                        }
                     }
-
-                    // Exponential backoff: 10ms, 20ms, 50ms, 100ms, 200ms, then 500ms
-                    let delay = min(500, max(10, 10 * (1 << attempt)))
-                    try? await Task.sleep(for: .milliseconds(delay))
-                    attempt += 1
+                } catch {
+                    logger.warning("⏱️ Timeout waiting for session ID (\(timeout)s). SSE stream will proceed anyway.")
                 }
 
                 if self.sessionID != nil {

Sources/MCP/Base/Transports/HTTPServer/StatefulHTTPServerTransport.swift

@@ -370,24 +370,34 @@ public actor StatefulHTTPServerTransport: Transport {
 
     // MARK: - Message Routing
 
-    private func routeResponse(_ data: Data, requestID: String) {
+    /// Routes a message to a specific request's SSE stream without closing it.
+    /// Used for server-initiated messages during request handling.
+    private func routeToRequestStream(_ data: Data, requestID: String) {
         let eventID = storeEvent(streamID: requestID, message: data)
 
         guard let continuation = requestSSEContinuations[requestID] else {
             logger.debug(
-                "No active stream for request, response stored for replay",
+                "No active stream for request, message stored for replay",
                 metadata: ["requestID": "\(requestID)"]
             )
             return
         }
 
-        // Format as SSE and yield
+        // Format as SSE and yield (but don't close the stream)
         let sseEvent = SSEEvent.message(data: data, id: eventID)
         continuation.yield(sseEvent.formatted())
+    }
+
+    /// Routes a response to a specific request's SSE stream and closes it.
+    /// Used for final responses to client requests.
+    private func routeResponse(_ data: Data, requestID: String) {
+        routeToRequestStream(data, requestID: requestID)
 
         // Response means the request is complete — close the stream
-        continuation.finish()
-        requestSSEContinuations.removeValue(forKey: requestID)
+        if let continuation = requestSSEContinuations[requestID] {
+            continuation.finish()
+            requestSSEContinuations.removeValue(forKey: requestID)
+        }
     }
 
     private func routeServerInitiatedMessage(_ data: Data) {