Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -34,7 +34,7 @@
@Service
@RequiredArgsConstructor
@Slf4j
public class GetProtectRulesTool extends BaseGetTool<GetProtectRulesParams, ProtectData> {
public class GetProtectRulesTool extends BaseSingleTool<GetProtectRulesParams, ProtectData> {

@Tool(
name = "get_protect_rules",
Expand All @@ -59,7 +59,7 @@ public class GetProtectRulesTool extends BaseGetTool<GetProtectRulesParams, Prot
- search_applications: Find application IDs by name or tag
- search_attacks: Search for attacks across the organization
""")
public ToolResponse<ProtectData> getProtectRules(
public SingleToolResponse<ProtectData> getProtectRules(
@ToolParam(description = "Application ID (use search_applications to find)") String appId) {
return executePipeline(() -> GetProtectRulesParams.of(appId));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -34,7 +34,7 @@
*/
@Service
@RequiredArgsConstructor
public class SearchAttacksTool extends BaseMcpTool<AttackFilterParams, AttackSummary> {
public class SearchAttacksTool extends BasePaginatedTool<AttackFilterParams, AttackSummary> {

@Tool(
name = "search_attacks",
Expand Down Expand Up @@ -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<AttackSummary> searchAttacks(
public PaginatedToolResponse<AttackSummary> searchAttacks(
@ToolParam(
description =
"Quick filter for attack categorization. Valid: ALL (no filter), ACTIVE (ongoing"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -34,7 +35,7 @@
* var filterBody = params.toAttacksFilterBody();
* }</pre>
*/
public class AttackFilterParams extends ToolValidationContext {
public class AttackFilterParams extends BaseToolParams {

/** Valid quickFilter values for validation (from AttackQuickFilterType). */
public static final Set<String> VALID_QUICK_FILTERS =
Expand Down Expand Up @@ -78,31 +79,31 @@ 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")
.get();

// 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 {
Expand All @@ -119,14 +120,16 @@ 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'",
sort));
}
}

params.setValidationResult(ctx);
return params;
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand All @@ -29,7 +30,7 @@
* }
* }</pre>
*/
public class GetProtectRulesParams extends ToolValidationContext {
public class GetProtectRulesParams extends BaseToolParams {

private String appId;

Expand All @@ -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;
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -30,7 +30,7 @@
*/
@Service
public class GetSessionMetadataTool
extends BaseGetTool<GetSessionMetadataParams, MetadataFilterResponse> {
extends BaseSingleTool<GetSessionMetadataParams, MetadataFilterResponse> {

@Tool(
name = "get_session_metadata",
Expand All @@ -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<MetadataFilterResponse> getSessionMetadata(
public SingleToolResponse<MetadataFilterResponse> getSessionMetadata(
@ToolParam(description = "Application ID (use search_applications to find)") String appId) {
return executePipeline(() -> GetSessionMetadataParams.of(appId));
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -35,7 +35,8 @@
* with BaseMcpTool and in-memory filtering.
*/
@Service
public class SearchApplicationsTool extends BaseMcpTool<ApplicationFilterParams, ApplicationData> {
public class SearchApplicationsTool
extends BasePaginatedTool<ApplicationFilterParams, ApplicationData> {

@Tool(
name = "search_applications",
Expand All @@ -56,7 +57,7 @@ public class SearchApplicationsTool extends BaseMcpTool<ApplicationFilterParams,
- get_session_metadata: Get session metadata for an application
- search_vulnerabilities: Search vulnerabilities across applications
""")
public PaginatedResponse<ApplicationData> searchApplications(
public PaginatedToolResponse<ApplicationData> 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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -33,7 +34,7 @@
* boolean matches = params.matches(application);
* }</pre>
*/
public class ApplicationFilterParams extends ToolValidationContext {
public class ApplicationFilterParams extends BaseToolParams {

private String name;
private String tag;
Expand All @@ -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;
Expand All @@ -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;
}

Expand Down
Loading