Merge pull request modelcontextprotocol#16 from modelcontextprotocol/davidsp/prompt-notification

feat: add prompts/list_changed notification

Author: dsp-ant

docs/spec/prompts.md

@@ -9,6 +9,36 @@ Prompts enable servers to provide templated conversations or instructions to cli
 An example of a prompt as a slash command in the Zed editor:
 ![Slash Command Example](slash-command.png)
 
+## Capabilities
+
+To indicate support for the Prompts API, servers MUST include a `prompts` capability in their `ServerCapabilities` during initialization. The `prompts` capability SHOULD be an empty object:
+
+```json
+{
+  "capabilities": {
+    "prompts": {}
+  }
+}
+```
+
+Clients SHOULD check for this capability before using the Prompts API.
+
+Servers MAY support notifications for changes to the prompt list. If a server supports this feature, it SHOULD include a `listChanged` property in its `prompts` capability:
+
+```json
+{
+  "capabilities": {
+    "prompts": {
+      "listChanged": true
+    }
+  }
+}
+```
+
+If a server supports this capability, it MAY send `notifications/prompts/list_changed` notifications to inform the client about changes to the available prompts.
+
+## Concepts
+
 ### Prompt
 
 A Prompt in the Model Context Protocol (MCP) represents a pre-defined set of messages or instructions that a server can provide to clients. Each Prompt is uniquely identified by a name and may have associated metadata such as a description and required arguments. Prompts can represent various types of interactions, including code reviews, data analysis tasks, or creative writing prompts.
@@ -221,24 +251,29 @@ Example:
 }
 ```
 
-## Error Handling
-
-Clients MUST be prepared to handle cases where listed prompts become unavailable between listing and retrieval attempts. Servers SHOULD provide appropriate error responses in such scenarios.
-
-## Security Considerations
+### Prompt List Changed Notification
 
-Implementations MUST carefully consider the security implications of exposing prompts, especially when dealing with sensitive data or customizable templates. Proper authentication and authorization mechanisms SHOULD be in place to prevent unauthorized access to prompts.
+If the server supports the `listChanged` capability for prompts, it MAY send a `notifications/prompts/list_changed` notification to inform the client that the list of available prompts has changed.
 
-## Capabilities
+#### Notification
 
-To indicate support for the Prompts API, servers MUST include a `prompts` capability in their `ServerCapabilities` during initialization. The `prompts` capability SHOULD be an empty object:
+Method: `notifications/prompts/list_changed`
+Params: None
 
+Example:
 ```json
 {
-  "capabilities": {
-    "prompts": {}
-  }
+  "jsonrpc": "2.0",
+  "method": "notifications/prompts/list_changed"
 }
 ```
 
-Clients SHOULD check for this capability before using the Prompts API.
+Upon receiving this notification, clients SHOULD request an updated prompt list using the `prompts/list` method to ensure they have the most up-to-date information about available prompts.
+
+## Error Handling
+
+Clients MUST be prepared to handle cases where listed prompts become unavailable between listing and retrieval attempts. Servers SHOULD provide appropriate error responses in such scenarios.
+
+## Security Considerations
+
+Implementations MUST carefully consider the security implications of exposing prompts, especially when dealing with sensitive data or customizable templates. Proper authentication and authorization mechanisms SHOULD be in place to prevent unauthorized access to prompts.

docs/spec/resources.md

@@ -7,9 +7,9 @@ weight: 4
 
 Resources enable servers to expose arbitrary data to clients in a structured way, specifically for providing context to language models. Clients can discover available resources, read their contents, and optionally subscribe to updates. Users may explicitly attach resources via the client UI, or clients can intelligently select appropriate resources to add to the context. Each resource is uniquely identified by a [URI](https://datatracker.ietf.org/doc/html/rfc3986).
 
-## Required Capabilities
+## Capabilities
 
-To use resources, the server MUST include the `resources` capability in its `ServerCapabilities` object during the initialization process. The `resources` capability MAY include a `subscribe` field set to `true` if the server supports resource subscriptions.
+To use resources, the server MUST include the `resources` capability in its `ServerCapabilities` object during the initialization process. The `resources` capability MAY include a `subscribe` field set to `true` if the server supports resource subscriptions. Additionally, the `resources` capability MAY include a `listChanged` field set to `true` if the server supports notifications for changes to the resource list.
 
 Clients intending to use resources SHOULD check for the presence of the `resources` capability in the server's capabilities before attempting to use any resource-related methods. If the capability is not present, the client MUST NOT attempt to use resource-related methods, as the server does not support them.
 
@@ -22,19 +22,20 @@ Example of server capabilities with basic resource support:
 }
 ```
 
-Example of server capabilities including resource support:
+Example of server capabilities including resource support with subscriptions and list change notifications:
 
 ```json
 {
   "capabilities": {
     "resources": {
-      "subscribe": true
+      "subscribe": true,
+      "listChanged": true
     }
   }
 }
 ```
 
