Merge pull request modelcontextprotocol#47 from modelcontextprotocol/justin/timeouts

Notification to cancel a previous request

Author: jspahrsummers

docs/spec/cancellation.md

@@ -0,0 +1,69 @@
+---
+title: Cancellation
+type: docs
+weight: 5
+---
+
+MCP supports request cancellation through a dedicated notification message. This allows either party to signal that they are no longer interested in the result of an in-flight request.
+
+## Cancellation Protocol
+
+When a party wants to cancel a request, they send a `cancelled` notification containing the ID of the request they wish to cancel:
+
+For example, initiating a request:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "abc123",
+  "method": "resources/read",
+  "params": {
+    "uri": "example://large-file"
+  }
+}
+```
+
+… then some time later, cancelling that request:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "cancelled",
+  "params": {
+    "requestId": "abc123",
+    "reason": "User interrupted operation"
+  }
+}
+```
+
+## Handling Cancellation
+
+Upon receiving a cancellation notification, the receiver SHOULD:
+
+1. Stop any processing related to the cancelled request
+2. Free any resources associated with that request
+3. Not send a response for the cancelled request (even if already computed)
+
+However, due to race conditions and message latency:
+
+- The notification may arrive after processing is complete
+- A response may already be in transit when cancellation is received
+- Multiple cancellation notifications for the same request ID may be received
+
+## Special Cases
+
+### Initialize Request
+
+The client MUST NOT attempt to cancel its `initialize` request. Cancelling initialization leaves the protocol in an undefined state.
+
+### Long-Running Operations
+
+For long-running operations that support progress notifications, progress notifications SHOULD stop being sent after receiving cancellation.
+
+## Best Practices
+
+1. Implement cancellation handlers for all long-running operations
+2. Free resources promptly when receiving cancellation
+3. Make cancellation handling idempotent
+4. Include meaningful reason strings to aid debugging
+5. Log cancellations appropriately for troubleshooting

schema/schema.json

@@ -87,6 +87,36 @@
             ],
             "type": "object"
         },
+        "CancelledNotification": {
+            "description": "This notification can be sent by either side to indicate that it is cancelling a previously-issued request.\n\nThe request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished.\n\nThis notification indicates that the result will be unused, so any associated processing SHOULD cease.\n\nA client MUST NOT attempt to cancel its `initialize` request.",
+            "properties": {
+                "method": {
+                    "const": "cancelled",
+                    "type": "string"
+                },
+                "params": {
+                    "properties": {
+                        "reason": {
+                            "description": "An optional string describing the reason for the cancellation. This MAY be logged or presented to the user.",
+                            "type": "string"
+                        },
+                        "requestId": {
+                            "$ref": "#/definitions/RequestId",
+                            "description": "The ID of the request to cancel.\n\nThis MUST correspond to the ID of a request previously issued in the same direction."
+                        }
+                    },
+                    "required": [
+                        "requestId"
+                    ],
+                    "type": "object"
+                }
+            },
+            "required": [
+                "method",
+                "params"
+            ],
+            "type": "object"
+        },
         "ClientCapabilities": {
             "description": "Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.",
             "properties": {
@@ -120,6 +150,9 @@
         },
         "ClientNotification": {
             "anyOf": [
+                {
+                    "$ref": "#/definitions/CancelledNotification"
+                },
                 {
                     "$ref": "#/definitions/InitializedNotification"
                 },
@@ -1659,6 +1692,9 @@
         },
         "ServerNotification": {
             "anyOf": [
+                {
+                    "$ref": "#/definitions/CancelledNotification"
+                },
                 {
                     "$ref": "#/definitions/ProgressNotification"
                 },

schema/schema.ts

@@ -114,6 +114,33 @@ export interface JSONRPCError {
  */
 export type EmptyResult = Result;
 
+/* Cancellation */
+/**
+ * This notification can be sent by either side to indicate that it is cancelling a previously-issued request.
+ *
+ * The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished.
+ *
+ * This notification indicates that the result will be unused, so any associated processing SHOULD cease.
+ *
+ * A client MUST NOT attempt to cancel its `initialize` request.
+ */
+export interface CancelledNotification extends Notification {
+  method: "cancelled";
+  params: {
+    /**
+     * The ID of the request to cancel.
+     *
+     * This MUST correspond to the ID of a request previously issued in the same direction.
+     */
+    requestId: RequestId;
+
+    /**
+     * An optional string describing the reason for the cancellation. This MAY be logged or presented to the user.
+     */
+    reason?: string;
+  };
+}
+
 /* Initialization */
 /**
  * This request is sent from the client to the server when it first connects, asking it to begin initialization.
@@ -615,7 +642,7 @@ export interface CallToolResult extends Result {
 
   /**
    * Whether the tool call ended in an error.
-   * 
+   *
    * If not set, this is assumed to be false (the call was successful).
    */
   isError?: boolean;
@@ -865,12 +892,12 @@ export interface ModelPreferences {
 export interface ModelHint {
   /**
    * A hint for a model name.
-   * 
+   *
    * The client SHOULD treat this as a substring of a model name; for example:
    *  - `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022`
    *  - `sonnet` should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc.
    *  - `claude` should match any Claude model
-   * 
+   *
    * The client MAY also map the string to a different provider's model name or a different model family, as long as it fills a similar niche; for example:
    *  - `gemini-1.5-flash` could match `claude-3-haiku-20240307`
    */
@@ -1013,6 +1040,7 @@ export type ClientRequest =
   | ListToolsRequest;
 
 export type ClientNotification =
+  | CancelledNotification
   | ProgressNotification
   | InitializedNotification
   | RootsListChangedNotification;
@@ -1026,6 +1054,7 @@ export type ServerRequest =
   | ListRootsRequest;
 
 export type ServerNotification =
+  | CancelledNotification
   | ProgressNotification
   | LoggingMessageNotification
   | ResourceUpdatedNotification