Skip to content

Commit 9eb56d1

Browse files
stephentoubstephentoub
committed
Update all Messages comments
1 parent 14b077b commit 9eb56d1

17 files changed

+149
-1098
lines changed

‎src/Common/Polyfills/System/IO/TextWriterExtensions.cs‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
using ModelContextProtocol.Utils;
2-
using System.Runtime.InteropServices;
3-
41
namespace System.IO;
52

63
internal static class TextWriterExtensions

‎src/ModelContextProtocol/Protocol/Messages/CancelledNotification.cs‎

Lines changed: 7 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,37 +4,26 @@ namespace ModelContextProtocol.Protocol.Messages;
44

55
/// <summary>
66
/// Represents a notification indicating that a request has been cancelled by the client,
7-
/// and that any associated processing SHOULD cease immediately.
7+
/// and that any associated processing should cease immediately.
88
/// </summary>
99
/// <remarks>
10-
/// This class is used in conjunction with the <see cref="NotificationMethods.CancelledNotification"/>
10+
/// This class is typically used in conjunction with the <see cref="NotificationMethods.CancelledNotification"/>
1111
/// method identifier. When a client sends this notification, the server should attempt to
1212
/// cancel any ongoing operations associated with the specified request ID.
1313
/// </remarks>
14-
/// <example>
15-
/// <code>
16-
/// // Client code to cancel an in-progress request
17-
/// await client.SendNotificationAsync(
18-
/// NotificationMethods.CancelledNotification,
19-
/// parameters: new CancelledNotification
20-
/// {
21-
/// RequestId = requestId,
22-
/// Reason = "Operation no longer needed"
23-
/// },
24-
/// cancellationToken);
25-
/// </code>
26-
/// </example>
2714
public sealed class CancelledNotification
2815
{
2916
/// <summary>
30-
/// The ID of the request to cancel. This must match the ID of an in-flight request
31-
/// that the sender wishes to cancel.
17+
/// Gets or sets the ID of the request to cancel.
3218
/// </summary>
19+
/// <remarks>
20+
/// This must match the ID of an in-flight request that the sender wishes to cancel.
21+
/// </remarks>
3322
[JsonPropertyName("requestId")]
3423
public RequestId RequestId { get; set; }
3524

3625
/// <summary>
37-
/// An optional string describing the reason for the cancellation.
26+
/// Gets or sets an optional string describing the reason for the cancellation request.
3827
/// </summary>
3928
[JsonPropertyName("reason")]
4029
public string? Reason { get; set; }

‎src/ModelContextProtocol/Protocol/Messages/ErrorCodes.cs‎

Lines changed: 5 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -6,132 +6,27 @@ namespace ModelContextProtocol.Protocol.Messages;
66
internal static class ErrorCodes
77
{
88
/// <summary>
9-
/// Invalid JSON was received by the server. This error code (-32700) indicates that
10-
/// the JSON syntax itself is malformed and cannot be parsed.
9+
/// Invalid JSON was received by the server.
1110
/// </summary>
12-
/// <remarks>
13-
/// Use this error code when the request contains invalid JSON that cannot be parsed by
14-
/// the JSON parser. This typically happens when there are syntax errors like missing quotes,
15-
/// invalid escape sequences, unbalanced brackets, or other JSON syntax violations.
16-
/// This is different from InvalidRequest which indicates that the JSON is valid but
17-
/// the request structure doesn't conform to the JSON-RPC specification.
18-
/// </remarks>
1911
public const int ParseError = -32700;
2012

2113
/// <summary>
22-
/// The JSON sent is not a valid Request object. This error code (-32600) indicates that
23-
/// the request structure doesn't conform to the JSON-RPC specification requirements.
14+
/// The JSON sent is not a valid Request object.
2415
/// </summary>
25-
/// <remarks>
26-
/// Use this error code when a request is malformed, such as missing required fields
27-
/// (like method or id), containing invalid values, or otherwise not following the
28-
/// JSON-RPC protocol structure. This is different from ParseError which indicates
29-
/// invalid JSON syntax.
30-
/// </remarks>
31-
/// <example>
32-
/// <code>
33-
/// var error = new JsonRpcError
34-
/// {
35-
/// Id = null, // Often the ID can't be determined from an invalid request
36-
/// Error = new JsonRpcErrorDetail
37-
/// {
38-
/// Code = ErrorCodes.InvalidRequest,
39-
/// Message = "The request object is missing required 'method' field",
40-
/// Data = JsonNode.Parse(@"{""receivedRequest"": " + JsonSerializer.Serialize(request) + "}")
41-
/// }
42-
/// };
43-
/// </code>
44-
/// </example>
4516
public const int InvalidRequest = -32600;
4617

4718
/// <summary>
48-
/// The method does not exist or is not available. This error code (-32601) indicates that
49-
/// the requested method name in the JSON-RPC request is not recognized by the server.
19+
/// The method does not exist / is not available.
5020
/// </summary>
51-
/// <remarks>
52-
/// Use this error code when a client requests a method that isn't implemented or available.
53-
/// This is a standard JSON-RPC error code that helps clients understand that the method
54-
/// they're trying to call doesn't exist, rather than failing for other reasons.
55-
/// </remarks>
56-
/// <example>
57-
/// <code>
58-
/// // Example 1: Creating a JSON-RPC error response for a method not found
59-
/// var methodNotFoundError = new JsonRpcError
60-
/// {
61-
/// Id = request.Id,
62-
/// Error = new JsonRpcErrorDetail
63-
/// {
64-
/// Code = ErrorCodes.MethodNotFound,
65-
/// Message = $"Method '{request.Method}' not found"
66-
/// }
67-
/// };
68-
///
69-
/// // Example 2: Throwing an exception with this error code
70-
/// throw new McpException("The method does not exist or is not available.", ErrorCodes.MethodNotFound);
71-
///
72-
/// // Example 3: Handling this specific error in exception handling
73-
/// try
74-
/// {
75-
/// await client.CallToolAsync("nonExistentTool", new { });
76-
/// }
77-
/// catch (McpException ex)
78-
/// {
79-
/// if (ex.ErrorCode == ErrorCodes.MethodNotFound)
80-
/// {
81-
/// // Handle tool not found error specifically
82-
/// Console.WriteLine("Tool not found. Available tools: " + string.Join(", ", await client.ListToolsAsync()));
83-
/// }
84-
/// }
85-
/// </code>
86-
/// </example>
8721
public const int MethodNotFound = -32601;
8822

8923
/// <summary>
90-
/// Invalid method parameter(s). This error code (-32602) indicates that the parameters
91-
/// provided in the request are invalid, missing, or of the wrong type.
24+
/// Invalid method parameter(s).
9225
/// </summary>
93-
/// <remarks>
94-
/// Use this error code when a request contains parameters that don't conform to the
95-
/// expected format or when required parameters are missing. This helps clients understand
96-
/// exactly what's wrong with their request.
97-
/// </remarks>
98-
/// <example>
99-
/// <code>
100-
/// var error = new JsonRpcError
101-
/// {
102-
/// Id = request.Id,
103-
/// Error = new JsonRpcErrorDetail
104-
/// {
105-
/// Code = ErrorCodes.InvalidParams,
106-
/// Message = "Missing required 'location' parameter",
107-
/// Data = JsonNode.Parse(@"{""requiredParams"": [""location""]}")
108-
/// }
109-
/// };
110-
/// </code>
111-
/// </example>
11226
public const int InvalidParams = -32602;
11327

11428
/// <summary>
115-
/// Internal JSON-RPC error. This error code (-32603) indicates that an internal error occurred
116-
/// while processing the request that is not covered by more specific error codes.
29+
/// Internal JSON-RPC error.
11730
/// </summary>
118-
/// <remarks>
119-
/// This is often used as a fallback error code when handling unexpected exceptions
120-
/// or when a more specific error code is not available.
121-
/// </remarks>
122-
/// <example>
123-
/// <code>
124-
/// var error = new JsonRpcError
125-
/// {
126-
/// Id = request.Id,
127-
/// Error = new JsonRpcErrorDetail
128-
/// {
129-
/// Code = ErrorCodes.InternalError,
130-
/// Message = "An internal error occurred while processing the request",
131-
/// Data = JsonNode.Parse($"{{\"errorDetails\": \"{ex.Message}\"}}")
132-
/// }
133-
/// };
134-
/// </code>
135-
/// </example>
13631
public const int InternalError = -32603;
13732
}

‎src/ModelContextProtocol/Protocol/Messages/IJsonRpcMessage.cs‎

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,40 +4,18 @@
44
namespace ModelContextProtocol.Protocol.Messages;
55

66
/// <summary>
7-
/// Base interface for all JSON-RPC messages in the Model Context Protocol (MCP).
7+
/// Represents any JSON-RPC message used in the Model Context Protocol (MCP).
88
/// </summary>
99
/// <remarks>
1010
/// This interface serves as the foundation for all message types in the JSON-RPC 2.0 protocol
1111
/// used by MCP, including requests, responses, notifications, and errors. JSON-RPC is a stateless,
1212
/// lightweight remote procedure call (RPC) protocol that uses JSON as its data format.
13-
///
14-
/// Messages implementing this interface are automatically serialized and deserialized using the
15-
/// <see cref="JsonRpcMessageConverter"/> to handle the polymorphic nature of the different message types.
1613
/// </remarks>
17-
/// <example>
18-
/// The following concrete implementations of this interface are used in the protocol:
19-
/// <code>
20-
/// // A request message (expects a response)
21-
/// var request = new JsonRpcRequest
22-
/// {
23-
/// Id = RequestId.Generate(),
24-
/// Method = "weather.getTemperature",
25-
/// Params = JsonNode.Parse("{\"location\":\"Seattle\"}")
26-
/// };
27-
///
28-
/// // A notification message (does not expect a response)
29-
/// var notification = new JsonRpcNotification
30-
/// {
31-
/// Method = "weather.update",
32-
/// Params = JsonNode.Parse("{\"location\":\"Seattle\",\"temperature\":72}")
33-
/// };
34-
/// </code>
35-
/// </example>
3614
[JsonConverter(typeof(JsonRpcMessageConverter))]
3715
public interface IJsonRpcMessage
3816
{
3917
/// <summary>
40-
/// JSON-RPC protocol version. Must be "2.0".
18+
/// Gets the JSON-RPC protocol version used.
4119
/// </summary>
4220
string JsonRpc { get; }
4321
}

‎src/ModelContextProtocol/Protocol/Messages/IJsonRpcMessageWithId.cs‎

Lines changed: 5 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,22 @@
11
namespace ModelContextProtocol.Protocol.Messages;
22

33
/// <summary>
4-
/// Base interface for JSON-RPC messages that include an ID.
4+
/// Represents a JSON-RPC message used in the Model Context Protocol (MCP) and that includes an ID.
55
/// </summary>
66
/// <remarks>
77
/// In the JSON-RPC protocol, messages with an ID require a response from the receiver.
88
/// This includes request messages (which expect a matching response) and response messages
99
/// (which include the ID of the original request they're responding to).
10-
///
1110
/// The ID is used to correlate requests with their responses, allowing asynchronous
1211
/// communication where multiple requests can be sent without waiting for responses.
1312
/// </remarks>
14-
/// <example>
15-
/// Message types that implement this interface:
16-
/// <code>
17-
/// // A request message with an ID (expects a response)
18-
/// var request = new JsonRpcRequest
19-
/// {
20-
/// Id = RequestId.Generate(),
21-
/// Method = "weather.getTemperature"
22-
/// };
23-
///
24-
/// // A successful response message with the same ID
25-
/// var response = new JsonRpcResponse
26-
/// {
27-
/// Id = request.Id,
28-
/// Result = JsonNode.Parse("72")
29-
/// };
30-
///
31-
/// // An error response message with the same ID
32-
/// var error = new JsonRpcError
33-
/// {
34-
/// Id = request.Id,
35-
/// Error = new JsonRpcErrorDetail
36-
/// {
37-
/// Code = ErrorCodes.InternalError,
38-
/// Message = "Unable to retrieve temperature data"
39-
/// }
40-
/// };
41-
/// </code>
42-
/// </example>
4313
public interface IJsonRpcMessageWithId : IJsonRpcMessage
4414
{
4515
/// <summary>
46-
/// The message identifier.
16+
/// Gets the message identifier.
4717
/// </summary>
18+
/// <remarks>
19+
/// Each ID is expected to be unique within the context of a given session.
20+
/// </remarks>
4821
RequestId Id { get; }
4922
}

‎src/ModelContextProtocol/Protocol/Messages/JsonRpcError.cs‎

Lines changed: 9 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -3,45 +3,33 @@
33
namespace ModelContextProtocol.Protocol.Messages;
44

55
/// <summary>
6-
/// An error response message in the JSON-RPC protocol.
6+
/// Represents an error response message in the JSON-RPC protocol.
77
/// </summary>
88
/// <remarks>
9+
/// <para>
910
/// Error responses are sent when a request cannot be fulfilled or encounters an error during processing.
1011
/// Like successful responses, error messages include the same ID as the original request, allowing the
1112
/// sender to match errors with their corresponding requests.
12-
///
13+
/// </para>
14+
/// <para>
1315
/// Each error response contains a structured error detail object with a numeric code, descriptive message,
1416
/// and optional additional data to provide more context about the error.
17+
/// </para>
1518
/// </remarks>
1619
public record JsonRpcError : IJsonRpcMessageWithId
1720
{
18-
/// <summary>
19-
/// JSON-RPC protocol version. Always "2.0".
20-
/// </summary>
21+
/// <inheritdoc />
2122
[JsonPropertyName("jsonrpc")]
2223
public string JsonRpc { get; init; } = "2.0";
2324

24-
/// <summary>
25-
/// Request identifier matching the original request.
26-
/// </summary>
25+
/// <inheritdoc />
2726
[JsonPropertyName("id")]
2827
public required RequestId Id { get; init; }
2928

3029
/// <summary>
31-
/// Detailed error information for the failed request, containing an error code,
32-
/// message, and optional additional data. This property provides structured
33-
/// information about the error that occurred during processing of the JSON-RPC request.
30+
/// Gets detailed error information for the failed request, containing an error code,
31+
/// message, and optional additional data
3432
/// </summary>
35-
/// <example>
36-
/// Example error handling:
37-
/// <code>
38-
/// if (response is JsonRpcError errorResponse)
39-
/// {
40-
/// Console.WriteLine($"Error code: {errorResponse.Error.Code}");
41-
/// Console.WriteLine($"Error message: {errorResponse.Error.Message}");
42-
/// }
43-
/// </code>
44-
/// </example>
4533
[JsonPropertyName("error")]
4634
public required JsonRpcErrorDetail Error { get; init; }
4735
}

0 commit comments

Comments
 (0)