n8n-nodes-composite

"Lord of the nodes, one node to rule them all"

A powerful n8n community node that enables you to create reusable, parameterized tools that can execute complex multi-step workflows. Perfect for building custom AI tools, modular workflows, and reusable business logic.

🚀 Features

• AI Tool Creation: Build custom tools that AI agents can discover and use
• Parameterized Workflows: Define typed parameters (string, number, boolean, object, array)
• Dual Output System: Send data to sub-workflows and receive processed results
• Pass-through Support: Optionally preserve original input data
• Error Handling: Configurable error handling with metadata
• Type Safety: Built-in parameter validation and type conversion
• Tool Metadata: Automatic execution tracking and timestamps

📦 Installation

npm install @ashleymcdonald/n8n-nodes-composite

🎯 Use Cases

AI Agent Tools

Create custom tools that AI agents can discover and execute:

• Data processors: Transform, validate, or enrich data
• API orchestrators: Chain multiple API calls with custom logic
• Business rule engines: Implement complex business logic as reusable tools

Workflow Modularity

• Reusable components: Build once, use everywhere
• Template workflows: Create standardized patterns
• Sub-workflow management: Encapsulate complex logic

Data Pipeline Building

• ETL operations: Extract, transform, load with custom parameters
• Data validation: Create reusable validation tools
• Multi-step processing: Chain operations with return handling

🔧 Configuration

Basic Setup

1. Tool Name: The identifier for your tool (used by AI agents)
2. Tool Description: Explains what your tool does
3. Parameters: Define input parameters with types and validation
4. Pass Through Original Input: Include original data in output
5. Wait for Return: Control whether to wait for return data

Parameter Types

| Type | Description | Example | |------|-------------|---------| | string | Text data | "Hello World" | | number | Numeric data | 42, 3.14 | | boolean | True/false | true, false | | object | JSON objects | {"key": "value"} | | array | Lists of data | [1, 2, 3] |

Advanced Configuration

Parameter Definition

{
  "name": "userId",
  "type": "string", 
  "description": "The user ID to process",
  "required": true,
  "defaultValue": "anonymous"
}

Pass-through Options

• Enabled: Original input available as _originalInput
• Disabled: Only processed parameters in output

Return Handling

• Wait for Return: Execution pauses until return data arrives
• No Wait: Immediate execution, return data handled separately

🌊 Data Flow

Input Flow

Input Data → Parameter Processing → Send Output → Sub-workflow

Return Flow

Sub-workflow → Return Input → Main Output

Dual Output System

• Main Output: Final results (empty if waiting for return)
• Send Output: Processed parameters sent to sub-workflows

💡 Examples

Example 1: User Data Processor

Configuration:

• Tool Name: User Data Processor
• Description: Validates and enriches user profile data

Parameters:

[
  {
    "name": "email",
    "type": "string",
    "required": true,
    "description": "User email address"
  },
  {
    "name": "age", 
    "type": "number",
    "required": false,
    "defaultValue": "0"
  }
]

Input:

{
  "email": "[email protected]",
  "age": "25",
  "extraData": "ignored"
}

Send Output:

{
  "email": "[email protected]",
  "age": 25,
  "_toolMetadata": {
    "toolName": "User Data Processor",
    "executionId": "exec_123",
    "timestamp": "2023-10-01T12:00:00.000Z"
  }
}

Example 2: API Chain Tool (with Pass-through)

Configuration:

• Tool Name: Multi API Processor
• Pass Through: true
• Wait for Return: true

Send Output:

{
  "apiEndpoint": "/users",
  "method": "GET",
  "_originalInput": {
    "userId": "12345",
    "context": "dashboard"
  },
  "_toolMetadata": { "..." }
}

🔄 Workflow Patterns

Pattern 1: Simple Tool

[Input] → [Composite] → [Process] → [Output]

Pattern 2: Tool with Return

[Input] → [Composite] → [Sub-workflow] 
            ↑              ↓
       [Main Output] ← [Return Data]

Pattern 3: AI Agent Tool

[AI Agent] → [Composite Tool] → [Business Logic] → [Results]

⚠️ Error Handling

When errors occur:

• Continue on Fail: Errors included in output with metadata
• Stop on Fail: Execution halts with error details

Error Output:

{
  "error": "Required parameter 'email' is missing",
  "_toolMetadata": {
    "toolName": "User Processor",
    "hasError": true,
    "timestamp": "2023-10-01T12:00:00.000Z"
  },
  "_originalInput": { "..." }
}

📊 Metadata

Every execution includes metadata:

{
  "_toolMetadata": {
    "toolName": "My Custom Tool",
    "executionId": "exec_abc123", 
    "timestamp": "2023-10-01T12:00:00.000Z",
    "hasError": false
  }
}

🤖 AI Integration

The Composite node is designed to work seamlessly with AI agents:

1. Tool Discovery: AI agents can discover available tools
2. Parameter Understanding: Type information helps AI format requests
3. Execution Tracking: Metadata enables monitoring and debugging
4. Error Recovery: Structured error responses for AI handling

AI Tool Schema

Automatically generates OpenAPI-style schemas:

{
  "name": "my_custom_tool",
  "description": "A custom tool description",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  }
}

🛠️ Development

Building

npm run build

Testing

npm test

Development Mode

npm run dev

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please see the repository for contribution guidelines.

📞 Support

• Issues: GitHub Issues
• Documentation: This README
• Community: n8n Community Forums