feat: add pre & post processing hooks for tools

[stenalpjolly]

Summary

This PR introduces full support for Tool Pre and Post-processing execution hooks (ToolPreProcessor and ToolPostProcessor) in the Java SDK, fully integrated with the decoupled transport architecture and updated to align with the new thread-safety and token resolution updates.

Expectation & Implementation

• Processor Pipeline: Adds the ability to register ToolPreProcessor and ToolPostProcessor instances on McpToolboxClientBuilder. The client propagates these hooks to all loaded tools during loadToolset and loadTool.
• Pre-Processing Hooks: Executed sequentially before tool execution, allowing arguments to be transformed, supplemented, or validated.
• Post-Processing Hooks: Executed sequentially after the transport layer returns a tool result, allowing the output to be mutated, audited, or wrapped.
• Thread-Safety Defenses: Fully aligned with the concurrent token resolution mechanism (AuthResolver) introduced in PR refactor: resolve multiple auth tokens concurrently and safely in Tool.execute #65. In addition, local tool execution maps (finalArgs and extraHeaders) are wrapped in Collections.synchronizedMap(...) to prevent any concurrent modifications during async processing.
• Backward Compatibility: Preserved all five deprecated constructors (delegating them to the new primary transport constructor) to ensure perfect backward compatibility for existing library callers.

Acceptance criteria

The PR must satisfy the following functional and integration requirements to be accepted:

1. Pre/Post-Processor Execution:
   • Registered pre-processors must execute and be able to mutate arguments before the tool call is made.
   • Registered post-processors must execute and be able to mutate the result after the transport returns it.
2. Hook Propagation:
   • Processors registered on the client builder must successfully propagate to all loaded tools via both loadToolset and loadTool.
3. Concurrency Defenses:
   • Thread-safe mapping of resolved tokens to execution parameters and headers must prevent race conditions during asynchronous credential retrieval.
4. Backward Compatibility & Quality Safeguards:
   • Preserved all five deprecated constructors to support legacy caller configurations.
   • Compilation and checkstyle checks must pass cleanly with 0 violations.
   • All 115 unit tests must pass with 100% success.
   • All modified and new classes must have 100.00% instruction and branch coverage.

Test cases

• Integration Propagation Verification: Added testClientPrePostProcessorsPropagation in McpToolboxClientImplTest to verify that pre/post-processors registered on the client are successfully propagated to individual tools loaded via both loadToolset and loadTool.
• 100% Coverage Target:
  • Added testProcessorsConfiguration in McpToolboxClientBuilderTest to verify non-null and null pre/post-processor configuration flows.
  • Added testDefaultValueDeepCloning_withList, testValidateAndSanitizeArgs_requiredParameterProvided, and testValidateAndSanitizeArgs_nullTypeWithNonNullValue in ToolTest to cover nested structures and parameter boundary checks.
  • Achieved 100% instruction and branch coverage for the modified Tool, McpToolboxClientBuilder, ResolvedAuth, and McpToolboxClientImpl classes with 115 passing unit tests.

Breaking changes

None.

[anubhav756]

/gcbrun

[stenalpjolly]

/gcbrun

[stenalpjolly]

/gcbrun

[stenalpjolly]

/gcbrun

[stenalpjolly]

/gcbrun

[stenalpjolly]

/gcbrun

[anubhav756]

Might cause conflicts with #65.

[stenalpjolly]

I have addressed the PR review comment:

• Wrapped the finalArgs and extraHeaders maps in Collections.synchronizedMap during tool execution to guarantee thread safety when resolving async OAuth/OIDC credentials concurrently.

[anubhav756]

/gcbrun

[stenalpjolly]

/gcbrun