feat: multi validation errors handling for MCP tools (#15)

* ref: convert float64 to int64 instead of int to prevent precision loss and ensure consistent behavior across platforms

* feat: collect validation errors for tools

* chore: improve error handling and code formatting

* chore: revert int to int64 conversion

* ref: implement fluent validation pattern for razorpay tools

* fix: lint errors

* ref: improve validation error handling pattern across API tools

* fix: define the error handler func

Author: ChiragChiranjib

.cursor/rules/new-tool-from-docs.mdc

@@ -59,10 +59,10 @@ Upon receiving this rule invocation:
 
 Before the implementation use the documentation URL provided to figure out the request contract, required parameters, descriptions of the parameters, and the response contract.
 
-Now follow the detailed implementation guide in [pkg/razorpay/README.md](../pkg/razorpay/README.md) for creating tools and start making code changes.
+Now follow the detailed implementation guide in [pkg/razorpay/README.md](mdc:../pkg/razorpay/README.md) for creating tools and start making code changes.
 
 Other guidelines:
-1. [Razorpay Go SDK Constants](https://github.com/razorpay/razorpay-go/blob/master/constants/url.go) - Use these constants for specifying the api endpoints while writing the tests.
+1. [Razorpay Go SDK Constants](mdc:https:/github.com/razorpay/razorpay-go/blob/master/constants/url.go) - Use these constants for specifying the api endpoints while writing the tests.
 2. Use the payload and response from the docs provided to write the positive test case for the tool.
 
 STYLE:
@@ -72,7 +72,7 @@ IMPORTANT: You **MUST** ALWAYS go through the Post Implementation steps once the
 
 ## Implementation References
 
-For detailed code patterns and examples, refer to the following sections in the [pkg/razorpay/README.md](../pkg/razorpay/README.md):
+For detailed code patterns and examples, refer to the following sections in the [pkg/razorpay/README.md](mdc:../pkg/razorpay/README.md):
 
 - **Tool Structure**: See the "Tool Structure" section for the function template
 - **Parameter Definition**: See the "Parameter Definition" section for defining parameters
@@ -160,7 +160,7 @@ If any checklist items remain unchecked, complete them before proceeding. The im
 Your tests MUST include:
 - Positive test case with all parameters
 - Negative test case for EACH required parameter
-- Negative test case for validation failures (e.g., wrong types)
+- Negative test case for multiple validation failures (e.g., wrong types)
 - Any edge cases specific to this tool
 
 ## ⚠️ Required Verification Steps ⚠️
@@ -192,16 +192,29 @@ Contains all Razorpay API tool implementations, including:
 - Parameter validation functions
 - Request/response handling
 
-### `pkg/razorpay/server.go` - Core Utilities
-
-**Path:** `pkg/razorpay/server.go`
-
-Contains essential utility functions used by all tools:
-- `RequiredParam[T]` - Type-safe required parameter extraction
-- `OptionalParam[T]` - Type-safe optional parameter extraction
-- `RequiredInt` - Integer parameter extraction
-- `OptionalInt` - Optional integer parameter extraction
-- `HandleValidationError` - Common validation error handling
+### `pkg/razorpay/tools_params.go` - Fluent Validator
+
+**Path:** `pkg/razorpay/tools_params.go`
+
+Contains the fluent validator implementation for parameter validation:
+- `Validator` - Type that provides a fluent interface for validation
+- `NewValidator` - Creates a new validator for a request
+- `HasErrors` - Checks if validation errors exist
+- `HandleErrorsIfAny` - Formats all errors into a tool result
+- `ValidateAndAddRequiredString` - Validates required string parameters
+- `ValidateAndAddOptionalString` - Validates optional string parameters
+- `ValidateAndAddRequiredInt` - Validates required integer parameters
+- `ValidateAndAddOptionalInt` - Validates optional integer parameters
+- `ValidateAndAddRequiredFloat` - Validates required float parameters
+- `ValidateAndAddOptionalFloat` - Validates optional float parameters
+- `ValidateAndAddRequiredBool` - Validates required boolean parameters
+- `ValidateAndAddOptionalBool` - Validates optional boolean parameters
+- `ValidateAndAddRequiredMap` - Validates required map parameters
+- `ValidateAndAddOptionalMap` - Validates optional map parameters
+- `ValidateAndAddRequiredArray` - Validates required array parameters
+- `ValidateAndAddOptionalArray` - Validates optional array parameters
+- `ValidateAndAddPagination` - Validates and adds pagination parameters
+- `ValidateAndAddExpand` - Validates and adds expand parameters
 
 ### `pkg/razorpay/test_helpers.go` - Testing Utilities
 

pkg/razorpay/README.md

@@ -79,32 +79,31 @@ Available parameter types:
 
 ### Parameter Validation
 
-Inside the handler function, use the helper functions for fetching the parameters and also enforcing the mandatory parameters:
+Inside the handler function, use the fluent validator pattern for parameter validation. This provides cleaner, more readable code through method chaining:
 
 ```go
-// Required parameters
-id, err := RequiredParam[string](r, "id")
-if result, err := HandleValidationError(err); result != nil {
-    return result, err
-}
+// Create a new validator
+v := NewValidator(&r)
 
-// Optional parameters
-description, err := OptionalParam[string](r, "description")
-if result, err := HandleValidationError(err); result != nil {
-    return result, err
-}
+// Create a map for API request parameters
+payload := make(map[string]interface{})
 
-// Required integers
-amount, err := RequiredInt(r, "amount")
-if result, err := HandleValidationError(err); result != nil {
-    return result, err
-}
+// Validate and add parameters to the payload with method chaining
+v.ValidateAndAddRequiredString(payload, "id").
+  ValidateAndAddOptionalString(payload, "description").
+  ValidateAndAddRequiredInt(payload, "amount").
+  ValidateAndAddOptionalInt(payload, "limit")
+
+// Validate and add common parameters
+v.ValidateAndAddPagination(payload).
+  ValidateAndAddExpand(payload)
 
-// Optional integers
-limit, err := OptionalInt(r, "limit")
-if result, err := HandleValidationError(err); result != nil {
-    return result, err
+// Check for validation errors
+if result, err := validator.HandleErrorsIfAny(); result != nil {
+	return result, err
 }
+
+// Proceed with API call using validated parameters in payload
 ```
 
 ### Example: GET Endpoint
@@ -127,11 +126,18 @@ func FetchResource(
         ctx context.Context,
         r mcpgo.CallToolRequest,
     ) (*mcpgo.ToolResult, error) {
-        id, err := RequiredParam[string](r, "id")
-        if result, err := HandleValidationError(err); result != nil {
-            return result, err
-        }
+        // Create validator and a payload map
+        payload := make(map[string]interface{})
+        v := NewValidator(&r).
+            ValidateAndAddRequiredString(payload, "id")
+        
+        // Check for validation errors
+        if result, err := validator.HandleErrorsIfAny(); result != nil {
+			return result, err
+		}
 
+        // Extract validated ID and make API call
+        id := payload["id"].(string)
         resource, err := client.Resource.Fetch(id, nil, nil)
         if err != nil {
             return mcpgo.NewToolResultError(
@@ -179,34 +185,19 @@ func CreateResource(
         ctx context.Context,
         r mcpgo.CallToolRequest,
     ) (*mcpgo.ToolResult, error) {
-        // Required parameters
-        amount, err := RequiredInt(r, "amount")
-        if result, err := HandleValidationError(err); result != nil {
-            return result, err
-        }
+        // Create payload map and validator
+        data := make(map[string]interface{})
+        v := NewValidator(&r).
+            ValidateAndAddRequiredInt(data, "amount").
+            ValidateAndAddRequiredString(data, "currency").
+            ValidateAndAddOptionalString(data, "description")
 
-        currency, err := RequiredParam[string](r, "currency")
-        if result, err := HandleValidationError(err); result != nil {
-            return result, err
-        }
+        // Check for validation errors
+        if result, err := validator.HandleErrorsIfAny(); result != nil {
+			return result, err
+		}
 
-        // Create request payload
-        data := map[string]interface{}{
-            "amount": amount,
-            "currency": currency,
-        }
-
-        // Optional parameters
-        description, err := OptionalParam[string](r, "description")
-        if result, err := HandleValidationError(err); result != nil {
-            return result, err
-        }
-        
-        if description != "" {
-            data["description"] = description
-        }
-
-        // Call the API
+        // Call the API with validated data
         resource, err := client.Resource.Create(data, nil)
         if err != nil {
             return mcpgo.NewToolResultError(
@@ -346,6 +337,16 @@ func Test_ToolName(t *testing.T) {
             ExpectError:    true,
             ExpectedErrMsg: "missing required parameter: param1",
         },
+        {
+            Name: "multiple validation errors",
+            Request: map[string]interface{}{
+                // Missing required parameters and/or including invalid types
+                "optional_param": "invalid_type", // Wrong type for a parameter
+            },
+            MockHttpClient: nil, // No HTTP client needed for validation errors
+            ExpectError:    true,
+            ExpectedErrMsg: "Validation errors:\n- missing required parameter: param1\n- invalid parameter type: optional_param",
+        },
         // Additional test cases for other scenarios
     }
 
@@ -390,7 +391,10 @@ After adding a new tool, Update the "Available Tools" section in the README.md i
 
 2. **Error Handling**: Always provide clear error messages
 
-3. **Validation**: Always validate required parameters
+3. **Validation**: Always validate required parameters and collect all validation errors before returning using fluent validator pattern.
+   - Use the `NewValidator` to create a validator
+   - Chain validation methods (`ValidateAndAddRequiredString`, etc.)
+   - Return formatted errors with `HandleErrorsIfAny()`
 
 4. **Documentation**: Describe all the parameters clearly for the LLMs to understand.