Skip to content

feat: introduce SDK exception hierarchy and tool parameter copying#81

Open
stenalpjolly wants to merge 1 commit into
googleapis:mainfrom
stenalpjolly:stenalpjolly_pr1-foundation
Open

feat: introduce SDK exception hierarchy and tool parameter copying#81
stenalpjolly wants to merge 1 commit into
googleapis:mainfrom
stenalpjolly:stenalpjolly_pr1-foundation

Conversation

@stenalpjolly

Copy link
Copy Markdown
Contributor

Summary

This pull request introduces the core exception hierarchy for the MCP Toolbox Java SDK (McpToolboxException, McpProtocolException, McpTransportException, and ToolExecutionException) and updates JsonRpc namespace structures. Additionally, it enhances Tool execution to deep-copy default list parameters and properly unwrap execution exceptions into McpToolboxException.

Expectation & Implementation

  • Expectation: SDK consumers need a structured exception hierarchy (McpToolboxException and subclasses) to distinguish between protocol failures (McpProtocolException), transport/HTTP status errors (McpTransportException), and tool invocation/validation failures (ToolExecutionException). Furthermore, default parameters of complex mutable types (such as lists) in Tool definitions must be deep-copied when injected into arguments to prevent unintended mutations across executions.
  • Implementation:
    • Added McpToolboxException base unchecked exception class.
    • Added McpProtocolException, McpTransportException (with HTTP status code tracking), and ToolExecutionException extending McpToolboxException.
    • Updated JsonRpc to encapsulate protocol payload structures cleanly.
    • Updated Tool execution logic (executeSync) to throw McpToolboxException when unwrapping futures and ensured deepCopy properly handles List alongside Map.

Test cases

  • Added unit tests in McpToolboxClientBuilderTest to verify all constructors of McpTransportException, McpToolboxException, McpProtocolException, ToolExecutionException, and McpException.
  • Verified JsonRpc instantiation via reflection in HttpMcpTransportTest.
  • Ran full unit and validation suite (mvn clean test jacoco:report), confirming 100% line coverage across com.google.cloud.mcp.exception.* and all existing tests passing.

Acceptance criteria

  • All exception hierarchy classes (McpToolboxException, McpProtocolException, McpTransportException, ToolExecutionException) are introduced under com.google.cloud.mcp.exception.
  • Tool.java throws McpToolboxException on synchronous execution failures and supports deep copying of List default values.
  • Code formatting conforms to google-java-format standards under JDK 22+.
  • 100% line coverage achieved across all classes in com.google.cloud.mcp.exception.*.

Breaking changes

  • None. This PR introduces foundational classes and internal execution enhancements without altering existing public method signatures.

TAG=agy
CONV=5010ae11-556f-4a11-aca4-d964083ca783

@stenalpjolly
stenalpjolly requested a review from a team as a code owner July 14, 2026 08:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant