zhongwei/gh-czlonkowski-n8n-skills

Fork 0

Files

Zhongwei Li 6062d3994e Initial commit

2025-11-29 18:17:17 +08:00

8.4 KiB

Raw Permalink Blame History

Workflow Management Tools Guide

Complete guide for creating, updating, and managing n8n workflows.

Tool Availability

⚠️ Requires n8n API: All tools in this guide need N8N_API_URL and N8N_API_KEY configured.

If unavailable, use template examples and validation-only workflows.

n8n_create_workflow

Success Rate: 96.8% | Speed: 100-500ms

Use when: Creating new workflows from scratch

Syntax:

n8n_create_workflow({
  name: "Webhook to Slack",  // Required
  nodes: [...],              // Required: array of nodes
  connections: {...},        // Required: connections object
  settings: {...}            // Optional: workflow settings
})

Returns: Created workflow with ID

Example:

n8n_create_workflow({
  name: "Webhook to Slack",
  nodes: [
    {
      id: "webhook-1",
      name: "Webhook",
      type: "n8n-nodes-base.webhook",  // Full prefix!
      typeVersion: 1,
      position: [250, 300],
      parameters: {
        path: "slack-notify",
        httpMethod: "POST"
      }
    },
    {
      id: "slack-1",
      name: "Slack",
      type: "n8n-nodes-base.slack",
      typeVersion: 1,
      position: [450, 300],
      parameters: {
        resource: "message",
        operation: "post",
        channel: "#general",
        text: "={{$json.body.message}}"
      }
    }
  ],
  connections: {
    "Webhook": {
      "main": [[{node: "Slack", type: "main", index: 0}]]
    }
  }
})

Notes:

Workflows created inactive (must activate separately)
Auto-sanitization runs on creation
Validate before creating for best results

n8n_update_partial_workflow (MOST USED!)

Success Rate: 99.0% | Speed: 50-200ms | Uses: 38,287 (most used tool!)

Use when: Making incremental changes to workflows

Common pattern: 56s average between edits (iterative building!)

15 Operation Types

Node Operations (6 types):

addNode - Add new node
removeNode - Remove node by ID or name
updateNode - Update node properties
moveNode - Change position
enableNode - Enable disabled node
disableNode - Disable active node

Connection Operations (5 types): 7. addConnection - Connect nodes 8. removeConnection - Remove connection 9. rewireConnection - Change target 10. cleanStaleConnections - Auto-remove broken connections 11. replaceConnections - Replace entire connections object

Metadata Operations (4 types): 12. updateSettings - Workflow settings 13. updateName - Rename workflow 14. addTag - Add tag 15. removeTag - Remove tag

Smart Parameters (NEW!)

IF nodes - Use semantic branch names:

{
  type: "addConnection",
  source: "IF",
  target: "True Handler",
  branch: "true"  // Instead of sourceIndex: 0
}

{
  type: "addConnection",
  source: "IF",
  target: "False Handler",
  branch: "false"  // Instead of sourceIndex: 1
}

Switch nodes - Use semantic case numbers:

{
  type: "addConnection",
  source: "Switch",
  target: "Handler A",
  case: 0
}

{
  type: "addConnection",
  source: "Switch",
  target: "Handler B",
  case: 1
}

AI Connection Types (8 types)

Full support for AI workflows:

// Language Model
{
  type: "addConnection",
  source: "OpenAI Chat Model",
  target: "AI Agent",
  sourceOutput: "ai_languageModel"
}

// Tool
{
  type: "addConnection",
  source: "HTTP Request Tool",
  target: "AI Agent",
  sourceOutput: "ai_tool"
}

// Memory
{
  type: "addConnection",
  source: "Window Buffer Memory",
  target: "AI Agent",
  sourceOutput: "ai_memory"
}

// All 8 types:
// - ai_languageModel
// - ai_tool
// - ai_memory
// - ai_outputParser
// - ai_embedding
// - ai_vectorStore
// - ai_document
// - ai_textSplitter

