Add support for MCP prompts (#336)

Author: josesimoes

README.md

@@ -1,4 +1,4 @@
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=nanoframework_lib-nanoframework.WebServer&metric=alert_status)](https://sonarcloud.io/dashboard?id=nanoframework_lib-nanoframework.WebServer) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=nanoframework_lib-nanoframework.WebServer&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=nanoframework_lib-nanoframework.WebServer) [![NuGet](https://img.shields.io/nuget/dt/nanoFramework.WebServer.svg?label=NuGet&style=flat&logo=nuget)](https://www.nuget.org/packages/nanoFramework.WebServer/) [![#yourfirstpr](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://github.com/nanoframework/Home/blob/main/CONTRIBUTING.md) [![Discord](https://img.shields.io/discord/478725473862549535.svg?logo=discord&logoColor=white&label=Discord&color=7289DA)](https://discord.gg/gCyBu8T)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=nanoframework_lib-nanoframework.WebServer&metric=alert_status)](https://sonarcloud.io/dashboard?id=nanoframework_lib-nanoframework.WebServer) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=nanoframework_lib-nanoframework.WebServer&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=nanoframework_lib-nanoframework.WebServer) [![NuGet](https://img.shields.io/nuget/dt/nanoFramework.WebServer.svg?label=NuGet&style=flat&logo=nuget)](https://www.nuget.org/packages/nanoFramework.WebServer/) [![#yourfirstpr](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://github.com/nanoframework/Home/blob/main/CONTRIBUTING.md) [![Discord](https://img.shields.io/discord/478725473862549535.svg?logo=discord&logoColor=white&label=Discord&color=7289DA)](https://discord.gg/gCyBu8T)
 
 ![nanoFramework logo](https://raw.githubusercontent.com/nanoframework/Home/main/resources/logo/nanoFramework-repo-logo.png)
 
@@ -60,7 +60,7 @@ private static void ServerCommandReceived(object source, WebServerEventArgs e)
 
 ### Controller-Based WebServer
 
-Controllers are supported including with parametarized routes like `api/led/{id}/dosomething/{order}`.
+Controllers are supported including with parametarized routes like 'api/led/{id}/dosomething/{order}'.
 
 ```csharp
 using (WebServer server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(MyController) }))
@@ -119,6 +119,30 @@ public class LedCommand
 }
 ```
 
+### Defining MCP Prompts
+
+You can define reusable, high-level prompts for AI agents using the `McpServerPrompt` attribute. Prompts encapsulate multi-step instructions or workflows that can be invoked by agents.
+
+Here's a simple example:
+
+```csharp
+using nanoFramework.WebServer.Mcp;
+
+public class McpPrompts
+{
+    [McpServerPrompt("echo_sanity_check", "Echo test prompt")]
+    public static PromptMessage[] EchoSanityCheck()
+    {
+        return new PromptMessage[]
+        {
+            new PromptMessage("Call Echo with the string 'Hello MCP world!' and return the response.")
+        };
+    }
+}
+```
+
+Prompts can be discovered and invoked by AI agents in the same way as tools. You can also define prompts with parameters using the `McpPromptParameter` attribute.
+
 ### Setting Up MCP Server
 
 ```csharp
@@ -129,6 +153,9 @@ public static void Main()
 
     // Discover and register MCP tools
     McpToolRegistry.DiscoverTools(new Type[] { typeof(IoTTools) });
+
+    // Discover and register MCP prompts
+    McpPromptRegistry.DiscoverPrompts(new Type[] { typeof(McpPrompts) });
 
     // Start WebServer with MCP support
     using (var server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(McpServerController) }))
@@ -187,11 +214,12 @@ POST /mcp
 - No compression support in request/response streams
 - MCP implementation supports server features only (no notifications or SSE)
 - No or single parameter limitation for MCP tools (use complex objects for multiple parameters)
+- Prompt parameters, when declared, are always mandatory.
 
 ## Installation
 
-Install `nanoFramework.WebServer` for the Web Server without File System support. Install `nanoFramework.WebServer.FileSystem` for file serving, so with devices supporting File System.
-Install `nanoFramework.WebServer.Mcp` for MCP support. It does contains the full `nanoFramework.WebServer` but does not include native file serving. You can add this feature fairly easilly by reusing the code function serving it.
+Install 'nanoFramework.WebServer' for the Web Server without File System support. Install 'nanoFramework.WebServer.FileSystem' for file serving, so with devices supporting File System.
+Install 'nanoFramework.WebServer.Mcp' for MCP support. It does contains the full 'nanoFramework.WebServer' but does not include native file serving. You can add this feature fairly easilly by reusing the code function serving it.
 
 ## Contributing
 

doc/model-context-protocol.md

@@ -27,14 +27,50 @@ The Model Context Protocol (MCP) is an open standard that enables seamless integ
 
 ### Key Features
 
-- **Automatic tool discovery** through reflection and attributes
+- **Automatic tool and prompt discovery** through reflection and attributes
+- **MCP Prompts**: Define reusable, high-level prompt workflows for AI agents, with support for parameters
 - **JSON-RPC 2.0 compliant** request/response handling
 - **Type-safe parameter handling** with automatic deserialization from JSON to .NET objects
 - **Flexible authentication** options (none, basic auth, API key)
 - **Complex object support** for both input parameters and return values
 - **Robust error handling** and validation
 - **Memory efficient** implementation optimized for embedded devices
 - **HTTPS support** with SSL/TLS encryption
+## Defining MCP Prompts
+
+MCP Prompts allow you to define reusable, multi-step instructions or workflows that can be invoked by AI agents. Prompts are discovered and registered similarly to tools, using the `[McpServerPrompt]` attribute on static methods that return an array of `PromptMessage`.
+
+Prompts can encapsulate complex logic, multi-step flows, or provide high-level instructions for agents. You can also define parameters for prompts using the `[McpPromptParameter]` attribute. **All parameters defined for a prompt are mandatory.**
+
+### Example: Defining a Prompt
+
+```csharp
+using nanoFramework.WebServer.Mcp;
+
+public class McpPrompts
+{
+    [McpServerPrompt("echo_sanity_check", "Echo test prompt")]
+    public static PromptMessage[] EchoSanityCheck()
+    {
+        return new PromptMessage[]
+        {
+            new PromptMessage("Call Echo with the string 'Hello MCP world!' and return the response.")
+        };
+    }
+
+    [McpServerPrompt("summarize_person", "Summarize a person with age threshold")]
+    [McpPromptParameter("ageThreshold", "The age threshold to determine if the person is a senior or junior.")]
+    public static PromptMessage[] SummarizePerson(string ageThreshold)
+    {
+        return new PromptMessage[]
+        {
+            new PromptMessage($"Call GetDefaultPerson, then if person.Age > {ageThreshold} label as senior, else junior.")
+        };
+    }
+}
+```
+
+Prompts are listed and invoked via the MCP protocol, just like tools.
 
 ### Supported Version
 
@@ -309,6 +345,11 @@ public static void Main()
         typeof(SensorTools)
     });
 
+    // Discover and register prompts
+    McpPromptRegistry.DiscoverPrompts(new Type[] {
+        typeof(McpPrompts)
+    });
+
     // Step 3: Start WebServer with MCP support
     using (var server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(McpServerController) }))
     {
@@ -482,7 +523,8 @@ POST /mcp
 }
 ```
 
-### 2. Tool Discovery
+
+### 2. Tool and Prompt Discovery
 
 Agent discovers available tools:
 
@@ -495,7 +537,18 @@ POST /mcp
 }
 ```
 
-The response will be the list of the tools. See next section for detailed examples.
+And prompts:
+
+```json
+POST /mcp
+{
+    "jsonrpc": "2.0",
+    "method": "prompts/list",
+    "id": 2
+}
+```
+
+There will be responses for tools and prompts. See next section for detailed examples.
 
 ### 3. Tool Invocation
 
@@ -519,15 +572,15 @@ POST /mcp
 
 ## Request/Response Examples
 
-This section shows real exampled of requests and responses.
+This section shows real examples of requests and responses.
+
 
 ### Tool Discovery
 
 **Request:**
 
 ```json
 POST /mcp
-
 {
     "jsonrpc": "2.0",
     "method": "tools/list",
@@ -611,6 +664,61 @@ POST /mcp
 }
 ```
 
+### Prompt Discovery
+
+**Request:**
+
+```json
+POST /mcp
+{
+    "jsonrpc": "2.0",
+    "method": "prompts/list",
+    "id": 1
+}
+```
+
+**Response:**
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {
+        "prompts": [
+            {
+                "name": "echo_sanity_check",
+                "description": "Echo test prompt",
+                "parameters": [],
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": "Call Echo with the string 'Hello MCP world!' and return the response."
+                    }
+                ]
+            },
+            {
+                "name": "summarize_person",
+                "description": "Summarize a person with age threshold",
+                "parameters": [
+                    {
+                        "name": "ageThreshold",
+                        "description": "The age threshold to determine if the person is a senior or junior.",
+                        "type": "string"
+                    }
+                ],
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": "Call GetDefaultPerson, then if person.Age > {ageThreshold} label as senior, else junior."
+                    }
+                ]
+            }
+        ],
+        "nextCursor": null
+    }
+}
+```
+
 ### Simple Tool Invocation
 
 **Request:**
@@ -714,6 +822,78 @@ POST /mcp
 }
 ```
 
+### Prompt usage
+
+#### Prompt Retrieval Example
+
+To retrieve a prompt, use the `prompts/get` method. Provide the prompt name and any required parameters.
+
+**Request:**
+
+```json
+POST /mcp
+{
+    "jsonrpc": "2.0",
+    "method": "prompts/get",
+    "params": {
+        "name": "echo_sanity_check",
+        "arguments": {}
+    },
+    "id": 5
+}
+```
+
+**Response:**
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 5,
+    "result": {
+        "messages": [
+            {
+                "role": "system",
+                "content": "Call Echo with the string 'Hello MCP world!' and return the response."
+            }
+        ]
+    }
+}
+```
+
+If the prompt requires parameters, include them in the `arguments` object:
+
+```json
+POST /mcp
+{
+    "jsonrpc": "2.0",
+    "method": "prompts/get",
+    "params": {
+        "name": "summarize_person",
+        "arguments": {
+            "ageThreshold": "65"
+        }
+    },
+    "id": 6
+}
+```
+
+**Response:**
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 6,
+    "result": {
+        "messages": [
+            {
+                "role": "system",
+                "content": "Call GetDefaultPerson, then if person.Age > 65 label as senior, else junior."
+            }
+        ]
+    }
+}
+```
+
 ## Error Handling
 
 The .NET nanoFramework MCP Server knows how to handle properly errors. The following will show examples of request and error responses.

nanoFramework.WebServer.Mcp/McpPromptMessage.cs

@@ -0,0 +1,55 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace nanoFramework.WebServer.Mcp
+{
+    /// <summary>
+    /// Represents a message within the Model Context Protocol (MCP) system, used for communication between clients and AI models.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A <see cref="PromptMessage"/> encapsulates content sent to or received from AI models in the Model Context Protocol.
+    /// Each message has a specific role (<see cref="Role.User"/> or <see cref="Role.Assistant"/>) and contains content which can be text.
+    /// </para>
+    /// <para>
+    /// It serves as a core data structure in the MCP message exchange flow, particularly in prompt formation and model responses.
+    /// </para>
+    /// </remarks>
+    public sealed class PromptMessage
+    {
+        /// <summary>
+        /// Gets or sets the text content of the message.
+        /// </summary>
+        public string Text { get; set; }
+
+        /// <summary>
+        /// Gets or sets the role of the message sender, specifying whether it's from a "user" or an "assistant".
+        /// </summary>
+        /// <remarks>
+        /// In the Model Context Protocol, each message must have a clear role assignment to maintain
+        /// the conversation flow. User messages represent queries or inputs from users, while assistant
+        /// messages represent responses generated by AI models.
+        /// </remarks>
+        public Role Role { get; set; } = Role.User;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PromptMessage"/> class with this prompt text.
+        /// </summary>
+        /// <param name="text">The text content of the message.</param>
+        public PromptMessage(string text)
+        {
+            Text = text;
+        }
+
+        /// <inheritdoc/>
+        public override string ToString()
+        {
+            return $"{{\"role\":\"{RoleToString(Role)}\",\"content\":{{\"type\": \"text\",\"text\":\"{Text}\"}}}}";
+        }
+
+        private static string RoleToString(Role role)
+        {
+            return role == Role.User ? "user" : "assistant";
+        }
+    }
+}