Clean up (use of) McpException and McpTransportException (#321)

* Clean up (use of) McpException

* Replace McpTransportException with InvalidOperationException

* Add cancellation test

Author: stephentoub

samples/EverythingServer/Program.cs

@@ -176,7 +176,7 @@ await ctx.Server.RequestSamplingAsync([
     {
         if (ctx.Params?.Level is null)
         {
-            throw new McpException("Missing required argument 'level'");
+            throw new McpException("Missing required argument 'level'", McpErrorCode.InvalidParams);
         }
 
         _minimumLoggingLevel = ctx.Params.Level;

src/ModelContextProtocol/Client/McpClient.cs

@@ -155,10 +155,10 @@ await SendMessageAsync(
                     new JsonRpcNotification { Method = NotificationMethods.InitializedNotification },
                     initializationCts.Token).ConfigureAwait(false);
             }
-            catch (OperationCanceledException oce) when (initializationCts.IsCancellationRequested)
+            catch (OperationCanceledException oce) when (initializationCts.IsCancellationRequested && !cancellationToken.IsCancellationRequested)
             {
                 LogClientInitializationTimeout(EndpointName);
-                throw new McpException("Initialization timed out", oce);
+                throw new TimeoutException("Initialization timed out", oce);
             }
         }
         catch (Exception e)

src/ModelContextProtocol/McpErrorCode.cs

@@ -0,0 +1,49 @@
+namespace ModelContextProtocol;
+
+/// <summary>
+/// Represents standard JSON-RPC error codes as defined in the MCP specification.
+/// </summary>
+public enum McpErrorCode
+{
+    /// <summary>
+    /// Indicates that the JSON received could not be parsed.
+    /// </summary>
+    /// <remarks>
+    /// This error occurs when the input contains malformed JSON or incorrect syntax.
+    /// </remarks>
+    ParseError = -32700,
+
+    /// <summary>
+    /// Indicates that the JSON payload does not conform to the expected Request object structure.
+    /// </summary>
+    /// <remarks>
+    /// The request is considered invalid if it lacks required fields or fails to follow the JSON-RPC protocol.
+    /// </remarks>
+    InvalidRequest = -32600,
+
+    /// <summary>
+    /// Indicates that the requested method does not exist or is not available on the server.
+    /// </summary>
+    /// <remarks>
+    /// This error is returned when the method name specified in the request cannot be found.
+    /// </remarks>
+    MethodNotFound = -32601,
+
+    /// <summary>
+    /// Indicates that one or more parameters provided in the request are invalid.
+    /// </summary>
+    /// <remarks>
+    /// This error is returned when the parameters do not match the expected method signature or constraints.
+    /// This includes cases where required parameters are missing or not understood, such as when a name for
+    /// a tool or prompt is not recognized.
+    /// </remarks>
+    InvalidParams = -32602,
+
+    /// <summary>
+    /// Indicates that an internal error occurred while processing the request.
+    /// </summary>
+    /// <remarks>
+    /// This error is used when the endpoint encounters an unexpected condition that prevents it from fulfilling the request.
+    /// </remarks>
+    InternalError = -32603,
+}

src/ModelContextProtocol/McpException.cs

@@ -1,8 +1,15 @@
 namespace ModelContextProtocol;
 
 /// <summary>
-/// Represents an exception that is thrown when a Model Context Protocol (MCP) error occurs.
+/// Represents an exception that is thrown when an Model Context Protocol (MCP) error occurs.
 /// </summary>
+/// <remarks>
+/// This exception is used to represent failures to do with protocol-level concerns, such as invalid JSON-RPC requests,
+/// invalid parameters, or internal errors. It is not intended to be used for application-level errors.
+/// <see cref="Exception.Message"/> or <see cref="ErrorCode"/> from a <see cref="McpException"/> may be 
+/// propagated to the remote endpoint; sensitive information should not be included. If sensitive details need
+/// to be included, a different exception type should be used.
+/// </remarks>
 public class McpException : Exception
 {
     /// <summary>
@@ -33,8 +40,8 @@ public McpException(string message, Exception? innerException) : base(message, i
     /// Initializes a new instance of the <see cref="McpException"/> class with a specified error message and JSON-RPC error code.
     /// </summary>
     /// <param name="message">The message that describes the error.</param>
-    /// <param name="errorCode">A JSON-RPC error code from <see cref="Protocol.Messages.ErrorCodes"/> class.</param>
-    public McpException(string message, int? errorCode) : this(message, null, errorCode)
+    /// <param name="errorCode">A <see cref="McpErrorCode"/>.</param>
+    public McpException(string message, McpErrorCode errorCode) : this(message, null, errorCode)
     {
     }
 
@@ -43,18 +50,15 @@ public McpException(string message, int? errorCode) : this(message, null, errorC
     /// </summary>
     /// <param name="message">The message that describes the error.</param>
     /// <param name="innerException">The exception that is the cause of the current exception, or a null reference if no inner exception is specified.</param>
-    /// <param name="errorCode">A JSON-RPC error code from <see cref="Protocol.Messages.ErrorCodes"/> class.</param>
-    public McpException(string message, Exception? innerException, int? errorCode) : base(message, innerException)
+    /// <param name="errorCode">A <see cref="McpErrorCode"/>.</param>
+    public McpException(string message, Exception? innerException, McpErrorCode errorCode) : base(message, innerException)
     {
         ErrorCode = errorCode;
     }
 
     /// <summary>
-    /// Gets the JSON-RPC error code associated with this exception.
+    /// Gets the error code associated with this exception.
     /// </summary>
-    /// <value>
-    /// A standard JSON-RPC error code, or <see langword="null"/> if the exception wasn't caused by a JSON-RPC error.
-    /// </value>
     /// <remarks>
     /// This property contains a standard JSON-RPC error code as defined in the MCP specification. Common error codes include:
     /// <list type="bullet">
@@ -65,5 +69,5 @@ public McpException(string message, Exception? innerException, int? errorCode) :
     /// <item><description>-32603: Internal error - Internal JSON-RPC error</description></item>
     /// </list>
     /// </remarks>
-    public int? ErrorCode { get; }
+    public McpErrorCode ErrorCode { get; } = McpErrorCode.InternalError;
 }

src/ModelContextProtocol/Protocol/Messages/ErrorCodes.cs

@@ -42,6 +42,6 @@ public interface IClientTransport
     /// This method is used by <see cref="McpClientFactory"/> to initialize the connection.
     /// </para>
     /// </remarks>
-    /// <exception cref="McpTransportException">The transport connection could not be established.</exception>
+    /// <exception cref="InvalidOperationException">The transport connection could not be established.</exception>
     Task<ITransport> ConnectAsync(CancellationToken cancellationToken = default);
 }

src/ModelContextProtocol/Protocol/Transport/IClientTransport.cs

@@ -58,11 +58,11 @@ public async Task ConnectAsync(CancellationToken cancellationToken = default)
 
             await _connectionEstablished.Task.WaitAsync(_options.ConnectionTimeout, cancellationToken).ConfigureAwait(false);
         }
-        catch (Exception ex) when (ex is not McpTransportException) // propagate transport exceptions
+        catch (Exception ex)
         {
             LogTransportConnectFailed(Name, ex);
             await CloseAsync().ConfigureAwait(false);
-            throw new McpTransportException("Failed to connect transport", ex);
+            throw new InvalidOperationException("Failed to connect transport", ex);
         }
     }
 
@@ -110,7 +110,7 @@ public override async Task SendMessageAsync(
             else
             {
                 JsonRpcResponse initializeResponse = JsonSerializer.Deserialize(responseContent, McpJsonUtilities.JsonContext.Default.JsonRpcResponse) ??
-                    throw new McpTransportException("Failed to initialize client");
+                    throw new InvalidOperationException("Failed to initialize client");
 
                 LogTransportReceivedMessage(Name, messageId);
                 await WriteMessageAsync(initializeResponse, cancellationToken).ConfigureAwait(false);
@@ -136,7 +136,7 @@ public override async Task SendMessageAsync(
                 LogRejectedPost(Name, messageId);
             }
 
-            throw new McpTransportException("Failed to send message");
+            throw new InvalidOperationException("Failed to send message");
         }
     }
 
@@ -273,34 +273,18 @@ private async Task ProcessSseMessage(string data, CancellationToken cancellation
 
     private void HandleEndpointEvent(string data)
     {
-        try
+        if (string.IsNullOrEmpty(data))
         {
-            if (string.IsNullOrEmpty(data))
-            {
-                LogTransportEndpointEventInvalid(Name);
-                return;
-            }
-
-            // If data is an absolute URL, the Uri will be constructed entirely from it and not the _sseEndpoint.
-            _messageEndpoint = new Uri(_sseEndpoint, data);
-
-            // Set connected state
-            SetConnected(true);
-            _connectionEstablished.TrySetResult(true);
+            LogTransportEndpointEventInvalid(Name);
+            return;
         }
-        catch (JsonException ex)
-        {
-            if (_logger.IsEnabled(LogLevel.Trace))
-            {
-                LogTransportEndpointEventParseFailedSensitive(Name, data, ex);
-            }
-            else
-            {
-                LogTransportEndpointEventParseFailed(Name, ex);
-            }
 
-            throw new McpTransportException("Failed to parse endpoint event", ex);
-        }
+        // If data is an absolute URL, the Uri will be constructed entirely from it and not the _sseEndpoint.
+        _messageEndpoint = new Uri(_sseEndpoint, data);
+
+        // Set connected state
+        SetConnected(true);
+        _connectionEstablished.TrySetResult(true);
     }
 
     private void CopyAdditionalHeaders(HttpRequestHeaders headers)

src/ModelContextProtocol/Protocol/Transport/McpTransportException.cs

@@ -23,14 +23,14 @@ public StdioClientSessionTransport(StdioClientTransportOptions options, Process
     /// <para>
     /// For stdio-based transports, this implementation first verifies that the underlying process 
     /// is still running before attempting to send the message. If the process has exited or cannot
-    /// be accessed, a <see cref="McpTransportException"/> is thrown with details about the failure.
+    /// be accessed, a <see cref="InvalidOperationException"/> is thrown with details about the failure.
     /// </para>
     /// <para>
     /// After verifying the process state, this method delegates to the base class implementation
     /// to handle the actual message serialization and transmission to the process's standard input stream.
     /// </para>
     /// </remarks>
-    /// <exception cref="McpTransportException">
+    /// <exception cref="InvalidOperationException">
     /// Thrown when the underlying process has exited or cannot be accessed.
     /// </exception>
     public override async Task SendMessageAsync(IJsonRpcMessage message, CancellationToken cancellationToken = default)
@@ -49,7 +49,7 @@ public override async Task SendMessageAsync(IJsonRpcMessage message, Cancellatio
 
         if (hasExited)
         {
-            throw new McpTransportException("Transport is not connected", processException);
+            throw new InvalidOperationException("Transport is not connected", processException);
         }
 
         await base.SendMessageAsync(message, cancellationToken).ConfigureAwait(false);

src/ModelContextProtocol/Protocol/Transport/SseClientSessionTransport.cs

@@ -154,7 +154,7 @@ public async Task<ITransport> ConnectAsync(CancellationToken cancellationToken =
             if (!processStarted)
             {
                 LogTransportProcessStartFailed(logger, endpointName);
-                throw new McpTransportException("Failed to start MCP server process");
+                throw new InvalidOperationException("Failed to start MCP server process");
             }
 
             LogTransportProcessStarted(logger, endpointName, process.Id);
@@ -176,7 +176,7 @@ public async Task<ITransport> ConnectAsync(CancellationToken cancellationToken =
                 LogTransportShutdownFailed(logger, endpointName, ex2);
             }
 
-            throw new McpTransportException("Failed to connect transport", ex);
+            throw new InvalidOperationException("Failed to connect transport", ex);
         }
     }