-In this example, the server supports both basic resource operations and subscriptions. If `subscribe` is omitted or set to `false`, the server only supports basic resource operations without subscriptions.
+In this example, the server supports basic resource operations, subscriptions, and notifications for resource list changes. If `subscribe` is omitted or set to `false`, the server only supports basic resource operations without subscriptions. Similarly, if `listChanged` is omitted or set to `false`, the server does not support notifications for changes to the resource list.
 
 ## Concepts
 ### Resource
@@ -345,7 +346,9 @@ Servers MUST only send this notification for resources that clients have explici
 
 ### Resource List Changed Notification
 
-When the list of available resources has changed, the server MUST send a `notifications/resources/list_changed` notification to the client.
+If the server supports the `listChanged` capability for resources, it MAY send a `notifications/resources/list_changed` notification to inform the client that the list of available resources has changed.
+
+#### Notification
 
 Method: `notifications/resources/list_changed`
 Params: None
@@ -358,7 +361,7 @@ Example:
 }
 ```
 
-Upon receiving this notification, clients SHOULD request an updated resource list using the `resources/list` method.
+Upon receiving this notification, clients SHOULD request an updated resource list using the `resources/list` method to ensure they have the most up-to-date information about available resources.
 
 ## Security Considerations
 

schema/schema.json

@@ -998,6 +998,30 @@
             ],
             "type": "object"
         },
+        "PromptListChangedNotification": {
+            "description": "An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.",
+            "properties": {
+                "method": {
+                    "const": "notifications/prompts/list_changed",
+                    "type": "string"
+                },
+                "params": {
+                    "additionalProperties": {},
+                    "properties": {
+                        "_meta": {
+                            "additionalProperties": {},
+                            "description": "This parameter name is reserved by MCP to allow clients and servers to attach additional metadata to their notifications.",
+                            "type": "object"
+                        }
+                    },
+                    "type": "object"
+                }
+            },
+            "required": [
+                "method"
+            ],
+            "type": "object"
+        },
         "PromptReference": {
             "description": "Identifies a prompt.",
             "properties": {
@@ -1302,14 +1326,22 @@
                     "type": "object"
                 },
                 "prompts": {
-                    "additionalProperties": true,
                     "description": "Present if the server offers any prompt templates.",
-                    "properties": {},
+                    "properties": {
+                        "listChanged": {
+                            "description": "Whether this server supports notifications for changes to the prompt list.",
+                            "type": "boolean"
+                        }
+                    },
                     "type": "object"
                 },
                 "resources": {
                     "description": "Present if the server offers any resources to read.",
                     "properties": {
+                        "listChanged": {
+                            "description": "Whether this server supports notifications for changes to the resource list.",
+                            "type": "boolean"
+                        },
                         "subscribe": {
                             "description": "Whether this server supports subscribing to resource updates.",
                             "type": "boolean"
@@ -1318,9 +1350,13 @@
                     "type": "object"
                 },
                 "tools": {
-                    "additionalProperties": true,
                     "description": "Present if the server offers any tools to call.",
-                    "properties": {},
+                    "properties": {
+                        "listChanged": {
+                            "description": "Whether this server supports notifications for changes to the tool list.",
+                            "type": "boolean"
+                        }
+                    },
                     "type": "object"
                 }
             },
@@ -1337,6 +1373,9 @@
                 {
                     "$ref": "#/definitions/ResourceUpdatedNotification"
                 },
+                {
+                    "$ref": "#/definitions/PromptListChangedNotification"
+                },
                 {
                     "$ref": "#/definitions/ToolListChangedNotification"
                 },

schema/schema.ts

@@ -173,7 +173,12 @@ export interface ServerCapabilities {
   /**
    * Present if the server offers any prompt templates.
    */
-  prompts?: object;
+  prompts?: {
+    /**
+     * Whether this server supports notifications for changes to the prompt list.
+     */
+    listChanged?: boolean;
+  };
   /**
    * Present if the server offers any resources to read.
    */
@@ -182,11 +187,20 @@ export interface ServerCapabilities {
      * Whether this server supports subscribing to resource updates.
      */
     subscribe?: boolean;
+    /**
+     * Whether this server supports notifications for changes to the resource list.
+     */
+    listChanged?: boolean;
   };
   /**
    * Present if the server offers any tools to call.
    */
-  tools?: object;
+  tools?: {
+    /**
+     * Whether this server supports notifications for changes to the tool list.
+     */
+    listChanged?: boolean;
+  };
 }
 
 /**
@@ -494,6 +508,13 @@ export interface PromptArgument {
   required?: boolean;
 }
 
+/**
+ * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
+ */
+export interface PromptListChangedNotification extends Notification {
+  method: "notifications/prompts/list_changed";
+}
+
 /* Tools */
 /**
  * Sent from the client to request a list of tools the server has.
@@ -771,7 +792,8 @@ export type ServerNotification =
   | LoggingMessageNotification
   | ResourceUpdatedNotification
   | ResourceListChangedNotification
-  | ToolListChangedNotification;
+  | ToolListChangedNotification
+  | PromptListChangedNotification;
 
 export type ServerResult =
   | EmptyResult