mcp-n8n-builder

Instructions

Implementation Reference

• src/tool-handlers/workflow-tools.ts:152-227 (handler)

  The main handler function that executes the create_workflow tool: validates input schema, checks for valid n8n nodes, creates the workflow via API client, optionally activates it, and returns success/error messages.

  export async function handle_create_workflow(
  	api_client: N8nApiClient,
  	args: any,
  ) {
  	try {
  		// Validate input with Zod
  		const parsed_input = CreateWorkflowInputSchema.parse(args);
  
  		// Validate that all nodes exist in n8n
  		const invalid_nodes =
  			await node_validator.validate_workflow_nodes(
  				parsed_input.workflow.nodes,
  			);
  
  		if (invalid_nodes.length > 0) {
  			// Format error message with suggestions
  			const error_messages = invalid_nodes.map((node) => {
  				const suggestion = node.suggestion
  					? `Did you mean '${node.suggestion}'?`
  					: 'No similar nodes found.';
  				return `- '${node.node_type}': Not a valid n8n node. ${suggestion}`;
  			});
  
  			// Include relevant sections from the workflow composition guide
  			const node_categories =
  				WORKFLOW_COMPOSITION_GUIDE.node_categories;
  
  			return {
  				content: [
  					{
  						type: 'text',
  						text:
  							`Workflow contains invalid node types:\n${error_messages.join(
  								'\n',
  							)}\n\nPlease correct these node types before creating the workflow.\n\n` +
  							`Here are the available node categories for reference:\n${node_categories}`,
  					},
  				],
  				isError: true,
  			};
  		}
  
  		const workflow = await api_client.create_workflow(
  			parsed_input.workflow,
  			parsed_input.activate,
  		);
  
  		const activation_status = workflow.active
  			? 'activated'
  			: 'created (not activated)';
  
  		return {
  			content: [
  				{
  					type: 'text',
  					text: `Successfully ${activation_status} workflow "${workflow.name}" (ID: ${workflow.id})`,
  				},
  			],
  		};
  	} catch (error: any) {
  		if (error.name === 'ZodError') {
  			return handle_validation_error(error);
  		}
  		return {
  			content: [
  				{
  					type: 'text',
  					text: `Error creating workflow: ${
  						error.message || String(error)
  					}`,
  				},
  			],
  			isError: true,
  		};
  	}
  }

• src/schemas.ts:49-52 (schema)

  Zod schema defining the input structure for the create_workflow tool, including the workflow object and optional activate flag.

  export const CreateWorkflowInputSchema = z.object({
  	workflow: WorkflowSchema,
  	activate: z.boolean().optional(),
  });

• src/tool-handlers/index.ts:87-133 (registration)

  Tool registration in the list of tools returned by ListToolsRequestSchema, defining name, description, and inputSchema for create_workflow.

  {
  	name: 'create_workflow',
  	description:
  		'Creates a new workflow in n8n with specified nodes and connections. Note that only workflows with automatic trigger nodes (schedule, webhook, etc.) can be activated - workflows with only manual triggers cannot be activated. Returns the created workflow with its assigned ID.',
  	inputSchema: {
  		type: 'object',
  		properties: {
  			workflow: {
  				type: 'object',
  				description:
  					'Complete workflow structure including nodes, connections, and settings',
  				properties: {
  					name: {
  						type: 'string',
  						description:
  							'Name of the workflow - use descriptive names for easier identification',
  					},
  					nodes: {
  						type: 'array',
  						description:
  							'Array of workflow nodes (triggers, actions, etc.)',
  						items: {
  							type: 'object',
  						},
  					},
  					connections: {
  						type: 'object',
  						description:
  							'Connections between nodes defining the workflow execution path',
  					},
  					settings: {
  						type: 'object',
  						description:
  							'Workflow settings like error handling, execution timeout, etc.',
  					},
  				},
  				required: ['name', 'nodes', 'connections'],
  			},
  			activate: {
  				type: 'boolean',
  				description:
  					'Whether to activate the workflow after creation (only works for workflows with automatic triggers)',
  			},
  		},
  		required: ['workflow'],
  	},
  },

• src/tool-handlers/index.ts:322-323 (registration)

  Dispatch in the CallToolRequestSchema switch statement that routes create_workflow calls to the handle_create_workflow function.

  case 'create_workflow':
  	return await handle_create_workflow(api_client, args);

• src/n8n-api-client.ts:118-134 (helper)

  API client method that performs the actual HTTP POST to create the workflow in n8n and optionally activates it.

  async create_workflow(
  	workflow: any,
  	activate?: boolean,
  ): Promise<any> {
  	const response = await this.request<any>(
  		'POST',
  		'/workflows',
  		workflow,
  	);
  
  	if (activate && response.id) {
  		await this.activate_workflow(response.id);
  		response.active = true;
  	}
  
  	return response;
  }