Add raw HTTP conformance tests + document MCP9005

halter73 · Copilot · halter73 · commit 30782f6102ba · 2026-06-05T17:20:40.000-07:00
Phase 5b + 6 of the SEP-2575/SEP-2567 work.

- tests/ModelContextProtocol.AspNetCore.Tests/RawHttpConformanceTests.cs: 5 new tests that drive the C# server directly with hand-crafted HttpClient requests, no McpClient involvement. Covers draft tools/call with full _meta, server/discover, -32004 on unsupported MCP-Protocol-Version, legacy initialize on a default (stateless+draft) server, and GET returning 405 when not stateful.

- docs/list-of-diagnostics.md: add MCP9005 row describing the stateful Streamable HTTP options as back-compat-only knobs since the draft revision is sessionless by default.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs/list-of-diagnostics.md b/docs/list-of-diagnostics.md
@@ -38,3 +38,4 @@ When APIs are marked as obsolete, a diagnostic is emitted to warn users that the
 | `MCP9002` | Removed | The `AddXxxFilter` extension methods on `IMcpServerBuilder` (e.g., `AddListToolsFilter`, `AddCallToolFilter`, `AddIncomingMessageFilter`) were superseded by `WithRequestFilters()` and `WithMessageFilters()`. |
 | `MCP9003` | In place | The `RequestContext<TParams>(McpServer, JsonRpcRequest)` constructor is obsolete. Use the overload that accepts a `parameters` argument: `RequestContext<TParams>(McpServer, JsonRpcRequest, TParams)`. |
 | `MCP9004` | In place | <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableLegacySse> opts into the legacy SSE transport which has no built-in HTTP-level backpressure. Use Streamable HTTP instead. See [Stateless — Legacy SSE transport](xref:stateless#legacy-sse-transport) for details. |
+| `MCP9005` | In place | The stateful Streamable HTTP configuration knobs on <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions> — `EventStreamStore`, `SessionMigrationHandler`, `PerSessionExecutionContext`, `IdleTimeout`, and `MaxIdleSessionCount` — only apply when `Stateless = false`. The draft protocol revision (`2026-07-28`) is sessionless, and the SDK now defaults `Stateless` to `true`. These knobs remain available for back-compat with the legacy stateful Streamable HTTP transport but new code should target the stateless path. |
diff --git a/tests/ModelContextProtocol.AspNetCore.Tests/RawHttpConformanceTests.cs b/tests/ModelContextProtocol.AspNetCore.Tests/RawHttpConformanceTests.cs
@@ -0,0 +1,189 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using ModelContextProtocol.AspNetCore.Tests.Utils;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using ModelContextProtocol.Tests.Utils;
+using System.Net;
+using System.Text;
+using System.Text.Json.Nodes;
+
+namespace ModelContextProtocol.AspNetCore.Tests;
+
+/// <summary>
+/// Wire-format conformance tests for the Streamable HTTP server driven directly via <see cref="HttpClient"/>,
+/// without going through <see cref="ModelContextProtocol.Client.McpClient"/>. These hand-craft HTTP
+/// requests and assert the exact status codes / response bodies the server emits for the SEP-2575 +
+/// SEP-2567 (sessionless, no-initialize) draft revision.
+/// </summary>
+public class RawHttpConformanceTests(ITestOutputHelper outputHelper) : KestrelInMemoryTest(outputHelper), IAsyncDisposable
+{
+    private const string DraftVersion = McpHttpHeaders.DraftProtocolVersion;
+    private const string ProtocolVersionHeader = "MCP-Protocol-Version";
+
+    private WebApplication? _app;
+
+    private async Task StartAsync()
+    {
+        Builder.Services
+            .AddMcpServer(options =>
+            {
+                options.ServerInfo = new Implementation { Name = nameof(RawHttpConformanceTests), Version = "1.0" };
+            })
+            .WithHttpTransport()
+            .WithTools([McpServerTool.Create((string text) => $"echo:{text}", new() { Name = "echo" })]);
+
+        _app = Builder.Build();
+        _app.MapMcp();
+        await _app.StartAsync(TestContext.Current.CancellationToken);
+
+        HttpClient.DefaultRequestHeaders.Accept.Add(new("application/json"));
+        HttpClient.DefaultRequestHeaders.Accept.Add(new("text/event-stream"));
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        if (_app is not null)
+        {
+            await _app.DisposeAsync();
+        }
+        base.Dispose();
+    }
+
+    private static StringContent JsonContent(string json) => new(json, Encoding.UTF8, "application/json");
+
+    /// <summary>
+    /// Reads either a direct JSON response or a single SSE message containing JSON-RPC and returns the
+    /// parsed JsonNode. The Streamable HTTP server can return either content type depending on negotiation;
+    /// raw HttpClient tests should accept either.
+    /// </summary>
+    private static async Task<JsonNode> ReadJsonResponseAsync(HttpResponseMessage response, CancellationToken cancellationToken)
+    {
+        var contentType = response.Content.Headers.ContentType?.MediaType;
+        var body = await response.Content.ReadAsStringAsync(cancellationToken);
+
+        if (contentType == "text/event-stream")
+        {
+            // Pull the first non-empty data: line out of the SSE payload.
+            foreach (var line in body.Split('\n'))
+            {
+                if (line.StartsWith("data:", StringComparison.Ordinal))
+                {
+                    var data = line.Substring("data:".Length).Trim();
+                    if (data.Length > 0)
+                    {
+                        return JsonNode.Parse(data)!;
+                    }
+                }
+            }
+            throw new InvalidOperationException("SSE response did not contain a JSON data event. Body: " + body);
+        }
+
+        return JsonNode.Parse(body)!;
+    }
+
+    private static string DraftMetaFragment(string protocolVersion = DraftVersion) =>
+        @"""_meta"":{""io.modelcontextprotocol/protocolVersion"":""" + protocolVersion +
+        @""",""io.modelcontextprotocol/clientInfo"":{""name"":""raw"",""version"":""1.0""}," +
+        @"""io.modelcontextprotocol/clientCapabilities"":{}}";
+
+    [Fact]
+    public async Task DraftToolsCall_WithFullMeta_Succeeds_200()
+    {
+        await StartAsync();
+
+        var body =
+            @"{""jsonrpc"":""2.0"",""id"":1,""method"":""tools/call"",""params"":{""name"":""echo"",""arguments"":{""text"":""hi""}," +
+            DraftMetaFragment() + "}}";
+
+        using var request = new HttpRequestMessage(HttpMethod.Post, "") { Content = JsonContent(body) };
+        request.Headers.Add(ProtocolVersionHeader, DraftVersion);
+        request.Headers.Add("Mcp-Method", "tools/call");
+        request.Headers.Add("Mcp-Name", "echo");
+        using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        var json = await ReadJsonResponseAsync(response, TestContext.Current.CancellationToken);
+        Assert.Equal("echo:hi", json["result"]!["content"]![0]!["text"]!.GetValue<string>());
+
+        // Per SEP-2567 draft is sessionless: server MUST NOT issue a Mcp-Session-Id.
+        Assert.False(response.Headers.Contains("mcp-session-id"));
+    }
+
+    [Fact]
+    public async Task ServerDiscover_RawPost_ReturnsDiscoverResult()
+    {
+        await StartAsync();
+
+        var body = @"{""jsonrpc"":""2.0"",""id"":1,""method"":""server/discover"",""params"":{" + DraftMetaFragment() + "}}";
+
+        using var request = new HttpRequestMessage(HttpMethod.Post, "") { Content = JsonContent(body) };
+        request.Headers.Add(ProtocolVersionHeader, DraftVersion);
+        request.Headers.Add("Mcp-Method", "server/discover");
+        using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        var json = await ReadJsonResponseAsync(response, TestContext.Current.CancellationToken);
+        var supported = json["result"]!["supportedVersions"]!.AsArray().Select(n => n!.GetValue<string>()).ToList();
+        Assert.Contains(DraftVersion, supported);
+    }
+
+    [Fact]
+    public async Task DraftPost_WithUnsupportedProtocolVersionHeader_Returns400_With_Minus32004()
+    {
+        await StartAsync();
+
+        var body =
+            @"{""jsonrpc"":""2.0"",""id"":1,""method"":""tools/call"",""params"":{""name"":""echo"",""arguments"":{""text"":""x""}," +
+            DraftMetaFragment("9999-99-99") + "}}";
+
+        using var request = new HttpRequestMessage(HttpMethod.Post, "") { Content = JsonContent(body) };
+        request.Headers.Add(ProtocolVersionHeader, "9999-99-99");
+        request.Headers.Add("Mcp-Method", "tools/call");
+        request.Headers.Add("Mcp-Name", "echo");
+        using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken);
+
+        // Per spec/streamable-http.mdx the server MUST return 400 Bad Request with -32004 and a data payload
+        // listing the supported versions. The dual-era client uses this to switch versions without fallback.
+        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+        var json = await ReadJsonResponseAsync(response, TestContext.Current.CancellationToken);
+        Assert.Equal((int)McpErrorCode.UnsupportedProtocolVersion, json["error"]!["code"]!.GetValue<int>());
+
+        var data = json["error"]!["data"];
+        Assert.NotNull(data);
+        Assert.Equal("9999-99-99", data!["requested"]!.GetValue<string>());
+        var supported = data["supported"]!.AsArray().Select(n => n!.GetValue<string>()).ToList();
+        Assert.Contains(DraftVersion, supported);
+    }
+
+    [Fact]
+    public async Task LegacyInitialize_StillSucceeds_OnDefaultServer()
+    {
+        await StartAsync();
+
+        var body = @"{""jsonrpc"":""2.0"",""id"":1,""method"":""initialize"",""params"":{""protocolVersion"":""2025-11-25"",""capabilities"":{},""clientInfo"":{""name"":""legacy"",""version"":""1.0""}}}";
+
+        using var request = new HttpRequestMessage(HttpMethod.Post, "") { Content = JsonContent(body) };
+        using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken);
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        var json = await ReadJsonResponseAsync(response, TestContext.Current.CancellationToken);
+        Assert.Equal("2025-11-25", json["result"]!["protocolVersion"]!.GetValue<string>());
+    }
+
+    [Fact]
+    public async Task GetEndpoint_NotMapped_UnderDefaultStatelessConfiguration_Returns405()
+    {
+        await StartAsync();
+
+        using var request = new HttpRequestMessage(HttpMethod.Get, "");
+        request.Headers.Accept.Add(new("text/event-stream"));
+        using var response = await HttpClient.SendAsync(request, TestContext.Current.CancellationToken);
+
+        // Stateless=true (the new default) doesn't map the GET endpoint - per SEP-2567 the standalone SSE
+        // stream is replaced by subscriptions/listen POST requests. Existing routing in
+        // McpEndpointRouteBuilderExtensions only maps GET when Stateless == false.
+        Assert.Equal(HttpStatusCode.MethodNotAllowed, response.StatusCode);
+    }
+}
+
