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'] } };