2.2.0: binary content blocks (ImageContentBlock, BlobResourceContents) serialize invalid base64 - client-side CallToolResult deserialization throws (regression of #1340)

[marcfreiheit]

Description

Binary content blocks (ImageContentBlock, EmbeddedResourceBlock with BlobResourceContents) round-trip incorrectly through McpJsonUtilities.DefaultOptions in 2.2.0: the writer does not emit valid base64 for the binary payload, so deserializing the produced JSON throws

System.Text.Json.JsonException: The JSON value could not be converted to ModelContextProtocol.Protocol.ResourceContents.
 ---> System.FormatException: Cannot decode JSON text that is not encoded as valid Base64 to bytes.
   at System.Text.Json.Utf8JsonReader.GetBytesFromBase64()
   at ModelContextProtocol.Protocol.ResourceContents.Converter.Read(...)

In practice this means a tool that returns a PDF via EmbeddedResourceBlock/BlobResourceContents (or an image via ImageContentBlock) over the Streamable HTTP transport breaks the client-side deserialization of the whole CallToolResult — the client (McpClient.CallToolAsync) throws and the result is lost.

This looks like a regression of #1340 / #1064: ImageContentBlock.Data is serialized as the raw bytes reinterpreted as a UTF-16 string (mostly U+FFFD replacement characters and escaped control characters in the JSON), not as base64.

Repro (console app, ModelContextProtocol.Core 2.2.0, net10.0)

using System.Text.Json;
using ModelContextProtocol;
using ModelContextProtocol.Protocol;

var bytes = new byte[900_000];
Random.Shared.NextBytes(bytes);

var result = new CallToolResult
{
    Content =
    [
        new EmbeddedResourceBlock
        {
            Resource = new BlobResourceContents
            {
                Uri = "demo://files/1/test.pdf",
                MimeType = "application/pdf",
                Blob = bytes,
            },
        },
    ],
};

var json = JsonSerializer.Serialize(result, McpJsonUtilities.DefaultOptions);
// throws FormatException("Cannot decode JSON text that is not encoded as valid Base64 to bytes."):
var back = JsonSerializer.Deserialize<CallToolResult>(json, McpJsonUtilities.DefaultOptions);

Same shape for images: serializing new ImageContentBlock { Data = bytes, MimeType = "image/png" } as ContentBlock produces a "data" property that is not base64 (raw bytes as string), and deserializing it back throws the same FormatException.

Interestingly, serializing the BlobResourceContents directly (not through the polymorphic CallToolResult/ContentBlock path) produces correct base64 — the asymmetry sits in the polymorphic converter path.

Expected behavior

blob/data are written as base64 strings (per spec) and round-trip through McpJsonUtilities.DefaultOptions.

Environment

• ModelContextProtocol / ModelContextProtocol.Core / ModelContextProtocol.AspNetCore 2.2.0
• .NET 10.0 (net10.0), macOS arm64
• Observed both in the minimal repro above and end-to-end over the Streamable HTTP transport (ASP.NET Core server to McpClient)

[luisangelrod]

Thanks for the detailed repro. I checked this against current main at 609499b2.

I can reproduce the exception when the raw payload is assigned directly to Blob or Data, but those two properties are the already-base64-encoded UTF-8 wire representation. For raw bytes, the intended construction path is:

Resource = BlobResourceContents.FromBytes(
    bytes,
    "demo://files/1/test.pdf",
    "application/pdf");

Content = [ImageContentBlock.FromBytes(bytes, "image/png")];

With those factories, I ran the same polymorphic CallToolResult round trip using 900,000-byte payloads on net10.0; both the blob and image cases passed and preserved the decoded bytes (2/2 tests). I also ran the existing FromBytes JSON round-trip theories for both types: all 8 payload cases passed on each of net472, net8.0, net9.0, and net10.0.

The direct concrete serialization result is not evidence that the polymorphic writer missed a base64 conversion: the default System.Text.Json byte-memory converter encodes the supplied memory, whereas the MCP protocol converter writes the Data/Blob value according to its documented wire-format contract.

So I do not think this is a serializer regression. There may still be an API discoverability opportunity here, since assigning raw bytes to these byte-typed properties is an understandable mistake. Improving examples or adding clearer guardrails could be worth discussing separately.

Note

This comment was prepared with AI assistance and verified against the current source and focused test results.