Skip to content

AIML-303 Part 6: Standardize tool architecture naming and composition [STACKED] - #56

Merged
ChrisEdwards merged 1 commit into
mainfrom
AIML-303-7-tool-architecture-refactor
Jan 7, 2026
Merged

ChrisEdwards merged 1 commit into
mainfrom
AIML-303-7-tool-architecture-refactor

Conversation

@ChrisEdwards

Copy link
Copy Markdown
Collaborator

⚠️ DO NOT MERGE - WAITING FOR #55

This is a stacked PR based on #55. Please review and merge #55 first, then rebase this PR onto main before merging.


Dependency Context:
This PR builds on PR #55 which cached the ContrastSDK instance. With the SDK caching in place, this PR refactors the tool architecture for consistent naming and reduced code duplication.


Why

The MCP tool architecture had inconsistent naming and duplicated code across base classes:

  • Response classes had inconsistent naming (PaginatedResponse vs ToolResponse)
  • Base classes had non-parallel names (BaseMcpTool vs BaseGetTool)
  • Both base classes duplicated SDK access methods and HTTP error mapping
  • Params classes used inheritance from ToolValidationContext instead of composition

What

  • Response naming alignment: PaginatedResponse → PaginatedToolResponse, ToolResponse → SingleToolResponse
  • Base class naming alignment: BaseMcpTool → BasePaginatedTool, BaseGetTool → BaseSingleTool
  • New BaseContrastTool: Extracted shared code (SDK access, HTTP error mapping)
  • New BaseToolParams: Enables composition pattern for all 13 params classes

How

New Class Hierarchy

BaseContrastTool (NEW)
├── @Autowired ContrastConfig config
├── getContrastSDK() / getOrgId()
├── mapHttpErrorCode(int code)
│
├── BasePaginatedTool<P, R>  (was BaseMcpTool)
│   └── Returns PaginatedToolResponse
│
└── BaseSingleTool<P, R>  (was BaseGetTool)
    └── Returns SingleToolResponse

Params Composition Pattern

Before (inheritance):

public class GetVulnerabilityParams extends ToolValidationContext {
    public static GetVulnerabilityParams of(String vulnId, String appId) {
        var params = new GetVulnerabilityParams();
        params.require(vulnId, "vulnId");  // Called on params
        return params;
    }
}

After (composition):

public class GetVulnerabilityParams extends BaseToolParams {
    public static GetVulnerabilityParams of(String vulnId, String appId) {
        var params = new GetVulnerabilityParams();
        var ctx = new ToolValidationContext();  // Composition
        ctx.require(vulnId, "vulnId");
        params.setValidationResult(ctx);  // Transfer errors/warnings
        return params;
    }
}

Step-by-Step Walkthrough

  1. Response classes (tool/base/):

    • Moved PaginatedResponse from data/ to tool/base/PaginatedToolResponse
    • Renamed ToolResponse to SingleToolResponse
    • Updated all imports (4 paginated tools, 9 single tools)
  2. Base classes (tool/base/):

    • Renamed BaseMcpTool → BasePaginatedTool
    • Renamed BaseGetTool → BaseSingleTool
    • Updated 13 tool class declarations
  3. New BaseContrastTool (tool/base/):

    • Extracted getContrastSDK(), getOrgId(), mapHttpErrorCode()
    • Both base classes now extend BaseContrastTool
  4. New BaseToolParams (tool/base/):

    • Implements ToolParams interface with boilerplate
    • Added errorIf() method to ToolValidationContext for composition
    • Migrated all 13 params classes from inheritance to composition

Testing

  • Unit tests: All 551 tests pass
  • Test renames: BaseMcpToolTest → BasePaginatedToolTest, BaseGetToolTest → BaseSingleToolTest, etc.
  • New tests: BaseContrastToolTest with parameterized HTTP error mapping tests
Tests run: 551, Failures: 0, Errors: 0, Skipped: 0

Files Changed

  • 41 files changed
  • 630 insertions, 282 deletions
  • 13 tool classes updated
  • 13 params classes migrated
  • 2 new base classes created
  • 4 response/test class renames

@ChrisEdwards ChrisEdwards changed the title AIML-303: Standardize tool architecture naming and composition [STACKED] AIML-303 Step 7: Standardize tool architecture naming and composition [STACKED] Dec 24, 2025
@ChrisEdwards ChrisEdwards changed the title AIML-303 Step 7: Standardize tool architecture naming and composition [STACKED] AIML-303 Part 7: Standardize tool architecture naming and composition [STACKED] Dec 24, 2025
@ChrisEdwards ChrisEdwards changed the title AIML-303 Part 7: Standardize tool architecture naming and composition [STACKED] AIML-303 Part 6: Standardize tool architecture naming and composition [STACKED] Dec 24, 2025
@ChrisEdwards
ChrisEdwards marked this pull request as ready for review December 24, 2025 08:53
@ChrisEdwards
ChrisEdwards force-pushed the AIML-303-6-cache-sdk-instance branch from c9c8250 to 7315bdd Compare January 2, 2026 17:04
@ChrisEdwards
ChrisEdwards force-pushed the AIML-303-7-tool-architecture-refactor branch from 8d88aa6 to 875761b Compare January 2, 2026 17:04
@ChrisEdwards
ChrisEdwards force-pushed the AIML-303-6-cache-sdk-instance branch from 7315bdd to 53f3b17 Compare January 6, 2026 17:24
@ChrisEdwards
ChrisEdwards force-pushed the AIML-303-7-tool-architecture-refactor branch from 875761b to 241c594 Compare January 6, 2026 17:25
@ChrisEdwards
ChrisEdwards force-pushed the AIML-303-6-cache-sdk-instance branch from 53f3b17 to b1cfc25 Compare January 7, 2026 00:12
- Rename response classes for clarity:
  - PaginatedResponse → PaginatedToolResponse
  - ToolResponse → SingleToolResponse
- Rename base classes to align with response types:
  - BaseMcpTool → BasePaginatedTool
  - BaseGetTool → BaseSingleTool
- Extract shared code into BaseContrastTool:
  - getContrastSDK() and getOrgId() helper methods
  - mapHttpErrorCode() for HTTP error mapping
- Use composition for params validation:
  - Create BaseToolParams for ToolParams boilerplate
  - Migrate all 13 params classes from inheritance to composition
  - Add errorIf() method to ToolValidationContext
- All 551 tests pass
@ChrisEdwards
ChrisEdwards force-pushed the AIML-303-7-tool-architecture-refactor branch from 241c594 to 67723fc Compare January 7, 2026 00:14
@ChrisEdwards
ChrisEdwards changed the base branch from AIML-303-6-cache-sdk-instance to main January 7, 2026 00:14
@ChrisEdwards
ChrisEdwards merged commit 906efb7 into main Jan 7, 2026
4 checks passed
@ChrisEdwards
ChrisEdwards deleted the AIML-303-7-tool-architecture-refactor branch January 7, 2026 01:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants