Surface Cosmos request charge (RUs) in MCP structured results

[mkrueger]

Relates to #162 (implements part (a); does not close the issue).

Summary

Surfaces the Cosmos DB request charge (RUs) consumed by data-plane commands as a uniform, machine-readable field on MCP tool results. This addresses part (a) of #162 (RU-cost surfacing) -- consistent RU reporting in structured output. It does not include the budget/--max-ru guardrails (part b), which are proposed as a separate follow-up.

Today RU is reported ad-hoc and inconsistently: query includes it in structured output only in one code path, most write commands print it to the console as a formatted string, and reads/deletes don't report it at all. This change makes RU a first-class, consistent part of the MCP structured contract.

What changed

• CommandState.RequestCharge -- a new nullable double that data-plane commands set with the RUs consumed.
• MCP payload -- McpResponseFactory emits a top-level requestCharge number in the structured tool result (and the equivalent text block) whenever it is set. The result document shape is unchanged; requestCharge is a sibling metadata field, so existing result parsers and CSV/table rendering are unaffected.
• Commands retrofitted to record the charge on the returned state:
  • query -- accumulates TotalRequestCharge across pages
  • print -- point-read charge from the response headers
  • mkitem, replace, patch -- single and bulk write charges
  • rm -- accumulates delete charges (previously untracked)
  • import / export -- bulk aggregate charge
  • sproc exec -- stored-procedure execution charge

Design notes

• RU is surfaced as payload metadata rather than being injected into the result document, to avoid changing the document contract that clients parse.
• Management operations (e.g. creating/replacing sproc/udf/trigger definitions) are intentionally out of scope; this focuses on data-plane reads/writes.

Docs

• Documented the requestCharge field in docs/mcp.md (payload shape table + notes).
• Added a CHANGELOG entry under Improvements referencing G2. RU-cost surfacing & budget guardrails #162.

Testing

• New McpResponseFactory tests: requestCharge present when set, omitted when unset.
• Extended the sproc exec test to assert the captured charge.
• Full offline suite green (1793 tests); main project builds with 0 warnings / 0 errors.

Stacking

Based on dev/mkrueger/mcp-structured-content (#168) because the requestCharge field extends the MCP structuredContent payload introduced there. GitHub will retarget the base to main once #168 merges.

Part of the Agentic & Automation roadmap, item G2.

Fixes #162

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

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

Show a code coverage summary of the most impacted files.

File	main b334f69	dev/mkrueger/request... 9576858	+/-
D:\a\CosmosDBSh...ds\RmCommand.cs	19%	17%	-2%
D:\a\CosmosDBSh...eItemCommand.cs	17%	16%	-1%
D:\a\CosmosDBSh...QueryCommand.cs	39%	39%	0%
D:\a\CosmosDBSh...mportCommand.cs	47%	47%	0%
D:\a\CosmosDBSh...xportCommand.cs	37%	37%	0%
D:\a\CosmosDBSh...CommandState.cs	80%	80%	0%
D:\a\CosmosDBSh...ponseFactory.cs	89%	90%	+1%
D:\a\CosmosDBSh...SprocCommand.cs	54%	55%	+1%
D:\a\CosmosDBSh...sourceFacade.cs	15%	17%	+2%
D:\a\CosmosDBSh...ucketCommand.cs	39%	96%	+57%

---

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

[Copilot]

Pull request overview

This PR adds a consistent way for data-plane commands to report Cosmos DB request charge (RUs) by storing it on CommandState and emitting it as a top-level requestCharge field in MCP tool-result payloads (both structuredContent and the legacy JSON text block).

Changes:

• Add CommandState.RequestCharge and include it as requestCharge in MCP success payloads when set.
• Retrofit multiple data-plane commands (query, print, mkitem, replace, patch, rm, import, export, sproc exec) to capture RU charge.
• Document the MCP payload shape and add/extend tests validating structuredContent parity and requestCharge behavior.

Reviewed changes

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

Show a summary per file

File	Description
docs/mcp.md	Documents tool-result payload shape and the new requestCharge metadata field.
CosmosDBShell/Azure.Data.Cosmos.Shell.Mcp/McpResponseFactory.cs	Emits StructuredContent and adds requestCharge to the MCP success payload when available.
CosmosDBShell/Azure.Data.Cosmos.Shell.Core/CommandState.cs	Introduces the nullable RequestCharge field for commands to populate.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/QueryCommand.cs	Attempts to aggregate query RU charges and store them on CommandState.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/PrintCommand.cs	Captures point-read RU charge from response headers.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/MakeItemCommand.cs	Accumulates RU charges across single/bulk writes and propagates to returned state.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/ReplaceCommand.cs	Returns total replace charge (single/bulk) and sets it on the returned state.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/PatchCommand.cs	Sets request charge from patch response.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/RmCommand.cs	Tracks delete RU charges and sets them on the command state.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/ImportCommand.cs	Sets aggregated RU charge on success.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/ExportCommand.cs	Sets aggregated RU charge on success.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/SprocCommand.cs	Captures RU charge from stored procedure execution.
CosmosDBShell.Tests/McpResponseFactoryTests.cs	Adds tests for StructuredContent population/parity and requestCharge presence/omission.
CosmosDBShell.Tests/CommandTests/SprocCommandExecutionTests.cs	Extends sproc exec test to assert RequestCharge is captured.
CHANGELOG.md	Adds entries describing structured MCP results and RU surfacing.

[Copilot]

Pull request overview

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