Skip to content

AIML-303 PR 1: Add ValidationHelper and ExceptionHandler utilities - #40

Closed
ChrisEdwards wants to merge 3 commits into
mainfrom
AIML-303-pr1-validation-helper
Closed

ChrisEdwards wants to merge 3 commits into
mainfrom
AIML-303-pr1-validation-helper

Conversation

@ChrisEdwards

Copy link
Copy Markdown
Collaborator

Why

Current MCP tool validation and error handling is scattered and inconsistent across services. Each tool validates parameters differently (or not at all), and exception handling is ad-hoc. This makes the codebase harder to maintain and leads to inconsistent user experiences.

This is PR 1 of the AIML-303 architecture standardization effort, establishing the foundational utilities that subsequent PRs will use.

What

Introduces two core utility classes (~200 lines total) that standardize validation and error handling:

ValidationHelper

Fluent builder for parameter validation with:

  • pagination() - validates page/pageSize with clamping (1-100) and warnings
  • enumSet() - parses comma-separated enum values (e.g., severities)
  • stringList() - validates against allowed values with defaults
  • requireWith() - cross-field validation (X requires Y)
  • mutuallyExclusive() - parameter conflict detection

ExceptionHandler

Categorized exception handling:

  • toPaginatedResponse() - for paginated tool errors
  • toToolResponse() - for non-paginated tool errors
  • Categories: auth failures, not found, rate limits, network errors, internal errors

How

ValidationHelper Pattern

var v = ValidationHelper.builder()
    .pagination(page, pageSize)
    .enumSet(severities, RuleSeverity.class, "severities", s -> this.severities = s)
    .requireWith(sessionValue, "sessionMetadataValue", sessionName, "sessionMetadataName");

if (!v.isValid()) {
  return PaginatedResponse.errors(v.page(), v.pageSize(), v.errors());
}

ExceptionHandler Pattern

} catch (Exception e) {
  return ExceptionHandler.toPaginatedResponse(e, page, pageSize);
}

Design Decisions

  • Composition over inheritance - utilities are standalone, not base classes
  • Immutable results - errors() and warnings() return unmodifiable lists
  • Leverages existing code - uses FilterHelper for parsing, SDK exception types
  • Thread-safe - new instance per validation, no shared state

Step-by-Step Walkthrough

  1. ValidationHelper.java (331 lines)

    • Static builder() factory creates new instance
    • Each validation method returns this for chaining
    • Errors/warnings accumulated in lists
    • isValid() checks if any errors exist
  2. ExceptionHandler.java (143 lines)

    • Static methods for exception categorization
    • Pattern matching on exception types
    • Rate limit detection via message content
    • ERROR logging for network failures (blocks all MCP functionality)
  3. ValidationHelperTest.java (408 lines)

    • 40 tests covering all validation methods
    • Edge cases: null, empty, whitespace, boundaries
    • Cross-field validation scenarios
  4. ExceptionHandlerTest.java (207 lines)

    • 8 tests covering all exception categories
    • Both paginated and non-paginated responses

Testing

  • Unit tests: 346 tests pass (0 failures)
  • New tests: 48 tests for ValidationHelper and ExceptionHandler
  • Coverage: All public methods tested with edge cases

Files Changed

File Lines Purpose
ValidationHelper.java +331 Fluent validation builder
ExceptionHandler.java +143 Categorized error handling
ValidationHelperTest.java +408 Validation tests
ExceptionHandlerTest.java +207 Exception handling tests
Total +1089

What's Next

This PR is the foundation for AIML-303. Subsequent PRs will:

  • PR 2: Update PaginatedResponse and create ToolResponse (mcp-fs3f)
  • PR 3: Create base patterns for tool implementation
  • PR 4: Apply patterns to search_vulnerabilities as reference implementation

Introduce core utility classes for standardizing MCP tool validation
and error handling as part of AIML-303 architecture improvements.

ValidationHelper: Fluent builder for parameter validation
- pagination() for page/pageSize with clamping and warnings
- enumSet() for RuleSeverity/ServerEnvironment parsing
- stringList() for status validation with allowed values
- requireWith() and mutuallyExclusive() for cross-field validation

ExceptionHandler: Categorized exception handling
- Authentication errors (UnauthorizedException)
- Resource not found (ResourceNotFoundException)
- Rate limiting (detected from message patterns)
- Network errors (IOException)
- Internal errors (with logging)

Includes comprehensive unit tests (44 tests total).
Add missing toToolResponse(Exception) method for non-paginated tools.
Returns "Error: " prefixed message using existing categorization logic.

Includes 4 new unit tests covering all exception categories.
Network errors block all MCP tool functionality and require
immediate attention, warranting ERROR level logging.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant