Merge pull request modelcontextprotocol#34 from modelcontextprotocol/justin/resources-in-messages

Support embedding resource contents in prompts

Author: jspahrsummers

docs/spec/prompts.md

@@ -47,6 +47,10 @@ A Prompt in the Model Context Protocol (MCP) represents a pre-defined set of mes
 
 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.
 
+### Embedded Resource Contents
+
+Prompts can include embedded resource contents from the MCP server. This allows servers to provide context-rich prompts that incorporate relevant data or files directly into the prompt structure.
+
 ## 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:
@@ -222,7 +226,7 @@ Example:
 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
+- `messages`: An array of `PromptMessage` objects representing the prompt content, which may include embedded resource contents
 
 Example:
 ```json
@@ -245,6 +249,22 @@ Example:
           "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": "user",
+        "content": {
+          "type": "resource",
+          "uri": "file:///workspace/project/requirements.txt",
+          "mimeType": "text/plain",
+          "text": "flask==2.0.1\nnumpy==1.21.0\npandas==1.3.0\n"
+        }
+      },
+      {
+        "role": "assistant",
+        "content": {
+          "type": "text",
+          "text": "I see you've also provided the contents of the requirements.txt file. This gives us additional context about the project environment. Let's consider these dependencies in our code review as well."
+        }
       }
     ]
   }

schema/schema.json

@@ -416,7 +416,7 @@
                 },
                 "messages": {
                     "items": {
-                        "$ref": "#/definitions/SamplingMessage"
+                        "$ref": "#/definitions/PromptMessage"
                     },
                     "type": "array"
                 }
@@ -1195,6 +1195,36 @@
             ],
             "type": "object"
         },
+        "PromptMessage": {
+            "description": "Describes a message returned as part of a prompt.\n\nThis is similar to `SamplingMessage`, but also supports the embedding of\nresource contents from the MCP server.",
+            "properties": {
+                "content": {
+                    "anyOf": [
+                        {
+                            "$ref": "#/definitions/TextContent"
+                        },
+                        {
+                            "$ref": "#/definitions/ImageContent"
+                        },
+                        {
+                            "$ref": "#/definitions/PromptResourceContents"
+                        }
+                    ]
+                },
+                "role": {
+                    "enum": [
+                        "assistant",
+                        "user"
+                    ],
+                    "type": "string"
+                }
+            },
+            "required": [
+                "content",
+                "role"
+            ],
+            "type": "object"
+        },
         "PromptReference": {
             "description": "Identifies a prompt.",
             "properties": {
@@ -1213,6 +1243,29 @@
             ],
             "type": "object"
         },
+        "PromptResourceContents": {
+            "description": "The contents of a resource, embedded into a prompt.\n\nIt is up to the client how best to render embedded resources for the benefit\nof the LLM and/or the user.",
+            "properties": {
+                "mimeType": {
+                    "description": "The MIME type of this resource, if known.",
+                    "type": "string"
+                },
+                "type": {
+                    "const": "resource",
+                    "type": "string"
+                },
+                "uri": {
+                    "description": "The URI of this resource.",
+                    "format": "uri",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "type",
+                "uri"
+            ],
+            "type": "object"
+        },
         "ReadResourceRequest": {
             "description": "Sent from the client to the server, to read a specific resource URI.",
             "properties": {

schema/schema.ts

@@ -157,10 +157,6 @@ export interface ClientCapabilities {
    * Experimental, non-standard capabilities that the client supports.
    */
   experimental?: { [key: string]: object };
-  /**
-   * Present if the client supports sampling from an LLM.
-   */
-  sampling?: object;
   /**
    * Present if the client supports listing roots.
    */
@@ -170,6 +166,10 @@ export interface ClientCapabilities {
      */
     listChanged?: boolean;
   };
+  /**
+   * Present if the client supports sampling from an LLM.
+   */
+  sampling?: object;
 }
 
 /**
@@ -515,7 +515,7 @@ export interface GetPromptResult extends Result {
    * An optional description for the prompt.
    */
   description?: string;
-  messages: SamplingMessage[];
+  messages: PromptMessage[];
 }
 
 /**
@@ -554,6 +554,27 @@ export interface PromptArgument {
   required?: boolean;
 }
 
+/**
+ * Describes a message returned as part of a prompt.
+ *
+ * This is similar to `SamplingMessage`, but also supports the embedding of
+ * resource contents from the MCP server. 
+ */
+export interface PromptMessage {
+  role: "user" | "assistant";
+  content: TextContent | ImageContent | PromptResourceContents;
+}
+
+/**
+ * The contents of a resource, embedded into a prompt.
+ * 
+ * It is up to the client how best to render embedded resources for the benefit
+ * of the LLM and/or the user.
+ */
+export interface PromptResourceContents extends ResourceContents {
+  type: "resource";
+}
+
 /**
  * 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.
  */