diff --git a/docs/solutions/best-practices/check-base-api-before-sdk-workarounds.md b/docs/solutions/best-practices/check-base-api-before-sdk-workarounds.md new file mode 100644 index 00000000..c4612132 --- /dev/null +++ b/docs/solutions/best-practices/check-base-api-before-sdk-workarounds.md @@ -0,0 +1,111 @@ +--- +module: MCP Server +date: 2025-12-05 +problem_type: best_practice +component: service_object +symptoms: + - "Built ~200 lines of in-memory filtering code to work around perceived SDK limitation" + - "Complex SessionFilteringResult record with early termination, pagination handling" + - "Performance concerns from fetching all data then filtering client-side" +root_cause: wrong_api +resolution_type: workflow_improvement +severity: high +tags: [sdk-design, api-investigation, workaround-prevention, contrast-sdk] +--- + +# Best Practice: Check Base API Before Building SDK Workarounds + +## Problem + +Built complex in-memory session filtering (~200 lines) in AssessService because the SDK's `TraceFilterForm` (GET) doesn't support session filtering. Assumed SDK exposed all available functionality. + +## Environment + +- Module: MCP Server - AssessService +- Affected Component: `search_app_vulnerabilities` tool +- Date: 2025-12-05 + +## Symptoms + +- Complex `SessionFilteringResult` record with early termination logic +- `fetchTracesWithEarlyTermination()` method spanning 100+ lines +- `buildSessionFilterPredicate()` for in-memory filtering +- Performance concerns: fetching up to 50,000 traces to filter client-side +- Truncation warnings when hitting limits + +## What Didn't Work + +**Assumed SDK represents full API capability:** +- Used `TraceFilterForm` with GET endpoint because that's what existing code used +- Didn't investigate TeamServer API directly +- Built elaborate workaround instead of checking alternatives + +## Solution + +**Always investigate the base API (TeamServer) before assuming SDK limitations.** + +Investigation revealed: +1. TeamServer has POST endpoint `/ng/{org}/traces/{app}/filter` that accepts `NgVulnerabilityFilterRequest` +2. This request object supports `agentSessionId` and `metadataFilters` natively +3. SDK already has `TraceFilterBody` class that maps to this, but it's incomplete +4. SDK has `getTraces(orgId, appId, TraceFilterBody, expand)` method - just needs pagination + +**Before building workarounds, always:** + +```bash +# 1. Check TeamServer controller for the endpoint +grep -r "traces.*filter" teamserver-app/src/main/java/contrast/teamserver/rest/ + +# 2. Check the request/response DTOs +find teamserver-app -name "*FilterRequest*" -o -name "*FilterBody*" + +# 3. Compare SDK classes to TeamServer DTOs +diff <(grep -E "private.*;" SDK/TraceFilterBody.java) \ + <(grep -E "private.*;" TeamServer/NgVulnerabilityFilterRequest.java) + +# 4. Check SDK for alternative methods +grep -A5 "TraceFilterBody" sdk/src/main/java/com/contrastsecurity/sdk/ContrastSDK.java +``` + +## Why This Works + +SDKs are often incomplete representations of APIs: +- SDK maintainers may not expose every endpoint +- Older SDK methods may use deprecated endpoints +- Newer API features may not be added to SDK yet +- SDK may have multiple methods for same data (GET vs POST) + +TeamServer is the source of truth. When SDK seems limited: +1. The API might support what you need via different endpoint +2. SDK might have the method but with different name/class +3. Small SDK enhancement may be easier than complex workaround + +## Prevention + +**Before building any workaround for perceived API limitation:** + +1. **Check TeamServer controllers** - Find the actual endpoint +2. **Check TeamServer DTOs** - See what parameters are supported +3. **Check SDK for alternatives** - Different method names, POST vs GET +4. **Compare SDK to DTO** - Identify gaps that need SDK enhancement +5. **Evaluate: SDK fix vs workaround** - Often SDK fix is cleaner + +**Questions to ask:** +- "Does the API support this natively?" +- "Is there a POST version of this GET endpoint?" +- "What does the TeamServer request object actually accept?" +- "Is the SDK class complete, or missing fields?" + +## Outcome + +Created beads to properly fix this: +- `mcp-3dcc` - Audit SDK `TraceFilterBody` vs TeamServer `NgVulnerabilityFilterRequest` +- `mcp-42zo` - Enhance SDK with missing fields and pagination +- `mcp-m4n2` - Implement proper `TraceFilterBody` builder in MCP +- `mcp-lxrt` - Delete the 200 lines of in-memory filtering code + +Result: Native API filtering, better performance, simpler code. + +## Related Issues + +- `mcp-g9dd` - Epic: Native Session Filtering via TraceFilterBody diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/GetProtectRulesTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/GetProtectRulesTool.java index b3455e9b..176ec33b 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/GetProtectRulesTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/GetProtectRulesTool.java @@ -18,8 +18,8 @@ import com.contrast.labs.ai.mcp.contrast.sdkextension.SDKExtension; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.ProtectData; import com.contrast.labs.ai.mcp.contrast.tool.adr.params.GetProtectRulesParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import java.util.List; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; @@ -34,7 +34,7 @@ @Service @RequiredArgsConstructor @Slf4j -public class GetProtectRulesTool extends BaseGetTool { +public class GetProtectRulesTool extends BaseSingleTool { @Tool( name = "get_protect_rules", @@ -59,7 +59,7 @@ public class GetProtectRulesTool extends BaseGetTool getProtectRules( + public SingleToolResponse getProtectRules( @ToolParam(description = "Application ID (use search_applications to find)") String appId) { return executePipeline(() -> GetProtectRulesParams.of(appId)); } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/SearchAttacksTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/SearchAttacksTool.java index 97e1e1f8..d64547c6 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/SearchAttacksTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/SearchAttacksTool.java @@ -17,11 +17,11 @@ import com.contrast.labs.ai.mcp.contrast.PaginationParams; import com.contrast.labs.ai.mcp.contrast.data.AttackSummary; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; import com.contrast.labs.ai.mcp.contrast.sdkextension.SDKExtension; import com.contrast.labs.ai.mcp.contrast.tool.adr.params.AttackFilterParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseMcpTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.BasePaginatedTool; import com.contrast.labs.ai.mcp.contrast.tool.base.ExecutionResult; +import com.contrast.labs.ai.mcp.contrast.tool.base.PaginatedToolResponse; import java.util.List; import lombok.RequiredArgsConstructor; import org.springframework.ai.tool.annotation.Tool; @@ -34,7 +34,7 @@ */ @Service @RequiredArgsConstructor -public class SearchAttacksTool extends BaseMcpTool { +public class SearchAttacksTool extends BasePaginatedTool { @Tool( name = "search_attacks", @@ -71,7 +71,7 @@ and sorting. Supports filtering by attack categorization (quickFilter), outcome - get_protect_rules: View configured protection rules for an application - search_applications: Find application IDs by name or tag """) - public PaginatedResponse searchAttacks( + public PaginatedToolResponse searchAttacks( @ToolParam( description = "Quick filter for attack categorization. Valid: ALL (no filter), ACTIVE (ongoing" diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/AttackFilterParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/AttackFilterParams.java index bff8581f..0ca65577 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/AttackFilterParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/AttackFilterParams.java @@ -16,6 +16,7 @@ package com.contrast.labs.ai.mcp.contrast.tool.adr.params; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.adr.AttacksFilterBody; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; import java.util.List; import java.util.Set; @@ -34,7 +35,7 @@ * var filterBody = params.toAttacksFilterBody(); * } */ -public class AttackFilterParams extends ToolValidationContext { +public class AttackFilterParams extends BaseToolParams { /** Valid quickFilter values for validation (from AttackQuickFilterType). */ public static final Set VALID_QUICK_FILTERS = @@ -78,11 +79,11 @@ public static AttackFilterParams of( String sort) { var params = new AttackFilterParams(); + var ctx = new ToolValidationContext(); // Parse quickFilter with validation params.quickFilter = - params - .stringParam(quickFilter, "quickFilter") + ctx.stringParam(quickFilter, "quickFilter") .toUpperCase() .allowedValues(VALID_QUICK_FILTERS) .defaultTo("ALL", "No quickFilter applied - showing all attack types") @@ -90,19 +91,19 @@ public static AttackFilterParams of( // Parse statusFilter with validation params.statusFilters = - params - .stringListParam(statusFilter, "statusFilter") + ctx.stringListParam(statusFilter, "statusFilter") .toUpperCase() .allowedValues(VALID_STATUS_FILTERS) .get(); // Parse keyword (no validation - pass through) - params.keyword = params.stringParam(keyword, "keyword").get(); + params.keyword = ctx.stringParam(keyword, "keyword").get(); // Parse includeSuppressed with smart default if (includeSuppressed == null) { params.includeSuppressed = false; - params.addWarning( + ctx.warnIf( + true, "Excluding suppressed attacks by default. " + "To see all attacks including suppressed, set includeSuppressed=true."); } else { @@ -119,7 +120,8 @@ public static AttackFilterParams of( if (trimmedSort.matches("^-?[a-zA-Z][a-zA-Z0-9_]*$")) { params.sort = trimmedSort; } else { - params.addError( + ctx.errorIf( + true, String.format( "Invalid sort format '%s'. Must be a field name with optional '-' prefix for" + " descending. Example: 'severity' or '-severity'", @@ -127,6 +129,7 @@ public static AttackFilterParams of( } } + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/GetProtectRulesParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/GetProtectRulesParams.java index 28872e2d..f9a25fc0 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/GetProtectRulesParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/adr/params/GetProtectRulesParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.adr.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * } * } */ -public class GetProtectRulesParams extends ToolValidationContext { +public class GetProtectRulesParams extends BaseToolParams { private String appId; @@ -44,12 +45,13 @@ private GetProtectRulesParams() {} */ public static GetProtectRulesParams of(String appId) { var params = new GetProtectRulesParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(appId, "appId"); - + ctx.require(appId, "appId"); params.appId = appId; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/GetSessionMetadataTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/GetSessionMetadataTool.java index 7a12493e..c4c16c35 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/GetSessionMetadataTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/GetSessionMetadataTool.java @@ -16,8 +16,8 @@ package com.contrast.labs.ai.mcp.contrast.tool.applications; import com.contrast.labs.ai.mcp.contrast.tool.applications.params.GetSessionMetadataParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrastsecurity.models.MetadataFilterResponse; import java.util.List; import org.springframework.ai.tool.annotation.Tool; @@ -30,7 +30,7 @@ */ @Service public class GetSessionMetadataTool - extends BaseGetTool { + extends BaseSingleTool { @Tool( name = "get_session_metadata", @@ -48,7 +48,7 @@ Use search_applications(name=...) to find the application ID from a name. - search_applications: Find application IDs by name, tag, or metadata - search_app_vulnerabilities: Search vulnerabilities with session filtering """) - public ToolResponse getSessionMetadata( + public SingleToolResponse getSessionMetadata( @ToolParam(description = "Application ID (use search_applications to find)") String appId) { return executePipeline(() -> GetSessionMetadataParams.of(appId)); } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/SearchApplicationsTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/SearchApplicationsTool.java index 7d2d6ca0..52926b0c 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/SearchApplicationsTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/SearchApplicationsTool.java @@ -19,12 +19,12 @@ import com.contrast.labs.ai.mcp.contrast.PaginationParams; import com.contrast.labs.ai.mcp.contrast.data.ApplicationData; import com.contrast.labs.ai.mcp.contrast.data.Metadata; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; import com.contrast.labs.ai.mcp.contrast.sdkextension.SDKHelper; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.application.Application; import com.contrast.labs.ai.mcp.contrast.tool.applications.params.ApplicationFilterParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseMcpTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.BasePaginatedTool; import com.contrast.labs.ai.mcp.contrast.tool.base.ExecutionResult; +import com.contrast.labs.ai.mcp.contrast.tool.base.PaginatedToolResponse; import java.util.List; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; @@ -35,7 +35,8 @@ * with BaseMcpTool and in-memory filtering. */ @Service -public class SearchApplicationsTool extends BaseMcpTool { +public class SearchApplicationsTool + extends BasePaginatedTool { @Tool( name = "search_applications", @@ -56,7 +57,7 @@ public class SearchApplicationsTool extends BaseMcpTool searchApplications( + public PaginatedToolResponse searchApplications( @ToolParam(description = "Page number (1-based), default: 1", required = false) Integer page, @ToolParam(description = "Items per page (max 100), default: 50", required = false) Integer pageSize, diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/ApplicationFilterParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/ApplicationFilterParams.java index 9f85dc03..aca56b90 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/ApplicationFilterParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/ApplicationFilterParams.java @@ -16,6 +16,7 @@ package com.contrast.labs.ai.mcp.contrast.tool.applications.params; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.application.Application; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; import org.springframework.util.StringUtils; @@ -33,7 +34,7 @@ * boolean matches = params.matches(application); * } */ -public class ApplicationFilterParams extends ToolValidationContext { +public class ApplicationFilterParams extends BaseToolParams { private String name; private String tag; @@ -56,6 +57,7 @@ public static ApplicationFilterParams of( String name, String tag, String metadataName, String metadataValue) { var params = new ApplicationFilterParams(); + var ctx = new ToolValidationContext(); // Store raw values - all filters are optional params.name = StringUtils.hasText(name) ? name : null; @@ -64,8 +66,9 @@ public static ApplicationFilterParams of( params.metadataValue = StringUtils.hasText(metadataValue) ? metadataValue : null; // Cross-field validation: metadataValue requires metadataName - params.requireIfPresent(metadataValue, "metadataValue", metadataName, "metadataName"); + ctx.requireIfPresent(metadataValue, "metadataValue", metadataName, "metadataName"); + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/GetSessionMetadataParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/GetSessionMetadataParams.java index 453711c1..3ef45b90 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/GetSessionMetadataParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/applications/params/GetSessionMetadataParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.applications.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * } * } */ -public class GetSessionMetadataParams extends ToolValidationContext { +public class GetSessionMetadataParams extends BaseToolParams { private String appId; @@ -44,11 +45,13 @@ private GetSessionMetadataParams() {} */ public static GetSessionMetadataParams of(String appId) { var params = new GetSessionMetadataParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(appId, "appId"); + ctx.require(appId, "appId"); params.appId = appId; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/GetVulnerabilityTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/GetVulnerabilityTool.java index 3b323e0d..c0737325 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/GetVulnerabilityTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/GetVulnerabilityTool.java @@ -25,8 +25,8 @@ import com.contrast.labs.ai.mcp.contrast.sdkextension.data.LibraryExtended; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.sca.LibraryObservation; import com.contrast.labs.ai.mcp.contrast.tool.assess.params.GetVulnerabilityParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrastsecurity.http.TraceFilterForm; import com.contrastsecurity.models.EventResource; import com.contrastsecurity.models.Stacktrace; @@ -48,7 +48,7 @@ @Service @RequiredArgsConstructor @Slf4j -public class GetVulnerabilityTool extends BaseGetTool { +public class GetVulnerabilityTool extends BaseSingleTool { private final VulnerabilityMapper vulnerabilityMapper; @@ -79,7 +79,7 @@ public class GetVulnerabilityTool extends BaseGetTool getVulnerability( + public SingleToolResponse getVulnerability( @ToolParam(description = "Vulnerability ID (use search_vulnerabilities to find)") String vulnId, @ToolParam(description = "Application ID (use search_applications to find)") String appId) { diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/ListVulnerabilityTypesTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/ListVulnerabilityTypesTool.java index 7b86869e..e5ca49f4 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/ListVulnerabilityTypesTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/ListVulnerabilityTypesTool.java @@ -16,8 +16,8 @@ package com.contrast.labs.ai.mcp.contrast.tool.assess; import com.contrast.labs.ai.mcp.contrast.tool.assess.params.ListVulnerabilityTypesParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrastsecurity.models.Rules; import java.util.ArrayList; import java.util.List; @@ -32,7 +32,7 @@ @Service @RequiredArgsConstructor public class ListVulnerabilityTypesTool - extends BaseGetTool> { + extends BaseSingleTool> { @Tool( name = "list_vulnerability_types", @@ -51,7 +51,7 @@ Returns the complete list of vulnerability types (rule names) available in Contr Note: The list is fetched dynamically from Contrast and reflects the rules configured for your organization, so it's always current. """) - public ToolResponse> listVulnerabilityTypes() { + public SingleToolResponse> listVulnerabilityTypes() { return executePipeline(ListVulnerabilityTypesParams::of); } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchAppVulnerabilitiesTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchAppVulnerabilitiesTool.java index 0289e182..8445d084 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchAppVulnerabilitiesTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchAppVulnerabilitiesTool.java @@ -16,13 +16,13 @@ package com.contrast.labs.ai.mcp.contrast.tool.assess; import com.contrast.labs.ai.mcp.contrast.PaginationParams; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; import com.contrast.labs.ai.mcp.contrast.data.VulnLight; import com.contrast.labs.ai.mcp.contrast.mapper.VulnerabilityMapper; import com.contrast.labs.ai.mcp.contrast.sdkextension.SDKExtension; import com.contrast.labs.ai.mcp.contrast.tool.assess.params.SearchAppVulnerabilitiesParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseMcpTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.BasePaginatedTool; import com.contrast.labs.ai.mcp.contrast.tool.base.ExecutionResult; +import com.contrast.labs.ai.mcp.contrast.tool.base.PaginatedToolResponse; import com.contrastsecurity.http.TraceFilterForm; import com.contrastsecurity.models.MetadataItem; import com.contrastsecurity.models.SessionMetadata; @@ -50,7 +50,7 @@ @RequiredArgsConstructor @Slf4j public class SearchAppVulnerabilitiesTool - extends BaseMcpTool { + extends BasePaginatedTool { private final VulnerabilityMapper vulnerabilityMapper; @@ -86,7 +86,7 @@ Supports all standard filters (severity, status, environment, dates, tags) PLUS: - Session metadata: appId="abc123", sessionMetadataName="branch", sessionMetadataValue="main" - Production critical: appId="abc123", severities="CRITICAL", environments="PRODUCTION" """) - public PaginatedResponse searchAppVulnerabilities( + public PaginatedToolResponse searchAppVulnerabilities( @ToolParam( description = "Application ID (required). Use search_applications to find app IDs by name.") diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchVulnerabilitiesTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchVulnerabilitiesTool.java index 26eadddc..4b13f2be 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchVulnerabilitiesTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/SearchVulnerabilitiesTool.java @@ -16,12 +16,12 @@ package com.contrast.labs.ai.mcp.contrast.tool.assess; import com.contrast.labs.ai.mcp.contrast.PaginationParams; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; import com.contrast.labs.ai.mcp.contrast.data.VulnLight; import com.contrast.labs.ai.mcp.contrast.mapper.VulnerabilityMapper; import com.contrast.labs.ai.mcp.contrast.tool.assess.params.VulnerabilityFilterParams; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseMcpTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.BasePaginatedTool; import com.contrast.labs.ai.mcp.contrast.tool.base.ExecutionResult; +import com.contrast.labs.ai.mcp.contrast.tool.base.PaginatedToolResponse; import com.contrastsecurity.http.TraceFilterForm; import java.util.EnumSet; import java.util.List; @@ -36,7 +36,8 @@ */ @Service @RequiredArgsConstructor -public class SearchVulnerabilitiesTool extends BaseMcpTool { +public class SearchVulnerabilitiesTool + extends BasePaginatedTool { private final VulnerabilityMapper vulnerabilityMapper; @@ -74,7 +75,7 @@ Returns paginated results with metadata including totalItems (when available) an - search_app_vulnerabilities: For app-scoped searches with session filtering - search_applications: To find application IDs by name, tag, or metadata """) - public PaginatedResponse searchVulnerabilities( + public PaginatedToolResponse searchVulnerabilities( @ToolParam(description = "Page number (1-based), default: 1", required = false) Integer page, @ToolParam(description = "Items per page (max 100), default: 50", required = false) Integer pageSize, diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/GetVulnerabilityParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/GetVulnerabilityParams.java index a66442ef..3ec0b877 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/GetVulnerabilityParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/GetVulnerabilityParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.assess.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * } * } */ -public class GetVulnerabilityParams extends ToolValidationContext { +public class GetVulnerabilityParams extends BaseToolParams { private String vulnId; private String appId; @@ -46,14 +47,16 @@ private GetVulnerabilityParams() {} */ public static GetVulnerabilityParams of(String vulnId, String appId) { var params = new GetVulnerabilityParams(); + var ctx = new ToolValidationContext(); // Validate required fields - params.require(vulnId, "vulnId"); - params.require(appId, "appId"); + ctx.require(vulnId, "vulnId"); + ctx.require(appId, "appId"); params.vulnId = vulnId; params.appId = appId; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/ListVulnerabilityTypesParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/ListVulnerabilityTypesParams.java index eac35d00..79661263 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/ListVulnerabilityTypesParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/ListVulnerabilityTypesParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.assess.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * var filterForm = params.toTraceFilterForm(); * } */ -public class ListVulnerabilityTypesParams extends ToolValidationContext { +public class ListVulnerabilityTypesParams extends BaseToolParams { /** Private constructor - use static factory method {@link #of}. */ private ListVulnerabilityTypesParams() {} @@ -40,6 +41,9 @@ private ListVulnerabilityTypesParams() {} * @return ListVulnerabilityTypesParams (always valid - no parameters required) */ public static ListVulnerabilityTypesParams of() { - return new ListVulnerabilityTypesParams(); + var params = new ListVulnerabilityTypesParams(); + var ctx = new ToolValidationContext(); + params.setValidationResult(ctx); + return params; } } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/SearchAppVulnerabilitiesParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/SearchAppVulnerabilitiesParams.java index 4a7106af..4b404c0d 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/SearchAppVulnerabilitiesParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/SearchAppVulnerabilitiesParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.assess.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; import com.contrastsecurity.http.RuleSeverity; import com.contrastsecurity.http.ServerEnvironment; @@ -39,7 +40,7 @@ * var filterForm = params.toTraceFilterForm(); * } */ -public class SearchAppVulnerabilitiesParams extends ToolValidationContext { +public class SearchAppVulnerabilitiesParams extends BaseToolParams { /** Valid status values for vulnerability filtering. */ public static final Set VALID_STATUSES = @@ -94,18 +95,17 @@ public static SearchAppVulnerabilitiesParams of( Boolean useLatestSessionParam) { var params = new SearchAppVulnerabilitiesParams(); + var ctx = new ToolValidationContext(); // Required field - params.require(appIdParam, "appId"); + ctx.require(appIdParam, "appId"); params.appId = appIdParam; // Parse filter parameters with fluent API - params.severities = - params.enumSetParam(severitiesParam, RuleSeverity.class, "severities").get(); + params.severities = ctx.enumSetParam(severitiesParam, RuleSeverity.class, "severities").get(); params.statuses = - params - .stringListParam(statusesParam, "statuses") + ctx.stringListParam(statusesParam, "statuses") .allowedValues(VALID_STATUSES) .defaultTo( DEFAULT_STATUSES, @@ -113,23 +113,23 @@ public static SearchAppVulnerabilitiesParams of( + "To see all statuses, specify statuses parameter explicitly.") .get(); - params.vulnTypes = params.stringListParam(vulnTypesParam, "vulnTypes").get(); + params.vulnTypes = ctx.stringListParam(vulnTypesParam, "vulnTypes").get(); params.environments = - params.enumSetParam(environmentsParam, ServerEnvironment.class, "environments").get(); + ctx.enumSetParam(environmentsParam, ServerEnvironment.class, "environments").get(); - params.lastSeenAfter = params.dateParam(lastSeenAfterParam, "lastSeenAfter").get(); - params.lastSeenBefore = params.dateParam(lastSeenBeforeParam, "lastSeenBefore").get(); - params.validateDateRange( + params.lastSeenAfter = ctx.dateParam(lastSeenAfterParam, "lastSeenAfter").get(); + params.lastSeenBefore = ctx.dateParam(lastSeenBeforeParam, "lastSeenBefore").get(); + ctx.validateDateRange( params.lastSeenAfter, params.lastSeenBefore, "lastSeenAfter", "lastSeenBefore"); // Add time filter note if dates were specified if (params.lastSeenAfter != null || params.lastSeenBefore != null) { - params.warnIf( + ctx.warnIf( true, "Time filters apply to LAST ACTIVITY DATE (lastTimeSeen), not discovery date."); } - params.vulnTags = params.stringListParam(vulnTagsParam, "vulnTags").get(); + params.vulnTags = ctx.stringListParam(vulnTagsParam, "vulnTags").get(); // Session filtering parameters with cross-field validation params.sessionMetadataName = sessionMetadataNameParam; @@ -137,12 +137,13 @@ public static SearchAppVulnerabilitiesParams of( params.useLatestSession = useLatestSessionParam; // Validate sessionMetadataValue requires sessionMetadataName - params.requireIfPresent( + ctx.requireIfPresent( sessionMetadataValueParam, "sessionMetadataValue", sessionMetadataNameParam, "sessionMetadataName"); + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/VulnerabilityFilterParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/VulnerabilityFilterParams.java index c0b82270..1a3a509a 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/VulnerabilityFilterParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/assess/params/VulnerabilityFilterParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.assess.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; import com.contrastsecurity.http.RuleSeverity; import com.contrastsecurity.http.ServerEnvironment; @@ -39,7 +40,7 @@ * var filterForm = params.toTraceFilterForm(); * } */ -public class VulnerabilityFilterParams extends ToolValidationContext { +public class VulnerabilityFilterParams extends BaseToolParams { /** Valid status values for vulnerability filtering. */ public static final Set VALID_STATUSES = @@ -82,14 +83,13 @@ public static VulnerabilityFilterParams of( String vulnTagsParam) { var params = new VulnerabilityFilterParams(); + var ctx = new ToolValidationContext(); - // Parse with fluent API - validation state collected in params instance - params.severities = - params.enumSetParam(severitiesParam, RuleSeverity.class, "severities").get(); + // Parse with fluent API - validation state collected in ctx + params.severities = ctx.enumSetParam(severitiesParam, RuleSeverity.class, "severities").get(); params.statuses = - params - .stringListParam(statusesParam, "statuses") + ctx.stringListParam(statusesParam, "statuses") .allowedValues(VALID_STATUSES) .defaultTo( DEFAULT_STATUSES, @@ -97,24 +97,25 @@ public static VulnerabilityFilterParams of( + "To see all statuses, specify statuses parameter explicitly.") .get(); - params.vulnTypes = params.stringListParam(vulnTypesParam, "vulnTypes").get(); + params.vulnTypes = ctx.stringListParam(vulnTypesParam, "vulnTypes").get(); params.environments = - params.enumSetParam(environmentsParam, ServerEnvironment.class, "environments").get(); + ctx.enumSetParam(environmentsParam, ServerEnvironment.class, "environments").get(); - params.lastSeenAfter = params.dateParam(lastSeenAfterParam, "lastSeenAfter").get(); - params.lastSeenBefore = params.dateParam(lastSeenBeforeParam, "lastSeenBefore").get(); - params.validateDateRange( + params.lastSeenAfter = ctx.dateParam(lastSeenAfterParam, "lastSeenAfter").get(); + params.lastSeenBefore = ctx.dateParam(lastSeenBeforeParam, "lastSeenBefore").get(); + ctx.validateDateRange( params.lastSeenAfter, params.lastSeenBefore, "lastSeenAfter", "lastSeenBefore"); // Add time filter note if dates were specified if (params.lastSeenAfter != null || params.lastSeenBefore != null) { - params.warnIf( + ctx.warnIf( true, "Time filters apply to LAST ACTIVITY DATE (lastTimeSeen), not discovery date."); } - params.vulnTags = params.stringListParam(vulnTagsParam, "vulnTags").get(); + params.vulnTags = ctx.stringListParam(vulnTagsParam, "vulnTags").get(); + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseContrastTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseContrastTool.java new file mode 100644 index 00000000..280100c2 --- /dev/null +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseContrastTool.java @@ -0,0 +1,72 @@ +/* + * Copyright 2025 Contrast Security + * + * 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.contrast.labs.ai.mcp.contrast.tool.base; + +import com.contrast.labs.ai.mcp.contrast.config.ContrastConfig; +import com.contrastsecurity.sdk.ContrastSDK; +import org.springframework.beans.factory.annotation.Autowired; + +/** + * Base class for all Contrast MCP tools. Provides common infrastructure shared across paginated and + * single-item tools. + * + *

