Initial commit
This commit is contained in:
Zhongwei Li
99
skills/n8n-mcp-tools-expert/README.md
Normal file
99
skills/n8n-mcp-tools-expert/README.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# n8n MCP Tools Expert
|
||||
|
||||
Expert guide for using n8n-mcp MCP tools effectively.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Teaches how to use n8n-mcp MCP server tools correctly for efficient workflow building.
|
||||
|
||||
## Activates On
|
||||
|
||||
- search nodes
|
||||
- find node
|
||||
- validate
|
||||
- MCP tools
|
||||
- template
|
||||
- workflow
|
||||
- n8n-mcp
|
||||
- tool selection
|
||||
|
||||
## File Count
|
||||
|
||||
5 files, ~1,150 lines total
|
||||
|
||||
## Priority
|
||||
|
||||
**HIGHEST** - Essential for correct MCP tool usage
|
||||
|
||||
## Dependencies
|
||||
|
||||
**n8n-mcp tools**: All of them! (40+ tools)
|
||||
|
||||
**Related skills**:
|
||||
- n8n Expression Syntax (write expressions for workflows)
|
||||
- n8n Workflow Patterns (use tools to build patterns)
|
||||
- n8n Validation Expert (interpret validation results)
|
||||
- n8n Node Configuration (configure nodes found with tools)
|
||||
|
||||
## Coverage
|
||||
|
||||
### Core Topics
|
||||
- Tool selection guide (which tool for which task)
|
||||
- nodeType format differences (nodes-base.* vs n8n-nodes-base.*)
|
||||
- Validation profiles (minimal/runtime/ai-friendly/strict)
|
||||
- Smart parameters (branch, case for multi-output nodes)
|
||||
- Auto-sanitization system
|
||||
- Workflow management (15 operation types)
|
||||
- AI connection types (8 types)
|
||||
|
||||
### Tool Categories
|
||||
- Node Discovery (search, list, essentials, info)
|
||||
- Configuration Validation (minimal, operation, workflow)
|
||||
- Workflow Management (create, update, validate)
|
||||
- Template Library (search, get)
|
||||
- Documentation (tools, database stats)
|
||||
|
||||
## Evaluations
|
||||
|
||||
5 scenarios (100% coverage expected):
|
||||
1. **eval-001**: Tool selection (search_nodes)
|
||||
2. **eval-002**: nodeType format (nodes-base.* prefix)
|
||||
3. **eval-003**: Validation workflow (profiles)
|
||||
4. **eval-004**: essentials vs info (5KB vs 100KB)
|
||||
5. **eval-005**: Smart parameters (branch, case)
|
||||
|
||||
## Key Features
|
||||
|
||||
✅ **Tool Selection Guide**: Which tool to use for each task
|
||||
✅ **Common Patterns**: Most effective tool usage sequences
|
||||
✅ **Format Guidance**: nodeType format differences explained
|
||||
✅ **Smart Parameters**: Semantic branch/case routing for multi-output nodes
|
||||
✅ **Auto-Sanitization**: Explains automatic validation fixes
|
||||
✅ **Comprehensive**: Covers all 40+ MCP tools
|
||||
|
||||
## Files
|
||||
|
||||
- **SKILL.md** (480 lines) - Core tool usage guide
|
||||
- **SEARCH_GUIDE.md** (220 lines) - Node discovery tools
|
||||
- **VALIDATION_GUIDE.md** (250 lines) - Validation tools and profiles
|
||||
- **WORKFLOW_GUIDE.md** (200 lines) - Workflow management
|
||||
- **README.md** (this file) - Skill metadata
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
- Correct nodeType formats (nodes-base.* for search tools)
|
||||
- When to use get_node_essentials vs get_node_info
|
||||
- How to use validation profiles effectively
|
||||
- Smart parameters for multi-output nodes (IF/Switch)
|
||||
- Common tool usage patterns and workflows
|
||||
|
||||
## Last Updated
|
||||
|
||||
2025-10-20
|
||||
|
||||
---
|
||||
|
||||
**Part of**: n8n-skills repository
|
||||
**Conceived by**: Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
|
||||
242
skills/n8n-mcp-tools-expert/SEARCH_GUIDE.md
Normal file
242
skills/n8n-mcp-tools-expert/SEARCH_GUIDE.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Node Discovery Tools Guide
|
||||
|
||||
Complete guide for finding and understanding n8n nodes.
|
||||
|
||||
---
|
||||
|
||||
## search_nodes (START HERE!)
|
||||
|
||||
**Success Rate**: 99.9% | **Speed**: <20ms
|
||||
|
||||
**Use when**: You know what you're looking for (keyword, service, use case)
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
search_nodes({
|
||||
query: "slack", // Required: search keywords
|
||||
mode: "OR", // Optional: OR (default), AND, FUZZY
|
||||
limit: 20 // Optional: max results (default 20, max 100)
|
||||
})
|
||||
```
|
||||
|
||||
**Returns**:
|
||||
```javascript
|
||||
{
|
||||
"query": "slack",
|
||||
"results": [
|
||||
{
|
||||
"nodeType": "nodes-base.slack", // For search/validate tools
|
||||
"workflowNodeType": "n8n-nodes-base.slack", // For workflow tools
|
||||
"displayName": "Slack",
|
||||
"description": "Consume Slack API",
|
||||
"category": "output",
|
||||
"relevance": "high"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Tips**:
|
||||
- Common searches: webhook, http, database, email, slack, google, ai
|
||||
- OR mode (default): matches any word
|
||||
- AND mode: requires all words
|
||||
- FUZZY mode: typo-tolerant (finds "slak" → Slack)
|
||||
|
||||
---
|
||||
|
||||
## get_node_essentials (RECOMMENDED!)
|
||||
|
||||
**Success Rate**: 91.7% | **Speed**: <10ms | **Size**: ~5KB
|
||||
|
||||
**Use when**: You've found the node and need configuration details
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
get_node_essentials({
|
||||
nodeType: "nodes-base.slack", // Required: SHORT prefix format
|
||||
includeExamples: true // Optional: get real template configs
|
||||
})
|
||||
```
|
||||
|
||||
**Returns**:
|
||||
- Available operations and resources
|
||||
- Essential properties (10-20 most common)
|
||||
- Metadata (isAITool, isTrigger, hasCredentials)
|
||||
- Real examples from templates (if includeExamples: true)
|
||||
|
||||
**Why use this**:
|
||||
- 5KB vs 100KB+ (get_node_info)
|
||||
- 91.7% success vs 80%
|
||||
- <10ms vs slower
|
||||
- Focused data (no information overload)
|
||||
|
||||
---
|
||||
|
||||
## get_node_info (USE SPARINGLY!)
|
||||
|
||||
**Success Rate**: 80% ⚠️ | **Size**: 100KB+
|
||||
|
||||
**Use when**:
|
||||
- Debugging complex configuration
|
||||
- Need complete property schema
|
||||
- Exploring advanced features
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
get_node_info({
|
||||
nodeType: "nodes-base.httpRequest"
|
||||
})
|
||||
```
|
||||
|
||||
**Warning**: 20% failure rate! Use get_node_essentials instead for most cases.
|
||||
|
||||
**Better alternatives**:
|
||||
1. get_node_essentials - operations list
|
||||
2. get_node_documentation - readable docs
|
||||
3. search_node_properties - specific property
|
||||
|
||||
---
|
||||
|
||||
## list_nodes (BROWSE BY CATEGORY)
|
||||
|
||||
**Success Rate**: 99.6% | **Speed**: <20ms
|
||||
|
||||
**Use when**: Exploring by category or listing all nodes
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
list_nodes({
|
||||
category: "trigger", // Optional: filter by category
|
||||
package: "n8n-nodes-base", // Optional: filter by package
|
||||
limit: 200 // Optional: default 50
|
||||
})
|
||||
```
|
||||
|
||||
**Categories**:
|
||||
- `trigger` - Webhook, Schedule, Manual, etc. (108 total)
|
||||
- `transform` - Code, Set, Function, etc.
|
||||
- `output` - HTTP Request, Email, Slack, etc.
|
||||
- `input` - Read data sources
|
||||
- `AI` - AI-capable nodes (270 total)
|
||||
|
||||
**Packages**:
|
||||
- `n8n-nodes-base` - Core nodes (437 total)
|
||||
- `@n8n/n8n-nodes-langchain` - AI nodes (100 total)
|
||||
|
||||
---
|
||||
|
||||
## search_node_properties (FIND SPECIFIC FIELDS)
|
||||
|
||||
**Use when**: Looking for specific property in a node
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
search_node_properties({
|
||||
nodeType: "nodes-base.httpRequest",
|
||||
query: "auth" // Find authentication properties
|
||||
})
|
||||
```
|
||||
|
||||
**Returns**: Property paths and descriptions matching query
|
||||
|
||||
**Common searches**: auth, header, body, json, url, method
|
||||
|
||||
---
|
||||
|
||||
## get_node_documentation (READABLE DOCS)
|
||||
|
||||
**Coverage**: 88% of nodes (470/537)
|
||||
|
||||
**Use when**: Need human-readable documentation with examples
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
get_node_documentation({
|
||||
nodeType: "nodes-base.slack"
|
||||
})
|
||||
```
|
||||
|
||||
**Returns**: Formatted docs with:
|
||||
- Usage examples
|
||||
- Authentication guide
|
||||
- Common patterns
|
||||
- Best practices
|
||||
|
||||
**Note**: Better than raw schema for learning!
|
||||
|
||||
---
|
||||
|
||||
## Common Workflow: Finding & Configuring
|
||||
|
||||
```
|
||||
Step 1: Search
|
||||
search_nodes({query: "slack"})
|
||||
→ Returns: nodes-base.slack
|
||||
|
||||
Step 2: Get Operations (18s avg thinking time)
|
||||
get_node_essentials({
|
||||
nodeType: "nodes-base.slack",
|
||||
includeExamples: true
|
||||
})
|
||||
→ Returns: operations list + example configs
|
||||
|
||||
Step 3: Validate Config
|
||||
validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config: {resource: "channel", operation: "create"},
|
||||
profile: "runtime"
|
||||
})
|
||||
→ Returns: validation result
|
||||
|
||||
Step 4: Use in Workflow
|
||||
(Configuration ready!)
|
||||
```
|
||||
|
||||
**Most common pattern**: search → essentials (18s average)
|
||||
|
||||
---
|
||||
|
||||
## Quick Comparison
|
||||
|
||||
| Tool | When to Use | Success | Speed | Size |
|
||||
|------|-------------|---------|-------|------|
|
||||
| search_nodes | Find by keyword | 99.9% | <20ms | Small |
|
||||
| get_node_essentials | Get config | 91.7% | <10ms | 5KB |
|
||||
| get_node_info | Full schema | 80% ⚠️ | Slow | 100KB+ |
|
||||
| list_nodes | Browse category | 99.6% | <20ms | Small |
|
||||
| get_node_documentation | Learn usage | N/A | Fast | Medium |
|
||||
|
||||
**Best Practice**: search → essentials → validate
|
||||
|
||||
---
|
||||
|
||||
## nodeType Format (CRITICAL!)
|
||||
|
||||
**Search/Validate Tools** (SHORT prefix):
|
||||
```javascript
|
||||
"nodes-base.slack"
|
||||
"nodes-base.httpRequest"
|
||||
"nodes-langchain.agent"
|
||||
```
|
||||
|
||||
**Workflow Tools** (FULL prefix):
|
||||
```javascript
|
||||
"n8n-nodes-base.slack"
|
||||
"n8n-nodes-base.httpRequest"
|
||||
"@n8n/n8n-nodes-langchain.agent"
|
||||
```
|
||||
|
||||
**Conversion**: search_nodes returns BOTH formats:
|
||||
```javascript
|
||||
{
|
||||
"nodeType": "nodes-base.slack", // Use with essentials
|
||||
"workflowNodeType": "n8n-nodes-base.slack" // Use with create_workflow
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate node configs
|
||||
- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Use nodes in workflows
|
||||
504
skills/n8n-mcp-tools-expert/SKILL.md
Normal file
504
skills/n8n-mcp-tools-expert/SKILL.md
Normal file
@@ -0,0 +1,504 @@
|
||||
---
|
||||
name: n8n-mcp-tools-expert
|
||||
description: Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, or using any n8n-mcp tool. Provides tool selection guidance, parameter formats, and common patterns.
|
||||
---
|
||||
|
||||
# n8n MCP Tools Expert
|
||||
|
||||
Master guide for using n8n-mcp MCP server tools to build workflows.
|
||||
|
||||
---
|
||||
|
||||
## Tool Categories
|
||||
|
||||
n8n-mcp provides **40+ tools** organized into categories:
|
||||
|
||||
1. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md)
|
||||
2. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md)
|
||||
3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
|
||||
4. **Template Library** - Search and access 2,653 real workflows
|
||||
5. **Documentation** - Get tool and node documentation
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Most Used Tools (by success rate)
|
||||
|
||||
| Tool | Use When | Success Rate | Speed |
|
||||
|------|----------|--------------|-------|
|
||||
| `search_nodes` | Finding nodes by keyword | 99.9% | <20ms |
|
||||
| `get_node_essentials` | Understanding node operations | 91.7% | <10ms |
|
||||
| `validate_node_operation` | Checking configurations | Varies | <100ms |
|
||||
| `n8n_create_workflow` | Creating workflows | 96.8% | 100-500ms |
|
||||
| `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 99.0% | 50-200ms |
|
||||
| `validate_workflow` | Checking complete workflow | 95.5% | 100-500ms |
|
||||
|
||||
---
|
||||
|
||||
## Tool Selection Guide
|
||||
|
||||
### Finding the Right Node
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
1. search_nodes({query: "keyword"})
|
||||
2. get_node_essentials({nodeType: "nodes-base.name"})
|
||||
3. [Optional] get_node_documentation({nodeType: "nodes-base.name"})
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
// Step 1: Search
|
||||
search_nodes({query: "slack"})
|
||||
// Returns: nodes-base.slack
|
||||
|
||||
// Step 2: Get details (18s avg between steps)
|
||||
get_node_essentials({nodeType: "nodes-base.slack"})
|
||||
// Returns: operations, properties, examples
|
||||
```
|
||||
|
||||
**Common pattern**: search → essentials (18s average)
|
||||
|
||||
### Validating Configuration
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
1. validate_node_minimal({nodeType, config: {}}) - Check required fields
|
||||
2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation
|
||||
3. [Repeat] Fix errors, validate again
|
||||
```
|
||||
|
||||
**Common pattern**: validate → fix → validate (23s thinking, 58s fixing per cycle)
|
||||
|
||||
### Managing Workflows
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
1. n8n_create_workflow({name, nodes, connections})
|
||||
2. n8n_validate_workflow({id})
|
||||
3. n8n_update_partial_workflow({id, operations: [...]})
|
||||
4. n8n_validate_workflow({id}) again
|
||||
```
|
||||
|
||||
**Common pattern**: iterative updates (56s average between edits)
|
||||
|
||||
---
|
||||
|
||||
## Critical: nodeType Formats
|
||||
|
||||
**Two different formats** for different tools!
|
||||
|
||||
### Format 1: Search/Validate Tools
|
||||
```javascript
|
||||
// Use SHORT prefix
|
||||
"nodes-base.slack"
|
||||
"nodes-base.httpRequest"
|
||||
"nodes-base.webhook"
|
||||
"nodes-langchain.agent"
|
||||
```
|
||||
|
||||
**Tools that use this**:
|
||||
- search_nodes (returns this format)
|
||||
- get_node_essentials
|
||||
- get_node_info
|
||||
- validate_node_minimal
|
||||
- validate_node_operation
|
||||
- get_property_dependencies
|
||||
|
||||
### Format 2: Workflow Tools
|
||||
```javascript
|
||||
// Use FULL prefix
|
||||
"n8n-nodes-base.slack"
|
||||
"n8n-nodes-base.httpRequest"
|
||||
"n8n-nodes-base.webhook"
|
||||
"@n8n/n8n-nodes-langchain.agent"
|
||||
```
|
||||
|
||||
**Tools that use this**:
|
||||
- n8n_create_workflow
|
||||
- n8n_update_partial_workflow
|
||||
- list_node_templates
|
||||
|
||||
### Conversion
|
||||
|
||||
```javascript
|
||||
// search_nodes returns BOTH formats
|
||||
{
|
||||
"nodeType": "nodes-base.slack", // For search/validate tools
|
||||
"workflowNodeType": "n8n-nodes-base.slack" // For workflow tools
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Mistake 1: Wrong nodeType Format
|
||||
|
||||
**Problem**: "Node not found" error
|
||||
|
||||
```javascript
|
||||
❌ get_node_essentials({nodeType: "slack"}) // Missing prefix
|
||||
❌ get_node_essentials({nodeType: "n8n-nodes-base.slack"}) // Wrong prefix
|
||||
|
||||
✅ get_node_essentials({nodeType: "nodes-base.slack"}) // Correct!
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Using get_node_info Instead of get_node_essentials
|
||||
|
||||
**Problem**: 20% failure rate, slow response, huge payload
|
||||
|
||||
```javascript
|
||||
❌ get_node_info({nodeType: "nodes-base.slack"})
|
||||
// Returns: 100KB+ data, 20% chance of failure
|
||||
|
||||
✅ get_node_essentials({nodeType: "nodes-base.slack"})
|
||||
// Returns: 5KB focused data, 91.7% success, <10ms
|
||||
```
|
||||
|
||||
**When to use get_node_info**:
|
||||
- Debugging complex configuration issues
|
||||
- Need complete property schema
|
||||
- Exploring advanced features
|
||||
|
||||
**Better alternatives**:
|
||||
1. get_node_essentials - for operations list
|
||||
2. get_node_documentation - for readable docs
|
||||
3. search_node_properties - for specific property
|
||||
|
||||
### ❌ Mistake 3: Not Using Validation Profiles
|
||||
|
||||
**Problem**: Too many false positives OR missing real errors
|
||||
|
||||
**Profiles**:
|
||||
- `minimal` - Only required fields (fast, permissive)
|
||||
- `runtime` - Values + types (recommended for pre-deployment)
|
||||
- `ai-friendly` - Reduce false positives (for AI configuration)
|
||||
- `strict` - Maximum validation (for production)
|
||||
|
||||
```javascript
|
||||
❌ validate_node_operation({nodeType, config}) // Uses default
|
||||
|
||||
✅ validate_node_operation({nodeType, config, profile: "runtime"}) // Explicit
|
||||
```
|
||||
|
||||
### ❌ Mistake 4: Ignoring Auto-Sanitization
|
||||
|
||||
**What happens**: ALL nodes sanitized on ANY workflow update
|
||||
|
||||
**Auto-fixes**:
|
||||
- Binary operators (equals, contains) → removes singleValue
|
||||
- Unary operators (isEmpty, isNotEmpty) → adds singleValue: true
|
||||
- IF/Switch nodes → adds missing metadata
|
||||
|
||||
**Cannot fix**:
|
||||
- Broken connections
|
||||
- Branch count mismatches
|
||||
- Paradoxical corrupt states
|
||||
|
||||
```javascript
|
||||
// After ANY update, auto-sanitization runs on ALL nodes
|
||||
n8n_update_partial_workflow({id, operations: [...]})
|
||||
// → Automatically fixes operator structures
|
||||
```
|
||||
|
||||
### ❌ Mistake 5: Not Using Smart Parameters
|
||||
|
||||
**Problem**: Complex sourceIndex calculations for multi-output nodes
|
||||
|
||||
**Old way** (manual):
|
||||
```javascript
|
||||
// IF node connection
|
||||
{
|
||||
type: "addConnection",
|
||||
source: "IF",
|
||||
target: "Handler",
|
||||
sourceIndex: 0 // Which output? Hard to remember!
|
||||
}
|
||||
```
|
||||
|
||||
**New way** (smart parameters):
|
||||
```javascript
|
||||
// IF node - semantic branch names
|
||||
{
|
||||
type: "addConnection",
|
||||
source: "IF",
|
||||
target: "True Handler",
|
||||
branch: "true" // Clear and readable!
|
||||
}
|
||||
|
||||
{
|
||||
type: "addConnection",
|
||||
source: "IF",
|
||||
target: "False Handler",
|
||||
branch: "false"
|
||||
}
|
||||
|
||||
// Switch node - semantic case numbers
|
||||
{
|
||||
type: "addConnection",
|
||||
source: "Switch",
|
||||
target: "Handler A",
|
||||
case: 0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Usage Patterns
|
||||
|
||||
### Pattern 1: Node Discovery (Most Common)
|
||||
|
||||
**Common workflow**: 18s average between steps
|
||||
|
||||
```javascript
|
||||
// Step 1: Search (fast!)
|
||||
const results = await search_nodes({
|
||||
query: "slack",
|
||||
mode: "OR", // Default: any word matches
|
||||
limit: 20
|
||||
});
|
||||
// → Returns: nodes-base.slack, nodes-base.slackTrigger
|
||||
|
||||
// Step 2: Get details (~18s later, user reviewing results)
|
||||
const details = await get_node_essentials({
|
||||
nodeType: "nodes-base.slack",
|
||||
includeExamples: true // Get real template configs
|
||||
});
|
||||
// → Returns: operations, properties, metadata
|
||||
```
|
||||
|
||||
### Pattern 2: Validation Loop
|
||||
|
||||
**Typical cycle**: 23s thinking, 58s fixing
|
||||
|
||||
```javascript
|
||||
// Step 1: Validate
|
||||
const result = await validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config: {
|
||||
resource: "channel",
|
||||
operation: "create"
|
||||
},
|
||||
profile: "runtime"
|
||||
});
|
||||
|
||||
// Step 2: Check errors (~23s thinking)
|
||||
if (!result.valid) {
|
||||
console.log(result.errors); // "Missing required field: name"
|
||||
}
|
||||
|
||||
// Step 3: Fix config (~58s fixing)
|
||||
config.name = "general";
|
||||
|
||||
// Step 4: Validate again
|
||||
await validate_node_operation({...}); // Repeat until clean
|
||||
```
|
||||
|
||||
### Pattern 3: Workflow Editing
|
||||
|
||||
**Most used update tool**: 99.0% success rate, 56s average between edits
|
||||
|
||||
```javascript
|
||||
// Iterative workflow building (NOT one-shot!)
|
||||
// Edit 1
|
||||
await n8n_update_partial_workflow({
|
||||
id: "workflow-id",
|
||||
operations: [{type: "addNode", node: {...}}]
|
||||
});
|
||||
|
||||
// ~56s later...
|
||||
|
||||
// Edit 2
|
||||
await n8n_update_partial_workflow({
|
||||
id: "workflow-id",
|
||||
operations: [{type: "addConnection", source: "...", target: "..."}]
|
||||
});
|
||||
|
||||
// ~56s later...
|
||||
|
||||
// Edit 3 (validation)
|
||||
await n8n_validate_workflow({id: "workflow-id"});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Detailed Guides
|
||||
|
||||
### Node Discovery Tools
|
||||
See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for:
|
||||
- search_nodes (99.9% success)
|
||||
- get_node_essentials vs get_node_info
|
||||
- list_nodes by category
|
||||
- search_node_properties for specific fields
|
||||
|
||||
### Validation Tools
|
||||
See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
|
||||
- Validation profiles explained
|
||||
- validate_node_minimal vs validate_node_operation
|
||||
- validate_workflow complete structure
|
||||
- Auto-sanitization system
|
||||
- Handling validation errors
|
||||
|
||||
### Workflow Management
|
||||
See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
|
||||
- n8n_create_workflow
|
||||
- n8n_update_partial_workflow (15 operation types!)
|
||||
- Smart parameters (branch, case)
|
||||
- AI connection types (8 types)
|
||||
- cleanStaleConnections recovery
|
||||
|
||||
---
|
||||
|
||||
## Template Usage
|
||||
|
||||
### Search Templates
|
||||
|
||||
```javascript
|
||||
// Search by keyword
|
||||
search_templates({
|
||||
query: "webhook slack",
|
||||
limit: 20
|
||||
});
|
||||
// → Returns: 1,085 templates with metadata
|
||||
|
||||
// Get template details
|
||||
get_template({
|
||||
templateId: 2947, // Weather to Slack
|
||||
mode: "structure" // or "full" for complete JSON
|
||||
});
|
||||
```
|
||||
|
||||
### Template Metadata
|
||||
|
||||
Templates include:
|
||||
- Complexity (simple, medium, complex)
|
||||
- Setup time estimate
|
||||
- Required services
|
||||
- Categories and use cases
|
||||
- View counts (popularity)
|
||||
|
||||
---
|
||||
|
||||
## Self-Help Tools
|
||||
|
||||
### Get Tool Documentation
|
||||
|
||||
```javascript
|
||||
// List all tools
|
||||
tools_documentation()
|
||||
|
||||
// Specific tool details
|
||||
tools_documentation({
|
||||
topic: "search_nodes",
|
||||
depth: "full"
|
||||
})
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```javascript
|
||||
// Verify MCP server connectivity
|
||||
n8n_health_check()
|
||||
// → Returns: status, features, API availability, version
|
||||
```
|
||||
|
||||
### Database Statistics
|
||||
|
||||
```javascript
|
||||
get_database_statistics()
|
||||
// → Returns: 537 nodes, 270 AI tools, 2,653 templates
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Availability
|
||||
|
||||
**Always Available** (no n8n API needed):
|
||||
- search_nodes, list_nodes, get_node_essentials ✅
|
||||
- validate_node_minimal, validate_node_operation ✅
|
||||
- validate_workflow, get_property_dependencies ✅
|
||||
- search_templates, get_template, list_tasks ✅
|
||||
- tools_documentation, get_database_statistics ✅
|
||||
|
||||
**Requires n8n API** (N8N_API_URL + N8N_API_KEY):
|
||||
- n8n_create_workflow ⚠️
|
||||
- n8n_update_partial_workflow ⚠️
|
||||
- n8n_validate_workflow (by ID) ⚠️
|
||||
- n8n_list_workflows, n8n_get_workflow ⚠️
|
||||
- n8n_trigger_webhook_workflow ⚠️
|
||||
|
||||
If API tools unavailable, use templates and validation-only workflows.
|
||||
|
||||
---
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
| Tool | Response Time | Payload Size | Reliability |
|
||||
|------|---------------|--------------|-------------|
|
||||
| search_nodes | <20ms | Small | 99.9% |
|
||||
| list_nodes | <20ms | Small | 99.6% |
|
||||
| get_node_essentials | <10ms | ~5KB | 91.7% |
|
||||
| get_node_info | Varies | 100KB+ | 80% ⚠️ |
|
||||
| validate_node_minimal | <100ms | Small | 97.4% |
|
||||
| validate_node_operation | <100ms | Medium | Varies |
|
||||
| validate_workflow | 100-500ms | Medium | 95.5% |
|
||||
| n8n_create_workflow | 100-500ms | Medium | 96.8% |
|
||||
| n8n_update_partial_workflow | 50-200ms | Small | 99.0% |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Do
|
||||
|
||||
- Use get_node_essentials over get_node_info (91.7% vs 80%)
|
||||
- Specify validation profile explicitly
|
||||
- Use smart parameters (branch, case) for clarity
|
||||
- Follow search → essentials → validate workflow
|
||||
- Iterate workflows (avg 56s between edits)
|
||||
- Validate after every significant change
|
||||
- Use includeExamples: true for real configs
|
||||
|
||||
### ❌ Don't
|
||||
|
||||
- Use get_node_info unless necessary (20% failure rate!)
|
||||
- Forget nodeType prefix (nodes-base.*)
|
||||
- Skip validation profiles (use "runtime")
|
||||
- Try to build workflows in one shot (iterate!)
|
||||
- Ignore auto-sanitization behavior
|
||||
- Use full prefix (n8n-nodes-base.*) with search tools
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Most Important**:
|
||||
1. Use **get_node_essentials**, not get_node_info (5KB vs 100KB, 91.7% vs 80%)
|
||||
2. nodeType formats differ: `nodes-base.*` (search) vs `n8n-nodes-base.*` (workflows)
|
||||
3. Specify **validation profiles** (runtime recommended)
|
||||
4. Use **smart parameters** (branch="true", case=0)
|
||||
5. **Auto-sanitization** runs on ALL nodes during updates
|
||||
6. Workflows are built **iteratively** (56s avg between edits)
|
||||
|
||||
**Common Workflow**:
|
||||
1. search_nodes → find node
|
||||
2. get_node_essentials → understand config
|
||||
3. validate_node_operation → check config
|
||||
4. n8n_create_workflow → build
|
||||
5. n8n_validate_workflow → verify
|
||||
6. n8n_update_partial_workflow → iterate
|
||||
|
||||
For details, see:
|
||||
- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery
|
||||
- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Configuration validation
|
||||
- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Workflow management
|
||||
|
||||
---
|
||||
|
||||
**Related Skills**:
|
||||
- n8n Expression Syntax - Write expressions in workflow fields
|
||||
- n8n Workflow Patterns - Architectural patterns from templates
|
||||
- n8n Validation Expert - Interpret validation errors
|
||||
- n8n Node Configuration - Operation-specific requirements
|
||||
377
skills/n8n-mcp-tools-expert/VALIDATION_GUIDE.md
Normal file
377
skills/n8n-mcp-tools-expert/VALIDATION_GUIDE.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# Configuration Validation Tools Guide
|
||||
|
||||
Complete guide for validating node configurations and workflows.
|
||||
|
||||
---
|
||||
|
||||
## Validation Philosophy
|
||||
|
||||
**Validate early, validate often**
|
||||
|
||||
Validation is typically iterative with validate → fix cycles
|
||||
|
||||
---
|
||||
|
||||
## validate_node_minimal (QUICK CHECK)
|
||||
|
||||
**Success Rate**: 97.4% | **Speed**: <100ms
|
||||
|
||||
**Use when**: Checking what fields are required
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
validate_node_minimal({
|
||||
nodeType: "nodes-base.slack",
|
||||
config: {} // Empty to see all required fields
|
||||
})
|
||||
```
|
||||
|
||||
**Returns**:
|
||||
```javascript
|
||||
{
|
||||
"valid": true, // Usually true (most nodes have no strict requirements)
|
||||
"missingRequiredFields": []
|
||||
}
|
||||
```
|
||||
|
||||
**When to use**: Planning configuration, seeing basic requirements
|
||||
|
||||
---
|
||||
|
||||
## validate_node_operation (FULL VALIDATION)
|
||||
|
||||
**Success Rate**: Varies | **Speed**: <100ms
|
||||
|
||||
**Use when**: Validating actual configuration before deployment
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config: {
|
||||
resource: "channel",
|
||||
operation: "create",
|
||||
channel: "general"
|
||||
},
|
||||
profile: "runtime" // Recommended!
|
||||
})
|
||||
```
|
||||
|
||||
### Validation Profiles
|
||||
|
||||
Choose based on your stage:
|
||||
|
||||
**minimal** - Only required fields
|
||||
- Fastest
|
||||
- Most permissive
|
||||
- Use: Quick checks during editing
|
||||
|
||||
**runtime** - Values + types (**RECOMMENDED**)
|
||||
- Balanced validation
|
||||
- Catches real errors
|
||||
- Use: Pre-deployment validation
|
||||
|
||||
**ai-friendly** - Reduce false positives
|
||||
- For AI-generated configs
|
||||
- Tolerates minor issues
|
||||
- Use: When AI configures nodes
|
||||
|
||||
**strict** - Maximum validation
|
||||
- Strictest rules
|
||||
- May have false positives
|
||||
- Use: Production deployment
|
||||
|
||||
### Returns
|
||||
|
||||
```javascript
|
||||
{
|
||||
"valid": false,
|
||||
"errors": [
|
||||
{
|
||||
"type": "missing_required",
|
||||
"property": "name",
|
||||
"message": "Channel name is required",
|
||||
"fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
|
||||
}
|
||||
],
|
||||
"warnings": [
|
||||
{
|
||||
"type": "best_practice",
|
||||
"property": "errorHandling",
|
||||
"message": "Slack API can have rate limits",
|
||||
"suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
|
||||
}
|
||||
],
|
||||
"suggestions": [],
|
||||
"summary": {
|
||||
"hasErrors": true,
|
||||
"errorCount": 1,
|
||||
"warningCount": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Types
|
||||
|
||||
- `missing_required` - Must fix
|
||||
- `invalid_value` - Must fix
|
||||
- `type_mismatch` - Must fix
|
||||
- `best_practice` - Should fix (warning)
|
||||
- `suggestion` - Optional improvement
|
||||
|
||||
---
|
||||
|
||||
## validate_workflow (STRUCTURE VALIDATION)
|
||||
|
||||
**Success Rate**: 95.5% | **Speed**: 100-500ms
|
||||
|
||||
**Use when**: Checking complete workflow before execution
|
||||
|
||||
**Syntax**:
|
||||
```javascript
|
||||
validate_workflow({
|
||||
workflow: {
|
||||
nodes: [...], // Array of nodes
|
||||
connections: {...} // Connections object
|
||||
},
|
||||
options: {
|
||||
validateNodes: true, // Default: true
|
||||
validateConnections: true, // Default: true
|
||||
validateExpressions: true, // Default: true
|
||||
profile: "runtime" // For node validation
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**Validates**:
|
||||
- Node configurations
|
||||
- Connection validity (no broken references)
|
||||
- Expression syntax ({{ }} patterns)
|
||||
- Workflow structure (triggers, flow)
|
||||
- AI connections (8 types)
|
||||
|
||||
**Returns**: Comprehensive validation report with errors, warnings, suggestions
|
||||
|
||||
---
|
||||
|
||||
## Validation Loop Pattern
|
||||
|
||||
**Typical cycle**: 23s thinking, 58s fixing
|
||||
|
||||
```
|
||||
1. Configure node
|
||||
↓
|
||||
2. validate_node_operation (23s thinking about errors)
|
||||
↓
|
||||
3. Fix errors
|
||||
↓
|
||||
4. validate_node_operation again (58s fixing)
|
||||
↓
|
||||
5. Repeat until valid
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
// Iteration 1
|
||||
let config = {
|
||||
resource: "channel",
|
||||
operation: "create"
|
||||
};
|
||||
|
||||
const result1 = validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config,
|
||||
profile: "runtime"
|
||||
});
|
||||
// → Error: Missing "name"
|
||||
|
||||
// Iteration 2 (~58s later)
|
||||
config.name = "general";
|
||||
|
||||
const result2 = validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config,
|
||||
profile: "runtime"
|
||||
});
|
||||
// → Valid!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto-Sanitization System
|
||||
|
||||
**When it runs**: On ANY workflow update (create or update_partial)
|
||||
|
||||
**What it fixes** (automatically on ALL nodes):
|
||||
1. Binary operators (equals, contains, greaterThan) → removes `singleValue`
|
||||
2. Unary operators (isEmpty, isNotEmpty, true, false) → adds `singleValue: true`
|
||||
3. Invalid operator structures → corrects to proper format
|
||||
4. IF v2.2+ nodes → adds complete `conditions.options` metadata
|
||||
5. Switch v3.2+ nodes → adds complete `conditions.options` for all rules
|
||||
|
||||
**What it CANNOT fix**:
|
||||
- Broken connections (references to non-existent nodes)
|
||||
- Branch count mismatches (3 Switch rules but only 2 outputs)
|
||||
- Paradoxical corrupt states (API returns corrupt, rejects updates)
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
// Before auto-sanitization
|
||||
{
|
||||
"type": "boolean",
|
||||
"operation": "equals",
|
||||
"singleValue": true // ❌ Binary operators shouldn't have this
|
||||
}
|
||||
|
||||
// After auto-sanitization (automatic!)
|
||||
{
|
||||
"type": "boolean",
|
||||
"operation": "equals"
|
||||
// singleValue removed automatically
|
||||
}
|
||||
```
|
||||
|
||||
**Recovery tools**:
|
||||
- `cleanStaleConnections` operation - removes broken connections
|
||||
- `n8n_autofix_workflow` - preview/apply fixes
|
||||
|
||||
---
|
||||
|
||||
## Binary vs Unary Operators
|
||||
|
||||
**Binary operators** (compare two values):
|
||||
- equals, notEquals, contains, notContains
|
||||
- greaterThan, lessThan, startsWith, endsWith
|
||||
- **Must NOT have** `singleValue: true`
|
||||
|
||||
**Unary operators** (check single value):
|
||||
- isEmpty, isNotEmpty, true, false
|
||||
- **Must have** `singleValue: true`
|
||||
|
||||
**Auto-sanitization fixes these automatically!**
|
||||
|
||||
---
|
||||
|
||||
## Handling Validation Errors
|
||||
|
||||
### Process
|
||||
|
||||
```
|
||||
1. Read error message carefully
|
||||
2. Check if it's a known false positive
|
||||
3. Fix real errors
|
||||
4. Validate again
|
||||
5. Iterate until clean
|
||||
```
|
||||
|
||||
### Common Errors
|
||||
|
||||
**"Required field missing"**
|
||||
→ Add the field with appropriate value
|
||||
|
||||
**"Invalid value"**
|
||||
→ Check allowed values in essentials/documentation
|
||||
|
||||
**"Type mismatch"**
|
||||
→ Convert to correct type (string/number/boolean)
|
||||
|
||||
**"Cannot have singleValue"**
|
||||
→ Auto-sanitization will fix on next update
|
||||
|
||||
**"Missing operator metadata"**
|
||||
→ Auto-sanitization will fix on next update
|
||||
|
||||
### False Positives
|
||||
|
||||
Some validation warnings may be acceptable:
|
||||
- Optional best practices
|
||||
- Node-specific edge cases
|
||||
- Profile-dependent issues
|
||||
|
||||
Use **ai-friendly** profile to reduce false positives.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Do
|
||||
|
||||
- Use **runtime** profile for pre-deployment
|
||||
- Validate after every configuration change
|
||||
- Fix errors immediately (avg 58s)
|
||||
- Iterate validation loop
|
||||
- Trust auto-sanitization for operator issues
|
||||
- Use minimal profile for quick checks
|
||||
- Complete workflow activation manually in n8n UI (API/MCP cannot activate workflows)
|
||||
|
||||
### ❌ Don't
|
||||
|
||||
- Skip validation before deployment
|
||||
- Ignore error messages
|
||||
- Use strict profile during development (too many warnings)
|
||||
- Assume validation passed (check result)
|
||||
- Try to manually fix auto-sanitization issues
|
||||
|
||||
---
|
||||
|
||||
## Example: Complete Validation Workflow
|
||||
|
||||
```javascript
|
||||
// Step 1: Get node requirements
|
||||
validate_node_minimal({
|
||||
nodeType: "nodes-base.slack",
|
||||
config: {}
|
||||
});
|
||||
// → Know what's required
|
||||
|
||||
// Step 2: Configure node
|
||||
const config = {
|
||||
resource: "message",
|
||||
operation: "post",
|
||||
channel: "#general",
|
||||
text: "Hello!"
|
||||
};
|
||||
|
||||
// Step 3: Validate configuration
|
||||
const result = validate_node_operation({
|
||||
nodeType: "nodes-base.slack",
|
||||
config,
|
||||
profile: "runtime"
|
||||
});
|
||||
|
||||
// Step 4: Check result
|
||||
if (result.valid) {
|
||||
console.log("✅ Configuration valid!");
|
||||
} else {
|
||||
console.log("❌ Errors:", result.errors);
|
||||
// Fix and validate again
|
||||
}
|
||||
|
||||
// Step 5: Validate in workflow context
|
||||
validate_workflow({
|
||||
workflow: {
|
||||
nodes: [{...config as node...}],
|
||||
connections: {...}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Key Points**:
|
||||
1. Use **runtime** profile (balanced validation)
|
||||
2. Validation loop: validate → fix (58s) → validate again
|
||||
3. Auto-sanitization fixes operator structures automatically
|
||||
4. Binary operators ≠ singleValue, Unary operators = singleValue: true
|
||||
5. Iterate until validation passes
|
||||
|
||||
**Tool Selection**:
|
||||
- **validate_node_minimal**: Quick check
|
||||
- **validate_node_operation**: Full config validation (**use this!**)
|
||||
- **validate_workflow**: Complete workflow check
|
||||
|
||||
**Related**:
|
||||
- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes
|
||||
- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Build workflows
|
||||
395
skills/n8n-mcp-tools-expert/WORKFLOW_GUIDE.md
Normal file
395
skills/n8n-mcp-tools-expert/WORKFLOW_GUIDE.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
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):
|
||||
1. `addNode` - Add new node
|
||||
2. `removeNode` - Remove node by ID or name
|
||||
3. `updateNode` - Update node properties
|
||||
4. `moveNode` - Change position
|
||||
5. `enableNode` - Enable disabled node
|
||||
6. `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:
|
||||
```javascript
|
||||
{
|
||||
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:
|
||||
```javascript
|
||||
{
|
||||
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:
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
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:
|
||||
```javascript
|
||||
{
|
||||
type: "cleanStaleConnections"
|
||||
}
|
||||
```
|
||||
|
||||
**Best-effort mode** - Apply what works:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
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:
|
||||
1. Open the workflow in n8n UI (provide workflow ID)
|
||||
2. Review the workflow configuration
|
||||
3. Manually activate the workflow using the activation toggle
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns from Telemetry
|
||||
|
||||
### Pattern 1: Edit → Validate (7,841 occurrences)
|
||||
|
||||
```javascript
|
||||
// Edit
|
||||
n8n_update_partial_workflow({...})
|
||||
// ↓ 23s (thinking about what to validate)
|
||||
// Validate
|
||||
n8n_validate_workflow({id})
|
||||
```
|
||||
|
||||
### Pattern 2: Validate → Fix (7,266 occurrences)
|
||||
|
||||
```javascript
|
||||
// Validate
|
||||
n8n_validate_workflow({id})
|
||||
// ↓ 58s (fixing errors)
|
||||
// Fix
|
||||
n8n_update_partial_workflow({...})
|
||||
```
|
||||
|
||||
### Pattern 3: Iterative Building (31,464 occurrences)
|
||||
|
||||
```javascript
|
||||
update → update → update → ... (56s avg between edits)
|
||||
```
|
||||
|
||||
**This shows**: Workflows are built **iteratively**, not in one shot!
|
||||
|
||||
---
|
||||
|
||||
## Retrieval Tools
|
||||
|
||||
### n8n_get_workflow
|
||||
```javascript
|
||||
n8n_get_workflow({id: "workflow-id"})
|
||||
// Returns: Complete workflow JSON
|
||||
```
|
||||
|
||||
### n8n_get_workflow_structure
|
||||
```javascript
|
||||
n8n_get_workflow_structure({id: "workflow-id"})
|
||||
// Returns: Nodes + connections only (no parameters)
|
||||
```
|
||||
|
||||
### n8n_get_workflow_minimal
|
||||
```javascript
|
||||
n8n_get_workflow_minimal({id: "workflow-id"})
|
||||
// Returns: ID, name, active, tags only (fast!)
|
||||
```
|
||||
|
||||
### n8n_list_workflows
|
||||
```javascript
|
||||
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**:
|
||||
1. **n8n_update_partial_workflow** is most-used tool (38,287 uses, 99.0% success)
|
||||
2. Workflows built **iteratively** (56s avg between edits)
|
||||
3. Use **smart parameters** (branch="true", case=0) for clarity
|
||||
4. **AI connections** supported (8 types with sourceOutput)
|
||||
5. **Auto-sanitization** runs on all operations
|
||||
6. Validate frequently (7,841 edit → validate patterns)
|
||||
|
||||
**Related**:
|
||||
- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes to add
|
||||
- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate workflows
|
||||
Reference in New Issue
Block a user