refactor: Restructure SDK into subpackages & implement versioned HTTP transport layers

[stenalpjolly]

Summary

Restructures the Java SDK package layout into domain-specific subpackages (client, transport, auth, tool, exception) instead of a single flat root package, and refactors the HTTP transport layer to delegate version-specific initialization and requests to dedicated subclass routers.

Expectation & Implementation

• Restructured Package Layout:
  • com.google.cloud.mcp (entrypoint classes)
  • com.google.cloud.mcp.client (client implementation classes)
  • com.google.cloud.mcp.transport (transport interfaces and HttpMcpTransport router)
  • com.google.cloud.mcp.transport.vXXXX (version-specific transport subclasses: v20241105, v20250326, v20250618, v20251125)
  • com.google.cloud.mcp.auth (credential handling and resolver classes)
  • com.google.cloud.mcp.tool (tool definition and runner classes)
  • com.google.cloud.mcp.exception (McpException)
• Versioned Transports:
  • Refactored HttpMcpTransport to instantiate and delegate all calls to a version-specific subclass implementation depending on the selected ProtocolVersion.
  • Moved shared fields/methods into BaseMcpTransport to reduce duplication.
• Example & Demo Applications:
  • Updated all imports and configurations inside example/ and demo-applications/cymbal-transit/ to resolve the new SDK packages successfully.

Test cases

• Run all unit tests locally excluding E2E:
  mvn test -Dtest="*Test,!*E2ETest" -Dnet.bytebuddy.experimental=true

Acceptance criteria

• All 129 unit tests pass successfully.
• Code conforms to google-java-format checkstyle standards.
• Examples and Cymbal Transit demo app compile successfully.

Breaking changes

• Yes, this is a breaking change because classes like McpToolboxClientBuilder, ToolDefinition, CredentialsProvider were moved from com.google.cloud.mcp package to domain subpackages. Callers must update their import declarations.

Migration Guide (v0.2.0 to v0.3.0)

Version 0.3.0 restructures the SDK package layout into domain-specific subpackages. If you are upgrading from 0.2.0, you must update your import statements as follows:

Old Import (v0.2.0)	New Import (v0.3.0)
import com.google.cloud.mcp.McpToolboxClientBuilder;	import com.google.cloud.mcp.client.McpToolboxClientBuilder;
import com.google.cloud.mcp.McpToolboxClient;	import com.google.cloud.mcp.McpToolboxClient; (Unchanged)
import com.google.cloud.mcp.Tool;	import com.google.cloud.mcp.tool.Tool;
import com.google.cloud.mcp.ToolDefinition;	import com.google.cloud.mcp.tool.ToolDefinition;
import com.google.cloud.mcp.CredentialsProvider;	import com.google.cloud.mcp.auth.CredentialsProvider;
import com.google.cloud.mcp.AuthTokenGetter;	import com.google.cloud.mcp.auth.AuthTokenGetter;
import com.google.cloud.mcp.GoogleCredentialsProvider;	import com.google.cloud.mcp.auth.GoogleCredentialsProvider;
import com.google.cloud.mcp.McpException;	import com.google.cloud.mcp.exception.McpException;

[anubhav756]

Would it be possible to show the old UX and the new UX around the breaking change?

[anubhav756]

Fyi, there are a lot of changes post the 2026 MCP version that are currently being added across other SDKs. See base branch mcp-v202606 and branches stacked on top of it.

We should be supporting the latest server v1.6.0 and for that it’s recommended to add those changes as well.

[anubhav756]

Can we also setup automated conformance tests going forward in the Java SDK like it’s setup for other languages?

[stenalpjolly]

Hi @anubhav756, thank you for the thorough review. I have resolved the feedback points as follows:

1. Migration Old UX vs. New UX:
   • I have updated the PR description with a side-by-side Migration Guide showcasing import statements and builder class mappings between 0.2.0 and the restructured 0.3.0 layouts.
2. Stateless MCP (v202606 / DRAFT-2026-v1):
   • The stateless transport class, parameters meta embedding, and version negotiation fallback mechanism are implemented in the dedicated PR feat: Implement Stateless MCP (SEP-2575) support #73 (linked to this issue). We are merging this package restructuring first to establish the subpackage namespaces, and PR feat: Implement Stateless MCP (SEP-2575) support #73 will be rebased and merged immediately after. Additionally, we are incorporating the missing routing headers (Mcp-Method / Mcp-Name) of SEP-2243 into PR feat: Implement Stateless MCP (SEP-2575) support #73 to fully comply with server v1.6.0.
3. Automated Conformance Tests:
   • Setting up automated conformance tests requires establishing a new integration test runner pipeline in Maven/CI, which we have tracked as a follow-up task to keep this PR focused strictly on the layout restructuring.
4. Encapsulation of JsonRpc:
   • To revert JsonRpc and its serialization nested models to package-private:
     • I have moved JsonRpc.java to the com.google.cloud.mcp.transport package.
     • Flattened all version-specific transport subclasses (e.g. HttpMcpTransportV20251125) directly into com.google.cloud.mcp.transport (removing the versioned subdirectories) so they are in the same package and can access JsonRpc natively without exposing it publicly.
     • Removed all direct imports/references of JsonRpc inside client implementations and tests, using Mockito class-name matchers instead to assert serialization behavior.
5. Breaking Changes Versioning:
   • The project version will be updated to 1.0.0 directly upon the official release.
6. Gemini 3.5 Flash Model:
   • Updated the reference logs and default comments in CymbalTransitController.java to target Gemini 3.5 Flash.
7. Obsolete commented code & Javadocs:
   • Removed commented-out return statements from findAllSchedules() and cleaned up REST controller Javadocs and example descriptions in CymbalTransitController.java and ExampleUsage.java.

All unit tests compile and pass successfully. Ready for another review!