all: expose JSON-RPC error codes, and support URLElicitationRequired errors (#655)

Expose the jsonrpc.Error type to allow access to underlying JSON-RPC
error codes. Also, expose common JSON-RPC error codes in the jsonrpc
package, and MCP error codes in the mcp package.

Also, implement support for the MCP URL elicitation required error
(-32042), enabling servers to request out-of-band user authorization and
clients to automatically handle these requests with retry logic.

Server-side:
- Add CodeURLElicitationRequired constant
- Add URLElicitationRequiredError() constructor.

Client-side:
- Add urlElicitationMiddleware to intercept URLElicitationRequired
  errors and retry calls.
- Update callElicitationCompleteHandler to signal waiting operations.
- Fix capability advertisement to support both form and URL modes.

Fixes #452
Fixes #623

mcp/shared.go

@@ -88,7 +88,7 @@ func addMiddleware(handlerp *MethodHandler, middleware []Middleware) {
 	}
 }
 
-func defaultSendingMethodHandler[S Session](ctx context.Context, method string, req Request) (Result, error) {
+func defaultSendingMethodHandler(ctx context.Context, method string, req Request) (Result, error) {
 	info, ok := req.GetSession().sendingMethodInfos()[method]
 	if !ok {
 		// This can be called from user code, with an arbitrary value for method.
@@ -331,16 +331,52 @@ func clientSessionMethod[P Params, R Result](f func(*ClientSession, context.Cont
 	}
 }
 
-// Error codes
+// MCP-specific error codes.
+const (
+	// CodeResourceNotFound indicates that a requested resource could not be found.
+	CodeResourceNotFound = -32002
+	// CodeURLElicitationRequired indicates that the server requires URL elicitation
+	// before processing the request. The client should execute the elicitation handler
+	// with the elicitations provided in the error data.
+	CodeURLElicitationRequired = -32042
+)
+
+// URLElicitationRequiredError returns an error indicating that URL elicitation is required
+// before the request can be processed. The elicitations parameter should contain the
+// elicitation requests that must be completed.
+func URLElicitationRequiredError(elicitations []*ElicitParams) error {
+	// Validate that all elicitations are URL mode
+	for _, elicit := range elicitations {
+		mode := elicit.Mode
+		if mode == "" {
+			mode = "form" // default mode
+		}
+		if mode != "url" {
+			panic(fmt.Sprintf("URLElicitationRequiredError requires all elicitations to be URL mode, got %q", mode))
+		}
+	}
+
+	data, err := json.Marshal(map[string]any{
+		"elicitations": elicitations,
+	})
+	if err != nil {
+		// This should never happen with valid ElicitParams
+		panic(fmt.Sprintf("failed to marshal elicitations: %v", err))
+	}
+	return &jsonrpc.Error{
+		Code:    CodeURLElicitationRequired,
+		Message: "URL elicitation required",
+		Data:    json.RawMessage(data),
+	}
+}
+
+// Internal error codes
 const (
-	codeResourceNotFound = -32002
 	// The error code if the method exists and was called properly, but the peer does not support it.
 	//
 	// TODO(rfindley): this code is wrong, and we should fix it to be
 	// consistent with other SDKs.
 	codeUnsupportedMethod = -31001
-	// The error code for invalid parameters
-	codeInvalidParams = -32602
 )
 
 // notifySessions calls Notify on all the sessions.