Example Usage

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [
    // Add node
    {
      type: "addNode",
      node: {
        name: "Transform",
        type: "n8n-nodes-base.set",
        position: [400, 300],
        parameters: {}
      }
    },
    // Connect it (smart parameter)
    {
      type: "addConnection",
      source: "IF",
      target: "Transform",
      branch: "true"  // Clear and semantic!
    }
  ]
})

Cleanup & Recovery

cleanStaleConnections - Remove broken connections:

{
  type: "cleanStaleConnections"
}

Best-effort mode - Apply what works:

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [...],
  continueOnError: true  // Don't fail if some operations fail
})

n8n_validate_workflow (by ID)

Success Rate: 99.7% | Speed: Network-dependent

Use when: Validating workflow stored in n8n

Syntax:

n8n_validate_workflow({
  id: "workflow-id",
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

Returns: Same as validate_workflow (from validation guide)

Workflow Lifecycle

Standard pattern:

1. CREATE
   n8n_create_workflow({...})
   → Returns workflow ID

2. VALIDATE
   n8n_validate_workflow({id})
   → Check for errors

3. EDIT (iterative! 56s avg between edits)
   n8n_update_partial_workflow({id, operations: [...]})
   → Make changes

4. VALIDATE AGAIN
   n8n_validate_workflow({id})
   → Verify changes

5. ACTIVATE (when ready)
   ⚠️ **IMPORTANT LIMITATION**: Workflow activation is NOT supported via API or MCP.
   Users must activate workflows manually in the n8n UI.

   The following operation will NOT activate the workflow:
   n8n_update_partial_workflow({id, operations: [{
     type: "updateSettings",
     settings: {active: true}
   }]})

   **Manual activation required**: Navigate to workflow in n8n UI and toggle activation.

6. MONITOR
   n8n_list_executions({workflowId: id})
   n8n_get_execution({id: execution_id})

Deployment Note: After creating and validating workflows via MCP, inform users they must:

Open the workflow in n8n UI (provide workflow ID)
Review the workflow configuration
Manually activate the workflow using the activation toggle

Common Patterns from Telemetry

Pattern 1: Edit → Validate (7,841 occurrences)

// Edit
n8n_update_partial_workflow({...})
// ↓ 23s (thinking about what to validate)
// Validate
n8n_validate_workflow({id})

Pattern 2: Validate → Fix (7,266 occurrences)

// Validate
n8n_validate_workflow({id})
// ↓ 58s (fixing errors)
// Fix
n8n_update_partial_workflow({...})

Pattern 3: Iterative Building (31,464 occurrences)

update → update → update → ... (56s avg between edits)

This shows: Workflows are built iteratively, not in one shot!

Retrieval Tools

n8n_get_workflow

n8n_get_workflow({id: "workflow-id"})
// Returns: Complete workflow JSON

n8n_get_workflow_structure

n8n_get_workflow_structure({id: "workflow-id"})
// Returns: Nodes + connections only (no parameters)

n8n_get_workflow_minimal

n8n_get_workflow_minimal({id: "workflow-id"})
// Returns: ID, name, active, tags only (fast!)

n8n_list_workflows

n8n_list_workflows({
  active: true,  // Optional: filter by status
  limit: 100,    // Optional: max results
  tags: ["production"]  // Optional: filter by tags
})

Best Practices

✅ Do

Build workflows iteratively (avg 56s between edits)
Use smart parameters (branch, case) for clarity
Validate after significant changes
Use atomic mode (default) for critical updates
Specify sourceOutput for AI connections
Clean stale connections after node renames/deletions

❌ Don't

Try to build workflows in one shot
Use sourceIndex when branch/case available
Skip validation before activation
Forget to test workflows after creation
Ignore auto-sanitization behavior

Summary

Most Important:

n8n_update_partial_workflow is most-used tool (38,287 uses, 99.0% success)
Workflows built iteratively (56s avg between edits)
Use smart parameters (branch="true", case=0) for clarity
AI connections supported (8 types with sourceOutput)
Auto-sanitization runs on all operations
Validate frequently (7,841 edit → validate patterns)

Related:

SEARCH_GUIDE.md - Find nodes to add
VALIDATION_GUIDE.md - Validate workflows

8.4 KiB Raw Permalink Blame History