n8n-mcp/tests/integration/fixes/agent-3-mcp-error-brief.md

Agent 3: MCP Error Handling Fix Brief

Assignment

Fix 16 failing tests related to MCP protocol error handling and validation.

Files to Fix

• tests/integration/mcp-protocol/error-handling.test.ts (16 tests)

Specific Failures to Address

1. Invalid Params Handling (3 retries)

FAIL: should handle invalid params
Expected: error message to match /missing|required|nodeType/i
Actual: 'MCP error -32603: MCP error -32603: C...'

2. Invalid Category Filter (2 retries)

FAIL: should handle invalid category filter
Test is not properly validating category parameter

3. Empty Search Query (3 retries)

FAIL: should handle empty search query
Expected: error message to contain 'query'
Actual: 'Should have thrown an error' (no error thrown)

4. Malformed Workflow Structure (3 retries)

FAIL: should handle malformed workflow structure
Expected: error to contain 'nodes'
Actual: No error thrown, or wrong error message
Error in logs: TypeError: workflow.nodes is not iterable

5. Circular Workflow References (2 retries)

Test implementation missing or incorrect

6. Non-existent Documentation Topics (2 retries)

Documentation tool not returning expected errors

7. Large Node Info Requests (2 retries)

Performance/memory issues with large payloads

8. Large Workflow Validation (2 retries)

Timeout or memory issues

9. Workflow with Many Nodes (2 retries)

Performance degradation not handled

10. Empty Responses (2 retries)

Edge case handling failure

11. Special Characters in Parameters (2 retries)

Unicode/special character validation issues

12. Unicode in Parameters (2 retries)

Unicode handling failures

13. Null and Undefined Handling (2 retries)

Null/undefined parameter validation

14. Error Message Quality (3 retries)

Expected: error to match /not found|invalid|missing/
Actual: 'should have thrown an error'

15. Missing Required Parameters (2 retries)

Parameter validation not working correctly

Root Causes

1. Validation Logic: MCP server not properly validating input parameters
2. Error Propagation: Errors caught but not properly formatted/returned
3. Type Checking: Missing or incorrect type validation
4. Error Messages: Generic errors instead of specific validation messages

Recommended Fixes

1. Enhance Parameter Validation

// In mcp/server.ts or relevant handler
async function validateToolParams(tool: string, params: any): Promise<void> {
  switch (tool) {
    case 'get_node_info':
      if (!params.nodeType) {
        throw new Error('Missing required parameter: nodeType');
      }
      if (typeof params.nodeType !== 'string') {
        throw new Error('Parameter nodeType must be a string');
      }
      break;
      
    case 'search_nodes':
      if (params.query !== undefined && params.query === '') {
        throw new Error('Parameter query cannot be empty');
      }
      break;
      
    case 'list_nodes':
      if (params.category && !['trigger', 'transform', 'output', 'input'].includes(params.category)) {
        throw new Error(`Invalid category: ${params.category}. Must be one of: trigger, transform, output, input`);
      }
      break;
  }
}

2. Fix Workflow Structure Validation

// In workflow validator
function validateWorkflowStructure(workflow: any): void {
  if (!workflow || typeof workflow !== 'object') {
    throw new Error('Workflow must be an object');
  }
  
  if (!Array.isArray(workflow.nodes)) {
    throw new Error('Workflow must have a nodes array');
  }
  
  if (!workflow.connections || typeof workflow.connections !== 'object') {
    throw new Error('Workflow must have a connections object');
  }
  
  // Check for circular references
  const visited = new Set<string>();
  const recursionStack = new Set<string>();
  
  for (const node of workflow.nodes) {
    if (hasCircularReference(node.id, workflow.connections, visited, recursionStack)) {
      throw new Error(`Circular reference detected starting from node: ${node.id}`);
    }
  }
}

3. Improve Error Response Format

// In MCP error handler
function formatMCPError(error: any, code: number = -32603): MCPError {
  let message = 'Internal error';
  
  if (error instanceof Error) {
    message = error.message;
  } else if (typeof error === 'string') {
    message = error;
  }
  
  // Ensure specific error messages
  if (message.includes('Missing required parameter')) {
    code = -32602; // Invalid params
  }
  
  return {
    code,
    message,
    data: process.env.NODE_ENV === 'test' ? { 
      originalError: error.toString() 
    } : undefined
  };
}

4. Handle Large Payloads

// Add payload size validation
function validatePayloadSize(data: any, maxSize: number = 10 * 1024 * 1024): void {
  const size = JSON.stringify(data).length;
  if (size > maxSize) {
    throw new Error(`Payload too large: ${size} bytes (max: ${maxSize})`);
  }
}

// In large workflow handler
async function handleLargeWorkflow(workflow: any): Promise<any> {
  // Validate size first
  validatePayloadSize(workflow);
  
  // Process in chunks if needed
  const nodeChunks = chunkArray(workflow.nodes, 100);
  const results = [];
  
  for (const chunk of nodeChunks) {
    const partialWorkflow = { ...workflow, nodes: chunk };
    const result = await validateWorkflow(partialWorkflow);
    results.push(result);
  }
  
  return mergeValidationResults(results);
}

5. Unicode and Special Character Handling

// Sanitize and validate unicode input
function validateUnicodeInput(input: any): void {
  if (typeof input === 'string') {
    // Check for control characters
    if (/[\x00-\x1F\x7F]/.test(input)) {
      throw new Error('Control characters not allowed in input');
    }
    
    // Validate UTF-8
    try {
      // This will throw if invalid UTF-8
      Buffer.from(input, 'utf8').toString('utf8');
    } catch {
      throw new Error('Invalid UTF-8 encoding in input');
    }
  } else if (typeof input === 'object' && input !== null) {
    // Recursively validate object properties
    for (const [key, value] of Object.entries(input)) {
      validateUnicodeInput(key);
      validateUnicodeInput(value);
    }
  }
}

6. Null/Undefined Handling

// Strict null/undefined validation
function validateNotNullish(params: any, paramName: string): void {
  if (params[paramName] === null) {
    throw new Error(`Parameter ${paramName} cannot be null`);
  }
  if (params[paramName] === undefined) {
    throw new Error(`Missing required parameter: ${paramName}`);
  }
}

Testing Strategy

1. Add validation at MCP entry points
2. Ensure errors bubble up correctly
3. Test each error scenario in isolation
4. Verify error messages are helpful

Dependencies

• Depends on Agent 2 (MSW) for proper mock setup
• May affect Agent 6 (Session) error handling

Success Metrics

• All 16 error handling tests pass
• Clear, specific error messages
• Proper error codes returned
• Large payloads handled gracefully
• Unicode/special characters validated

Progress Tracking

Create /tests/integration/fixes/agent-3-progress.md and update after each fix:

# Agent 3 Progress

## Fixed Tests
- [ ] should handle invalid params
- [ ] should handle invalid category filter  
- [ ] should handle empty search query
- [ ] should handle malformed workflow structure
- [ ] should handle circular workflow references
- [ ] should handle non-existent documentation topics
- [ ] should handle large node info requests
- [ ] should handle large workflow validation
- [ ] should handle workflow with many nodes
- [ ] should handle empty responses gracefully
- [ ] should handle special characters in parameters
- [ ] should handle unicode in parameters
- [ ] should handle null and undefined gracefully
- [ ] should provide helpful error messages
- [ ] should indicate missing required parameters
- [ ] (identify 16th test)

## Blockers
- None yet

## Notes
- [Document validation rules added]
- [Note any error format changes]