Skip to content

Commit b03fd43

Browse files
dsp-antdsp-ant
authored
Merge pull request modelcontextprotocol#14 from modelcontextprotocol/davidsp/prompts
Enhance and clarify Prompts API specification
2 parents 6be0e7d + 7f0ec2d commit b03fd43

File tree

1 file changed

+189
-96
lines changed

1 file changed

+189
-96
lines changed

‎docs/spec/prompts.md‎

Lines changed: 189 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -4,148 +4,241 @@ type: docs
44
weight: 3
55
---
66

7-
The Prompts API allows clients to retrieve information about available prompts and prompt templates from the server. Prompts are templated conversations with a model that the client can retrieve. Commonly clients present available prompts to users as slash/at commands or similar approaches, e.g. by typing `/a-prompt`.
7+
Prompts enable servers to provide templated conversations or instructions to clients in a structured way, specifically for interacting with language models. Clients can discover available prompts, retrieve their contents, and optionally provide arguments to customize them. Users may explicitly select prompts via the client UI, or clients can intelligently suggest appropriate prompts based on context. Each prompt is uniquely identified by a name.
88

9-
## Capabilities
9+
An example of a prompt as a slash command in the Zed editor:
10+
![Slash Command Example](slash-command.png)
11+
12+
### Prompt
13+
14+
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.
15+
16+
### Prompt Templates
17+
18+
Prompt Templates are prompts that can be dynamically generated or customized based on provided arguments. They allow servers to expose a flexible set of prompts that can be tailored to specific use cases. Clients can use these templates by providing the required arguments when retrieving the prompt.
19+
20+
## Use Cases
21+
22+
Common use cases for prompts include providing standardized instructions for code reviews, data analysis tasks, or creative writing exercises. Here are examples of kinds of prompts that an MCP server could expose:
23+
24+
### Code Review
25+
26+
A prompt template for conducting code reviews:
1027

11-
To indicate support for the Prompts API, server and client **MUST** agree on the `prompts` capability in their capabilities during initialization.
28+
```json
29+
{
30+
"name": "code_review",
31+
"description": "Analyze code quality and suggest improvements",
32+
"arguments": [
33+
{
34+
"name": "language",
35+
"description": "Programming language of the code",
36+
"required": true
37+
},
38+
{
39+
"name": "code",
40+
"description": "The code snippet to review",
41+
"required": true
42+
}
43+
]
44+
}
45+
```
1246

13-
## Request example
47+
### Data Analysis
48+
49+
A prompt for guiding data analysis tasks:
50+
51+
```json
52+
{
53+
"name": "data_analysis",
54+
"description": "Provide step-by-step guidance for analyzing a dataset",
55+
"arguments": [
56+
{
57+
"name": "dataset_description",
58+
"description": "Brief description of the dataset",
59+
"required": true
60+
},
61+
{
62+
"name": "analysis_goal",
63+
"description": "The main goal of the analysis",
64+
"required": true
65+
}
66+
]
67+
}
68+
```
69+
70+
## Diagram
71+
72+
The following diagram visualizes a common interaction sequence between
73+
client and server for using prompts:
1474

1575
```mermaid
1676
sequenceDiagram
1777
participant Client
1878
participant Server
1979
80+
Note over Client,Server: List prompts
2081
Client->>Server: prompts/list
2182
Server-->>Client: ListPromptsResult
83+
2284
Note over Client,Server: Client selects a prompt
23-
Client->>Server: prompts/get
85+
Client->>Server: prompts/get (Prompt A)
2486
Server-->>Client: GetPromptResult
2587
```
2688

27-
# Messages
28-
29-
## List Prompts
89+
## Messages
3090

31-
The client **SHOULD** send a `prompts/list` request to retrieve a list of available prompts and prompt templates from the server.
91+
This section defines the protocol messages for prompt management in the Model Context Protocol (MCP).
3292

33-
### Request
93+
### Listing Prompts
3494

35-
- method: "prompts/list"
36-
- params: none
95+
The Listing Prompts operation allows clients to discover available prompts on the server. This operation is fundamental to the prompt management process in the Model Context Protocol (MCP). When a client sends a `prompts/list` request, the server responds with a comprehensive list of prompts and prompt templates it can provide. This list enables clients to understand what prompts are available, facilitating subsequent operations such as retrieving specific prompts.
3796

38-
### Response
97+
#### Request
3998

40-
The server **MUST** respond with a `ListPromptsResult` as defined in the TypeScript interface:
99+
To retrieve a list of available prompts from the server, the client MUST send a `prompts/list` request.
41100

42-
```typescript
43-
export interface ListPromptsResult extends Result {
44-
prompts: Prompt[];
45-
}
46-
```
101+
* Method: `prompts/list`
102+
* Params: None
47103

