feat: add Spring Boot auto-configuration support to core SDK

.github/workflows/compile.yml

@@ -27,3 +27,9 @@ jobs:
       run: |
         cd example
         mvn compile
+
+    - name: Build Spring Boot Example with Maven
+      run: |
+        cd example-spring-boot
+        mvn compile
+

example-spring-boot/README.md

@@ -0,0 +1,58 @@
+# Spring Boot Auto-Configuration Example ☕
+
+This is a sample Spring Boot 3.x application demonstrating how to integrate the MCP Toolbox SDK using Spring's auto-configuration capabilities.
+
+With the auto-configuration module enabled, you do not need to write boilerplate code to instantiate, configure, or manage the lifecycle of the `McpToolboxClient`. The SDK client is automatically configured and registered as a Spring bean.
+
+---
+
+## Prerequisites
+
+- **Java Development Kit (JDK):** Version 17 or higher.
+- **Apache Maven:** Version 3.6 or higher.
+- **MCP Toolbox Server:** A running instance of the Toolbox server (e.g. running locally or on Cloud Run).
+
+---
+
+## How It Works
+
+1. **Auto-Detection:** The SDK's auto-configuration checks for the presence of the property `google.cloud.mcp.toolbox.base-url`.
+2. **Bean Instantiation:** If the property is present, a singleton `McpToolboxClient` bean is instantiated and registered in the application context.
+3. **Fallback Safe:** If a user registers their own custom `McpToolboxClient` bean, the SDK's auto-configuration backs off.
+
+---
+
+## Getting Started
+
+### 1. Build and Install the Core SDK
+Since the example depends on the local `0.3.0-SNAPSHOT` version of the SDK, you must first build and install the SDK to your local Maven cache (`~/.m2`):
+
+```bash
+# In the repository root directory (mcp-toolbox-sdk-java)
+mvn install -DskipTests -Dfmt.skip=true -Djacoco.skip=true
+```
+
+### 2. Configure the Toolbox Connection
+Open `src/main/resources/application.properties` and configure the base URL of your running MCP Toolbox instance:
+
+```properties
+google.cloud.mcp.toolbox.base-url=http://localhost:5000/mcp
+```
+
+### 3. Run the Application
+Navigate to the example directory and run the Spring Boot app:
+
+```bash
+cd example-spring-boot
+mvn spring-boot:run
+```
+
+Upon a successful connection and tool execution, you will see output in the logs similar to:
+
+```text
+=== Spring Boot Auto-Configuration Success ===
+Connecting to MCP server: McpToolboxClientImpl{baseUrl=http://localhost:5000/mcp}
+Tool execution result content:
+ - Result value 1
+ - Result value 2
+```

example-spring-boot/pom.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2026 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ you may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>3.2.5</version>
+    <relativePath/> <!-- lookup parent from repository -->
+  </parent>
+
+  <groupId>com.example</groupId>
+  <artifactId>mcp-toolbox-spring-boot-example</artifactId>
+  <version>1.0.0-SNAPSHOT</version>
+  <name>mcp-toolbox-spring-boot-example</name>
+  <description>Demo project for MCP Toolbox Spring Boot integration</description>
+
+  <properties>
+    <java.version>17</java.version>
+  </properties>
+
+  <dependencies>
+    <!-- Import Spring Boot Web Starter -->
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter</artifactId>
+    </dependency>
+
+    <!-- Import MCP Toolbox SDK -->
+    <dependency>
+      <groupId>com.google.cloud.mcp</groupId>
+      <artifactId>mcp-toolbox-sdk-java</artifactId>
+      <version>0.3.0-SNAPSHOT</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>