Subclasses get access to: + * + *

    + *
  • ContrastSDK instance via {@link #getContrastSDK()} + *
  • Organization ID via {@link #getOrgId()} + *
  • HTTP error code mapping via {@link #mapHttpErrorCode(int)} + *
+ */ +public abstract class BaseContrastTool { + + @Autowired protected ContrastConfig config; + + /** + * Returns the cached ContrastSDK instance from configuration. + * + * @return cached ContrastSDK + */ + protected ContrastSDK getContrastSDK() { + return config.getSDK(); + } + + /** + * Returns the organization ID from configuration. + * + * @return organization ID + */ + protected String getOrgId() { + return config.getOrgId(); + } + + /** + * Maps HTTP error codes to user-friendly error messages. + * + * @param code HTTP status code + * @return user-friendly error message + */ + protected String mapHttpErrorCode(int code) { + return switch (code) { + case 401 -> "Authentication failed. Verify API credentials."; + case 403 -> "Access denied. User lacks permission for this resource."; + case 404 -> "Resource not found."; + case 429 -> "Rate limit exceeded. Retry later."; + case 500, 502, 503 -> "Contrast API error. Try again later."; + default -> "API error (HTTP " + code + ")"; + }; + } +} diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseMcpTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BasePaginatedTool.java similarity index 80% rename from src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseMcpTool.java rename to src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BasePaginatedTool.java index b3e7fe83..aa94c8eb 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseMcpTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BasePaginatedTool.java @@ -16,18 +16,14 @@ package com.contrast.labs.ai.mcp.contrast.tool.base; import com.contrast.labs.ai.mcp.contrast.PaginationParams; -import com.contrast.labs.ai.mcp.contrast.config.ContrastConfig; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; import com.contrastsecurity.exceptions.HttpResponseException; import com.contrastsecurity.exceptions.ResourceNotFoundException; import com.contrastsecurity.exceptions.UnauthorizedException; -import com.contrastsecurity.sdk.ContrastSDK; import java.util.ArrayList; import java.util.List; import java.util.UUID; import java.util.function.Supplier; import lombok.extern.slf4j.Slf4j; -import org.springframework.beans.factory.annotation.Autowired; /** * Abstract base class for paginated MCP search tools. Enforces a consistent processing pipeline via @@ -48,9 +44,7 @@ * @param the result item type */ @Slf4j -public abstract class BaseMcpTool

{ - - @Autowired protected ContrastConfig config; +public abstract class BasePaginatedTool

extends BaseContrastTool { /** * Template method - defines the mandatory processing pipeline. Subclasses implement doExecute() @@ -61,7 +55,7 @@ public abstract class BaseMcpTool

{ * @param paramsSupplier lazy supplier of tool-specific parameters * @return paginated response with items or errors */ - protected final PaginatedResponse executePipeline( + protected final PaginatedToolResponse executePipeline( Integer page, Integer pageSize, Supplier

paramsSupplier) { var requestId = UUID.randomUUID().toString().substring(0, 8); @@ -81,7 +75,7 @@ protected final PaginatedResponse executePipeline( // 4. Single validation checkpoint - ALL errors collected if (!params.isValid()) { logValidationError(requestId, params.errors()); - return PaginatedResponse.validationError( + return PaginatedToolResponse.validationError( pagination.page(), pagination.pageSize(), params.errors()); } @@ -106,7 +100,7 @@ protected final PaginatedResponse executePipeline( .setCause(e) .setMessage("Request failed unexpectedly") .log(); - return PaginatedResponse.error( + return PaginatedToolResponse.error( pagination.page(), pagination.pageSize(), "Internal error: " + e.getMessage()); } } @@ -123,25 +117,7 @@ protected final PaginatedResponse executePipeline( protected abstract ExecutionResult doExecute( PaginationParams pagination, P params, List warnings) throws Exception; - /** - * Returns the cached ContrastSDK instance from configuration. - * - * @return cached ContrastSDK - */ - protected ContrastSDK getContrastSDK() { - return config.getSDK(); - } - - /** - * Returns the organization ID from configuration. - * - * @return organization ID - */ - protected String getOrgId() { - return config.getOrgId(); - } - - private PaginatedResponse handleException( + private PaginatedToolResponse handleException( Exception e, PaginationParams pagination, String requestId, String userMessage) { log.atWarn() .addKeyValue("requestId", requestId) @@ -149,21 +125,13 @@ private PaginatedResponse handleException( .setMessage("Request failed: {}") .addArgument(e.getMessage()) .log(); - return PaginatedResponse.error(pagination.page(), pagination.pageSize(), userMessage); + return PaginatedToolResponse.error(pagination.page(), pagination.pageSize(), userMessage); } - private PaginatedResponse handleHttpResponseException( + private PaginatedToolResponse handleHttpResponseException( HttpResponseException e, PaginationParams pagination, String requestId) { - String errorMessage = - switch (e.getCode()) { - case 401 -> "Authentication failed. Verify API credentials."; - case 403 -> "Access denied. User lacks permission for this resource."; - case 404 -> "Resource not found."; - case 429 -> "Rate limit exceeded. Retry later."; - case 500, 502, 503 -> "Contrast API error. Try again later."; - default -> "API error: " + e.getMessage(); - }; + String errorMessage = mapHttpErrorCode(e.getCode()); log.atWarn() .addKeyValue("requestId", requestId) @@ -172,10 +140,10 @@ private PaginatedResponse handleHttpResponseException( .addArgument(e.getMessage()) .log(); - return PaginatedResponse.error(pagination.page(), pagination.pageSize(), errorMessage); + return PaginatedToolResponse.error(pagination.page(), pagination.pageSize(), errorMessage); } - private PaginatedResponse buildSuccessResponse( + private PaginatedToolResponse buildSuccessResponse( ExecutionResult result, PaginationParams pagination, List warnings, @@ -190,7 +158,7 @@ private PaginatedResponse buildSuccessResponse( logSuccess(requestId, duration, result.items().size(), result.totalItems()); - return PaginatedResponse.success( + return PaginatedToolResponse.success( result.items(), pagination.page(), pagination.pageSize(), diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseGetTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseSingleTool.java similarity index 76% rename from src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseGetTool.java rename to src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseSingleTool.java index 0d1d13a0..c4cc8da4 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseGetTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseSingleTool.java @@ -15,17 +15,14 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.base; -import com.contrast.labs.ai.mcp.contrast.config.ContrastConfig; import com.contrastsecurity.exceptions.HttpResponseException; import com.contrastsecurity.exceptions.ResourceNotFoundException; import com.contrastsecurity.exceptions.UnauthorizedException; -import com.contrastsecurity.sdk.ContrastSDK; import java.util.ArrayList; import java.util.List; import java.util.UUID; import java.util.function.Supplier; import lombok.extern.slf4j.Slf4j; -import org.springframework.beans.factory.annotation.Autowired; /** * Abstract base class for non-paginated MCP get tools. Enforces a consistent processing pipeline @@ -45,9 +42,7 @@ * @param the result item type */ @Slf4j -public abstract class BaseGetTool

{ - - @Autowired protected ContrastConfig config; +public abstract class BaseSingleTool

extends BaseContrastTool { /** * Template method - defines the mandatory processing pipeline for single-item retrieval. @@ -57,7 +52,7 @@ public abstract class BaseGetTool

{ * @param paramsSupplier lazy supplier of tool-specific parameters * @return tool response with item or errors */ - protected final ToolResponse executePipeline(Supplier

paramsSupplier) { + protected final SingleToolResponse executePipeline(Supplier

paramsSupplier) { var requestId = UUID.randomUUID().toString().substring(0, 8); long startTime = System.currentTimeMillis(); @@ -70,7 +65,7 @@ protected final ToolResponse executePipeline(Supplier

paramsSupplier) { // 3. Single validation checkpoint - ALL errors collected if (!params.isValid()) { logValidationError(requestId, params.errors()); - return ToolResponse.error(params.errors()); + return SingleToolResponse.error(params.errors()); } // 4. Execute - doExecute returns item or null if not found @@ -80,11 +75,11 @@ protected final ToolResponse executePipeline(Supplier

paramsSupplier) { if (result == null) { logNotFound(requestId, duration); - return ToolResponse.notFound("Resource not found", warnings); + return SingleToolResponse.notFound("Resource not found", warnings); } logSuccess(requestId, duration); - return ToolResponse.success(result, warnings); + return SingleToolResponse.success(result, warnings); } catch (ResourceNotFoundException e) { return handleException(e, requestId, "Resource not found: " + e.getMessage(), warnings); @@ -99,7 +94,7 @@ protected final ToolResponse executePipeline(Supplier

paramsSupplier) { .setCause(e) .setMessage("Request failed unexpectedly") .log(); - return ToolResponse.error("Internal error: " + e.getMessage()); + return SingleToolResponse.error("Internal error: " + e.getMessage()); } } @@ -113,25 +108,7 @@ protected final ToolResponse executePipeline(Supplier

paramsSupplier) { */ protected abstract R doExecute(P params, List warnings) throws Exception; - /** - * Returns the cached ContrastSDK instance from configuration. - * - * @return cached ContrastSDK - */ - protected ContrastSDK getContrastSDK() { - return config.getSDK(); - } - - /** - * Returns the organization ID from configuration. - * - * @return organization ID - */ - protected String getOrgId() { - return config.getOrgId(); - } - - private ToolResponse handleException( + private SingleToolResponse handleException( Exception e, String requestId, String userMessage, List warnings) { log.atWarn() .addKeyValue("requestId", requestId) @@ -142,21 +119,13 @@ private ToolResponse handleException( // Include warnings in error response for context var allWarnings = new ArrayList<>(warnings); allWarnings.add(userMessage); - return new ToolResponse<>(null, List.of(userMessage), warnings, false); + return new SingleToolResponse<>(null, List.of(userMessage), warnings, false); } - private ToolResponse handleHttpResponseException( + private SingleToolResponse handleHttpResponseException( HttpResponseException e, String requestId, List warnings) { - String errorMessage = - switch (e.getCode()) { - case 401 -> "Authentication failed. Verify API credentials."; - case 403 -> "Access denied. User lacks permission for this resource."; - case 404 -> "Resource not found."; - case 429 -> "Rate limit exceeded. Retry later."; - case 500, 502, 503 -> "Contrast API error. Try again later."; - default -> "API error: " + e.getMessage(); - }; + String errorMessage = mapHttpErrorCode(e.getCode()); log.atWarn() .addKeyValue("requestId", requestId) @@ -165,7 +134,7 @@ private ToolResponse handleHttpResponseException( .addArgument(e.getMessage()) .log(); - return ToolResponse.error(errorMessage); + return SingleToolResponse.error(errorMessage); } private void logValidationError(String requestId, List errors) { diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseToolParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseToolParams.java new file mode 100644 index 00000000..56ee6590 --- /dev/null +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseToolParams.java @@ -0,0 +1,76 @@ +/* + * Copyright 2025 Contrast Security + * + * 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.contrast.labs.ai.mcp.contrast.tool.base; + +import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; +import java.util.List; + +/** + * Base class for tool parameters that provides the ToolParams boilerplate. Subclasses store + * domain-specific fields and use composition with ToolValidationContext for validation. + * + *

Usage pattern: + * + *

{@code
+ * public class MyParams extends BaseToolParams {
+ *   private String myField;
+ *
+ *   public static MyParams of(String value) {
+ *     var params = new MyParams();
+ *     var ctx = new ToolValidationContext();  // Composition, not inheritance
+ *
+ *     ctx.require(value, "myField");
+ *     params.myField = value;
+ *
+ *     params.setValidationResult(ctx);  // Transfer errors/warnings
+ *     return params;
+ *   }
+ *
+ *   public String myField() { return myField; }
+ * }
+ * }
+ */ +public abstract class BaseToolParams implements ToolParams { + + private List errors = List.of(); + private List warnings = List.of(); + + @Override + public boolean isValid() { + return errors.isEmpty(); + } + + @Override + public List errors() { + return errors; + } + + @Override + public List warnings() { + return warnings; + } + + /** + * Transfer validation results from a ToolValidationContext to this params instance. Call this at + * the end of static factory methods after all validation is complete. + * + * @param ctx the validation context containing errors and warnings + */ + protected void setValidationResult(ToolValidationContext ctx) { + this.errors = ctx.errors(); + this.warnings = ctx.warnings(); + } +} diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/data/PaginatedResponse.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/PaginatedToolResponse.java similarity index 87% rename from src/main/java/com/contrast/labs/ai/mcp/contrast/data/PaginatedResponse.java rename to src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/PaginatedToolResponse.java index 599d33f0..0eee8288 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/data/PaginatedResponse.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/PaginatedToolResponse.java @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package com.contrast.labs.ai.mcp.contrast.data; +package com.contrast.labs.ai.mcp.contrast.tool.base; import java.util.List; @@ -34,7 +34,7 @@ * @param warnings Non-fatal warnings (e.g., applied defaults, empty results) - informational * @param durationMs Execution duration in milliseconds (null for validation errors) */ -public record PaginatedResponse( +public record PaginatedToolResponse( List items, int page, int pageSize, @@ -45,7 +45,7 @@ public record PaginatedResponse( Long durationMs) { /** Compact constructor ensures non-null, immutable lists. */ - public PaginatedResponse { + public PaginatedToolResponse { items = items != null ? List.copyOf(items) : List.of(); errors = errors != null ? List.copyOf(errors) : List.of(); warnings = warnings != null ? List.copyOf(warnings) : List.of(); @@ -73,7 +73,7 @@ public boolean isSuccess() { * @param item type * @return successful paginated response */ - public static PaginatedResponse success( + public static PaginatedToolResponse success( List items, int page, int pageSize, @@ -81,7 +81,7 @@ public static PaginatedResponse success( boolean hasMorePages, List warnings, Long durationMs) { - return new PaginatedResponse<>( + return new PaginatedToolResponse<>( items, page, pageSize, totalItems, hasMorePages, List.of(), warnings, durationMs); } @@ -94,9 +94,10 @@ public static PaginatedResponse success( * @param item type * @return error response with no items */ - public static PaginatedResponse validationError( + public static PaginatedToolResponse validationError( int page, int pageSize, List errors) { - return new PaginatedResponse<>(List.of(), page, pageSize, 0, false, errors, List.of(), null); + return new PaginatedToolResponse<>( + List.of(), page, pageSize, 0, false, errors, List.of(), null); } /** @@ -108,8 +109,8 @@ public static PaginatedResponse validationError( * @param item type * @return empty response with warning */ - public static PaginatedResponse empty(int page, int pageSize, String warningMessage) { - return new PaginatedResponse<>( + public static PaginatedToolResponse empty(int page, int pageSize, String warningMessage) { + return new PaginatedToolResponse<>( List.of(), page, pageSize, 0, false, List.of(), List.of(warningMessage), null); } @@ -122,8 +123,8 @@ public static PaginatedResponse empty(int page, int pageSize, String warn * @param item type * @return error response with no items */ - public static PaginatedResponse error(int page, int pageSize, String errorMessage) { - return new PaginatedResponse<>( + public static PaginatedToolResponse error(int page, int pageSize, String errorMessage) { + return new PaginatedToolResponse<>( List.of(), page, pageSize, 0, false, List.of(errorMessage), List.of(), null); } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/ToolResponse.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/SingleToolResponse.java similarity index 76% rename from src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/ToolResponse.java rename to src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/SingleToolResponse.java index bf3d2fd3..d472231b 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/ToolResponse.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/base/SingleToolResponse.java @@ -20,7 +20,7 @@ /** * Response wrapper for non-paginated tools (get_* tools). Separates errors from warnings like - * PaginatedResponse. + * PaginatedToolResponse. * * @param the type of data in the response * @param data the response data (null if not found or error) @@ -28,10 +28,11 @@ * @param warnings non-fatal warnings (e.g., applied defaults) * @param found true if the requested item was found, false if not found or error */ -public record ToolResponse(T data, List errors, List warnings, boolean found) { +public record SingleToolResponse( + T data, List errors, List warnings, boolean found) { /** Compact constructor ensures non-null, immutable error and warning lists. */ - public ToolResponse { + public SingleToolResponse { errors = errors != null ? List.copyOf(errors) : List.of(); warnings = warnings != null ? List.copyOf(warnings) : List.of(); } @@ -53,8 +54,8 @@ public boolean isSuccess() { * @param the data type * @return successful response */ - public static ToolResponse success(T data, List warnings) { - return new ToolResponse<>(data, List.of(), warnings, true); + public static SingleToolResponse success(T data, List warnings) { + return new SingleToolResponse<>(data, List.of(), warnings, true); } /** @@ -64,7 +65,7 @@ public static ToolResponse success(T data, List warnings) { * @param the data type * @return successful response */ - public static ToolResponse success(T data) { + public static SingleToolResponse success(T data) { return success(data, List.of()); } @@ -76,10 +77,10 @@ public static ToolResponse success(T data) { * @param the data type * @return not-found response with found=false */ - public static ToolResponse notFound(String message, List warnings) { + public static SingleToolResponse notFound(String message, List warnings) { var allWarnings = new ArrayList<>(warnings); allWarnings.add(message); - return new ToolResponse<>(null, List.of(), allWarnings, false); + return new SingleToolResponse<>(null, List.of(), allWarnings, false); } /** @@ -89,8 +90,8 @@ public static ToolResponse notFound(String message, List warnings * @param the data type * @return error response */ - public static ToolResponse error(String error) { - return new ToolResponse<>(null, List.of(error), List.of(), false); + public static SingleToolResponse error(String error) { + return new SingleToolResponse<>(null, List.of(error), List.of(), false); } /** @@ -100,7 +101,7 @@ public static ToolResponse error(String error) { * @param the data type * @return error response */ - public static ToolResponse error(List errors) { - return new ToolResponse<>(null, errors, List.of(), false); + public static SingleToolResponse error(List errors) { + return new SingleToolResponse<>(null, errors, List.of(), false); } } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/GetRouteCoverageTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/GetRouteCoverageTool.java index d758c494..0b2dbb99 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/GetRouteCoverageTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/GetRouteCoverageTool.java @@ -19,8 +19,8 @@ import com.contrast.labs.ai.mcp.contrast.sdkextension.data.routecoverage.Route; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.routecoverage.RouteCoverageBySessionIDAndMetadataRequestExtended; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.routecoverage.RouteCoverageResponse; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrast.labs.ai.mcp.contrast.tool.coverage.params.RouteCoverageParams; import com.contrastsecurity.models.RouteCoverageMetadataLabelValues; import java.util.Collections; @@ -38,7 +38,8 @@ @Service @RequiredArgsConstructor @Slf4j -public class GetRouteCoverageTool extends BaseGetTool { +public class GetRouteCoverageTool + extends BaseSingleTool { @Tool( name = "get_route_coverage", @@ -71,7 +72,7 @@ Filtering options (mutually exclusive): - search_applications: Find application IDs by name or tag - get_session_metadata: View available session metadata fields """) - public ToolResponse getRouteCoverage( + public SingleToolResponse getRouteCoverage( @ToolParam(description = "Application ID (use search_applications to find)") String appId, @ToolParam( description = diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/params/RouteCoverageParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/params/RouteCoverageParams.java index 059e136a..6186f47a 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/params/RouteCoverageParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/coverage/params/RouteCoverageParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.coverage.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; import org.springframework.util.StringUtils; @@ -31,7 +32,7 @@ * } * } */ -public class RouteCoverageParams extends ToolValidationContext { +public class RouteCoverageParams extends BaseToolParams { private String appId; private String sessionMetadataName; @@ -56,28 +57,28 @@ public static RouteCoverageParams of( String sessionMetadataValue, Boolean useLatestSession) { var params = new RouteCoverageParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(appId, "appId"); + ctx.require(appId, "appId"); // Validate paired metadata params - both or neither must be provided // Treat empty strings as null (no filter) boolean hasName = StringUtils.hasText(sessionMetadataName); boolean hasValue = StringUtils.hasText(sessionMetadataValue); - if (hasName && !hasValue) { - params.addError("sessionMetadataValue is required when sessionMetadataName is provided"); - } - if (hasValue && !hasName) { - params.addError("sessionMetadataName is required when sessionMetadataValue is provided"); - } + ctx.errorIf( + hasName && !hasValue, + "sessionMetadataValue is required when sessionMetadataName is provided"); + ctx.errorIf( + hasValue && !hasName, + "sessionMetadataName is required when sessionMetadataValue is provided"); // Warn if both useLatestSession and metadata params provided (mutually exclusive) - if (Boolean.TRUE.equals(useLatestSession) && hasName) { - params.addWarning( - "Both useLatestSession and sessionMetadataName provided - " - + "useLatestSession takes precedence and sessionMetadata filter will be ignored"); - } + ctx.warnIf( + Boolean.TRUE.equals(useLatestSession) && hasName, + "Both useLatestSession and sessionMetadataName provided - " + + "useLatestSession takes precedence and sessionMetadata filter will be ignored"); // Store values (empty strings normalized to null) params.appId = appId; @@ -85,6 +86,7 @@ public static RouteCoverageParams of( params.sessionMetadataValue = hasValue ? sessionMetadataValue : null; params.useLatestSession = useLatestSession; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastProjectTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastProjectTool.java index a9b31c4c..fd4bff56 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastProjectTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastProjectTool.java @@ -15,8 +15,8 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.sast; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrast.labs.ai.mcp.contrast.tool.sast.params.GetSastProjectParams; import com.contrastsecurity.sdk.scan.Project; import java.util.List; @@ -31,7 +31,7 @@ */ @Service @Slf4j -public class GetSastProjectTool extends BaseGetTool { +public class GetSastProjectTool extends BaseSingleTool { @Tool( name = "get_scan_project", @@ -56,7 +56,7 @@ public class GetSastProjectTool extends BaseGetTool getScanProject( + public SingleToolResponse getScanProject( @ToolParam(description = "Scan project name (case-sensitive, must match exactly)") String projectName) { return executePipeline(() -> GetSastProjectParams.of(projectName)); diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastResultsTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastResultsTool.java index 7191dcbf..ad362394 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastResultsTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/GetSastResultsTool.java @@ -15,8 +15,8 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.sast; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrast.labs.ai.mcp.contrast.tool.sast.params.GetSastResultsParams; import java.io.BufferedReader; import java.io.InputStreamReader; @@ -36,7 +36,7 @@ @Deprecated @Service @Slf4j -public class GetSastResultsTool extends BaseGetTool { +public class GetSastResultsTool extends BaseSingleTool { @Tool( name = "get_scan_results", @@ -62,7 +62,7 @@ public class GetSastResultsTool extends BaseGetTool getScanResults( + public SingleToolResponse getScanResults( @ToolParam(description = "Scan project name (case-sensitive, must match exactly)") String projectName) { return executePipeline(() -> GetSastResultsParams.of(projectName)); diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastProjectParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastProjectParams.java index 84a6f28b..0b416d46 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastProjectParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastProjectParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.sast.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * } * } */ -public class GetSastProjectParams extends ToolValidationContext { +public class GetSastProjectParams extends BaseToolParams { private String projectName; @@ -44,12 +45,13 @@ private GetSastProjectParams() {} */ public static GetSastProjectParams of(String projectName) { var params = new GetSastProjectParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(projectName, "projectName"); - + ctx.require(projectName, "projectName"); params.projectName = projectName; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastResultsParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastResultsParams.java index 69e79db8..d37f4c66 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastResultsParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sast/params/GetSastResultsParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.sast.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * } * } */ -public class GetSastResultsParams extends ToolValidationContext { +public class GetSastResultsParams extends BaseToolParams { private String projectName; @@ -44,12 +45,13 @@ private GetSastResultsParams() {} */ public static GetSastResultsParams of(String projectName) { var params = new GetSastResultsParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(projectName, "projectName"); - + ctx.require(projectName, "projectName"); params.projectName = projectName; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationLibrariesTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationLibrariesTool.java index 5378bb0a..6587825b 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationLibrariesTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationLibrariesTool.java @@ -18,8 +18,8 @@ import com.contrast.labs.ai.mcp.contrast.sdkextension.SDKExtension; import com.contrast.labs.ai.mcp.contrast.sdkextension.SDKHelper; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.LibraryExtended; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrast.labs.ai.mcp.contrast.tool.sca.params.ListApplicationLibrariesParams; import java.util.List; import lombok.extern.slf4j.Slf4j; @@ -37,7 +37,7 @@ @Service @Slf4j public class ListApplicationLibrariesTool - extends BaseGetTool> { + extends BaseSingleTool> { @Tool( name = "list_application_libraries", @@ -64,7 +64,7 @@ Use search_applications(name=...) to find the application ID from a name. - search_applications: Find application IDs by name, tag, or metadata - list_applications_by_cve: Find applications affected by a specific CVE """) - public ToolResponse> listApplicationLibraries( + public SingleToolResponse> listApplicationLibraries( @ToolParam(description = "Application ID (use search_applications to find)") String appId) { return executePipeline(() -> ListApplicationLibrariesParams.of(appId)); } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationsByCveTool.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationsByCveTool.java index e015f302..40301258 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationsByCveTool.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/ListApplicationsByCveTool.java @@ -21,8 +21,8 @@ import com.contrast.labs.ai.mcp.contrast.sdkextension.data.CveData; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.Library; import com.contrast.labs.ai.mcp.contrast.sdkextension.data.LibraryExtended; -import com.contrast.labs.ai.mcp.contrast.tool.base.BaseGetTool; -import com.contrast.labs.ai.mcp.contrast.tool.base.ToolResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseSingleTool; +import com.contrast.labs.ai.mcp.contrast.tool.base.SingleToolResponse; import com.contrast.labs.ai.mcp.contrast.tool.sca.params.ListApplicationsByCveParams; import java.util.Collections; import java.util.List; @@ -40,7 +40,8 @@ */ @Service @Slf4j -public class ListApplicationsByCveTool extends BaseGetTool { +public class ListApplicationsByCveTool + extends BaseSingleTool { @Tool( name = "list_applications_by_cve", @@ -65,7 +66,7 @@ Takes a CVE ID (e.g., CVE-2021-44228) and returns: - list_application_libraries: Get all libraries for a specific application - search_applications: Find applications by name, tag, or metadata """) - public ToolResponse listApplicationsByCve( + public SingleToolResponse listApplicationsByCve( @ToolParam(description = "CVE identifier (e.g., CVE-2021-44228)") String cveId) { return executePipeline(() -> ListApplicationsByCveParams.of(cveId)); } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationLibrariesParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationLibrariesParams.java index 26bc83fc..ff6be712 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationLibrariesParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationLibrariesParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.sca.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; /** @@ -29,7 +30,7 @@ * } * } */ -public class ListApplicationLibrariesParams extends ToolValidationContext { +public class ListApplicationLibrariesParams extends BaseToolParams { private String appId; @@ -44,11 +45,13 @@ private ListApplicationLibrariesParams() {} */ public static ListApplicationLibrariesParams of(String appId) { var params = new ListApplicationLibrariesParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(appId, "appId"); + ctx.require(appId, "appId"); params.appId = appId; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationsByCveParams.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationsByCveParams.java index 9caff10c..0dd19f26 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationsByCveParams.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/sca/params/ListApplicationsByCveParams.java @@ -15,6 +15,7 @@ */ package com.contrast.labs.ai.mcp.contrast.tool.sca.params; +import com.contrast.labs.ai.mcp.contrast.tool.base.BaseToolParams; import com.contrast.labs.ai.mcp.contrast.tool.validation.ToolValidationContext; import java.util.regex.Pattern; import org.springframework.util.StringUtils; @@ -31,7 +32,7 @@ * } * } */ -public class ListApplicationsByCveParams extends ToolValidationContext { +public class ListApplicationsByCveParams extends BaseToolParams { /** CVE ID format pattern: CVE-YYYY-NNNNN (4+ digit sequence number) */ private static final Pattern CVE_PATTERN = Pattern.compile("^CVE-\\d{4}-\\d{4,}$"); @@ -49,19 +50,22 @@ private ListApplicationsByCveParams() {} */ public static ListApplicationsByCveParams of(String cveId) { var params = new ListApplicationsByCveParams(); + var ctx = new ToolValidationContext(); // Validate required field - params.require(cveId, "cveId"); + ctx.require(cveId, "cveId"); // Validate CVE format if provided if (StringUtils.hasText(cveId) && !CVE_PATTERN.matcher(cveId).matches()) { - params.addError( + ctx.errorIf( + true, "cveId must be in CVE format (e.g., CVE-2021-44228). " + "Format: CVE-YYYY-NNNNN where YYYY is the year and NNNNN is a sequence number."); } params.cveId = cveId; + params.setValidationResult(ctx); return params; } diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/validation/ToolValidationContext.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/validation/ToolValidationContext.java index a9d1fe1d..284df274 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/validation/ToolValidationContext.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/tool/validation/ToolValidationContext.java @@ -209,6 +209,18 @@ public void warnIf(boolean condition, String message) { } } + /** + * Adds an error if the condition is true. + * + * @param condition the condition to check + * @param message the error message if condition is true + */ + public void errorIf(boolean condition, String message) { + if (condition) { + errors.add(message); + } + } + /** * Adds an error message. Protected for use by Spec classes and subclasses. * diff --git a/src/main/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationHandler.java b/src/main/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationHandler.java index 86a2acf5..8ad8db6d 100644 --- a/src/main/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationHandler.java +++ b/src/main/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationHandler.java @@ -16,7 +16,7 @@ package com.contrast.labs.ai.mcp.contrast.utils; import com.contrast.labs.ai.mcp.contrast.PaginationParams; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.PaginatedToolResponse; import java.util.ArrayList; import java.util.List; import org.springframework.stereotype.Component; @@ -41,7 +41,7 @@ public class PaginationHandler { * @param Type of items * @return PaginatedResponse with calculated hasMorePages and messages */ - public PaginatedResponse createPaginatedResponse( + public PaginatedToolResponse createPaginatedResponse( List items, PaginationParams params, Integer totalCount) { return createPaginatedResponse(items, params, totalCount, List.of()); } @@ -57,7 +57,7 @@ public PaginatedResponse createPaginatedResponse( * @param Type of items * @return PaginatedResponse with calculated hasMorePages and messages */ - public PaginatedResponse createPaginatedResponse( + public PaginatedToolResponse createPaginatedResponse( List items, PaginationParams params, Integer totalCount, List additionalWarnings) { boolean hasMorePages = calculateHasMorePages(params, totalCount, items.size()); var emptyResultWarning = buildEmptyResultMessage(items, params, totalCount); @@ -72,7 +72,7 @@ public PaginatedResponse createPaginatedResponse( warnings.add(emptyResultWarning); } - return PaginatedResponse.success( + return PaginatedToolResponse.success( items, params.page(), params.pageSize(), totalCount, hasMorePages, warnings, null); } diff --git a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseContrastToolTest.java b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseContrastToolTest.java new file mode 100644 index 00000000..6ffb89b7 --- /dev/null +++ b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseContrastToolTest.java @@ -0,0 +1,98 @@ +/* + * Copyright 2025 Contrast Security + * + * 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.contrast.labs.ai.mcp.contrast.tool.base; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +import com.contrast.labs.ai.mcp.contrast.config.ContrastConfig; +import com.contrastsecurity.sdk.ContrastSDK; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.springframework.test.util.ReflectionTestUtils; + +/** Unit tests for {@link BaseContrastTool}. */ +class BaseContrastToolTest { + + private TestableContrastTool tool; + private ContrastConfig config; + private ContrastSDK sdk; + + @BeforeEach + void setUp() { + tool = new TestableContrastTool(); + config = mock(); + sdk = mock(); + + when(config.getSDK()).thenReturn(sdk); + when(config.getOrgId()).thenReturn("test-org-123"); + + ReflectionTestUtils.setField(tool, "config", config); + } + + @Test + void getContrastSDK_should_return_sdk_from_config() { + var result = tool.getContrastSDK(); + + assertThat(result).isSameAs(sdk); + } + + @Test + void getOrgId_should_return_orgId_from_config() { + var result = tool.getOrgId(); + + assertThat(result).isEqualTo("test-org-123"); + } + + @ParameterizedTest + @CsvSource({ + "401, Authentication failed. Verify API credentials.", + "403, Access denied. User lacks permission for this resource.", + "404, Resource not found.", + "429, Rate limit exceeded. Retry later.", + "500, Contrast API error. Try again later.", + "502, Contrast API error. Try again later.", + "503, Contrast API error. Try again later.", + "418, API error (HTTP 418)" + }) + void mapHttpErrorCode_should_return_user_friendly_message(int code, String expectedMessage) { + var result = tool.mapHttpErrorCode(code); + + assertThat(result).isEqualTo(expectedMessage); + } + + /** Concrete implementation for testing abstract base class. */ + private static class TestableContrastTool extends BaseContrastTool { + // Expose protected methods for testing + @Override + public ContrastSDK getContrastSDK() { + return super.getContrastSDK(); + } + + @Override + public String getOrgId() { + return super.getOrgId(); + } + + @Override + public String mapHttpErrorCode(int code) { + return super.mapHttpErrorCode(code); + } + } +} diff --git a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseMcpToolTest.java b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BasePaginatedToolTest.java similarity index 98% rename from src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseMcpToolTest.java rename to src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BasePaginatedToolTest.java index 7c2887ad..59e76a8d 100644 --- a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseMcpToolTest.java +++ b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BasePaginatedToolTest.java @@ -28,7 +28,7 @@ import org.junit.jupiter.api.Test; import org.springframework.test.util.ReflectionTestUtils; -class BaseMcpToolTest { +class BasePaginatedToolTest { private TestSearchTool tool; private ContrastConfig config; @@ -265,8 +265,8 @@ void executePipeline_should_track_duration() { assertThat(result.durationMs()).isGreaterThanOrEqualTo(0); } - // Test implementation of BaseMcpTool - private static class TestSearchTool extends BaseMcpTool { + // Test implementation of BasePaginatedTool + private static class TestSearchTool extends BasePaginatedTool { private DoExecuteHandler handler; void setDoExecuteHandler(DoExecuteHandler handler) { diff --git a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseGetToolTest.java b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseSingleToolTest.java similarity index 98% rename from src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseGetToolTest.java rename to src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseSingleToolTest.java index 480465fe..5c62cce8 100644 --- a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseGetToolTest.java +++ b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/BaseSingleToolTest.java @@ -27,7 +27,7 @@ import org.junit.jupiter.api.Test; import org.springframework.test.util.ReflectionTestUtils; -class BaseGetToolTest { +class BaseSingleToolTest { private TestGetTool tool; private ContrastConfig config; @@ -189,8 +189,8 @@ void executePipeline_should_allow_doExecute_to_add_warnings() { assertThat(result.warnings()).contains("Partial data returned"); } - // Test implementation of BaseGetTool - private static class TestGetTool extends BaseGetTool { + // Test implementation of BaseSingleTool + private static class TestGetTool extends BaseSingleTool { private DoExecuteHandler handler; void setDoExecuteHandler(DoExecuteHandler handler) { diff --git a/src/test/java/com/contrast/labs/ai/mcp/contrast/data/PaginatedResponseTest.java b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/PaginatedToolResponseTest.java similarity index 78% rename from src/test/java/com/contrast/labs/ai/mcp/contrast/data/PaginatedResponseTest.java rename to src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/PaginatedToolResponseTest.java index a8675766..d679603e 100644 --- a/src/test/java/com/contrast/labs/ai/mcp/contrast/data/PaginatedResponseTest.java +++ b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/PaginatedToolResponseTest.java @@ -13,20 +13,21 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package com.contrast.labs.ai.mcp.contrast.data; +package com.contrast.labs.ai.mcp.contrast.tool.base; import static org.assertj.core.api.Assertions.assertThat; import java.util.List; import org.junit.jupiter.api.Test; -class PaginatedResponseTest { +class PaginatedToolResponseTest { // ========== success() factory method tests ========== @Test void success_should_createResponseWithEmptyErrors() { - var response = PaginatedResponse.success(List.of("item1"), 1, 50, 1, false, List.of(), 100L); + var response = + PaginatedToolResponse.success(List.of("item1"), 1, 50, 1, false, List.of(), 100L); assertThat(response.items()).containsExactly("item1"); assertThat(response.errors()).isEmpty(); @@ -38,7 +39,7 @@ void success_should_createResponseWithEmptyErrors() { @Test void success_should_includeWarnings() { var response = - PaginatedResponse.success( + PaginatedToolResponse.success( List.of("item1"), 1, 50, 1, false, List.of("Applied default status"), 100L); assertThat(response.items()).containsExactly("item1"); @@ -52,7 +53,7 @@ void success_should_includeWarnings() { @Test void validationError_should_createResponseWithErrors() { var response = - PaginatedResponse.validationError( + PaginatedToolResponse.validationError( 1, 50, List.of("Invalid severity: CRIT", "Invalid status: UNKNOWN")); assertThat(response.items()).isEmpty(); @@ -68,7 +69,7 @@ void validationError_should_createResponseWithErrors() { @Test void error_should_createSingleErrorResponse() { - var response = PaginatedResponse.error(2, 25, "Page 2 exceeds available pages"); + var response = PaginatedToolResponse.error(2, 25, "Page 2 exceeds available pages"); assertThat(response.items()).isEmpty(); assertThat(response.errors()).containsExactly("Page 2 exceeds available pages"); @@ -82,7 +83,7 @@ void error_should_createSingleErrorResponse() { @Test void empty_should_createEmptyResponseWithWarning() { - var response = PaginatedResponse.empty(1, 50, "No items found."); + var response = PaginatedToolResponse.empty(1, 50, "No items found."); assertThat(response.items()).isEmpty(); assertThat(response.errors()).isEmpty(); @@ -94,14 +95,15 @@ void empty_should_createEmptyResponseWithWarning() { @Test void isSuccess_should_returnFalseWhenErrorsPresent() { - var response = PaginatedResponse.error(1, 50, "Error occurred"); + var response = PaginatedToolResponse.error(1, 50, "Error occurred"); assertThat(response.isSuccess()).isFalse(); } @Test void isSuccess_should_returnTrueWhenNoErrors() { - var response = PaginatedResponse.success(List.of(), 1, 50, 0, false, List.of("warning"), null); + var response = + PaginatedToolResponse.success(List.of(), 1, 50, 0, false, List.of("warning"), null); assertThat(response.isSuccess()).isTrue(); } @@ -111,7 +113,7 @@ void isSuccess_should_returnTrueWhenNoErrors() { @Test @SuppressWarnings("deprecation") void message_deprecated_should_returnErrors() { - var response = PaginatedResponse.validationError(1, 50, List.of("Error 1", "Error 2")); + var response = PaginatedToolResponse.validationError(1, 50, List.of("Error 1", "Error 2")); assertThat(response.message()).isEqualTo("Error 1 Error 2"); } @@ -120,7 +122,7 @@ void message_deprecated_should_returnErrors() { @SuppressWarnings("deprecation") void message_deprecated_should_returnWarningsWhenNoErrors() { var response = - PaginatedResponse.success( + PaginatedToolResponse.success( List.of(), 1, 50, 0, false, List.of("Warning 1", "Warning 2"), null); assertThat(response.message()).isEqualTo("Warning 1 Warning 2"); @@ -129,7 +131,7 @@ void message_deprecated_should_returnWarningsWhenNoErrors() { @Test @SuppressWarnings("deprecation") void message_deprecated_should_returnNullWhenNoMessagesExist() { - var response = PaginatedResponse.success(List.of("item"), 1, 50, 1, false, List.of(), 100L); + var response = PaginatedToolResponse.success(List.of("item"), 1, 50, 1, false, List.of(), 100L); assertThat(response.message()).isNull(); } @@ -138,21 +140,22 @@ void message_deprecated_should_returnNullWhenNoMessagesExist() { @Test void compactConstructor_should_ensureNonNullLists_whenItemsNull() { - var response = new PaginatedResponse(null, 1, 50, 0, false, List.of(), List.of(), null); + var response = + new PaginatedToolResponse(null, 1, 50, 0, false, List.of(), List.of(), null); assertThat(response.items()).isNotNull().isEmpty(); } @Test void compactConstructor_should_ensureNonNullLists_whenErrorsNull() { - var response = new PaginatedResponse<>(List.of(), 1, 50, 0, false, null, List.of(), null); + var response = new PaginatedToolResponse<>(List.of(), 1, 50, 0, false, null, List.of(), null); assertThat(response.errors()).isNotNull().isEmpty(); } @Test void compactConstructor_should_ensureNonNullLists_whenWarningsNull() { - var response = new PaginatedResponse<>(List.of(), 1, 50, 0, false, List.of(), null, null); + var response = new PaginatedToolResponse<>(List.of(), 1, 50, 0, false, List.of(), null, null); assertThat(response.warnings()).isNotNull().isEmpty(); } @@ -163,7 +166,7 @@ void compactConstructor_should_makeListsImmutable() { mutableItems.add("item1"); var response = - new PaginatedResponse<>(mutableItems, 1, 50, 1, false, List.of(), List.of(), null); + new PaginatedToolResponse<>(mutableItems, 1, 50, 1, false, List.of(), List.of(), null); // Modify original list mutableItems.add("item2"); @@ -177,7 +180,7 @@ void compactConstructor_should_makeListsImmutable() { @Test void should_preservePaginationMetadata() { var response = - PaginatedResponse.success(List.of("a", "b", "c"), 3, 25, 100, true, List.of(), 150L); + PaginatedToolResponse.success(List.of("a", "b", "c"), 3, 25, 100, true, List.of(), 150L); assertThat(response.page()).isEqualTo(3); assertThat(response.pageSize()).isEqualTo(25); diff --git a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/ToolResponseTest.java b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/SingleToolResponseTest.java similarity index 78% rename from src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/ToolResponseTest.java rename to src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/SingleToolResponseTest.java index 2f474326..64db2f55 100644 --- a/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/ToolResponseTest.java +++ b/src/test/java/com/contrast/labs/ai/mcp/contrast/tool/base/SingleToolResponseTest.java @@ -22,13 +22,13 @@ import java.util.List; import org.junit.jupiter.api.Test; -class ToolResponseTest { +class SingleToolResponseTest { @Test void success_should_create_response_with_data_and_warnings() { var warnings = List.of("warning1", "warning2"); - var response = ToolResponse.success("data", warnings); + var response = SingleToolResponse.success("data", warnings); assertThat(response.data()).isEqualTo("data"); assertThat(response.warnings()).containsExactly("warning1", "warning2"); @@ -39,7 +39,7 @@ void success_should_create_response_with_data_and_warnings() { @Test void success_should_create_response_with_data_only() { - var response = ToolResponse.success("data"); + var response = SingleToolResponse.success("data"); assertThat(response.data()).isEqualTo("data"); assertThat(response.warnings()).isEmpty(); @@ -52,7 +52,7 @@ void success_should_create_response_with_data_only() { void notFound_should_create_response_with_message_in_warnings() { var existingWarnings = List.of("existing"); - var response = ToolResponse.notFound("Item not found", existingWarnings); + var response = SingleToolResponse.notFound("Item not found", existingWarnings); assertThat(response.data()).isNull(); assertThat(response.warnings()).containsExactly("existing", "Item not found"); @@ -63,7 +63,7 @@ void notFound_should_create_response_with_message_in_warnings() { @Test void notFound_should_work_with_empty_warnings() { - var response = ToolResponse.notFound("Not found", List.of()); + var response = SingleToolResponse.notFound("Not found", List.of()); assertThat(response.warnings()).containsExactly("Not found"); assertThat(response.found()).isFalse(); @@ -71,7 +71,7 @@ void notFound_should_work_with_empty_warnings() { @Test void error_should_create_response_with_single_error() { - var response = ToolResponse.error("Something went wrong"); + var response = SingleToolResponse.error("Something went wrong"); assertThat(response.data()).isNull(); assertThat(response.errors()).containsExactly("Something went wrong"); @@ -84,7 +84,7 @@ void error_should_create_response_with_single_error() { void error_should_create_response_with_multiple_errors() { var errors = List.of("error1", "error2"); - var response = ToolResponse.error(errors); + var response = SingleToolResponse.error(errors); assertThat(response.data()).isNull(); assertThat(response.errors()).containsExactly("error1", "error2"); @@ -95,7 +95,7 @@ void error_should_create_response_with_multiple_errors() { @Test void constructor_should_handle_null_errors() { - var response = new ToolResponse<>("data", null, List.of("warn"), true); + var response = new SingleToolResponse<>("data", null, List.of("warn"), true); assertThat(response.errors()).isEmpty(); assertThat(response.warnings()).containsExactly("warn"); @@ -103,7 +103,7 @@ void constructor_should_handle_null_errors() { @Test void constructor_should_handle_null_warnings() { - var response = new ToolResponse<>("data", List.of("err"), null, true); + var response = new SingleToolResponse<>("data", List.of("err"), null, true); assertThat(response.errors()).containsExactly("err"); assertThat(response.warnings()).isEmpty(); @@ -111,7 +111,7 @@ void constructor_should_handle_null_warnings() { @Test void errors_should_be_immutable() { - var response = ToolResponse.error("error"); + var response = SingleToolResponse.error("error"); assertThatThrownBy(() -> response.errors().add("new error")) .isInstanceOf(UnsupportedOperationException.class); @@ -119,7 +119,7 @@ void errors_should_be_immutable() { @Test void warnings_should_be_immutable() { - var response = ToolResponse.success("data", List.of("warning")); + var response = SingleToolResponse.success("data", List.of("warning")); assertThatThrownBy(() -> response.warnings().add("new warning")) .isInstanceOf(UnsupportedOperationException.class); @@ -128,7 +128,7 @@ void warnings_should_be_immutable() { @Test void errors_should_be_defensive_copy() { var mutableErrors = new ArrayList<>(List.of("error1")); - var response = new ToolResponse<>("data", mutableErrors, List.of(), true); + var response = new SingleToolResponse<>("data", mutableErrors, List.of(), true); mutableErrors.add("error2"); @@ -138,7 +138,7 @@ void errors_should_be_defensive_copy() { @Test void warnings_should_be_defensive_copy() { var mutableWarnings = new ArrayList<>(List.of("warning1")); - var response = new ToolResponse<>("data", List.of(), mutableWarnings, true); + var response = new SingleToolResponse<>("data", List.of(), mutableWarnings, true); mutableWarnings.add("warning2"); @@ -147,22 +147,22 @@ void warnings_should_be_defensive_copy() { @Test void isSuccess_should_return_true_when_no_errors() { - var response = new ToolResponse<>("data", List.of(), List.of("warning"), true); + var response = new SingleToolResponse<>("data", List.of(), List.of("warning"), true); assertThat(response.isSuccess()).isTrue(); } @Test void isSuccess_should_return_false_when_errors_exist() { - var response = new ToolResponse<>("data", List.of("error"), List.of(), true); + var response = new SingleToolResponse<>("data", List.of("error"), List.of(), true); assertThat(response.isSuccess()).isFalse(); } @Test void found_should_distinguish_not_found_from_error() { - var notFoundResponse = ToolResponse.notFound("Not found", List.of()); - var errorResponse = ToolResponse.error("Error occurred"); + var notFoundResponse = SingleToolResponse.notFound("Not found", List.of()); + var errorResponse = SingleToolResponse.error("Error occurred"); // Both have found=false, but different semantics assertThat(notFoundResponse.found()).isFalse(); diff --git a/src/test/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationTestHelper.java b/src/test/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationTestHelper.java index 67e7beca..afdb4c96 100644 --- a/src/test/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationTestHelper.java +++ b/src/test/java/com/contrast/labs/ai/mcp/contrast/utils/PaginationTestHelper.java @@ -17,7 +17,7 @@ import static org.junit.jupiter.api.Assertions.*; -import com.contrast.labs.ai.mcp.contrast.data.PaginatedResponse; +import com.contrast.labs.ai.mcp.contrast.tool.base.PaginatedToolResponse; /** * Reusable test utilities for validating paginated responses. Provides assertion methods to verify @@ -27,7 +27,7 @@ public class PaginationTestHelper { /** Asserts that a paginated response has valid structure and values */ public static void assertValidPaginatedResponse( - PaginatedResponse response, int expectedPage, int expectedPageSize) { + PaginatedToolResponse response, int expectedPage, int expectedPageSize) { assertNotNull(response, "Response should not be null"); assertNotNull(response.items(), "Items list should not be null"); assertEquals(expectedPage, response.page(), "Page mismatch"); @@ -52,19 +52,19 @@ public static void assertValidPaginatedResponse( } /** Asserts that response contains a validation message */ - public static void assertHasValidationMessage(PaginatedResponse response) { + public static void assertHasValidationMessage(PaginatedToolResponse response) { assertNotNull(response.message(), "Expected validation message"); assertFalse(response.message().isEmpty(), "Message should not be empty"); } /** Asserts that response represents an empty page */ - public static void assertEmptyPage(PaginatedResponse response) { + public static void assertEmptyPage(PaginatedToolResponse response) { assertTrue(response.items().isEmpty(), "Expected empty items"); assertFalse(response.hasMorePages(), "Empty page should have no more pages"); } /** Asserts that hasMorePages logic is correct */ - public static void assertHasMorePagesLogic(PaginatedResponse response) { + public static void assertHasMorePagesLogic(PaginatedToolResponse response) { if (response.totalItems() != null) { // When totalItems available, hasMorePages should be accurate int itemsFetched = response.page() * response.pageSize(); @@ -78,14 +78,14 @@ public static void assertHasMorePagesLogic(PaginatedResponse response) { } /** Asserts that response has no validation message (clean response) */ - public static void assertNoValidationMessage(PaginatedResponse response) { + public static void assertNoValidationMessage(PaginatedToolResponse response) { assertTrue( response.message() == null || response.message().isEmpty(), "Expected no validation message"); } /** Asserts that the response contains the expected number of items */ - public static void assertItemCount(PaginatedResponse response, int expectedCount) { + public static void assertItemCount(PaginatedToolResponse response, int expectedCount) { assertEquals( expectedCount, response.items().size(),