fix: resolve SplitInBatches output confusion for AI assistants (#97)

## Problem AI assistants were consistently connecting SplitInBatches node outputs backwards because: - Output index 0 = "done" (runs after loop completes) - Output index 1 = "loop" (processes items inside loop) This counterintuitive ordering caused incorrect workflow connections. ## Solution Enhanced the n8n-mcp system to expose and clarify output information: ### Database & Schema - Added `outputs` and `output_names` columns to nodes table - Updated NodeRepository to store/retrieve output information ### Node Parsing - Enhanced NodeParser to extract outputs and outputNames from nodes - Properly handles versioned nodes like SplitInBatchesV3 ### MCP Server - Modified getNodeInfo to return detailed output descriptions - Added connection guidance for each output - Special handling for loop nodes (SplitInBatches, IF, Switch) ### Documentation - Enhanced DocsMapper to inject critical output guidance - Added warnings about counterintuitive output ordering - Provides correct connection patterns for loop nodes ### Workflow Validation - Added validateSplitInBatchesConnection method - Detects reversed connections and provides specific errors - Added checkForLoopBack with depth limit to prevent stack overflow - Smart heuristics to identify likely connection mistakes ## Testing - Created comprehensive test suite (81 tests) - Unit tests for all modified components - Edge case handling for malformed data - Performance testing with large workflows ## Impact AI assistants will now: - See explicit output indices and names (e.g., "Output 0: done") - Receive clear connection guidance - Get validation errors when connections are reversed - Have enhanced documentation explaining the correct pattern Fixes #97 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-07 15:58:07 +02:00
parent a4e711a4e8
commit f508d9873b
12 changed files with 2895 additions and 12 deletions
--- a/src/database/node-repository.ts
+++ b/src/database/node-repository.ts
@@ -22,8 +22,9 @@ export class NodeRepository {
        node_type, package_name, display_name, description,
        category, development_style, is_ai_tool, is_trigger,
        is_webhook, is_versioned, version, documentation,
-        properties_schema, operations, credentials_required
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        properties_schema, operations, credentials_required,
+        outputs, output_names
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
    `);
    
    stmt.run(
@@ -41,7 +42,9 @@ export class NodeRepository {
      node.documentation || null,
      JSON.stringify(node.properties, null, 2),
      JSON.stringify(node.operations, null, 2),
-      JSON.stringify(node.credentials, null, 2)
+      JSON.stringify(node.credentials, null, 2),
+      node.outputs ? JSON.stringify(node.outputs, null, 2) : null,
+      node.outputNames ? JSON.stringify(node.outputNames, null, 2) : null
    );
  }
  
@@ -70,7 +73,9 @@ export class NodeRepository {
      properties: this.safeJsonParse(row.properties_schema, []),
      operations: this.safeJsonParse(row.operations, []),
      credentials: this.safeJsonParse(row.credentials_required, []),
-      hasDocumentation: !!row.documentation
+      hasDocumentation: !!row.documentation,
+      outputs: row.outputs ? this.safeJsonParse(row.outputs, null) : null,
+      outputNames: row.output_names ? this.safeJsonParse(row.output_names, null) : null
    };
  }
  
@@ -238,7 +243,9 @@ export class NodeRepository {
      properties: this.safeJsonParse(row.properties_schema, []),
      operations: this.safeJsonParse(row.operations, []),
      credentials: this.safeJsonParse(row.credentials_required, []),
-      hasDocumentation: !!row.documentation
+      hasDocumentation: !!row.documentation,
+      outputs: row.outputs ? this.safeJsonParse(row.outputs, null) : null,
+      outputNames: row.output_names ? this.safeJsonParse(row.output_names, null) : null
    };
  }
 }
--- a/src/database/schema.sql
+++ b/src/database/schema.sql
@@ -15,6 +15,8 @@ CREATE TABLE IF NOT EXISTS nodes (
  properties_schema TEXT,
  operations TEXT,
  credentials_required TEXT,
+  outputs TEXT, -- JSON array of output definitions
+  output_names TEXT, -- JSON array of output names
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );

--- a/src/mappers/docs-mapper.ts
+++ b/src/mappers/docs-mapper.ts
@@ -50,8 +50,12 @@ export class DocsMapper {
    for (const relativePath of possiblePaths) {
      try {
        const fullPath = path.join(this.docsPath, relativePath);
-        const content = await fs.readFile(fullPath, 'utf-8');
+        let content = await fs.readFile(fullPath, 'utf-8');
        console.log(`  ✓ Found docs at: ${relativePath}`);
+        
+        // Inject special guidance for loop nodes
+        content = this.enhanceLoopNodeDocumentation(nodeType, content);
+        
        return content;
      } catch (error) {
        // File doesn't exist, try next
@@ -62,4 +66,56 @@ export class DocsMapper {
    console.log(`  ✗ No docs found for ${nodeName}`);
    return null;
  }
+
+  private enhanceLoopNodeDocumentation(nodeType: string, content: string): string {
+    // Add critical output index information for SplitInBatches
+    if (nodeType.includes('splitInBatches')) {
+      const outputGuidance = `
+
+## CRITICAL OUTPUT CONNECTION INFORMATION
+
+**⚠️ OUTPUT INDICES ARE COUNTERINTUITIVE ⚠️**
+
+The SplitInBatches node has TWO outputs with specific indices:
+- **Output 0 (index 0) = "done"**: Receives final processed data when loop completes
+- **Output 1 (index 1) = "loop"**: Receives current batch data during iteration
+
+### Correct Connection Pattern:
+1. Connect nodes that PROCESS items inside the loop to **Output 1 ("loop")**
+2. Connect nodes that run AFTER the loop completes to **Output 0 ("done")**
+3. The last processing node in the loop must connect back to the SplitInBatches node
+
+### Common Mistake:
+AI assistants often connect these backwards because the logical flow (loop first, then done) doesn't match the technical indices (done=0, loop=1).
+
+`;
+      // Insert after the main description
+      const insertPoint = content.indexOf('## When to use');
+      if (insertPoint > -1) {
+        content = content.slice(0, insertPoint) + outputGuidance + content.slice(insertPoint);
+      } else {
+        // Append if no good insertion point found
+        content = outputGuidance + '\n' + content;
+      }
+    }
+
+    // Add guidance for IF node
+    if (nodeType.includes('.if')) {
+      const outputGuidance = `
+
+## Output Connection Information
+
+The IF node has TWO outputs:
+- **Output 0 (index 0) = "true"**: Items that match the condition
+- **Output 1 (index 1) = "false"**: Items that do not match the condition
+
+`;
+      const insertPoint = content.indexOf('## Node parameters');
+      if (insertPoint > -1) {
+        content = content.slice(0, insertPoint) + outputGuidance + content.slice(insertPoint);
+      }
+    }
+
+    return content;
+  }
 }
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -834,10 +834,26 @@ export class N8NDocumentationMCPServer {
        null
    };
    
+    // Process outputs to provide clear mapping
+    let outputs = undefined;
+    if (node.outputNames && node.outputNames.length > 0) {
+      outputs = node.outputNames.map((name: string, index: number) => {
+        // Special handling for loop nodes like SplitInBatches
+        const descriptions = this.getOutputDescriptions(node.nodeType, name, index);
+        return {
+          index,
+          name,
+          description: descriptions.description,
+          connectionGuidance: descriptions.connectionGuidance
+        };
+      });
+    }
+    
    return {
      ...node,
      workflowNodeType: getWorkflowNodeType(node.package, node.nodeType),
-      aiToolCapabilities
+      aiToolCapabilities,
+      outputs
    };
  }

@@ -1937,6 +1953,52 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
    };
  }
  
+  private getOutputDescriptions(nodeType: string, outputName: string, index: number): { description: string, connectionGuidance: string } {
+    // Special handling for loop nodes
+    if (nodeType === 'nodes-base.splitInBatches') {
+      if (outputName === 'done' && index === 0) {
+        return {
+          description: 'Final processed data after all iterations complete',
+          connectionGuidance: 'Connect to nodes that should run AFTER the loop completes'
+        };
+      } else if (outputName === 'loop' && index === 1) {
+        return {
+          description: 'Current batch data for this iteration',
+          connectionGuidance: 'Connect to nodes that process items INSIDE the loop (and connect their output back to this node)'
+        };
+      }
+    }
+    
+    // Special handling for IF node
+    if (nodeType === 'nodes-base.if') {
+      if (outputName === 'true' && index === 0) {
+        return {
+          description: 'Items that match the condition',
+          connectionGuidance: 'Connect to nodes that handle the TRUE case'
+        };
+      } else if (outputName === 'false' && index === 1) {
+        return {
+          description: 'Items that do not match the condition',
+          connectionGuidance: 'Connect to nodes that handle the FALSE case'
+        };
+      }
+    }
+    
+    // Special handling for Switch node
+    if (nodeType === 'nodes-base.switch') {
+      return {
+        description: `Output ${index}: ${outputName || 'Route ' + index}`,
+        connectionGuidance: `Connect to nodes for the "${outputName || 'route ' + index}" case`
+      };
+    }
+    
+    // Default handling
+    return {
+      description: outputName || `Output ${index}`,
+      connectionGuidance: `Connect to downstream nodes`
+    };
+  }
+
  private getCommonAIToolUseCases(nodeType: string): string[] {
    const useCaseMap: Record<string, string[]> = {
      'nodes-base.slack': [
--- a/src/parsers/node-parser.ts
+++ b/src/parsers/node-parser.ts
@@ -16,14 +16,19 @@ export interface ParsedNode {
  isVersioned: boolean;
  packageName: string;
  documentation?: string;
+  outputs?: any[];
+  outputNames?: string[];
 }

 export class NodeParser {
  private propertyExtractor = new PropertyExtractor();
+  private currentNodeClass: any = null;
  
  parse(nodeClass: any, packageName: string): ParsedNode {
+    this.currentNodeClass = nodeClass;
    // Get base description (handles versioned nodes)
    const description = this.getNodeDescription(nodeClass);
+    const outputInfo = this.extractOutputs(description);
    
    return {
      style: this.detectStyle(nodeClass),
@@ -39,7 +44,9 @@ export class NodeParser {
      operations: this.propertyExtractor.extractOperations(nodeClass),
      version: this.extractVersion(nodeClass),
      isVersioned: this.detectVersioned(nodeClass),
-      packageName: packageName
+      packageName: packageName,
+      outputs: outputInfo.outputs,
+      outputNames: outputInfo.outputNames
    };
  }
  
@@ -222,4 +229,51 @@ export class NodeParser {
    
    return false;
  }
+
+  private extractOutputs(description: any): { outputs?: any[], outputNames?: string[] } {
+    const result: { outputs?: any[], outputNames?: string[] } = {};
+    
+    // First check the base description
+    if (description.outputs) {
+      result.outputs = Array.isArray(description.outputs) ? description.outputs : [description.outputs];
+    }
+    
+    if (description.outputNames) {
+      result.outputNames = Array.isArray(description.outputNames) ? description.outputNames : [description.outputNames];
+    }
+    
+    // If no outputs found and this is a versioned node, check the latest version
+    if (!result.outputs && !result.outputNames) {
+      const nodeClass = this.currentNodeClass; // We'll need to track this
+      if (nodeClass) {
+        try {
+          const instance = new nodeClass();
+          if (instance.nodeVersions) {
+            // Get the latest version
+            const versions = Object.keys(instance.nodeVersions).map(Number);
+            const latestVersion = Math.max(...versions);
+            const versionedDescription = instance.nodeVersions[latestVersion]?.description;
+            
+            if (versionedDescription) {
+              if (versionedDescription.outputs) {
+                result.outputs = Array.isArray(versionedDescription.outputs) 
+                  ? versionedDescription.outputs 
+                  : [versionedDescription.outputs];
+              }
+              
+              if (versionedDescription.outputNames) {
+                result.outputNames = Array.isArray(versionedDescription.outputNames) 
+                  ? versionedDescription.outputNames 
+                  : [versionedDescription.outputNames];
+              }
+            }
+          }
+        } catch (e) {
+          // Ignore errors from instantiating node
+        }
+      }
+    }
+    
+    return result;
+  }
 }
--- a/src/services/workflow-validator.ts
+++ b/src/services/workflow-validator.ts
@@ -627,6 +627,9 @@ export class WorkflowValidator {
    result: WorkflowValidationResult,
    outputType: 'main' | 'error' | 'ai_tool'
  ): void {
+    // Get source node for special validation
+    const sourceNode = nodeMap.get(sourceName);
+    
    outputs.forEach((outputConnections, outputIndex) => {
      if (!outputConnections) return;
      
@@ -641,12 +644,26 @@ export class WorkflowValidator {
          return;
        }

+        // Special validation for SplitInBatches node
+        if (sourceNode && sourceNode.type === 'n8n-nodes-base.splitInBatches') {
+          this.validateSplitInBatchesConnection(
+            sourceNode,
+            outputIndex,
+            connection,
+            nodeMap,
+            result
+          );
+        }
+
        // Check for self-referencing connections
        if (connection.node === sourceName) {
-          result.warnings.push({
-            type: 'warning',
-            message: `Node "${sourceName}" has a self-referencing connection. This can cause infinite loops.`
-          });
+          // This is only a warning for non-loop nodes
+          if (sourceNode && sourceNode.type !== 'n8n-nodes-base.splitInBatches') {
+            result.warnings.push({
+              type: 'warning',
+              message: `Node "${sourceName}" has a self-referencing connection. This can cause infinite loops.`
+            });
+          }
        }

        const targetNode = nodeMap.get(connection.node);
@@ -1470,4 +1487,133 @@ export class WorkflowValidator {
      );
    }
  }
+
+  /**
+   * Validate SplitInBatches node connections for common mistakes
+   */
+  private validateSplitInBatchesConnection(
+    sourceNode: WorkflowNode,
+    outputIndex: number,
+    connection: { node: string; type: string; index: number },
+    nodeMap: Map<string, WorkflowNode>,
+    result: WorkflowValidationResult
+  ): void {
+    const targetNode = nodeMap.get(connection.node);
+    if (!targetNode) return;
+
+    // Check if connections appear to be reversed
+    // Output 0 = "done", Output 1 = "loop"
+    
+    if (outputIndex === 0) {
+      // This is the "done" output (index 0)
+      // Check if target looks like it should be in the loop
+      const targetType = targetNode.type.toLowerCase();
+      const targetName = targetNode.name.toLowerCase();
+      
+      // Common patterns that suggest this node should be inside the loop
+      if (targetType.includes('function') || 
+          targetType.includes('code') ||
+          targetType.includes('item') ||
+          targetName.includes('process') ||
+          targetName.includes('transform') ||
+          targetName.includes('handle')) {
+        
+        // Check if this node connects back to the SplitInBatches
+        const hasLoopBack = this.checkForLoopBack(targetNode.name, sourceNode.name, nodeMap);
+        
+        if (hasLoopBack) {
+          result.errors.push({
+            type: 'error',
+            nodeId: sourceNode.id,
+            nodeName: sourceNode.name,
+            message: `SplitInBatches outputs appear reversed! Node "${targetNode.name}" is connected to output 0 ("done") but connects back to the loop. It should be connected to output 1 ("loop") instead. Remember: Output 0 = "done" (post-loop), Output 1 = "loop" (inside loop).`
+          });
+        } else {
+          result.warnings.push({
+            type: 'warning',
+            nodeId: sourceNode.id,
+            nodeName: sourceNode.name,
+            message: `Node "${targetNode.name}" is connected to the "done" output (index 0) but appears to be a processing node. Consider connecting it to the "loop" output (index 1) if it should process items inside the loop.`
+          });
+        }
+      }
+    } else if (outputIndex === 1) {
+      // This is the "loop" output (index 1)
+      // Check if target looks like it should be after the loop
+      const targetType = targetNode.type.toLowerCase();
+      const targetName = targetNode.name.toLowerCase();
+      
+      // Common patterns that suggest this node should be after the loop
+      if (targetType.includes('aggregate') ||
+          targetType.includes('merge') ||
+          targetType.includes('email') ||
+          targetType.includes('slack') ||
+          targetName.includes('final') ||
+          targetName.includes('complete') ||
+          targetName.includes('summary') ||
+          targetName.includes('report')) {
+        
+        result.warnings.push({
+          type: 'warning',
+          nodeId: sourceNode.id,
+          nodeName: sourceNode.name,
+          message: `Node "${targetNode.name}" is connected to the "loop" output (index 1) but appears to be a post-processing node. Consider connecting it to the "done" output (index 0) if it should run after all iterations complete.`
+        });
+      }
+      
+      // Check if loop output doesn't eventually connect back
+      const hasLoopBack = this.checkForLoopBack(targetNode.name, sourceNode.name, nodeMap);
+      if (!hasLoopBack) {
+        result.warnings.push({
+          type: 'warning',
+          nodeId: sourceNode.id,
+          nodeName: sourceNode.name,
+          message: `The "loop" output connects to "${targetNode.name}" but doesn't connect back to the SplitInBatches node. The last node in the loop should connect back to complete the iteration.`
+        });
+      }
+    }
+  }
+
+  /**
+   * Check if a node eventually connects back to a target node
+   */
+  private checkForLoopBack(
+    startNode: string,
+    targetNode: string,
+    nodeMap: Map<string, WorkflowNode>,
+    visited: Set<string> = new Set(),
+    maxDepth: number = 50
+  ): boolean {
+    if (maxDepth <= 0) return false; // Prevent stack overflow
+    if (visited.has(startNode)) return false;
+    visited.add(startNode);
+
+    const node = nodeMap.get(startNode);
+    if (!node) return false;
+
+    // Check direct connections from this node
+    const connections = (node as any).connections;
+    if (!connections) return false;
+
+    for (const [outputType, outputs] of Object.entries(connections)) {
+      if (!Array.isArray(outputs)) continue;
+      
+      for (const outputConnections of outputs) {
+        if (!Array.isArray(outputConnections)) continue;
+        
+        for (const conn of outputConnections) {
+          if (conn.node === targetNode) {
+            return true;
+          }
+          
+          // Recursively check connected nodes
+          if (this.checkForLoopBack(conn.node, targetNode, nodeMap, visited, maxDepth - 1)) {
+            return true;
+          }
+        }
+      }
+    }
+
+    return false;
+  }
 }