example-spring-boot/src/main/java/com/example/demo/DemoApplication.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.demo;
+
+import com.google.cloud.mcp.McpToolboxClient;
+import java.util.Map;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+
+/** Demo application demonstrating the autowired McpToolboxClient. */
+@SpringBootApplication
+public class DemoApplication {
+
+  public static void main(String[] args) {
+    SpringApplication.run(DemoApplication.class, args);
+  }
+
+  /**
+   * Run a simple tool invocation after startup to verify auto-configuration is loaded.
+   *
+   * @param client Autowired McpToolboxClient bean from the SDK.
+   * @return CommandLineRunner bean.
+   */
+  @Bean
+  public CommandLineRunner run(McpToolboxClient client) {
+    return args -> {
+      System.out.println("=== Spring Boot Auto-Configuration Success ===");
+      System.out.println("Connecting to MCP server: " + client.toString());
+
+      // Attempt to invoke a toy price tool asynchronously
+      client
+          .invokeTool("get-toy-price", Map.of("description", "plush dinosaur"))
+          .thenAccept(
+              result -> {
+                System.out.println("Tool execution result content:");
+                result
+                    .content()
+                    .forEach(content -> System.out.println(" - " + content.text()));
+              })
+          .exceptionally(
+              ex -> {
+                System.err.println("Failed to invoke tool: " + ex.getMessage());
+                return null;
+              })
+          .join(); // Wait for demo execution completion
+    };
+  }
+}

example-spring-boot/src/main/resources/application.properties

@@ -0,0 +1,7 @@
+# Spring application properties for MCP Toolbox configuration
+
+# Configure the base URL of the MCP Toolbox server
+google.cloud.mcp.toolbox.base-url=http://localhost:5000/mcp
+
+# Optional: Configure API key if your server requires it
+# google.cloud.mcp.toolbox.api-key=YOUR_API_KEY

pom.xml

@@ -94,7 +94,39 @@
             <version>${google.auth.version}</version>
         </dependency>
 
+        <!-- Spring Boot Autoconfigure (Optional) -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-autoconfigure</artifactId>
+            <version>3.2.5</version>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-configuration-processor</artifactId>
+            <version>3.2.5</version>
+            <optional>true</optional>
+        </dependency>
+
         <!-- Testing -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-test</artifactId>
+            <version>3.2.5</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework</groupId>
+            <artifactId>spring-test</artifactId>
+            <version>6.1.6</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.24.2</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>

src/main/java/com/google/cloud/mcp/autoconfigure/McpToolboxAutoConfiguration.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.mcp.autoconfigure;
+
+import com.google.cloud.mcp.McpToolboxClient;
+import com.google.cloud.mcp.client.McpToolboxClientBuilder;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/** Auto-configuration for the MCP Toolbox SDK Client. */
+@AutoConfiguration
+@ConditionalOnClass(McpToolboxClient.class)
+@ConditionalOnProperty(name = "google.cloud.mcp.toolbox.base-url")
+@EnableConfigurationProperties(McpToolboxProperties.class)
+public class McpToolboxAutoConfiguration {
+
+  private final McpToolboxProperties properties;
+
+  public McpToolboxAutoConfiguration(McpToolboxProperties properties) {
+    this.properties = properties;
+  }
+
+  /**
+   * Registers a default {@link McpToolboxClient} bean if none is already defined.
+   *
+   * @return A configured {@link McpToolboxClient} instance.
+   */
+  @Bean
+  @ConditionalOnMissingBean
+  public McpToolboxClient mcpToolboxClient() {
+    McpToolboxClient.Builder builder =
+        new McpToolboxClientBuilder().baseUrl(properties.getBaseUrl());
+    if (properties.getApiKey() != null && !properties.getApiKey().isEmpty()) {
+      builder.apiKey(properties.getApiKey());
+    }
+    return builder.build();
+  }
+}

src/main/java/com/google/cloud/mcp/autoconfigure/McpToolboxProperties.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.mcp.autoconfigure;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/** Configuration properties for the MCP Toolbox SDK. */
+@ConfigurationProperties(prefix = "google.cloud.mcp.toolbox")
+public class McpToolboxProperties {
+  /** Base URL for the MCP Toolbox service. */
+  private String baseUrl;
+
+  /** API Key or token for the MCP Toolbox service (optional). */
+  private String apiKey;
+
+  public String getBaseUrl() {
+    return baseUrl;
+  }
+
+  public void setBaseUrl(String baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+
+  public String getApiKey() {
+    return apiKey;
+  }
+
+  public void setApiKey(String apiKey) {
+    this.apiKey = apiKey;
+  }
+}

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1 @@
+com.google.cloud.mcp.autoconfigure.McpToolboxAutoConfiguration