Merge pull request #14 from modelcontextprotocol/davidsp/prompts

Enhance and clarify Prompts API specification

docs/spec/prompts.md

@@ -4,148 +4,241 @@ type: docs
 weight: 3
 ---
 
-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`.
+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.
 
-## Capabilities
+An example of a prompt as a slash command in the Zed editor:
+![Slash Command Example](slash-command.png)
+
+### 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.
+
+### Prompt Templates
+
+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.
+
+## Use Cases
+
+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:
+
+### Code Review
+
+A prompt template for conducting code reviews:
 
-To indicate support for the Prompts API, server and client **MUST** agree on the `prompts` capability in their capabilities during initialization.
+```json
+{
+  "name": "code_review",
+  "description": "Analyze code quality and suggest improvements",
+  "arguments": [
+    {
+      "name": "language",
+      "description": "Programming language of the code",
+      "required": true
+    },
+    {
+      "name": "code",
+      "description": "The code snippet to review",
+      "required": true
+    }
+  ]
+}
+```
 
-## Request example
+### Data Analysis
+
+A prompt for guiding data analysis tasks:
+
+```json
+{
+  "name": "data_analysis",
+  "description": "Provide step-by-step guidance for analyzing a dataset",
+  "arguments": [
+    {
+      "name": "dataset_description",
+      "description": "Brief description of the dataset",
+      "required": true
+    },
+    {
+      "name": "analysis_goal",
+      "description": "The main goal of the analysis",
+      "required": true
+    }
+  ]
+}
+```
+
+## Diagram
+
+The following diagram visualizes a common interaction sequence between
+client and server for using prompts:
 
 ```mermaid
 sequenceDiagram
     participant Client
     participant Server
 
+    Note over Client,Server: List prompts
     Client->>Server: prompts/list
     Server-->>Client: ListPromptsResult
+
     Note over Client,Server: Client selects a prompt
-    Client->>Server: prompts/get
+    Client->>Server: prompts/get (Prompt A)
     Server-->>Client: GetPromptResult
 ```
 
-# Messages
-
-## List Prompts
+## Messages
 
-The client **SHOULD** send a `prompts/list` request to retrieve a list of available prompts and prompt templates from the server.
+This section defines the protocol messages for prompt management in the Model Context Protocol (MCP).
 
-### Request
+### Listing Prompts
 
-- method: "prompts/list"
-- params: none
+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.
 
-### Response
+#### Request
 
-The server **MUST** respond with a `ListPromptsResult` as defined in the TypeScript interface:
+To retrieve a list of available prompts from the server, the client MUST send a `prompts/list` request.
 
-```typescript
-export interface ListPromptsResult extends Result {
-  prompts: Prompt[];
-}
-```
+* Method: `prompts/list`
+* Params: None
 
-Each `Prompt` object in the `prompts` array **MUST** conform to the following TypeScript interface:
-
-```typescript
-export interface Prompt {
-  name: string;
-  description?: string;
-  arguments?: {
-    name: string;
-    description?: string;
-    required?: boolean;
-  }[];
+Example request from a client to a server:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "prompts/list"
 }
 ```
 
-The server **MUST** include:
-
-- prompts: An array of `Prompt` objects describing the available prompts/templates
+#### Response
 
-Each `Prompt` object **MUST** contain:
+The server MUST respond with a `ListPromptsResult` containing:
 
-- name: A string identifying the prompt/template
-- description: An optional string describing the prompt (if provided)
-- arguments: An optional array of argument definitions (if the prompt is a template)
+- `prompts`: An array of `Prompt` objects
 
-Argument definitions, if present, **MUST** include:
-
-- name: The argument name
-- description: An optional description of the argument
-- required: An optional boolean indicating if the argument is required
+Example:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "prompts": [
+      {
+        "name": "code_review",
+        "description": "Analyze code quality and suggest improvements",
+        "arguments": [
+          {
+            "name": "language",
+            "description": "Programming language of the code",
+            "required": true
+          },
+          {
+            "name": "code",
+            "description": "The code snippet to review",
+            "required": true
+          }
+        ]
+      },
+      {
+        "name": "data_analysis",
+        "description": "Provide step-by-step guidance for analyzing a dataset",
+        "arguments": [
+          {
+            "name": "dataset_description",
+            "description": "Brief description of the dataset",
+            "required": true
+          },
+          {
+            "name": "analysis_goal",
+            "description": "The main goal of the analysis",
+            "required": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
-The server **SHOULD** provide descriptive names and descriptions to help clients understand the purpose and usage of each prompt or template.
+### Getting a Prompt
 
-## Getting a prompt
+#### Request
 
-To retrieve a specific prompt or instantiate a prompt template, the client **SHOULD** send a `prompts/get` request.
+To retrieve the contents of a specific prompt, the client MUST send a `prompts/get` request.
 
-### Request
+Method: `prompts/get`
+Params:
+  - `name`: The name of the prompt to retrieve (string, required)
+  - `arguments`: An optional object containing argument values for prompt templates
 
-- method: "prompts/get"
-- params:
-  - name: The name of the prompt/template to retrieve
-  - arguments: An optional object containing argument values for templates
+Example:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "prompts/get",
+  "params": {
+    "name": "code_review",
+    "arguments": {
+      "language": "Python",
+      "code": "def add(a, b):\n    return a + b"
+    }
+  }
+}
+```
 
-### Response
+#### Response
 
-The server **MUST** respond with a `GetPromptResult` containing:
+The server MUST respond with a `GetPromptResult` containing:
 
-- description: An optional string describing the prompt
-- messages: An array of `SamplingMessage` objects representing the prompt content
+- `description`: An optional string describing the prompt
+- `messages`: An array of `SamplingMessage` objects representing the prompt content
 
-Each `SamplingMessage` **MUST** have:
+Example:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "description": "A prompt for analyzing code quality",
+    "messages": [
+      {
+        "role": "user",
+        "content": {
+          "type": "text",
+          "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"
+        }
+      },
+      {
+        "role": "assistant",
+        "content": {
+          "type": "text",
+          "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:"
+        }
+      }
+    ]
+  }
+}
+```
 
-- role: Either "user" or "assistant"
-- content: Either a text object or an image object
+## Error Handling
 
-Text content objects **MUST** contain:
+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.
 
-- type: "text"
-- text: The text content
+## Security Considerations
 
-Image content objects **MUST** contain:
+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.
 
-- type: "image"
-- data: Base64-encoded image data
-- mimeType: The MIME type of the image
+## Capabilities
 
-Example response:
+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
 {
-  "description": "A prompt for analyzing code quality",
-  "messages": [
-    {
-      "role": "user",
-      "content": {
-        "type": "text",
-        "text": "Please review the following code snippet and provide feedback on its quality and potential improvements:"
-      }
-    },
-    {
-      "role": "assistant",
-      "content": {
-        "type": "text",
-        "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."
-      }
-    },
-    {
-      "role": "user",
-      "content": {
-        "type": "text",
-        "text": "{{code}}"
-      }
-    }
-  ]
+  "capabilities": {
+    "prompts": {}
+  }
 }
 ```
 
-In this example, `{{code}}` is a placeholder that would be replaced with the actual code snippet when the prompt is used.
-
-## Capabilities
-
-To indicate support for the Prompts API, servers **MUST** include a `prompts` capability in their `ServerCapabilities` during initialization.
-
-Clients **SHOULD** check for this capability before using the Prompts API.
+Clients SHOULD check for this capability before using the Prompts API.