feat(mcp): add URL-mode elicitation support (containers#862)

Extend the Elicitor interface to support URL-mode elicitation added in
go-sdk v1.4.0. Refactor Elicit() to accept an ElicitParams struct
(instead of separate message/schema arguments) with fields for both
form mode (Message, RequestedSchema) and URL mode (URL, ElicitationID).

Fix error detection for mode-specific unsupported elicitation errors
by matching all three go-sdk error variants.

Follow-up to containers#804.

Signed-off-by: Marc Nuri <[email protected]>

Author: manusa

internal/test/mcp.go

@@ -26,6 +26,7 @@ type mcpClientConfig struct {
 	endpoint             string
 	allowConnectionError bool
 	elicitationHandler   func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
+	capabilities         *mcp.ClientCapabilities
 }
 
 // httpHeaderOption sets custom HTTP headers
@@ -112,6 +113,21 @@ func WithElicitationHandler(handler func(context.Context, *mcp.ElicitRequest) (*
 	return elicitationHandlerOption{handler: handler}
 }
 
+// clientCapabilitiesOption sets custom client capabilities on the MCP client
+type clientCapabilitiesOption struct {
+	capabilities *mcp.ClientCapabilities
+}
+
+func (o clientCapabilitiesOption) apply(c *mcpClientConfig) {
+	c.capabilities = o.capabilities
+}
+
+// WithClientCapabilities sets explicit client capabilities on the MCP client.
+// This overrides capabilities inferred from handlers (e.g., elicitation mode support).
+func WithClientCapabilities(capabilities *mcp.ClientCapabilities) McpClientOption {
+	return clientCapabilitiesOption{capabilities: capabilities}
+}
+
 // headerRoundTripper injects HTTP headers into requests
 type headerRoundTripper struct {
 	base    http.RoundTripper
@@ -202,6 +218,7 @@ func NewMcpClient(t *testing.T, mcpHttpServer http.Handler, options ...McpClient
 	// Create go-sdk client with notification handlers
 	clientOptions := &mcp.ClientOptions{
 		ElicitationHandler: cfg.elicitationHandler,
+		Capabilities:       cfg.capabilities,
 		ToolListChangedHandler: func(_ context.Context, req *mcp.ToolListChangedRequest) {
 			ret.notifications.capture(&CapturedNotification{
 				Method: "notifications/tools/list_changed",

pkg/api/toolsets.go

@@ -110,10 +110,26 @@ type ToolHandlerFunc func(params ToolHandlerParams) (*ToolCallResult, error)
 
 // Elicitor provides a mechanism for tools and prompts to request additional information
 // from the user during execution via the MCP elicitation protocol.
-// The elicitation request is forwarded to the MCP client, which presents a form to the user.
+// It supports two modes:
+//   - Form mode: presents a schema-based form to the user (set Message and RequestedSchema in ElicitParams).
+//   - URL mode: directs the user to a URL (set Message, URL, and optionally ElicitationID in ElicitParams).
+//
 // See MCP specification: https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
 type Elicitor interface {
-	Elicit(ctx context.Context, message string, requestedSchema *jsonschema.Schema) (*ElicitResult, error)
+	Elicit(ctx context.Context, params *ElicitParams) (*ElicitResult, error)
+}
+
+// ElicitParams contains the parameters for an elicitation request.
+// The elicitation mode is inferred from the fields: if URL is set, URL mode is used; otherwise form mode.
+type ElicitParams struct {
+	// Message is the message to present to the user.
+	Message string
+	// RequestedSchema is a JSON Schema defining the expected form fields. Used in form mode only.
+	RequestedSchema *jsonschema.Schema
+	// URL is the URL to present to the user. Used in URL mode only.
+	URL string
+	// ElicitationID is a tracking identifier for out-of-band URL elicitation completion. Used in URL mode only.
+	ElicitationID string
 }
 
 // ElicitAction constants define the possible user responses to an elicitation request.
@@ -129,7 +145,7 @@ const (
 
 // ElicitResult represents the user's response to an elicitation request.
 type ElicitResult struct {
-	// Action is one of ElicitActionAccept, ElicitActionDecline, or ElicitActionCancel.
+	// Action is one of the ElicitAction constants.
 	Action string
 	// Content contains the submitted form data. Only populated when Action is ElicitActionAccept.
 	Content map[string]any

pkg/mcp/elicit.go

@@ -8,7 +8,6 @@ import (
 
 	"github.com/containers/kubernetes-mcp-server/pkg/api"
 	"github.com/containers/kubernetes-mcp-server/pkg/mcplog"
-	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
@@ -20,15 +19,24 @@ type sessionElicitor struct{}
 
 var _ api.Elicitor = &sessionElicitor{}
 
-func (s *sessionElicitor) Elicit(ctx context.Context, message string, requestedSchema *jsonschema.Schema) (*api.ElicitResult, error) {
+func (s *sessionElicitor) Elicit(ctx context.Context, params *api.ElicitParams) (*api.ElicitResult, error) {
 	session, ok := ctx.Value(mcplog.MCPSessionContextKey).(*mcp.ServerSession)
 	if !ok || session == nil {
 		return nil, fmt.Errorf("no MCP session found in context")
 	}
 
-	result, err := session.Elicit(ctx, &mcp.ElicitParams{Message: message, RequestedSchema: requestedSchema})
+	result, err := session.Elicit(ctx, &mcp.ElicitParams{
+		Message:         params.Message,
+		RequestedSchema: params.RequestedSchema,
+		URL:             params.URL,
+		ElicitationID:   params.ElicitationID,
+	})
 	if err != nil {
-		if strings.Contains(err.Error(), "does not support elicitation") {
+		// The go-sdk does not export a typed error for unsupported elicitation.
+		// This string check mirrors the go-sdk's own test approach (mcp/mcp_test.go).
+		// The go-sdk returns three variants: "client does not support elicitation",
+		// "client does not support "form" elicitation", and "client does not support "url" elicitation".
+		if strings.Contains(err.Error(), "does not support") && strings.Contains(err.Error(), "elicitation") {
 			return nil, fmt.Errorf("%w: %s", ErrElicitationNotSupported, err.Error())
 		}
 		return nil, err

pkg/mcp/elicit_test.go

@@ -3,6 +3,7 @@ package mcp
 import (
 	"context"
 	"errors"
+	"fmt"
 	"testing"
 
 	"github.com/containers/kubernetes-mcp-server/internal/test"
@@ -59,7 +60,7 @@ func (s *ElicitationSuite) registerElicitingToolset(handler api.ToolHandlerFunc)
 
 func (s *ElicitationSuite) TestElicitationAccepted() {
 	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
-		result, err := params.Elicit(params.Context, "Please confirm", nil)
+		result, err := params.Elicit(params.Context, &api.ElicitParams{Message: "Please confirm"})
 		if err != nil {
 			return nil, err
 		}
@@ -90,7 +91,7 @@ func (s *ElicitationSuite) TestElicitationAccepted() {
 
 func (s *ElicitationSuite) TestElicitationDeclined() {
 	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
-		result, err := params.Elicit(params.Context, "Please confirm", nil)
+		result, err := params.Elicit(params.Context, &api.ElicitParams{Message: "Please confirm"})
 		if err != nil {
 			return nil, err
 		}
@@ -118,7 +119,7 @@ func (s *ElicitationSuite) TestElicitationDeclined() {
 
 func (s *ElicitationSuite) TestElicitationWithUnsupportedClient() {
 	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
-		_, err := params.Elicit(params.Context, "Please confirm", nil)
+		_, err := params.Elicit(params.Context, &api.ElicitParams{Message: "Please confirm"})
 		if err != nil {
 			if errors.Is(err, ErrElicitationNotSupported) {
 				return api.NewToolCallResult("fallback-result", nil), nil
@@ -144,6 +145,121 @@ func (s *ElicitationSuite) TestElicitationWithUnsupportedClient() {
 	})
 }
 
+func (s *ElicitationSuite) TestElicitationURLAccepted() {
+	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
+		result, err := params.Elicit(params.Context, &api.ElicitParams{
+			Message: "Please complete the form",
+			URL:     "https://example.com/form",
+		})
+		if err != nil {
+			return nil, err
+		}
+		return api.NewToolCallResult("action="+result.Action, nil), nil
+	})
+
+	s.InitMcpClient(
+		test.WithElicitationHandler(
+			func(_ context.Context, _ *mcp.ElicitRequest) (*mcp.ElicitResult, error) {
+				return &mcp.ElicitResult{Action: "accept"}, nil
+			},
+		),
+		test.WithClientCapabilities(&mcp.ClientCapabilities{
+			Elicitation: &mcp.ElicitationCapabilities{
+				URL: &mcp.URLElicitationCapabilities{},
+			},
+		}),
+	)
+
+	toolResult, err := s.CallTool("elicit_test_tool", map[string]any{})
+
+	s.Run("returns accepted action for URL elicitation", func() {
+		s.NoError(err)
+		s.Require().NotNil(toolResult)
+		s.False(toolResult.IsError)
+		s.Require().Len(toolResult.Content, 1)
+		textContent, ok := toolResult.Content[0].(*mcp.TextContent)
+		s.Require().True(ok)
+		s.Equal("action=accept", textContent.Text)
+	})
+}
+
+func (s *ElicitationSuite) TestElicitationURLWithElicitationID() {
+	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
+		result, err := params.Elicit(params.Context, &api.ElicitParams{
+			Message:       "Please complete the form",
+			URL:           "https://example.com/form",
+			ElicitationID: "elicit-123",
+		})
+		if err != nil {
+			return nil, err
+		}
+		return api.NewToolCallResult("action="+result.Action, nil), nil
+	})
+
+	s.InitMcpClient(
+		test.WithElicitationHandler(
+			func(_ context.Context, req *mcp.ElicitRequest) (*mcp.ElicitResult, error) {
+				if req.Params.ElicitationID != "elicit-123" {
+					return nil, fmt.Errorf("expected elicitationID 'elicit-123', got '%s'", req.Params.ElicitationID)
+				}
+				return &mcp.ElicitResult{Action: "accept"}, nil
+			},
+		),
+		test.WithClientCapabilities(&mcp.ClientCapabilities{
+			Elicitation: &mcp.ElicitationCapabilities{
+				URL: &mcp.URLElicitationCapabilities{},
+			},
+		}),
+	)
+
+	toolResult, err := s.CallTool("elicit_test_tool", map[string]any{})
+
+	s.Run("forwards elicitationID to the client", func() {
+		s.NoError(err)
+		s.Require().NotNil(toolResult)
+		s.False(toolResult.IsError)
+		s.Require().Len(toolResult.Content, 1)
+		textContent, ok := toolResult.Content[0].(*mcp.TextContent)
+		s.Require().True(ok)
+		s.Equal("action=accept", textContent.Text)
+	})
+}
+
+func (s *ElicitationSuite) TestElicitationURLWithUnsupportedClient() {
+	s.registerElicitingToolset(func(params api.ToolHandlerParams) (*api.ToolCallResult, error) {
+		_, err := params.Elicit(params.Context, &api.ElicitParams{
+			Message: "Please complete the form",
+			URL:     "https://example.com/form",
+		})
+		if err != nil {
+			if errors.Is(err, ErrElicitationNotSupported) {
+				return api.NewToolCallResult("url-fallback-result", nil), nil
+			}
+			return nil, err
+		}
+		return api.NewToolCallResult("should-not-reach", nil), nil
+	})
+
+	// Client supports elicitation but not URL mode (default capabilities = form only)
+	s.InitMcpClient(test.WithElicitationHandler(
+		func(_ context.Context, _ *mcp.ElicitRequest) (*mcp.ElicitResult, error) {
+			return &mcp.ElicitResult{Action: "accept"}, nil
+		},
+	))
+
+	toolResult, err := s.CallTool("elicit_test_tool", map[string]any{})
+
+	s.Run("tool handles unsupported URL elicitation gracefully", func() {
+		s.NoError(err)
+		s.Require().NotNil(toolResult)
+		s.False(toolResult.IsError)
+		s.Require().Len(toolResult.Content, 1)
+		textContent, ok := toolResult.Content[0].(*mcp.TextContent)
+		s.Require().True(ok)
+		s.Equal("url-fallback-result", textContent.Text)
+	})
+}
+
 // mockElicitToolset is a test toolset that provides tools using the Elicitor interface
 type mockElicitToolset struct {
 	tools []api.ServerTool