48-
Each `Prompt` object in the `prompts` array **MUST** conform to the following TypeScript interface:
49-
50-
```typescript
51-
export interface Prompt {
52-
name: string;
53-
description?: string;
54-
arguments?: {
55-
name: string;
56-
description?: string;
57-
required?: boolean;
58-
}[];
104+
Example request from a client to a server:
105+
```json
106+
{
107+
"jsonrpc": "2.0",
108+
"id": 1,
109+
"method": "prompts/list"
59110
}
60111
```
61112

62-
The server **MUST** include:
63-
64-
- prompts: An array of `Prompt` objects describing the available prompts/templates
113+
#### Response
65114

66-
Each `Prompt` object **MUST** contain:
115+
The server MUST respond with a `ListPromptsResult` containing:
67116

68-
- name: A string identifying the prompt/template
69-
- description: An optional string describing the prompt (if provided)
70-
- arguments: An optional array of argument definitions (if the prompt is a template)
117+
- `prompts`: An array of `Prompt` objects
71118

72-
Argument definitions, if present, **MUST** include:
73-
74-
- name: The argument name
75-
- description: An optional description of the argument
76-
- required: An optional boolean indicating if the argument is required
119+
Example:
120+
```json
121+
{
122+
"jsonrpc": "2.0",
123+
"id": 1,
124+
"result": {
125+
"prompts": [
126+
{
127+
"name": "code_review",
128+
"description": "Analyze code quality and suggest improvements",
129+
"arguments": [
130+
{
131+
"name": "language",
132+
"description": "Programming language of the code",
133+
"required": true
134+
},
135+
{
136+
"name": "code",
137+
"description": "The code snippet to review",
138+
"required": true
139+
}
140+
]
141+
},
142+
{
143+
"name": "data_analysis",
144+
"description": "Provide step-by-step guidance for analyzing a dataset",
145+
"arguments": [
146+
{
147+
"name": "dataset_description",
148+
"description": "Brief description of the dataset",
149+
"required": true
150+
},
151+
{
152+
"name": "analysis_goal",
153+
"description": "The main goal of the analysis",
154+
"required": true
155+
}
156+
]
157+
}
158+
]
159+
}
160+
}
161+
```
77162

78-
The server **SHOULD** provide descriptive names and descriptions to help clients understand the purpose and usage of each prompt or template.
163+
### Getting a Prompt
79164

80-
## Getting a prompt
165+
#### Request
81166

82-
To retrieve a specific prompt or instantiate a prompt template, the client **SHOULD** send a `prompts/get` request.
167+
To retrieve the contents of a specific prompt, the client MUST send a `prompts/get` request.
83168

84-
### Request
169+
Method: `prompts/get`
170+
Params:
171+
- `name`: The name of the prompt to retrieve (string, required)
172+
- `arguments`: An optional object containing argument values for prompt templates
85173

86-
- method: "prompts/get"
87-
- params:
88-
- name: The name of the prompt/template to retrieve
89-
- arguments: An optional object containing argument values for templates
174+
Example:
175+
```json
176+
{
177+
"jsonrpc": "2.0",
178+
"id": 2,
179+
"method": "prompts/get",
180+
"params": {
181+
"name": "code_review",
182+
"arguments": {
183+
"language": "Python",
184+
"code": "def add(a, b):\n return a + b"
185+
}
186+
}
187+
}
188+
```
90189

91-
### Response
190+
#### Response
92191

93-
The server **MUST** respond with a `GetPromptResult` containing:
192+
The server MUST respond with a `GetPromptResult` containing:
94193

95-
- description: An optional string describing the prompt
96-
- messages: An array of `SamplingMessage` objects representing the prompt content
194+
- `description`: An optional string describing the prompt
195+
- `messages`: An array of `SamplingMessage` objects representing the prompt content
97196

98-
Each `SamplingMessage` **MUST** have:
197+
Example:
198+
```json
199+
{
200+
"jsonrpc": "2.0",
201+
"id": 2,
202+
"result": {
203+
"description": "A prompt for analyzing code quality",
204+
"messages": [
205+
{
206+
"role": "user",
207+
"content": {
208+
"type": "text",
209+
"text": "Please review the following Python code snippet and provide feedback on its quality and potential improvements:\n\ndef add(a, b):\n return a + b"
210+
}
211+
},
212+
{
213+
"role": "assistant",
214+
"content": {
215+
"type": "text",
216+
"text": "Certainly! I'd be happy to review the Python code snippet and provide feedback on its quality and potential improvements. Let's analyze it:"
217+
}
218+
}
219+
]
220+
}
221+
}
222+
```
99223

100-
- role: Either "user" or "assistant"
101-
- content: Either a text object or an image object
224+
## Error Handling
102225

103-
Text content objects **MUST** contain:
226+
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.
104227

105-
- type: "text"
106-
- text: The text content
228+
## Security Considerations
107229

108-
Image content objects **MUST** contain:
230+
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.
109231

110-
- type: "image"
111-
- data: Base64-encoded image data
112-
- mimeType: The MIME type of the image
232+
## Capabilities
113233

114-
Example response:
234+
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:
115235

116236
```json
117237
{
118-
"description": "A prompt for analyzing code quality",
119-
"messages": [
120-
{
121-
"role": "user",
122-
"content": {
123-
"type": "text",
124-
"text": "Please review the following code snippet and provide feedback on its quality and potential improvements:"
125-
}
126-
},
127-
{
128-
"role": "assistant",
129-
"content": {
130-
"type": "text",
131-
"text": "Certainly! I'd be happy to review the code snippet and provide feedback on its quality and potential improvements. Please share the code you'd like me to analyze."
132-
}
133-
},
134-
{
135-
"role": "user",
136-
"content": {
137-
"type": "text",
138-
"text": "{{code}}"
139-
}
140-
}
141-
]
238+
"capabilities": {
239+
"prompts": {}
240+
}
142241
}
143242
```
144243

145-
In this example, `{{code}}` is a placeholder that would be replaced with the actual code snippet when the prompt is used.
146-
147-
## Capabilities
148-
149-
To indicate support for the Prompts API, servers **MUST** include a `prompts` capability in their `ServerCapabilities` during initialization.
150-
151-
Clients **SHOULD** check for this capability before using the Prompts API.
244+
Clients SHOULD check for this capability before using the Prompts API.

0 commit comments

Comments
 (0)