chore: import upstream snapshot with attribution

2026-07-13 13:21:23 +08:00
commit b957a53def
5423 changed files with 863745 additions and 0 deletions
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
+    <NoWarn>$(NoWarn);CA2249;CS0612;SKEXP0001;VSTHRD111;CA2007;RCS1263</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="ModelContextProtocol" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Debug" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Agents\Abstractions\Agents.Abstractions.csproj" />
+    <ProjectReference Include="..\..\..\src\Agents\Core\Agents.Core.csproj" />
+    <ProjectReference Include="..\..\..\src\Connectors\Connectors.AzureOpenAI\Connectors.AzureOpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\SemanticKernel.Abstractions\SemanticKernel.Abstractions.csproj" />
+    <ProjectReference Include="..\..\..\src\SemanticKernel.Core\SemanticKernel.Core.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,188 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Net;
+using System.Text;
+using System.Web;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using ModelContextProtocol.Client;
+
+var config = new ConfigurationBuilder()
+    .AddUserSecrets<Program>()
+    .AddEnvironmentVariables()
+    .Build();
+
+if (config["OpenAI:ApiKey"] is not { } apiKey)
+{
+    Console.Error.WriteLine("Please provide a valid OpenAI:ApiKey to run this sample. See the associated README.md for more details.");
+    return;
+}
+
+// We can customize a shared HttpClient with a custom handler if desired
+using var sharedHandler = new SocketsHttpHandler
+{
+    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
+    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1)
+};
+using var httpClient = new HttpClient(sharedHandler);
+
+var consoleLoggerFactory = LoggerFactory.Create(builder =>
+{
+    builder.AddConsole();
+});
+
+// Create streamable HTTP client transport for the MCP server
+var serverUrl = "http://localhost:7071/";
+var transport = new HttpClientTransport(new()
+{
+    Endpoint = new Uri(serverUrl),
+    Name = "Secure Weather Client",
+    OAuth = new()
+    {
+        ClientId = "ProtectedMcpClient",
+        RedirectUri = new Uri("http://localhost:1179/callback"),
+        AuthorizationRedirectDelegate = HandleAuthorizationUrlAsync,
+    }
+}, httpClient, consoleLoggerFactory);
+
+// Create an MCPClient for the protected MCP server
+await using var mcpClient = await McpClient.CreateAsync(transport, loggerFactory: consoleLoggerFactory);
+
+// Retrieve the list of tools available on the GitHub server
+var tools = await mcpClient.ListToolsAsync().ConfigureAwait(false);
+foreach (var tool in tools)
+{
+    Console.WriteLine($"{tool.Name}: {tool.Description}");
+}
+
+// Prepare and build kernel with the MCP tools as Kernel functions
+var builder = Kernel.CreateBuilder();
+builder.Services
+    .AddLogging(c => c.AddDebug().SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Trace))
+    .AddOpenAIChatCompletion(
+        modelId: config["OpenAI:ChatModelId"] ?? "gpt-4o-mini",
+        apiKey: apiKey);
+Kernel kernel = builder.Build();
+kernel.Plugins.AddFromFunctions("WeatherApi", tools.Select(aiFunction => aiFunction.AsKernelFunction()));
+
+// Enable automatic function calling
+OpenAIPromptExecutionSettings executionSettings = new()
+{
+    Temperature = 0,
+    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new() { RetainArgumentTypes = true })
+};
+
+// Test using weather tools
+var prompt = "Get current weather alerts for New York?";
+var result = await kernel.InvokePromptAsync(prompt, new(executionSettings)).ConfigureAwait(false);
+Console.WriteLine($"\n\n{prompt}\n{result}");
+
+// Define the agent
+ChatCompletionAgent agent = new()
+{
+    Instructions = "Answer questions about weather alerts for US states.",
+    Name = "WeatherAgent",
+    Kernel = kernel,
+    Arguments = new KernelArguments(executionSettings),
+};
+
+// Respond to user input, invoking functions where appropriate.
+ChatMessageContent response = await agent.InvokeAsync("Get the current weather alerts for Washington?").FirstAsync();
+Console.WriteLine($"\n\nResponse from WeatherAgent:\n{response.Content}");
+
+/// <summary>
+/// Handles the OAuth authorization URL by starting a local HTTP server and opening a browser.
+/// This implementation demonstrates how SDK consumers can provide their own authorization flow.
+/// </summary>
+/// <param name="authorizationUrl">The authorization URL to open in the browser.</param>
+/// <param name="redirectUri">The redirect URI where the authorization code will be sent.</param>
+/// <param name="cancellationToken">The cancellation token.</param>
+/// <returns>The authorization code extracted from the callback, or null if the operation failed.</returns>
+static async Task<string?> HandleAuthorizationUrlAsync(Uri authorizationUrl, Uri redirectUri, CancellationToken cancellationToken)
+{
+    Console.WriteLine("Starting OAuth authorization flow...");
+    Console.WriteLine($"Opening browser to: {authorizationUrl}");
+
+    var listenerPrefix = redirectUri.GetLeftPart(UriPartial.Authority);
+    if (!listenerPrefix.EndsWith("/", StringComparison.InvariantCultureIgnoreCase))
+    {
+        listenerPrefix += "/";
+    }
+
+    using var listener = new HttpListener();
+    listener.Prefixes.Add(listenerPrefix);
+
+    try
+    {
+        listener.Start();
+        Console.WriteLine($"Listening for OAuth callback on: {listenerPrefix}");
+
+        OpenBrowser(authorizationUrl);
+
+        var context = await listener.GetContextAsync();
+        var query = HttpUtility.ParseQueryString(context.Request.Url?.Query ?? string.Empty);
+        var code = query["code"];
+        var error = query["error"];
+
+        string responseHtml = "<html><body><h1>Authentication complete</h1><p>You can close this window now.</p></body></html>";
+        byte[] buffer = Encoding.UTF8.GetBytes(responseHtml);
+        context.Response.ContentLength64 = buffer.Length;
+        context.Response.ContentType = "text/html";
+        context.Response.OutputStream.Write(buffer, 0, buffer.Length);
+        context.Response.Close();
+
+        if (!string.IsNullOrEmpty(error))
+        {
+            Console.WriteLine($"Auth error: {error}");
+            return null;
+        }
+
+        if (string.IsNullOrEmpty(code))
+        {
+            Console.WriteLine("No authorization code received");
+            return null;
+        }
+
+        Console.WriteLine("Authorization code received successfully.");
+        return code;
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error getting auth code: {ex.Message}");
+        return null;
+    }
+    finally
+    {
+        if (listener.IsListening)
+        {
+            listener.Stop();
+        }
+    }
+}
+
+/// <summary>
+/// Opens the specified URL in the default browser.
+/// </summary>
+/// <param name="url">The URL to open.</param>
+static void OpenBrowser(Uri url)
+{
+    try
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = url.ToString(),
+            UseShellExecute = true
+        };
+        Process.Start(psi);
+    }
+    catch (Exception ex)
+    {
+        Console.WriteLine($"Error opening browser. {ex.Message}");
+        Console.WriteLine($"Please manually open this URL: {url}");
+    }
+}
@@ -0,0 +1,144 @@
+# Model Context Protocol Sample
+
+This example demonstrates how to use tools from a protected Model Context Protocol server with Semantic Kernel.
+
+MCP is an open protocol that standardizes how applications provide context to LLMs.
+
+For information on Model Context Protocol (MCP) please refer to the [documentation](https://modelcontextprotocol.io/introduction).
+
+The sample shows:
+
+1. How to connect to a protected MCP Server using  OAuth 2.0 authentication
+1. How to implement a custom OAuth authorization flow with browser-based authentication
+1. Retrieve the list of tools the MCP Server makes available
+1. Convert the MCP tools to Semantic Kernel functions so they can be added to a Kernel instance
+1. Invoke the tools from Semantic Kernel using function calling
+
+## Installing Prerequisites
+
+- A self-signed certificate to enable HTTPS use in development, see [dotnet dev-certs](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-dev-certs)
+- .NET 10.0 or later
+- A running TestOAuthServer (for OAuth authentication), see [Start the Test OAuth Server](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/ProtectedMCPClient#step-1-start-the-test-oauth-server)
+- A running ProtectedMCPServer (for MCP services), see [Start the Protected MCP Server](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/ProtectedMCPClient#step-2-start-the-protected-mcp-server)
+ 
+## Configuring Secrets or Environment Variables
+
+The example requires credentials to access OpenAI.
+
+If you have set up those credentials as secrets within Secret Manager or through environment variables for other samples from the solution in which this project is found, they will be re-used.
+
+### To set your secrets with Secret Manager
+
+```text
+cd dotnet/samples/Demos/ModelContextProtocolPluginAuth
+
+dotnet user-secrets init
+
+dotnet user-secrets set "OpenAI:ChatModelId" "..."
+dotnet user-secrets set "OpenAI:ApiKey" "..."
+ "..."
+```
+
+### To set your secrets with environment variables
+
+Use these names:
+
+```text
+# OpenAI
+OpenAI__ChatModelId
+OpenAI__ApiKey
+```
+
+## Setup and Running
+
+### Step 1: Start the Test OAuth Server
+
+First, you need to start the TestOAuthServer which provides OAuth authentication:
+
+```bash
+cd <MCP CSHARP-SDK>\tests\ModelContextProtocol.TestOAuthServer
+dotnet run --framework net10.0
+```
+
+The OAuth server will start at `https://localhost:7029`
+
+### Step 2: Start the Protected MCP Server
+
+Next, start the ProtectedMCPServer which provides the weather tools:
+
+```bash
+cd <MCP CSHARP-SDK>\samples\ProtectedMCPServer
+dotnet run
+```
+
+The protected server will start at `http://localhost:7071`
+
+### Step 3: Run the ModelContextProtocolPluginAuth sample
+
+Finally, run this client:
+
+```bash
+dotnet run
+```
+
+## What Happens
+
+1. The client attempts to connect to the protected MCP server at `http://localhost:7071`
+2. The server responds with OAuth metadata indicating authentication is required
+3. The client initiates OAuth 2.0 authorization code flow:
+   - Opens a browser to the authorization URL at the OAuth server
+   - Starts a local HTTP listener on `http://localhost:1179/callback` to receive the authorization code
+   - Exchanges the authorization code for an access token
+4. The client uses the access token to authenticate with the MCP server
+5. The client lists available tools and calls the `GetAlerts` tool for New York state
+
+The following diagram outlines an example OAuth flow:
+
+```mermaid
+sequenceDiagram
+    participant Client as Client
+    participant Server as MCP Server (Resource Server)
+    participant AuthServer as Authorization Server 
+
+    Client->>Server: MCP request without access token
+    Server-->>Client: HTTP 401 Unauthorized with WWW-Authenticate header
+    Note over Client: Analyze and delegate tasks
+    Client->>Server: GET /.well-known/oauth-protected-resource
+    Server-->>Client: Resource metadata with authorization server URL
+    Note over Client: Validate RS metadata, build AS metadata URL
+    Client->>AuthServer: GET /.well-known/oauth-authorization-server
+    AuthServer-->>Client: Authorization server metadata
+    Note over Client,AuthServer: OAuth 2.0 authorization flow happens here
+    Client->>AuthServer: Token request
+    AuthServer-->>Client: Access token
+     Client->>Server: MCP request with access token
+    Server-->>Client: MCP response
+    Note over Client,Server: MCP communication continues with valid token
+```
+
+## OAuth Configuration
+
+The client is configured with:
+- **Client ID**: `demo-client`
+- **Client Secret**: `demo-secret` 
+- **Redirect URI**: `http://localhost:1179/callback`
+- **OAuth Server**: `https://localhost:7029`
+- **Protected Resource**: `http://localhost:7071`
+
+## Available Tools
+
+Once authenticated, the client can access weather tools including:
+- **GetAlerts**: Get weather alerts for a US state
+- **GetForecast**: Get weather forecast for a location (latitude/longitude)
+
+## Troubleshooting
+
+- Ensure the ASP.NET Core dev certificate is trusted.
+  ```
+  dotnet dev-certs https --clean
+  dotnet dev-certs https --trust
+  ```
+- Ensure all three services are running in the correct order
+- Check that ports 7029, 7071, and 1179 are available
+- If the browser doesn't open automatically, copy the authorization URL from the console and open it manually
+- Make sure to allow the OAuth server's self-signed certificate in your browser