n8n-MCP

Instructions

Implementation Reference

• src/mcp/handlers-n8n-manager.ts:739-869 (handler)

  The core handler function for the 'n8n_update_full_workflow' tool. Parses input, creates optional backup, validates workflow structure, performs the update via N8nApiClient.updateWorkflow, tracks telemetry, and returns success/error response.

  export async function handleUpdateWorkflow(
    args: unknown,
    repository: NodeRepository,
    context?: InstanceContext
  ): Promise<McpToolResponse> {
    const startTime = Date.now();
    const sessionId = `mutation_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
    let workflowBefore: any = null;
    let userIntent = 'Full workflow update';
  
    try {
      const client = ensureApiConfigured(context);
      const input = updateWorkflowSchema.parse(args);
      const { id, createBackup, intent, ...updateData } = input;
      userIntent = intent || 'Full workflow update';
  
      // If nodes/connections are being updated, validate the structure
      if (updateData.nodes || updateData.connections) {
        // Always fetch current workflow for validation (need all fields like name)
        const current = await client.getWorkflow(id);
        workflowBefore = JSON.parse(JSON.stringify(current));
  
        // Create backup before modifying workflow (default: true)
        if (createBackup !== false) {
          try {
            const versioningService = new WorkflowVersioningService(repository, client);
            const backupResult = await versioningService.createBackup(id, current, {
              trigger: 'full_update'
            });
  
            logger.info('Workflow backup created', {
              workflowId: id,
              versionId: backupResult.versionId,
              versionNumber: backupResult.versionNumber,
              pruned: backupResult.pruned
            });
          } catch (error: any) {
            logger.warn('Failed to create workflow backup', {
              workflowId: id,
              error: error.message
            });
            // Continue with update even if backup fails (non-blocking)
          }
        }
  
        const fullWorkflow = {
          ...current,
          ...updateData
        };
  
        // Validate workflow structure (n8n API expects FULL form: n8n-nodes-base.*)
        const errors = validateWorkflowStructure(fullWorkflow);
        if (errors.length > 0) {
          return {
            success: false,
            error: 'Workflow validation failed',
            details: { errors }
          };
        }
      }
  
      // Update workflow
      const workflow = await client.updateWorkflow(id, updateData);
  
      // Track successful mutation
      if (workflowBefore) {
        trackWorkflowMutationForFullUpdate({
          sessionId,
          toolName: 'n8n_update_full_workflow',
          userIntent,
          operations: [], // Full update doesn't use diff operations
          workflowBefore,
          workflowAfter: workflow,
          mutationSuccess: true,
          durationMs: Date.now() - startTime,
        }).catch(err => {
          logger.warn('Failed to track mutation telemetry:', err);
        });
      }
  
      return {
        success: true,
        data: {
          id: workflow.id,
          name: workflow.name,
          active: workflow.active,
          nodeCount: workflow.nodes?.length || 0
        },
        message: `Workflow "${workflow.name}" updated successfully. Use n8n_get_workflow with mode 'structure' to verify current state.`
      };
    } catch (error) {
      // Track failed mutation
      if (workflowBefore) {
        trackWorkflowMutationForFullUpdate({
          sessionId,
          toolName: 'n8n_update_full_workflow',
          userIntent,
          operations: [],
          workflowBefore,
          workflowAfter: workflowBefore, // No change since it failed
          mutationSuccess: false,
          mutationError: error instanceof Error ? error.message : 'Unknown error',
          durationMs: Date.now() - startTime,
        }).catch(err => {
          logger.warn('Failed to track mutation telemetry for failed operation:', err);
        });
      }
  
      if (error instanceof z.ZodError) {
        return {
          success: false,
          error: 'Invalid input',
          details: { errors: error.errors }
        };
      }
  
      if (error instanceof N8nApiError) {
        return {
          success: false,
          error: getUserFriendlyErrorMessage(error),
          code: error.code,
          details: error.details as Record<string, unknown> | undefined
        };
      }
  
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error occurred'
      };
    }
  }

• src/mcp/tools-n8n-manager.ts:91-123 (schema)

  The tool definition including name, description, and inputSchema for registration in the MCP server.

  {
    name: 'n8n_update_full_workflow',
    description: `Full workflow update. Requires complete nodes[] and connections{}. For incremental use n8n_update_partial_workflow.`,
    inputSchema: {
      type: 'object',
      properties: {
        id: { 
          type: 'string', 
          description: 'Workflow ID to update' 
        },
        name: { 
          type: 'string', 
          description: 'New workflow name' 
        },
        nodes: { 
          type: 'array', 
          description: 'Complete array of workflow nodes (required if modifying workflow structure)',
          items: {
            type: 'object',
            additionalProperties: true
          }
        },
        connections: { 
          type: 'object', 
          description: 'Complete connections object (required if modifying workflow structure)' 
        },
        settings: { 
          type: 'object', 
          description: 'Workflow settings to update' 
        }
      },
      required: ['id']
    }

• src/mcp/tool-docs/workflow_management/n8n-update-full-workflow.ts:1-59 (schema)

  Tool documentation providing detailed usage, examples, best practices, and related tools for n8n_update_full_workflow.

  import { ToolDocumentation } from '../types';
  
  export const n8nUpdateFullWorkflowDoc: ToolDocumentation = {
    name: 'n8n_update_full_workflow',
    category: 'workflow_management',
    essentials: {
      description: 'Full workflow update. Requires complete nodes[] and connections{}. For incremental use n8n_update_partial_workflow.',
      keyParameters: ['id', 'nodes', 'connections'],
      example: 'n8n_update_full_workflow({id: "wf_123", nodes: [...], connections: {...}})',
      performance: 'Network-dependent',
      tips: [
        'Include intent parameter in every call - helps to return better responses',
        'Must provide complete workflow',
        'Use update_partial for small changes',
        'Validate before updating'
      ]
    },
    full: {
      description: 'Performs a complete workflow update by replacing the entire workflow definition. Requires providing the complete nodes array and connections object, even for small changes. This is a full replacement operation - any nodes or connections not included will be removed.',
      parameters: {
        id: { type: 'string', required: true, description: 'Workflow ID to update' },
        name: { type: 'string', description: 'New workflow name (optional)' },
        nodes: { type: 'array', description: 'Complete array of workflow nodes (required if modifying structure)' },
        connections: { type: 'object', description: 'Complete connections object (required if modifying structure)' },
        settings: { type: 'object', description: 'Workflow settings to update (timezone, error handling, etc.)' },
        intent: { type: 'string', description: 'Intent of the change - helps to return better response. Include in every tool call. Example: "Migrate workflow to new node versions".' }
      },
      returns: 'Minimal summary (id, name, active, nodeCount) for token efficiency. Use n8n_get_workflow with mode "structure" to verify current state if needed.',
      examples: [
        'n8n_update_full_workflow({id: "abc", intent: "Rename workflow for clarity", name: "New Name"}) - Rename with intent',
        'n8n_update_full_workflow({id: "abc", name: "New Name"}) - Rename only',
        'n8n_update_full_workflow({id: "xyz", intent: "Add error handling nodes", nodes: [...], connections: {...}}) - Full structure update',
        'const wf = n8n_get_workflow({id}); wf.nodes.push(newNode); n8n_update_full_workflow({...wf, intent: "Add data processing node"}); // Add node'
      ],
      useCases: [
        'Major workflow restructuring',
        'Bulk node updates',
        'Workflow imports/cloning',
        'Complete workflow replacement',
        'Settings changes'
      ],
      performance: 'Network-dependent - typically 200-500ms. Larger workflows take longer. Consider update_partial for better performance.',
      bestPractices: [
        'Always include intent parameter - it helps provide better responses',
        'Get workflow first, modify, then update',
        'Validate with validate_workflow before updating',
        'Use update_partial for small changes',
        'Test updates in non-production first'
      ],
      pitfalls: [
        'Requires N8N_API_URL and N8N_API_KEY configured',
        'Must include ALL nodes/connections',
        'Missing nodes will be deleted',
        'Can break active workflows',
        'No partial updates - use update_partial instead'
      ],
      relatedTools: ['n8n_get_workflow', 'n8n_update_partial_workflow', 'validate_workflow', 'n8n_create_workflow']
    }
  };