Skip to content

Commit

Permalink
Merge pull request #16 from modelcontextprotocol/davidsp/prompt-notif…
Browse files Browse the repository at this point in the history 
…ication

feat: add prompts/list_changed notification
  • Loading branch information
@dsp-ant
dsp-ant authored Oct 3, 2024
2 parents b03fd43 + 8a99233 commit 335bb87
Show file tree
Hide file tree
Showing 4 changed files with 125 additions and 26 deletions.
59 changes: 47 additions & 12 deletions docs/spec/prompts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
17 changes: 10 additions & 7 deletions docs/spec/resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
47 changes: 43 additions & 4 deletions schema/schema.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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"
Expand All @@ -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"
}
},
Expand All @@ -1337,6 +1373,9 @@
{
"$ref": "#/definitions/ResourceUpdatedNotification"
},
{
"$ref": "#/definitions/PromptListChangedNotification"
},
{
"$ref": "#/definitions/ToolListChangedNotification"
},
Expand Down
28 changes: 25 additions & 3 deletions schema/schema.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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;
};
}

/**
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -771,7 +792,8 @@ export type ServerNotification =
| LoggingMessageNotification
| ResourceUpdatedNotification
| ResourceListChangedNotification
| ToolListChangedNotification;
| ToolListChangedNotification
| PromptListChangedNotification;

export type ServerResult =
| EmptyResult
Expand Down

0 comments on commit 335bb87

Please sign in to comment.