error-transport-context

name: "error-transport-context" description: "Preserve service request context across MCP and CLI error envelopes." domain: "error-handling" confidence: "high" source: "observed"

Context

Use this when improving diagnostics in the MCP/CLI/service seam without changing Core or COM behavior.

Patterns

• Put shared diagnostics on ServiceResponse, not in host-specific wrappers.
• Stamp failed responses with the originating command and sessionId at the service boundary so both MCP and CLI inherit the same context.
• Mirror new shared fields in ExcelToolsBase and CliErrorOutput while keeping existing compatibility fields like error, errorMessage, and isError.
• Prefer additive fields over message rewrites so existing clients keep working.

Examples

• src/ExcelMcp.Service/ExcelMcpService.cs: enrich failures in ProcessAsync() via a request-context helper.
• src/ExcelMcp.McpServer/Tools/ExcelToolsBase.cs: include command and sessionId in serialized error JSON.
• src/ExcelMcp.CLI/Infrastructure/CliErrorOutput.cs: emit the same fields in CLI failure envelopes.

Anti-Patterns

• Do not add MCP-only diagnostics that CLI cannot emit.
• Do not push transport diagnostics down into Core commands just to label routed actions.
• Do not remove existing error fields that current tests or clients already consume.