refactor: deprecate tool pre and post processing hooks to align with cross-SDK architecture

src/main/java/com/google/cloud/mcp/McpToolboxClient.java

@@ -156,15 +156,19 @@ interface Builder {
      *
      * @param preProcessor The pre-processor to add.
      * @return The builder instance.
+     * @deprecated Use orchestration framework callbacks instead of client-level pre-processors.
      */
+    @Deprecated
     Builder preProcessor(ToolPreProcessor preProcessor);
 
     /**
      * Adds a global post-processor that will be applied to all tools loaded by this client.
      *
      * @param postProcessor The post-processor to add.
      * @return The builder instance.
+     * @deprecated Use orchestration framework callbacks instead of client-level post-processors.
      */
+    @Deprecated
     Builder postProcessor(ToolPostProcessor postProcessor);
 
     /**

src/main/java/com/google/cloud/mcp/client/McpToolboxClientBuilder.java

@@ -30,6 +30,7 @@
 import java.util.concurrent.CompletableFuture;
 
 /** Implementation of the {@link McpToolboxClient.Builder} interface. */
+@SuppressWarnings("deprecation")
 public final class McpToolboxClientBuilder implements McpToolboxClient.Builder {
   private String baseUrl;
   private String apiKey;
@@ -70,6 +71,7 @@ public McpToolboxClient.Builder credentialsProvider(CredentialsProvider credenti
     return this;
   }
 
+  @Deprecated
   @Override
   public McpToolboxClient.Builder preProcessor(ToolPreProcessor preProcessor) {
     if (preProcessor != null) {
@@ -78,6 +80,7 @@ public McpToolboxClient.Builder preProcessor(ToolPreProcessor preProcessor) {
     return this;
   }
 
+  @Deprecated
   @Override
   public McpToolboxClient.Builder postProcessor(ToolPostProcessor postProcessor) {
     if (postProcessor != null) {

src/main/java/com/google/cloud/mcp/client/McpToolboxClientImpl.java

@@ -40,6 +40,7 @@
 import java.util.logging.Logger;
 
 /** Default implementation using Java 11 HttpClient. */
+@SuppressWarnings("deprecation")
 public final class McpToolboxClientImpl implements McpToolboxClient {
 
   /** Logger for logging messages. */
@@ -78,10 +79,9 @@ public McpToolboxClientImpl(final Transport clientTransport) {
    * Constructs a new McpToolboxClientImpl.
    *
    * @param transport The underlying MCP transport layer.
-   * @param headers Fallback headers for deprecated constructor compatibility.
-   * @param credentialsProvider Fallback provider for deprecated constructor compatibility.
+   * @param headers Default HTTP headers.
+   * @param credentialsProvider Provider for credentials.
    */
-  @Deprecated
   public McpToolboxClientImpl(
       Transport transport, Map<String, String> headers, CredentialsProvider credentialsProvider) {
     this(transport, headers, credentialsProvider, null, null);
@@ -161,14 +161,17 @@ private static CredentialsProvider apiKeyToProvider(final String apiKey) {
   }
 
   /**
-   * Primary constructor for McpToolboxClientImpl.
+   * Constructs a new McpToolboxClientImpl with pre- and post-processors.
    *
    * @param transport The underlying MCP transport layer.
    * @param headers Default HTTP headers.
    * @param credentialsProvider Provider for credentials.
    * @param preProcessors List of pre-processors.
    * @param postProcessors List of post-processors.
+   * @deprecated Use {@link #McpToolboxClientImpl(Transport, Map, CredentialsProvider)} instead.
+   *     Pre- and post-processors are deprecated in favor of orchestration framework callbacks.
    */
+  @Deprecated
   public McpToolboxClientImpl(
       Transport transport,
       Map<String, String> headers,

src/main/java/com/google/cloud/mcp/tool/Tool.java

@@ -32,6 +32,7 @@
  * Represents a loaded tool ready to be invoked. Handles parameter binding, authentication token
  * resolution, and input validation.
  */
+@SuppressWarnings("deprecation")
 public class Tool {
   private final String name;
   private final ToolDefinition definition;
@@ -183,7 +184,9 @@ private static ToolDefinition pruneParameter(
    *
    * @param processor The pre-processor to add.
    * @return The tool instance.
+   * @deprecated Use orchestration framework callbacks instead of tool-level pre-processors.
    */
+  @Deprecated
   public Tool addPreProcessor(final ToolPreProcessor processor) {
     List<ToolPreProcessor> newPre = new ArrayList<>(this.preProcessors);
     newPre.add(processor);
@@ -202,7 +205,9 @@ public Tool addPreProcessor(final ToolPreProcessor processor) {
    *
    * @param processor The post-processor to add.
    * @return A new tool instance with the post-processor added.
+   * @deprecated Use orchestration framework callbacks instead of tool-level post-processors.
    */
+  @Deprecated
   public Tool addPostProcessor(final ToolPostProcessor processor) {
     List<ToolPostProcessor> newPost = new ArrayList<>(this.postProcessors);
     newPost.add(processor);

src/main/java/com/google/cloud/mcp/tool/ToolPostProcessor.java

@@ -18,7 +18,14 @@
 
 import java.util.concurrent.CompletableFuture;
 
-/** A functional interface for post-processing tool results after invocation. */
+/**
+ * A functional interface for post-processing tool results after invocation.
+ *
+ * @deprecated Tool execution hooks are deprecated in the core SDK to align with cross-SDK
+ *     architecture. Use orchestration framework callbacks (e.g., ADK, LangChain4j, or Spring AI)
+ *     for post-invocation interception.
+ */
+@Deprecated
 @FunctionalInterface
 public interface ToolPostProcessor {
 

src/main/java/com/google/cloud/mcp/tool/ToolPreProcessor.java

@@ -19,7 +19,14 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 
-/** A functional interface for pre-processing tool inputs before invocation. */
+/**
+ * A functional interface for pre-processing tool inputs before invocation.
+ *
+ * @deprecated Tool execution hooks are deprecated in the core SDK to align with cross-SDK
+ *     architecture. Use orchestration framework callbacks (e.g., ADK, LangChain4j, or Spring AI)
+ *     for pre-invocation interception.
+ */
+@Deprecated
 @FunctionalInterface
 public interface ToolPreProcessor {
 

src/test/java/com/google/cloud/mcp/client/McpToolboxClientBuilderTest.java

@@ -170,6 +170,7 @@ void testCustomHttpClientAndExecutor() {
   }
 
   @Test
+  @SuppressWarnings("deprecation")
   void testProcessorsConfiguration() {
     ToolPreProcessor pre = (name, args) -> CompletableFuture.completedFuture(args);
     ToolPostProcessor post = (name, result) -> CompletableFuture.completedFuture(result);

src/test/java/com/google/cloud/mcp/client/McpToolboxClientImplTest.java

@@ -858,7 +858,7 @@ void testEnsureInitialized_withNotificationSerializationFailure() throws Excepti
     assertTrue(ex.getCause().getMessage().contains("Simulated notification serialization failure"));
   }
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings({"unchecked", "deprecation"})
   @Test
   void testClientPrePostProcessorsPropagation() throws Exception {
     Transport mockTransport = mock(Transport.class);

src/test/java/com/google/cloud/mcp/tool/ToolTest.java

@@ -284,7 +284,7 @@ void testToolDefinitionHints() {
   }
 
   @Test
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings({"unchecked", "deprecation"})
   void testExecute_withPreAndPostProcessors_modifiesArgsAndResult() throws Exception {
     // Arrange
     Map<String, Object> initialArgs = new HashMap<>();
@@ -343,6 +343,7 @@ void testExecute_withPreAndPostProcessors_modifiesArgsAndResult() throws Excepti
   }
 
   @Test
+  @SuppressWarnings("deprecation")
   void testExecute_preProcessorException_failsFutureWithoutInvokingClient() {
     // Arrange
     Map<String, Object> initialArgs = new HashMap<>();