Repository navigation
AIML-303 PR 1: Add ValidationHelper and ExceptionHandler utilities - #40
Closed
ChrisEdwards wants to merge 3 commits into
Closed
ChrisEdwards wants to merge 3 commits into
ChrisEdwards wants to merge 3 commits into
Conversation
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.
This was referenced Dec 12, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 warningsenumSet()- parses comma-separated enum values (e.g., severities)stringList()- validates against allowed values with defaultsrequireWith()- cross-field validation (X requires Y)mutuallyExclusive()- parameter conflict detectionExceptionHandler
Categorized exception handling:
toPaginatedResponse()- for paginated tool errorstoToolResponse()- for non-paginated tool errorsHow
ValidationHelper Pattern
ExceptionHandler Pattern
Design Decisions
errors()andwarnings()return unmodifiable listsStep-by-Step Walkthrough
ValidationHelper.java (331 lines)
builder()factory creates new instancethisfor chainingisValid()checks if any errors existExceptionHandler.java (143 lines)
ValidationHelperTest.java (408 lines)
ExceptionHandlerTest.java (207 lines)
Testing
Files Changed
What's Next
This PR is the foundation for AIML-303. Subsequent PRs will: