[Mike Krüger (mkrueger)]

Summary

First slice of #154 (M2 — structured JSON tool results for MCP). MCP tool results now expose their machine-readable payload as first-class CallToolResult.StructuredContent, in addition to the existing JSON text block.

Important context: the payload was already JSON — McpResponseFactory has been building { result, outputText?, error?, currentLocation } and shipping it inside a TextContentBlock. This PR promotes that same payload into the dedicated structuredContent field so structured-content clients consume it directly, while keeping the text block for backward compatibility. The two representations are kept byte-for-byte equivalent.

This satisfies three of the four acceptance criteria (structured content over MCP for query/ls/print and every other command that returns data; existing text clients still work; documented contract; schema-stability tests). The remaining criterion — per-tool outputSchema — is deliberately deferred to a follow-up (see below).

Changes

• McpResponseFactory.CreateResponse: set StructuredContent to the payload (serialized to JsonElement, the type Core 1.1.0 exposes) alongside the existing text block.
• docs/mcp.md: new Tool Results section documenting the dual representation and the payload shape (result / outputText / error / currentLocation).
• CHANGELOG.md: Unreleased entry.
• Tests: structuredContent is populated and byte-for-byte matches the text block on success and error.

Deliberately out of scope (follow-up)

• Per-tool outputSchema. Tool.OutputSchema exists in the pinned SDK (Core 1.1.0), but generating stable per-command schemas is a larger design surface and belongs in its own PR. I'd derive them from the same command metadata that already produces InputSchema.
• Continuation token in the envelope. The issue lists it, but the query path doesn't currently expose paging — that's a separate data-plumbing task, not a formatting change. (RU charge is already present in query results.)

Validation

• dotnet build — clean.
• dotnet test — 45 MCP/ToolOperations/help/localization tests pass, including the new parity tests.

Notes

• SDK verified: CallToolResult.StructuredContent (JsonElement?) and Tool.OutputSchema (JsonElement?) both exist in ModelContextProtocol.Core 1.1.0 — no SDK bump required.
• Independent of M1. stdio transport for the MCP server #153 (stdio transport).

[Copilot]

Pull request overview

This PR updates the Cosmos DB Shell MCP server response envelope so every tool call returns its existing JSON payload both as MCP structured content (CallToolResult.StructuredContent) and as the existing JSON text content block, enabling structured-content clients while preserving backward compatibility for text-only clients.

Changes:

• Populate CallToolResult.StructuredContent with the same { result, outputText?, error?, currentLocation } payload currently emitted as JSON text.
• Document the dual-representation contract and payload shape in docs/mcp.md.
• Add tests to validate structured-content population and parity expectations; add a changelog entry under Unreleased.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/mcp.md	Documents the MCP tool-result payload shape and the dual structured/text representations.
CosmosDBShell/Azure.Data.Cosmos.Shell.Mcp/McpResponseFactory.cs	Emits the tool-result payload as StructuredContent alongside the existing JSON text content block.
CosmosDBShell.Tests/McpResponseFactoryTests.cs	Adds test coverage for StructuredContent population and parity expectations.
CHANGELOG.md	Adds an Unreleased entry describing structured MCP tool results.

Comments suppressed due to low confidence (1)

CosmosDBShell/Azure.Data.Cosmos.Shell.Mcp/McpResponseFactory.cs:69

• CreateResponse currently serializes the payload twice (once via JsonSerializer.SerializeToElement and again via payload.ToJsonString). This makes the “byte-for-byte equivalent” guarantee fragile (different code paths can produce different escaping/ordering) and adds unnecessary overhead. Serialize once to a JsonElement and derive the text block from GetRawText() to keep both representations locked together.

            StructuredContent = JsonSerializer.SerializeToElement(payload, JsonOptions),
            Content =
            [
                new TextContentBlock
                {

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall coverage in the dev/mkrueger/mcp-str... branch remains at 61%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main b334f69	dev/mkrueger/mcp-str... bc30323	+/-
D:\a\CosmosDBSh...ponseFactory.cs	89%	90%	+1%

---

_{Updated July 13, 2026 09:22 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.