.Net: Samples for MCP Resources and Resource Templates (#11433)

### Motivation, Context and Description

This PR adds two new MCP samples that demonstrate how to use SK to power
MCP resources and resource templates on the server side, and how to use
them with the SK client side.

Additionally, it updates to the latest version of the
ModelContextProtocol NuGet package.

Author: SergeyMenshykh

dotnet/Directory.Packages.props

@@ -34,7 +34,7 @@
     <PackageVersion Include="Grpc.AspNetCore.Server" Version="2.70.0" />
     <PackageVersion Include="Grpc.AspNetCore.Server.Reflection" Version="2.70.0" />
     <PackageVersion Include="Grpc.Tools" Version="2.70.0" />
-    <PackageVersion Include="ModelContextProtocol" Version="0.1.0-preview.4" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.1.0-preview.6" />
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.13" />
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="8.0.14" />
     <PackageVersion Include="Microsoft.ML.Tokenizers.Data.Cl100kBase" Version="1.0.1" />

dotnet/samples/Demos/ModelContextProtocolClientServer/MCPClient/Extensions/ReadResourceResultExtensions.cs

@@ -0,0 +1,80 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.ChatCompletion;
+using ModelContextProtocol.Protocol.Types;
+
+namespace MCPClient;
+
+/// <summary>
+/// Extension methods for <see cref="ReadResourceResult"/>.
+/// </summary>
+public static class ReadResourceResultExtensions
+{
+    /// <summary>
+    /// Converts a <see cref="ReadResourceResult"/> to a <see cref="ChatMessageContentItemCollection"/>.
+    /// </summary>
+    /// <param name="readResourceResult">The MCP read resource result to convert.</param>
+    /// <returns>The corresponding <see cref="ChatMessageContentItemCollection"/>.</returns>
+    public static ChatMessageContentItemCollection ToChatMessageContentItemCollection(this ReadResourceResult readResourceResult)
+    {
+        if (readResourceResult.Contents.Count == 0)
+        {
+            throw new InvalidOperationException("The resource does not contain any contents.");
+        }
+
+        ChatMessageContentItemCollection result = [];
+
+        foreach (var resourceContent in readResourceResult.Contents)
+        {
+            Dictionary<string, object?> metadata = new()
+            {
+                ["uri"] = resourceContent.Uri
+            };
+
+            if (resourceContent is TextResourceContents textResourceContent)
+            {
+                result.Add(new TextContent()
+                {
+                    Text = textResourceContent.Text,
+                    MimeType = textResourceContent.MimeType,
+                    Metadata = metadata,
+                });
+            }
+            else if (resourceContent is BlobResourceContents blobResourceContent)
+            {
+                if (blobResourceContent.MimeType?.StartsWith("image", System.StringComparison.InvariantCulture) ?? false)
+                {
+                    result.Add(new ImageContent()
+                    {
+                        Data = Convert.FromBase64String(blobResourceContent.Blob),
+                        MimeType = blobResourceContent.MimeType,
+                        Metadata = metadata,
+                    });
+                }
+                else if (blobResourceContent.MimeType?.StartsWith("audio", System.StringComparison.InvariantCulture) ?? false)
+                {
+                    result.Add(new AudioContent
+                    {
+                        Data = Convert.FromBase64String(blobResourceContent.Blob),
+                        MimeType = blobResourceContent.MimeType,
+                        Metadata = metadata,
+                    });
+                }
+                else
+                {
+                    result.Add(new BinaryContent
+                    {
+                        Data = Convert.FromBase64String(blobResourceContent.Blob),
+                        MimeType = blobResourceContent.MimeType,
+                        Metadata = metadata,
+                    });
+                }
+            }
+        }
+
+        return result;
+    }
+}

dotnet/samples/Demos/ModelContextProtocolClientServer/MCPClient/MCPClient.csproj

@@ -18,7 +18,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Connectors\Connectors.AzureOpenAI\Connectors.AzureOpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Connectors\Connectors.OpenAI\Connectors.OpenAI.csproj" />
     <ProjectReference Include="..\..\..\..\src\SemanticKernel.Abstractions\SemanticKernel.Abstractions.csproj" />
     <ProjectReference Include="..\..\..\..\src\SemanticKernel.Core\SemanticKernel.Core.csproj" />
   </ItemGroup>

dotnet/samples/Demos/ModelContextProtocolClientServer/MCPClient/Program.cs

@@ -20,11 +20,113 @@ internal sealed class Program
 {
     public static async Task Main(string[] args)
     {
-        // Use the MCP tools with the Semantic Kernel
-        await UseMCPToolsWithSKAsync();
+        await UseMCPToolsAsync();
 
-        // Use the MCP tools and MCP prompt with the Semantic Kernel
-        await UseMCPToolsAndPromptWithSKAsync();
+        await UseMCPToolsAndPromptAsync();
+
+        await UseMCPResourcesAsync();
+
+        await UseMCPResourceTemplatesAsync();
+    }
+
+    /// <summary>
+    /// Demonstrates how to use the MCP resources with the Semantic Kernel.
+    /// The code in this method:
+    /// 1. Creates an MCP client.
+    /// 2. Retrieves the list of resources provided by the MCP server.
+    /// 3. Retrieves the `image://cat.jpg` resource content from the MCP server.
+    /// 4. Adds the image to the chat history and prompts the AI model to describe the content of the image.
+    /// </summary>
+    private static async Task UseMCPResourcesAsync()
+    {
+        Console.WriteLine($"Running the {nameof(UseMCPResourcesAsync)} sample.");
+
+        // Create an MCP client
+        await using IMcpClient mcpClient = await CreateMcpClientAsync();
+
+        // Retrieve list of resources provided by the MCP server and display them
+        IList<Resource> resources = await mcpClient.ListResourcesAsync();
+        DisplayResources(resources);
+
+        // Create a kernel
+        Kernel kernel = CreateKernelWithChatCompletionService();
+
+        // Enable automatic function calling
+        OpenAIPromptExecutionSettings executionSettings = new()
+        {
+            Temperature = 0,
+            FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new() { RetainArgumentTypes = true })
+        };
+
+        // Retrieve the `image://cat.jpg` resource from the MCP server
+        ReadResourceResult resource = await mcpClient.ReadResourceAsync("image://cat.jpg");
+
+        // Add the resource to the chat history and prompt the AI model to describe the content of the image
+        ChatHistory chatHistory = [];
+        chatHistory.AddUserMessage(resource.ToChatMessageContentItemCollection());
+        chatHistory.AddUserMessage("Describe the content of the image?");
+
+        // Execute a prompt using the MCP resource and prompt added to the chat history
+        IChatCompletionService chatCompletion = kernel.GetRequiredService<IChatCompletionService>();
+
+        ChatMessageContent result = await chatCompletion.GetChatMessageContentAsync(chatHistory, executionSettings, kernel);
+
+        Console.WriteLine(result);
+        Console.WriteLine();
+
+        // The expected output is: The image features a fluffy cat sitting in a lush, colorful garden.
+        // The garden is filled with various flowers and plants, creating a vibrant and serene atmosphere...
+    }
+
+    /// <summary>
+    /// Demonstrates how to use the MCP resource templates with the Semantic Kernel.
+    /// The code in this method:
+    /// 1. Creates an MCP client.
+    /// 2. Retrieves the list of resource templates provided by the MCP server.
+    /// 3. Reads relevant to the prompt records from the `vectorStore://records/{prompt}` MCP resource template.
+    /// 4. Adds the records to the chat history and prompts the AI model to explain what SK is.
+    /// </summary>
+    private static async Task UseMCPResourceTemplatesAsync()
+    {
+        Console.WriteLine($"Running the {nameof(UseMCPResourceTemplatesAsync)} sample.");
+
+        // Create an MCP client
+        await using IMcpClient mcpClient = await CreateMcpClientAsync();
+
+        // Retrieve list of resource templates provided by the MCP server and display them
+        IList<ResourceTemplate> resourceTemplates = await mcpClient.ListResourceTemplatesAsync();
+        DisplayResourceTemplates(resourceTemplates);
+
+        // Create a kernel
+        Kernel kernel = CreateKernelWithChatCompletionService();
+
+        // Enable automatic function calling
+        OpenAIPromptExecutionSettings executionSettings = new()
+        {
+            Temperature = 0,
+            FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new() { RetainArgumentTypes = true })
+        };
+
+        string prompt = "What is the Semantic Kernel?";
+
+        // Retrieve relevant to the prompt records via MCP resource template
+        ReadResourceResult resource = await mcpClient.ReadResourceAsync($"vectorStore://records/{prompt}");
+
+        // Add the resource content/records to the chat history and prompt the AI model to explain what SK is
+        ChatHistory chatHistory = [];
+        chatHistory.AddUserMessage(resource.ToChatMessageContentItemCollection());
+        chatHistory.AddUserMessage(prompt);
+
+        // Execute a prompt using the MCP resource and prompt added to the chat history
+        IChatCompletionService chatCompletion = kernel.GetRequiredService<IChatCompletionService>();
+
+        ChatMessageContent result = await chatCompletion.GetChatMessageContentAsync(chatHistory, executionSettings, kernel);
+
+        Console.WriteLine(result);
+        Console.WriteLine();
+
+        // The expected output is: The Semantic Kernel (SK) is a lightweight software development kit (SDK) designed for use in .NET applications.
+        // It acts as an orchestrator that facilitates interaction between AI models and available plugins, enabling them to work together to produce desired outputs.
     }
 
     /// <summary>
