feat: add idiomatic sync client support and advanced builder options

README.md

@@ -216,15 +216,19 @@ public class App {
 For a detailed example, check the ExampleUsage.java file in the example folder of this repo.
 
 > [!NOTE]
->
-> The SDK is Async-First, using Java's `CompletableFuture` to bridge both patterns naturally.
-> - Asynchronous: Chain methods using `.thenCompose()`, `.thenAccept()`, and `.exceptionally()` for non-blocking execution.
-> - If you prefer synchronous execution, simply call `.join()` on the result to block until completion.
+> The SDK is async-first, but provides a pure synchronous blocking experience using `McpToolboxSyncClient`.
+> - **Asynchronous Client (`McpToolboxClient`):** Chain methods using `.thenCompose()`, `.thenAccept()`, and `.exceptionally()`.
+> - **Synchronous Client (`McpToolboxSyncClient`):** Call blocking methods directly. Under the hood, it manages threads safely and translates checked/execution exceptions into unchecked `McpToolboxException`s.
+
 ```java
-// Async (Non-blocking)
-client.invokeTool("tool-name", args).thenAccept(result -> ...);
-// Sync (Blocking)
-ToolResult result = client.invokeTool("tool-name", args).join();
+// Create a Synchronous Client
+McpToolboxSyncClient client = McpToolboxClient.builder()
+    .baseUrl("https://my-toolbox-service.a.run.app/mcp")
+    .buildSync();
+
+// Invoke a tool synchronously
+ToolResult result = client.invokeTool("get-toy-price", Map.of("description", "plush dinosaur"));
+System.out.println("Output: " + result.content().get(0).text());
 ```
 
 ## Authentication

demo-applications/cymbal-transit/pom.xml

@@ -69,7 +69,7 @@
     <dependency>
         <groupId>com.google.cloud.mcp</groupId>
         <artifactId>mcp-toolbox-sdk-java</artifactId>
-        <version>0.2.0</version>
+        <version>0.2.1-SNAPSHOT</version>
     </dependency>
 
     <!-- Java Annotations -->

demo-applications/cymbal-transit/src/main/java/cloudcode/cymbal/CymbalTransitApplication.java

@@ -40,6 +40,8 @@ public static void main(final String[] args) throws Exception {
     // Start the Spring Boot application.
     app.run(args);
     logger.info(
-        "Hello from Cloud Run! The container started successfully and is listening for HTTP requests on " + port);
+        "Hello from Cloud Run! The container started successfully and is listening for HTTP"
+            + " requests on "
+            + port);
   }
 }