@@ -38,9 +140,9 @@ public static async Task Main(string[] args)
     /// 6. The AI model calls WeatherUtils-GetWeatherForCity function with the current date time and the `Boston` arguments extracted from the prompt to get the weather information.
     /// 7. Having received the weather information from the function call, the AI model returns the answer to the prompt.
     /// </summary>
-    private static async Task UseMCPToolsWithSKAsync()
+    private static async Task UseMCPToolsAsync()
     {
-        Console.WriteLine($"Running the {nameof(UseMCPToolsWithSKAsync)} sample.");
+        Console.WriteLine($"Running the {nameof(UseMCPToolsAsync)} sample.");
 
         // Create an MCP client
         await using IMcpClient mcpClient = await CreateMcpClientAsync();
@@ -86,9 +188,9 @@ private static async Task UseMCPToolsWithSKAsync()
     /// 9. The AI model calls WeatherUtils-GetWeatherForCity function with the current date time and the `Boston` arguments extracted from the prompt to get the weather information.
     /// 10. Having received the weather information from the function call, the AI model returns the answer to the prompt.
     /// </summary>
-    private static async Task UseMCPToolsAndPromptWithSKAsync()
+    private static async Task UseMCPToolsAndPromptAsync()
     {
-        Console.WriteLine($"Running the {nameof(UseMCPToolsAndPromptWithSKAsync)} sample.");
+        Console.WriteLine($"Running the {nameof(UseMCPToolsAndPromptAsync)} sample.");
 
         // Create an MCP client
         await using IMcpClient mcpClient = await CreateMcpClientAsync();
@@ -208,7 +310,7 @@ private static void DisplayTools(IList<McpClientTool> tools)
         Console.WriteLine("Available MCP tools:");
         foreach (var tool in tools)
         {
-            Console.WriteLine($"- {tool.Name}: {tool.Description}");
+            Console.WriteLine($"- Name: {tool.Name}, Description: {tool.Description}");
         }
         Console.WriteLine();
     }
@@ -222,7 +324,27 @@ private static void DisplayPrompts(IList<McpClientPrompt> prompts)
         Console.WriteLine("Available MCP prompts:");
         foreach (var prompt in prompts)
         {
-            Console.WriteLine($"- {prompt.Name}: {prompt.Description}");
+            Console.WriteLine($"- Name: {prompt.Name}, Description: {prompt.Description}");
+        }
+        Console.WriteLine();
+    }
+
+    private static void DisplayResources(IList<Resource> resources)
+    {
+        Console.WriteLine("Available MCP resources:");
+        foreach (var resource in resources)
+        {
+            Console.WriteLine($"- Name: {resource.Name}, Uri: {resource.Uri}, Description: {resource.Description}");
+        }
+        Console.WriteLine();
+    }
+
+    private static void DisplayResourceTemplates(IList<ResourceTemplate> resourceTemplates)
+    {
+        Console.WriteLine("Available MCP resource templates:");
+        foreach (var template in resourceTemplates)
+        {
+            Console.WriteLine($"- Name: {template.Name}, Description: {template.Description}");
         }
         Console.WriteLine();
     }

dotnet/samples/Demos/ModelContextProtocolClientServer/MCPServer/EmbeddedResource.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Reflection;
+
+namespace MCPServer;
+
+/// <summary>
+/// Reads embedded resources.
+/// </summary>
+public static class EmbeddedResource
+{
+    private static readonly string? s_namespace = typeof(EmbeddedResource).Namespace;
+
+    /// <summary>
+    /// Read an embedded resource as a string.
+    /// </summary>
+    /// <param name="resourcePath">The path to the resource, relative to the assembly namespace.</param>
+    /// <returns>A string containing the resource content.</returns>
+    public static string ReadAsString(string resourcePath)
+    {
+        Stream stream = ReadAsStream(resourcePath);
+
+        using StreamReader reader = new(stream);
+        return reader.ReadToEnd();
+    }
+
+    /// <summary>
+    /// Read an embedded resource as a byte array.
+    /// </summary>
+    /// <param name="resourcePath">The path to the resource, relative to the assembly namespace.</param>
+    /// <returns>A byte array containing the resource content.</returns>
+    public static byte[] ReadAsBytes(string resourcePath)
+    {
+        Stream stream = ReadAsStream(resourcePath);
+
+        using MemoryStream memoryStream = new();
+        stream.CopyTo(memoryStream);
+        return memoryStream.ToArray();
+    }
+
+    /// <summary>
+    /// Read an embedded resource as a stream.
+    /// </summary>
+    /// <param name="resourcePath">The path to the resource, relative to the assembly namespace.</param>
+    /// <returns>A stream containing the resource content.</returns>
+    public static Stream ReadAsStream(string resourcePath)
+    {
+        // Get the current assembly. Note: this class is in the same assembly where the embedded resources are stored.
+        Assembly assembly =
+            typeof(EmbeddedResource).GetTypeInfo().Assembly ??
+            throw new InvalidOperationException($"[{s_namespace}] {resourcePath} assembly not found");
+
+        // Resources are mapped like types, using the namespace and appending "." (dot) and the file name
+        string resourceName = $"{s_namespace}.{resourcePath}";
+
+        return
+            assembly.GetManifestResourceStream(resourceName) ??
+            throw new InvalidOperationException($"{resourceName} resource not found");
+    }
+}