feat: Update skills for n8n-mcp unified tool API (v1.1.0)

BREAKING: Updated all skills to reflect n8n-mcp tool consolidation:

## Tool API Changes
- get_node_essentials → get_node({detail: "standard"})
- get_node_info → get_node({detail: "full"})
- get_node_documentation → get_node({mode: "docs"})
- search_node_properties → get_node({mode: "search_properties"})
- validate_node_minimal → validate_node({mode: "minimal"})
- validate_node_operation → validate_node({mode: "full"})
- get_property_dependencies → REMOVED (use get_node modes)

## New Features Documented
- Workflow activation via API (activateWorkflow/deactivateWorkflow operations)
- n8n_deploy_template - deploy templates directly to n8n
- n8n_workflow_versions - version history and rollback
- n8n_test_workflow - trigger execution
- n8n_executions - manage executions
- Smart parameters (branch, case) for IF/Switch connections
- Intent parameter for better AI responses

## Documentation Updates
- Added YouTube video introduction with thumbnail
- Added GitHub stars badge (1.2k milestone)
- Added build.sh script for dist packaging
- Fixed "5 skills" → "7 skills" inconsistency in README

## Files Updated
- n8n-mcp-tools-expert: Complete rewrite of SKILL.md, SEARCH_GUIDE.md,
  VALIDATION_GUIDE.md, WORKFLOW_GUIDE.md
- n8n-node-configuration: Updated SKILL.md, DEPENDENCIES.md
- n8n-validation-expert: Updated SKILL.md, ERROR_CATALOG.md, FALSE_POSITIVES.md
- n8n-workflow-patterns: Updated SKILL.md, README.md
- README.md, CLAUDE.md: Modernized documentation

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Romuald Członkowski
2026-01-08 15:37:57 +01:00
parent ec350daa6e
commit d9c2872029
27 changed files with 2393 additions and 610 deletions

View File

@@ -1,6 +1,6 @@
{ {
"name": "n8n-mcp-skills", "name": "n8n-mcp-skills",
"version": "1.0.0", "version": "1.1.0",
"description": "Expert skills for building n8n workflows with n8n-mcp", "description": "Expert skills for building n8n workflows with n8n-mcp",
"author": { "author": {
"name": "Romuald Członkowski", "name": "Romuald Członkowski",

180
CLAUDE.md
View File

@@ -8,10 +8,10 @@ This is the **n8n-skills** repository - a collection of Claude Code skills desig
**Repository**: https://github.com/czlonkowski/n8n-skills **Repository**: https://github.com/czlonkowski/n8n-skills
**Purpose**: Create 5 complementary meta-skills that provide expert guidance on using n8n-mcp MCP tools effectively for building n8n workflows. **Purpose**: 7 complementary skills that provide expert guidance on using n8n-mcp MCP tools effectively for building n8n workflows.
**Architecture**: **Architecture**:
- **n8n-mcp MCP Server**: Provides data access (525 nodes, validation, templates) - **n8n-mcp MCP Server**: Provides data access (800+ nodes, validation, templates, workflow management)
- **Claude Skills**: Provides expert guidance on HOW to use MCP tools - **Claude Skills**: Provides expert guidance on HOW to use MCP tools
- **Together**: Expert workflow builder with progressive disclosure - **Together**: Expert workflow builder with progressive disclosure
@@ -19,120 +19,91 @@ This is the **n8n-skills** repository - a collection of Claude Code skills desig
``` ```
n8n-skills/ n8n-skills/
├── README.md # Project overview ├── README.md # Project overview with video
├── LICENSE # MIT License ├── LICENSE # MIT License
├── skills/ # (To be created) Individual skill implementations ├── skills/ # Individual skill implementations
│ ├── n8n-expression-syntax/ │ ├── n8n-expression-syntax/
│ ├── n8n-mcp-tools-expert/ │ ├── n8n-mcp-tools-expert/
│ ├── n8n-workflow-patterns/ │ ├── n8n-workflow-patterns/
│ ├── n8n-validation-expert/ │ ├── n8n-validation-expert/
── n8n-node-configuration/ ── n8n-node-configuration/
├── evaluations/ # (To be created) Test scenarios for each skill │ ├── n8n-code-javascript/
├── docs/ # Documentation │ └── n8n-code-python/
│ └── SKILLS_IMPLEMENTATION_GUIDE.md # Complete implementation guide ├── evaluations/ # Test scenarios for each skill
── .gitignore # Git ignore (excludes docs/) ── docs/ # Documentation
├── dist/ # Distribution packages
└── .claude-plugin/ # Claude Code plugin configuration
``` ```
## Implementation Timeline ## The 7 Skills
- **Week 1**: n8n Expression Syntax (PoC - 4 files, ~350 lines)
- **Week 2**: n8n MCP Tools Expert + n8n Workflow Patterns
- **Week 3**: n8n Validation Expert + n8n Node Configuration
- **Week 4**: Testing, refinement, documentation
- **Week 5-6**: Distribution, plugin packaging
## Five Skills to Implement
### 1. n8n Expression Syntax ### 1. n8n Expression Syntax
**Priority**: Foundation (Week 1)
- Teaches correct n8n expression syntax ({{}} patterns) - Teaches correct n8n expression syntax ({{}} patterns)
- Covers common mistakes and fixes - Covers common mistakes and fixes
- Files: SKILL.md, COMMON_MISTAKES.md, EXAMPLES.md - Critical gotcha: Webhook data under `$json.body`
### 2. n8n MCP Tools Expert ### 2. n8n MCP Tools Expert (HIGHEST PRIORITY)
**Priority**: Highest (fixes 20% failure rate)
- Teaches how to use n8n-mcp MCP tools effectively - Teaches how to use n8n-mcp MCP tools effectively
- Covers node discovery, validation, workflow management - Covers unified tools: `get_node`, `validate_node`, `search_nodes`
- Files: SKILL.md, SEARCH_GUIDE.md, VALIDATION_GUIDE.md, WORKFLOW_GUIDE.md - Workflow management with `n8n_update_partial_workflow`
- New: `n8n_deploy_template`, `n8n_workflow_versions`, `activateWorkflow`
### 3. n8n Workflow Patterns ### 3. n8n Workflow Patterns
**Priority**: High (addresses 813 webhook searches)
- Teaches proven workflow architectural patterns - Teaches proven workflow architectural patterns
- 5 patterns from 31,917 real workflows - 5 patterns: webhook, HTTP API, database, AI, scheduled
- Files: SKILL.md + 5 pattern files (webhook, http, database, ai, scheduled)
### 4. n8n Validation Expert ### 4. n8n Validation Expert
**Priority**: Medium
- Interprets validation errors and guides fixing - Interprets validation errors and guides fixing
- Handles false positives and validation loops - Handles false positives and validation loops
- Files: SKILL.md, ERROR_CATALOG.md, FALSE_POSITIVES.md - Auto-fix with `n8n_autofix_workflow`
### 5. n8n Node Configuration ### 5. n8n Node Configuration
**Priority**: Medium
- Operation-aware node configuration guidance - Operation-aware node configuration guidance
- Property dependencies and common patterns - Property dependencies and common patterns
- Files: SKILL.md, DEPENDENCIES.md, OPERATION_PATTERNS.md
## Data-Driven Design ### 6. n8n Code JavaScript
- Write JavaScript in n8n Code nodes
- Data access patterns, `$helpers`, DateTime
These skills are based on telemetry analysis of: ### 7. n8n Code Python
- 447,557 real MCP tool usage events - Write Python in n8n Code nodes
- 31,917 workflows created - Limitations awareness (no external libraries)
- 19,113 validation errors
- 15,107 validation feedback loops
## Skill Structure ## Key MCP Tools
Each skill follows this format: The n8n-mcp server provides these unified tools:
```markdown ### Node Discovery
--- - `search_nodes` - Find nodes by keyword
name: Skill Name - `get_node` - Unified node info with detail levels (minimal, standard, full) and modes (info, docs, search_properties, versions)
description: When to use this skill. Use when [trigger conditions].
---
# Skill Name ### Validation
- `validate_node` - Unified validation with modes (minimal, full) and profiles (runtime, ai-friendly, strict)
- `validate_workflow` - Complete workflow validation
## [Content organized in sections] ### Workflow Management
``` - `n8n_create_workflow` - Create new workflows
- `n8n_update_partial_workflow` - Incremental updates (17 operation types including `activateWorkflow`)
- `n8n_validate_workflow` - Validate by ID
- `n8n_autofix_workflow` - Auto-fix common issues
- `n8n_deploy_template` - Deploy template to n8n instance
- `n8n_workflow_versions` - Version history and rollback
- `n8n_test_workflow` - Test execution
- `n8n_executions` - Manage executions
## Development Approach ### Templates
- `search_templates` - Multiple modes (keyword, by_nodes, by_task, by_metadata)
- `get_template` - Get template details
**Evaluation-Driven Development**: ### Guides
1. Create 3+ evaluations FIRST for each skill - `tools_documentation` - Meta-documentation for all tools
2. Establish baseline (test without skill) - `ai_agents_guide` - AI agent workflow guidance
3. Write minimal SKILL.md (under 500 lines)
4. Test against evaluations
5. Iterate until 100% pass
6. Add reference files as needed
## Key Implementation Guidelines ## Important Patterns
### File Organization
- Keep SKILL.md files under 500 lines
- Split complex content into reference files
- Use markdown with clear sections
- Link between related files
### Skill Activation
Skills activate automatically when queries match their description triggers:
- "How do I write n8n expressions?" → n8n Expression Syntax
- "Find me a Slack node" → n8n MCP Tools Expert
- "Build a webhook workflow" → n8n Workflow Patterns
### Cross-Skill Integration
Skills are designed to work together:
- Use n8n Workflow Patterns to identify structure
- Use n8n MCP Tools Expert to find nodes
- Use n8n Node Configuration for setup
- Use n8n Expression Syntax for data mapping
- Use n8n Validation Expert to validate
## Important Patterns from Telemetry
### Most Common Tool Usage Pattern ### Most Common Tool Usage Pattern
``` ```
search_nodes → get_node_essentials (9,835 occurrences, 18s avg) search_nodes → get_node (18s avg between steps)
``` ```
### Most Common Validation Pattern ### Most Common Validation Pattern
@@ -151,34 +122,25 @@ Avg 56 seconds between edits
### When Adding New Skills ### When Adding New Skills
1. Create skill directory under `skills/` 1. Create skill directory under `skills/`
2. Follow the structure in `docs/SKILLS_IMPLEMENTATION_GUIDE.md` 2. Write SKILL.md with frontmatter
3. Write SKILL.md with frontmatter 3. Add reference files as needed
4. Add reference files as needed 4. Create 3+ evaluations in `evaluations/`
5. Create 3+ evaluations in `evaluations/` 5. Test thoroughly before committing
6. Test thoroughly before committing
### When Creating Evaluations ### Skill Activation
Place in `evaluations/[skill-name]/eval-NNN-description.json` Skills activate automatically when queries match their description triggers:
- "How do I write n8n expressions?" → n8n Expression Syntax
- "Find me a Slack node" → n8n MCP Tools Expert
- "Build a webhook workflow" → n8n Workflow Patterns
Format: ### Cross-Skill Integration
```json Skills are designed to work together:
{ - Use n8n Workflow Patterns to identify structure
"id": "skill-NNN", - Use n8n MCP Tools Expert to find nodes
"skills": ["skill-name"], - Use n8n Node Configuration for setup
"query": "User question or scenario", - Use n8n Expression Syntax for data mapping
"expected_behavior": [ - Use n8n Code JavaScript/Python for custom logic
"List of expected behaviors", - Use n8n Validation Expert to validate
"What skill should do",
"What content it should reference"
]
}
```
### Git Workflow
- Work on feature branches
- Commit frequently with clear messages
- Test skills before pushing
- Keep main branch stable
## Requirements ## Requirements
@@ -188,9 +150,9 @@ Format:
## Distribution ## Distribution
Final distribution will be: Available as:
1. **GitHub Repository**: Full source code and documentation 1. **GitHub Repository**: Full source code and documentation
2. **Claude Code Plugin**: Packaged skills with plugin.json 2. **Claude Code Plugin**: `npm install @anthropic/claude-code-plugin-n8n-skills`
3. **Individual Skill Uploads**: For Claude.ai users 3. **Individual Skill Uploads**: For Claude.ai users
## Credits ## Credits
@@ -202,4 +164,4 @@ Part of the n8n-mcp project.
## License ## License
MIT License - See LICENSE file for details. MIT License - See LICENSE file for details.
- Add to every commit and PR: Concieved by Romuald Członkowski - and then link to www.aiadvisors.pl/en. Don't add it in conversations - Add to every commit and PR: Conceived by Romuald Członkowski - and then link to www.aiadvisors.pl/en. Don't add it in conversations

View File

@@ -2,14 +2,19 @@
**Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server** **Expert Claude Code skills for building flawless n8n workflows using the n8n-mcp MCP server**
[![GitHub stars](https://img.shields.io/github/stars/czlonkowski/n8n-skills?style=social)](https://github.com/czlonkowski/n8n-skills)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![n8n-mcp](https://img.shields.io/badge/n8n--mcp-compatible-green.svg)](https://github.com/czlonkowski/n8n-mcp) [![n8n-mcp](https://img.shields.io/badge/n8n--mcp-compatible-green.svg)](https://github.com/czlonkowski/n8n-mcp)
## Watch the Introduction Video
[![n8n Skills Introduction](skills.png)](https://youtu.be/e6VvRqmUY2Y?si=6Igply3cadjO6Xx0)
--- ---
## 🎯 What is this? ## 🎯 What is this?
This repository contains 5 complementary **Claude Code skills** that teach AI assistants how to build production-ready n8n workflows using the [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) MCP server. This repository contains **7 complementary Claude Code skills** that teach AI assistants how to build production-ready n8n workflows using the [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) MCP server.
### Why These Skills Exist ### Why These Skills Exist

51
build.sh Executable file
View File

@@ -0,0 +1,51 @@
#!/bin/bash
# Build script for n8n-skills distribution packages
# Creates zip files for both Claude.ai (individual skills) and Claude Code (bundle)
set -e
DIST_DIR="dist"
VERSION="1.1.0"
echo "🔨 Building n8n-skills distribution packages..."
# Create dist directory if it doesn't exist
mkdir -p "$DIST_DIR"
# Remove old zips
echo "🗑️ Removing old zip files..."
rm -f "$DIST_DIR"/*.zip
# Build individual skill zips (for Claude.ai)
echo "📦 Building individual skill zips for Claude.ai..."
SKILLS=(
"n8n-expression-syntax"
"n8n-mcp-tools-expert"
"n8n-workflow-patterns"
"n8n-validation-expert"
"n8n-node-configuration"
)
for skill in "${SKILLS[@]}"; do
echo " - $skill"
zip -rq "$DIST_DIR/${skill}-v${VERSION}.zip" "skills/${skill}/" -x "*.DS_Store"
done
# Build complete bundle (for Claude Code)
echo "📦 Building complete bundle for Claude Code..."
zip -rq "$DIST_DIR/n8n-mcp-skills-v${VERSION}.zip" \
.claude-plugin/ \
README.md \
LICENSE \
skills/ \
-x "*.DS_Store"
# Show results
echo ""
echo "✅ Build complete! Files in $DIST_DIR/:"
echo ""
ls -lh "$DIST_DIR"/*.zip
echo ""
echo "📊 Package sizes:"
du -h "$DIST_DIR"/*.zip

28
dist/README.md vendored
View File

@@ -6,7 +6,7 @@ This folder contains distribution packages for different Claude platforms.
### Complete Bundle (Recommended) ### Complete Bundle (Recommended)
- **`n8n-mcp-skills-v1.0.0.zip`** (168 KB) - All 7 skills in one package - **`n8n-mcp-skills-v1.1.0.zip`** (172 KB) - All 7 skills in one package
**Includes:** **Includes:**
- Skill #1: n8n Expression Syntax - Skill #1: n8n Expression Syntax
@@ -23,18 +23,18 @@ This folder contains distribution packages for different Claude platforms.
/plugin install czlonkowski/n8n-skills /plugin install czlonkowski/n8n-skills
# Or install from local file # Or install from local file
/plugin install /path/to/n8n-mcp-skills-v1.0.0.zip /plugin install /path/to/n8n-mcp-skills-v1.1.0.zip
``` ```
### For Claude.ai Users (Individual Skills) ### For Claude.ai Users (Individual Skills)
Upload each skill separately via Settings → Capabilities → Skills (bottom of page): Upload each skill separately via Settings → Capabilities → Skills (bottom of page):
- `n8n-expression-syntax-v1.0.0.zip` - n8n expression syntax and common patterns - `n8n-expression-syntax-v1.1.0.zip` - n8n expression syntax and common patterns
- `n8n-mcp-tools-expert-v1.0.0.zip` - Expert guide for using n8n-mcp tools (recommended to install first) - `n8n-mcp-tools-expert-v1.1.0.zip` - Expert guide for using n8n-mcp tools (recommended to install first)
- `n8n-workflow-patterns-v1.0.0.zip` - 5 proven workflow architectural patterns - `n8n-workflow-patterns-v1.1.0.zip` - 5 proven workflow architectural patterns
- `n8n-validation-expert-v1.0.0.zip` - Validation error interpretation and fixing - `n8n-validation-expert-v1.1.0.zip` - Validation error interpretation and fixing
- `n8n-node-configuration-v1.0.0.zip` - Operation-aware node configuration - `n8n-node-configuration-v1.1.0.zip` - Operation-aware node configuration
**Installation:** **Installation:**
1. Go to Settings → Capabilities → Skills (bottom of page) 1. Go to Settings → Capabilities → Skills (bottom of page)
@@ -49,7 +49,7 @@ Upload each skill separately via Settings → Capabilities → Skills (bottom of
| Platform | Package | What You Get | | Platform | Package | What You Get |
|----------|---------|--------------| |----------|---------|--------------|
| **Claude.ai** | Individual zips | 5 core skills (upload separately) | | **Claude.ai** | Individual zips | 5 core skills (upload separately) |
| **Claude Code** | Complete bundle (n8n-mcp-skills-v1.0.0.zip) | All 7 skills at once | | **Claude Code** | Complete bundle (n8n-mcp-skills-v1.1.0.zip) | All 7 skills at once |
| **Claude API** | Complete bundle | All 7 skills (extract skills/ folder) | | **Claude API** | Complete bundle | All 7 skills (extract skills/ folder) |
**Note:** Code skills (#6 JavaScript, #7 Python) are only in the complete bundle. **Note:** Code skills (#6 JavaScript, #7 Python) are only in the complete bundle.
@@ -60,12 +60,12 @@ Upload each skill separately via Settings → Capabilities → Skills (bottom of
``` ```
dist/ dist/
├── n8n-mcp-skills-v1.0.0.zip (168 KB) ★ RECOMMENDED ├── n8n-mcp-skills-v1.1.0.zip (168 KB) ★ RECOMMENDED
├── n8n-expression-syntax-v1.0.0.zip (11 KB) ├── n8n-expression-syntax-v1.1.0.zip (11 KB)
├── n8n-mcp-tools-expert-v1.0.0.zip (15 KB) ├── n8n-mcp-tools-expert-v1.1.0.zip (15 KB)
├── n8n-workflow-patterns-v1.0.0.zip (35 KB) ├── n8n-workflow-patterns-v1.1.0.zip (35 KB)
├── n8n-validation-expert-v1.0.0.zip (18 KB) ├── n8n-validation-expert-v1.1.0.zip (18 KB)
├── n8n-node-configuration-v1.0.0.zip (17 KB) ├── n8n-node-configuration-v1.1.0.zip (17 KB)
└── README.md (this file) └── README.md (this file)
``` ```

Binary file not shown.

BIN
dist/n8n-mcp-tools-expert-v1.1.0.zip vendored Normal file

Binary file not shown.

Binary file not shown.

BIN
dist/n8n-node-configuration-v1.1.0.zip vendored Normal file

Binary file not shown.

Binary file not shown.

BIN
dist/n8n-validation-expert-v1.1.0.zip vendored Normal file

Binary file not shown.

File diff suppressed because it is too large Load Diff

BIN
skills.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.0 MiB

View File

@@ -6,7 +6,7 @@ Complete guide for finding and understanding n8n nodes.
## search_nodes (START HERE!) ## search_nodes (START HERE!)
**Success Rate**: 99.9% | **Speed**: <20ms **Speed**: <20ms
**Use when**: You know what you're looking for (keyword, service, use case) **Use when**: You know what you're looking for (keyword, service, use case)
@@ -15,7 +15,9 @@ Complete guide for finding and understanding n8n nodes.
search_nodes({ search_nodes({
query: "slack", // Required: search keywords query: "slack", // Required: search keywords
mode: "OR", // Optional: OR (default), AND, FUZZY mode: "OR", // Optional: OR (default), AND, FUZZY
limit: 20 // Optional: max results (default 20, max 100) limit: 20, // Optional: max results (default 20)
source: "all", // Optional: all, core, community, verified
includeExamples: false // Optional: include template configs
}) })
``` ```
@@ -38,24 +40,38 @@ search_nodes({
**Tips**: **Tips**:
- Common searches: webhook, http, database, email, slack, google, ai - Common searches: webhook, http, database, email, slack, google, ai
- OR mode (default): matches any word - `OR` mode (default): matches any word
- AND mode: requires all words - `AND` mode: requires all words
- FUZZY mode: typo-tolerant (finds "slak" Slack) - `FUZZY` mode: typo-tolerant (finds "slak" Slack)
- Use `source: "core"` for only built-in nodes
- Use `includeExamples: true` for real-world configs
--- ---
## get_node_essentials (RECOMMENDED!) ## get_node (UNIFIED NODE INFORMATION)
**Success Rate**: 91.7% | **Speed**: <10ms | **Size**: ~5KB The `get_node` tool provides all node information with different detail levels and modes.
### Detail Levels (mode="info")
| Detail | Tokens | Use When |
|--------|--------|----------|
| `minimal` | ~200 | Quick metadata check |
| `standard` | ~1-2K | **Most use cases (DEFAULT)** |
| `full` | ~3-8K | Complex debugging only |
### Standard Detail (RECOMMENDED)
**Speed**: <10ms | **Size**: ~1-2K tokens
**Use when**: You've found the node and need configuration details **Use when**: You've found the node and need configuration details
**Syntax**:
```javascript ```javascript
get_node_essentials({ get_node({
nodeType: "nodes-base.slack", // Required: SHORT prefix format nodeType: "nodes-base.slack", // Required: SHORT prefix format
includeExamples: true // Optional: get real template configs includeExamples: true // Optional: get real template configs
}) })
// detail="standard" is the default
``` ```
**Returns**: **Returns**:
@@ -64,105 +80,161 @@ get_node_essentials({
- Metadata (isAITool, isTrigger, hasCredentials) - Metadata (isAITool, isTrigger, hasCredentials)
- Real examples from templates (if includeExamples: true) - Real examples from templates (if includeExamples: true)
**Why use this**: ### Minimal Detail
- 5KB vs 100KB+ (get_node_info)
- 91.7% success vs 80%
- <10ms vs slower
- Focused data (no information overload)
--- **Speed**: <5ms | **Size**: ~200 tokens
## get_node_info (USE SPARINGLY!) **Use when**: Just need basic metadata
**Success Rate**: 80% | **Size**: 100KB+
**Use when**:
- Debugging complex configuration
- Need complete property schema
- Exploring advanced features
**Syntax**:
```javascript ```javascript
get_node_info({ get_node({
nodeType: "nodes-base.httpRequest" nodeType: "nodes-base.slack",
detail: "minimal"
}) })
``` ```
**Warning**: 20% failure rate! Use get_node_essentials instead for most cases. **Returns**: nodeType, displayName, description, category
**Better alternatives**: ### Full Detail (USE SPARINGLY)
1. get_node_essentials - operations list
2. get_node_documentation - readable docs
3. search_node_properties - specific property
--- **Speed**: <100ms | **Size**: ~3-8K tokens
## list_nodes (BROWSE BY CATEGORY) **Use when**: Debugging complex configuration, need complete schema
**Success Rate**: 99.6% | **Speed**: <20ms
**Use when**: Exploring by category or listing all nodes
**Syntax**:
```javascript ```javascript
list_nodes({ get_node({
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", nodeType: "nodes-base.httpRequest",
query: "auth" // Find authentication properties detail: "full"
}) })
``` ```
**Returns**: Property paths and descriptions matching query **Warning**: Large payload! Use `standard` for most cases.
**Common searches**: auth, header, body, json, url, method
--- ---
## get_node_documentation (READABLE DOCS) ## get_node Modes
**Coverage**: 88% of nodes (470/537) ### mode="docs" (READABLE DOCUMENTATION)
**Use when**: Need human-readable documentation with examples **Use when**: Need human-readable documentation with examples
**Syntax**:
```javascript ```javascript
get_node_documentation({ get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack",
mode: "docs"
}) })
``` ```
**Returns**: Formatted docs with: **Returns**: Formatted markdown with:
- Usage examples - Usage examples
- Authentication guide - Authentication guide
- Common patterns - Common patterns
- Best practices - Best practices
**Note**: Better than raw schema for learning! **Better than raw schema for learning!**
### mode="search_properties" (FIND SPECIFIC FIELDS)
**Use when**: Looking for specific property in a node
```javascript
get_node({
nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "auth", // Required for this mode
maxPropertyResults: 20 // Optional: default 20
})
```
**Returns**: Property paths and descriptions matching query
**Common searches**: auth, header, body, json, url, method, credential
### mode="versions" (VERSION HISTORY)
**Use when**: Need to check node version history
```javascript
get_node({
nodeType: "nodes-base.executeWorkflow",
mode: "versions"
})
```
**Returns**: Version history with breaking changes flags
### mode="compare" (COMPARE VERSIONS)
**Use when**: Need to see differences between versions
```javascript
get_node({
nodeType: "nodes-base.httpRequest",
mode: "compare",
fromVersion: "3.0",
toVersion: "4.1" // Optional: defaults to latest
})
```
**Returns**: Property-level changes between versions
### mode="breaking" (BREAKING CHANGES ONLY)
**Use when**: Checking for breaking changes before upgrades
```javascript
get_node({
nodeType: "nodes-base.httpRequest",
mode: "breaking",
fromVersion: "3.0"
})
```
**Returns**: Only breaking changes (not all changes)
### mode="migrations" (AUTO-MIGRATABLE)
**Use when**: Checking what can be auto-migrated
```javascript
get_node({
nodeType: "nodes-base.httpRequest",
mode: "migrations",
fromVersion: "3.0"
})
```
**Returns**: Changes that can be automatically migrated
---
## Additional Parameters
### includeTypeInfo
Add type structure metadata (validation rules, JS types)
```javascript
get_node({
nodeType: "nodes-base.if",
includeTypeInfo: true // Adds ~80-120 tokens per property
})
```
Use for complex nodes like filter, resourceMapper
### includeExamples
Include real-world configuration examples from templates
```javascript
get_node({
nodeType: "nodes-base.slack",
includeExamples: true // Adds ~200-400 tokens per example
})
```
Only works with `mode: "info"` and `detail: "standard"`
--- ---
@@ -174,14 +246,14 @@ search_nodes({query: "slack"})
→ Returns: nodes-base.slack → Returns: nodes-base.slack
Step 2: Get Operations (18s avg thinking time) Step 2: Get Operations (18s avg thinking time)
get_node_essentials({ get_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
includeExamples: true includeExamples: true
}) })
→ Returns: operations list + example configs → Returns: operations list + example configs
Step 3: Validate Config Step 3: Validate Config
validate_node_operation({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config: {resource: "channel", operation: "create"}, config: {resource: "channel", operation: "create"},
profile: "runtime" profile: "runtime"
@@ -192,21 +264,23 @@ Step 4: Use in Workflow
(Configuration ready!) (Configuration ready!)
``` ```
**Most common pattern**: search essentials (18s average) **Most common pattern**: search get_node (18s average)
--- ---
## Quick Comparison ## Quick Comparison
| Tool | When to Use | Success | Speed | Size | | Tool/Mode | When to Use | Speed | Size |
|------|-------------|---------|-------|------| |-----------|-------------|-------|------|
| search_nodes | Find by keyword | 99.9% | <20ms | Small | | `search_nodes` | Find by keyword | <20ms | Small |
| get_node_essentials | Get config | 91.7% | <10ms | 5KB | | `get_node (standard)` | **Get config (DEFAULT)** | <10ms | 1-2K |
| get_node_info | Full schema | 80% | Slow | 100KB+ | | `get_node (minimal)` | Quick metadata | <5ms | 200 |
| list_nodes | Browse category | 99.6% | <20ms | Small | | `get_node (full)` | Complex debugging | <100ms | 3-8K |
| get_node_documentation | Learn usage | N/A | Fast | Medium | | `get_node (docs)` | Learn usage | Fast | Medium |
| `get_node (search_properties)` | Find specific field | Fast | Small |
| `get_node (versions)` | Check versions | Fast | Small |
**Best Practice**: search essentials validate **Best Practice**: search get_node(standard) validate
--- ---
@@ -229,13 +303,71 @@ Step 4: Use in Workflow
**Conversion**: search_nodes returns BOTH formats: **Conversion**: search_nodes returns BOTH formats:
```javascript ```javascript
{ {
"nodeType": "nodes-base.slack", // Use with essentials "nodeType": "nodes-base.slack", // Use with get_node, validate_node
"workflowNodeType": "n8n-nodes-base.slack" // Use with create_workflow "workflowNodeType": "n8n-nodes-base.slack" // Use with n8n_create_workflow
} }
``` ```
--- ---
## Examples
### Find and Configure HTTP Request
```javascript
// Step 1: Search
search_nodes({query: "http request"})
// Step 2: Get standard info
get_node({nodeType: "nodes-base.httpRequest"})
// Step 3: Find auth options
get_node({
nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "authentication"
})
// Step 4: Validate config
validate_node({
nodeType: "nodes-base.httpRequest",
config: {method: "POST", url: "https://api.example.com"},
profile: "runtime"
})
```
### Explore AI Nodes
```javascript
// Find all AI-related nodes
search_nodes({query: "ai agent", source: "all"})
// Get AI Agent documentation
get_node({nodeType: "nodes-langchain.agent", mode: "docs"})
// Get configuration details with examples
get_node({
nodeType: "nodes-langchain.agent",
includeExamples: true
})
```
### Check Version Compatibility
```javascript
// See all versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})
// Check breaking changes from v1 to v2
get_node({
nodeType: "nodes-base.executeWorkflow",
mode: "breaking",
fromVersion: "1.0"
})
```
---
## Related ## Related
- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate node configs - [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Validate node configs

View File

@@ -11,13 +11,13 @@ Master guide for using n8n-mcp MCP server tools to build workflows.
## Tool Categories ## Tool Categories
n8n-mcp provides **40+ tools** organized into categories: n8n-mcp provides tools organized into categories:
1. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md) 1. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md)
2. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) 2. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md)
3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) 3. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
4. **Template Library** - Search and access 2,653 real workflows 4. **Template Library** - Search and deploy 2,700+ real workflows
5. **Documentation** - Get tool and node documentation 5. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
--- ---
@@ -25,14 +25,15 @@ n8n-mcp provides **40+ tools** organized into categories:
### Most Used Tools (by success rate) ### Most Used Tools (by success rate)
| Tool | Use When | Success Rate | Speed | | Tool | Use When | Speed |
|------|----------|--------------|-------| |------|----------|-------|
| `search_nodes` | Finding nodes by keyword | 99.9% | <20ms | | `search_nodes` | Finding nodes by keyword | <20ms |
| `get_node_essentials` | Understanding node operations | 91.7% | <10ms | | `get_node` | Understanding node operations (detail="standard") | <10ms |
| `validate_node_operation` | Checking configurations | Varies | <100ms | | `validate_node` | Checking configurations (mode="full") | <100ms |
| `n8n_create_workflow` | Creating workflows | 96.8% | 100-500ms | | `n8n_create_workflow` | Creating workflows | 100-500ms |
| `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 99.0% | 50-200ms | | `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 50-200ms |
| `validate_workflow` | Checking complete workflow | 95.5% | 100-500ms | | `validate_workflow` | Checking complete workflow | 100-500ms |
| `n8n_deploy_template` | Deploy template to n8n instance | 200-500ms |
--- ---
@@ -43,8 +44,8 @@ n8n-mcp provides **40+ tools** organized into categories:
**Workflow**: **Workflow**:
``` ```
1. search_nodes({query: "keyword"}) 1. search_nodes({query: "keyword"})
2. get_node_essentials({nodeType: "nodes-base.name"}) 2. get_node({nodeType: "nodes-base.name"})
3. [Optional] get_node_documentation({nodeType: "nodes-base.name"}) 3. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})
``` ```
**Example**: **Example**:
@@ -53,19 +54,23 @@ n8n-mcp provides **40+ tools** organized into categories:
search_nodes({query: "slack"}) search_nodes({query: "slack"})
// Returns: nodes-base.slack // Returns: nodes-base.slack
// Step 2: Get details (18s avg between steps) // Step 2: Get details
get_node_essentials({nodeType: "nodes-base.slack"}) get_node({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples // Returns: operations, properties, examples (standard detail)
// Step 3: Get readable documentation
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// Returns: markdown documentation
``` ```
**Common pattern**: search essentials (18s average) **Common pattern**: search get_node (18s average)
### Validating Configuration ### Validating Configuration
**Workflow**: **Workflow**:
``` ```
1. validate_node_minimal({nodeType, config: {}}) - Check required fields 1. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation 2. validate_node({nodeType, config, profile: "runtime"}) - Full validation
3. [Repeat] Fix errors, validate again 3. [Repeat] Fix errors, validate again
``` ```
@@ -79,6 +84,7 @@ get_node_essentials({nodeType: "nodes-base.slack"})
2. n8n_validate_workflow({id}) 2. n8n_validate_workflow({id})
3. n8n_update_partial_workflow({id, operations: [...]}) 3. n8n_update_partial_workflow({id, operations: [...]})
4. n8n_validate_workflow({id}) again 4. n8n_validate_workflow({id}) again
5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})
``` ```
**Common pattern**: iterative updates (56s average between edits) **Common pattern**: iterative updates (56s average between edits)
@@ -100,11 +106,9 @@ get_node_essentials({nodeType: "nodes-base.slack"})
**Tools that use this**: **Tools that use this**:
- search_nodes (returns this format) - search_nodes (returns this format)
- get_node_essentials - get_node
- get_node_info - validate_node
- validate_node_minimal - validate_workflow
- validate_node_operation
- get_property_dependencies
### Format 2: Workflow Tools ### Format 2: Workflow Tools
```javascript ```javascript
@@ -118,7 +122,6 @@ get_node_essentials({nodeType: "nodes-base.slack"})
**Tools that use this**: **Tools that use this**:
- n8n_create_workflow - n8n_create_workflow
- n8n_update_partial_workflow - n8n_update_partial_workflow
- list_node_templates
### Conversion ### Conversion
@@ -134,40 +137,43 @@ get_node_essentials({nodeType: "nodes-base.slack"})
## Common Mistakes ## Common Mistakes
### Mistake 1: Wrong nodeType Format ### Mistake 1: Wrong nodeType Format
**Problem**: "Node not found" error **Problem**: "Node not found" error
```javascript ```javascript
get_node_essentials({nodeType: "slack"}) // Missing prefix // WRONG
get_node_essentials({nodeType: "n8n-nodes-base.slack"}) // Wrong prefix get_node({nodeType: "slack"}) // Missing prefix
get_node({nodeType: "n8n-nodes-base.slack"}) // Wrong prefix
get_node_essentials({nodeType: "nodes-base.slack"}) // Correct! // CORRECT
get_node({nodeType: "nodes-base.slack"})
``` ```
### Mistake 2: Using get_node_info Instead of get_node_essentials ### Mistake 2: Using detail="full" by Default
**Problem**: 20% failure rate, slow response, huge payload **Problem**: Huge payload, slower response, token waste
```javascript ```javascript
get_node_info({nodeType: "nodes-base.slack"}) // WRONG - Returns 3-8K tokens, use sparingly
// Returns: 100KB+ data, 20% chance of failure get_node({nodeType: "nodes-base.slack", detail: "full"})
get_node_essentials({nodeType: "nodes-base.slack"}) // CORRECT - Returns 1-2K tokens, covers 95% of use cases
// Returns: 5KB focused data, 91.7% success, <10ms get_node({nodeType: "nodes-base.slack"}) // detail="standard" is default
get_node({nodeType: "nodes-base.slack", detail: "standard"})
``` ```
**When to use get_node_info**: **When to use detail="full"**:
- Debugging complex configuration issues - Debugging complex configuration issues
- Need complete property schema - Need complete property schema with all nested options
- Exploring advanced features - Exploring advanced features
**Better alternatives**: **Better alternatives**:
1. get_node_essentials - for operations list 1. `get_node({detail: "standard"})` - for operations list (default)
2. get_node_documentation - for readable docs 2. `get_node({mode: "docs"})` - for readable documentation
3. search_node_properties - for specific property 3. `get_node({mode: "search_properties", propertyQuery: "auth"})` - for specific property
### Mistake 3: Not Using Validation Profiles ### Mistake 3: Not Using Validation Profiles
**Problem**: Too many false positives OR missing real errors **Problem**: Too many false positives OR missing real errors
@@ -178,12 +184,14 @@ get_node_essentials({nodeType: "nodes-base.slack"})
- `strict` - Maximum validation (for production) - `strict` - Maximum validation (for production)
```javascript ```javascript
validate_node_operation({nodeType, config}) // Uses default // WRONG - Uses default profile
validate_node({nodeType, config})
validate_node_operation({nodeType, config, profile: "runtime"}) // Explicit // CORRECT - Explicit profile
validate_node({nodeType, config, profile: "runtime"})
``` ```
### Mistake 4: Ignoring Auto-Sanitization ### Mistake 4: Ignoring Auto-Sanitization
**What happens**: ALL nodes sanitized on ANY workflow update **What happens**: ALL nodes sanitized on ANY workflow update
@@ -203,7 +211,7 @@ n8n_update_partial_workflow({id, operations: [...]})
// → Automatically fixes operator structures // → Automatically fixes operator structures
``` ```
### Mistake 5: Not Using Smart Parameters ### Mistake 5: Not Using Smart Parameters
**Problem**: Complex sourceIndex calculations for multi-output nodes **Problem**: Complex sourceIndex calculations for multi-output nodes
@@ -244,6 +252,25 @@ n8n_update_partial_workflow({id, operations: [...]})
} }
``` ```
### Mistake 6: Not Using intent Parameter
**Problem**: Less helpful tool responses
```javascript
// WRONG - No context for response
n8n_update_partial_workflow({
id: "abc",
operations: [{type: "addNode", node: {...}}]
})
// CORRECT - Better AI responses
n8n_update_partial_workflow({
id: "abc",
intent: "Add error handling for API failures",
operations: [{type: "addNode", node: {...}}]
})
```
--- ---
## Tool Usage Patterns ## Tool Usage Patterns
@@ -262,7 +289,7 @@ const results = await search_nodes({
// → Returns: nodes-base.slack, nodes-base.slackTrigger // → Returns: nodes-base.slack, nodes-base.slackTrigger
// Step 2: Get details (~18s later, user reviewing results) // Step 2: Get details (~18s later, user reviewing results)
const details = await get_node_essentials({ const details = await get_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
includeExamples: true // Get real template configs includeExamples: true // Get real template configs
}); });
@@ -275,7 +302,7 @@ const details = await get_node_essentials({
```javascript ```javascript
// Step 1: Validate // Step 1: Validate
const result = await validate_node_operation({ const result = await validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config: { config: {
resource: "channel", resource: "channel",
@@ -293,7 +320,7 @@ if (!result.valid) {
config.name = "general"; config.name = "general";
// Step 4: Validate again // Step 4: Validate again
await validate_node_operation({...}); // Repeat until clean await validate_node({...}); // Repeat until clean
``` ```
### Pattern 3: Workflow Editing ### Pattern 3: Workflow Editing
@@ -305,6 +332,7 @@ await validate_node_operation({...}); // Repeat until clean
// Edit 1 // Edit 1
await n8n_update_partial_workflow({ await n8n_update_partial_workflow({
id: "workflow-id", id: "workflow-id",
intent: "Add webhook trigger",
operations: [{type: "addNode", node: {...}}] operations: [{type: "addNode", node: {...}}]
}); });
@@ -313,6 +341,7 @@ await n8n_update_partial_workflow({
// Edit 2 // Edit 2
await n8n_update_partial_workflow({ await n8n_update_partial_workflow({
id: "workflow-id", id: "workflow-id",
intent: "Connect webhook to processor",
operations: [{type: "addConnection", source: "...", target: "..."}] operations: [{type: "addConnection", source: "...", target: "..."}]
}); });
@@ -320,6 +349,13 @@ await n8n_update_partial_workflow({
// Edit 3 (validation) // Edit 3 (validation)
await n8n_validate_workflow({id: "workflow-id"}); await n8n_validate_workflow({id: "workflow-id"});
// Ready? Activate!
await n8n_update_partial_workflow({
id: "workflow-id",
intent: "Activate workflow for production",
operations: [{type: "activateWorkflow"}]
});
``` ```
--- ---
@@ -328,15 +364,14 @@ await n8n_validate_workflow({id: "workflow-id"});
### Node Discovery Tools ### Node Discovery Tools
See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for: See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for:
- search_nodes (99.9% success) - search_nodes
- get_node_essentials vs get_node_info - get_node with detail levels (minimal, standard, full)
- list_nodes by category - get_node modes (info, docs, search_properties, versions)
- search_node_properties for specific fields
### Validation Tools ### Validation Tools
See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for: See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
- Validation profiles explained - Validation profiles explained
- validate_node_minimal vs validate_node_operation - validate_node with modes (minimal, full)
- validate_workflow complete structure - validate_workflow complete structure
- Auto-sanitization system - Auto-sanitization system
- Handling validation errors - Handling validation errors
@@ -344,10 +379,12 @@ See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
### Workflow Management ### Workflow Management
See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for: See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
- n8n_create_workflow - n8n_create_workflow
- n8n_update_partial_workflow (15 operation types!) - n8n_update_partial_workflow (17 operation types!)
- Smart parameters (branch, case) - Smart parameters (branch, case)
- AI connection types (8 types) - AI connection types (8 types)
- cleanStaleConnections recovery - Workflow activation (activateWorkflow/deactivateWorkflow)
- n8n_deploy_template
- n8n_workflow_versions
--- ---
@@ -356,28 +393,58 @@ See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
### Search Templates ### Search Templates
```javascript ```javascript
// Search by keyword // Search by keyword (default mode)
search_templates({ search_templates({
query: "webhook slack", query: "webhook slack",
limit: 20 limit: 20
}); });
// → Returns: 1,085 templates with metadata
// Get template details // Search by node types
get_template({ search_templates({
templateId: 2947, // Weather to Slack searchMode: "by_nodes",
mode: "structure" // or "full" for complete JSON nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]
});
// Search by task type
search_templates({
searchMode: "by_task",
task: "webhook_processing"
});
// Search by metadata (complexity, setup time)
search_templates({
searchMode: "by_metadata",
complexity: "simple",
maxSetupMinutes: 15
}); });
``` ```
### Template Metadata ### Get Template Details
Templates include: ```javascript
- Complexity (simple, medium, complex) get_template({
- Setup time estimate templateId: 2947,
- Required services mode: "structure" // nodes+connections only
- Categories and use cases });
- View counts (popularity)
get_template({
templateId: 2947,
mode: "full" // complete workflow JSON
});
```
### Deploy Template Directly
```javascript
// Deploy template to your n8n instance
n8n_deploy_template({
templateId: 2947,
name: "My Weather to Slack", // Custom name (optional)
autoFix: true, // Auto-fix common issues (default)
autoUpgradeVersions: true // Upgrade node versions (default)
});
// Returns: workflow ID, required credentials, fixes applied
```
--- ---
@@ -386,7 +453,7 @@ Templates include:
### Get Tool Documentation ### Get Tool Documentation
```javascript ```javascript
// List all tools // Overview of all tools
tools_documentation() tools_documentation()
// Specific tool details // Specific tool details
@@ -394,21 +461,29 @@ tools_documentation({
topic: "search_nodes", topic: "search_nodes",
depth: "full" depth: "full"
}) })
// Code node guides
tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
tools_documentation({topic: "python_code_node_guide", depth: "full"})
```
### AI Agent Guide
```javascript
// Comprehensive AI workflow guide
ai_agents_guide()
// Returns: Architecture, connections, tools, validation, best practices
``` ```
### Health Check ### Health Check
```javascript ```javascript
// Verify MCP server connectivity // Quick health check
n8n_health_check() n8n_health_check()
// → Returns: status, features, API availability, version
```
### Database Statistics // Detailed diagnostics
n8n_health_check({mode: "diagnostic"})
```javascript // → Returns: status, env vars, tool status, API connectivity
get_database_statistics()
// → Returns: 537 nodes, 270 AI tools, 2,653 templates
``` ```
--- ---
@@ -416,79 +491,140 @@ get_database_statistics()
## Tool Availability ## Tool Availability
**Always Available** (no n8n API needed): **Always Available** (no n8n API needed):
- search_nodes, list_nodes, get_node_essentials - search_nodes, get_node
- validate_node_minimal, validate_node_operation - validate_node, validate_workflow
- validate_workflow, get_property_dependencies - search_templates, get_template
- search_templates, get_template, list_tasks - tools_documentation, ai_agents_guide
- tools_documentation, get_database_statistics
**Requires n8n API** (N8N_API_URL + N8N_API_KEY): **Requires n8n API** (N8N_API_URL + N8N_API_KEY):
- n8n_create_workflow - n8n_create_workflow
- n8n_update_partial_workflow - n8n_update_partial_workflow
- n8n_validate_workflow (by ID) - n8n_validate_workflow (by ID)
- n8n_list_workflows, n8n_get_workflow - n8n_list_workflows, n8n_get_workflow
- n8n_trigger_webhook_workflow - n8n_test_workflow
- n8n_executions
- n8n_deploy_template
- n8n_workflow_versions
- n8n_autofix_workflow
If API tools unavailable, use templates and validation-only workflows. If API tools unavailable, use templates and validation-only workflows.
--- ---
## Unified Tool Reference
### get_node (Unified Node Information)
**Detail Levels** (mode="info", default):
- `minimal` (~200 tokens) - Basic metadata only
- `standard` (~1-2K tokens) - Essential properties + operations (RECOMMENDED)
- `full` (~3-8K tokens) - Complete schema (use sparingly)
**Operation Modes**:
- `info` (default) - Node schema with detail level
- `docs` - Readable markdown documentation
- `search_properties` - Find specific properties (use with propertyQuery)
- `versions` - List all versions with breaking changes
- `compare` - Compare two versions
- `breaking` - Show only breaking changes
- `migrations` - Show auto-migratable changes
```javascript
// Standard (recommended)
get_node({nodeType: "nodes-base.httpRequest"})
// Get documentation
get_node({nodeType: "nodes-base.webhook", mode: "docs"})
// Search for properties
get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
// Check versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})
```
### validate_node (Unified Validation)
**Modes**:
- `full` (default) - Comprehensive validation with errors/warnings/suggestions
- `minimal` - Quick required fields check only
**Profiles** (for mode="full"):
- `minimal` - Very lenient
- `runtime` - Standard (default, recommended)
- `ai-friendly` - Balanced for AI workflows
- `strict` - Most thorough (production)
```javascript
// Full validation with runtime profile
validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})
// Quick required fields check
validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})
```
---
## Performance Characteristics ## Performance Characteristics
| Tool | Response Time | Payload Size | Reliability | | Tool | Response Time | Payload Size |
|------|---------------|--------------|-------------| |------|---------------|--------------|
| search_nodes | <20ms | Small | 99.9% | | search_nodes | <20ms | Small |
| list_nodes | <20ms | Small | 99.6% | | get_node (standard) | <10ms | ~1-2KB |
| get_node_essentials | <10ms | ~5KB | 91.7% | | get_node (full) | <100ms | 3-8KB |
| get_node_info | Varies | 100KB+ | 80% | | validate_node (minimal) | <50ms | Small |
| validate_node_minimal | <100ms | Small | 97.4% | | validate_node (full) | <100ms | Medium |
| validate_node_operation | <100ms | Medium | Varies | | validate_workflow | 100-500ms | Medium |
| validate_workflow | 100-500ms | Medium | 95.5% | | n8n_create_workflow | 100-500ms | Medium |
| n8n_create_workflow | 100-500ms | Medium | 96.8% | | n8n_update_partial_workflow | 50-200ms | Small |
| n8n_update_partial_workflow | 50-200ms | Small | 99.0% | | n8n_deploy_template | 200-500ms | Medium |
--- ---
## Best Practices ## Best Practices
### Do ### Do
- Use `get_node({detail: "standard"})` for most use cases
- Use get_node_essentials over get_node_info (91.7% vs 80%) - Specify validation profile explicitly (`profile: "runtime"`)
- Specify validation profile explicitly - Use smart parameters (`branch`, `case`) for clarity
- Use smart parameters (branch, case) for clarity - Include `intent` parameter in workflow updates
- Follow search essentials validate workflow - Follow search get_node validate workflow
- Iterate workflows (avg 56s between edits) - Iterate workflows (avg 56s between edits)
- Validate after every significant change - Validate after every significant change
- Use includeExamples: true for real configs - Use `includeExamples: true` for real configs
- Use `n8n_deploy_template` for quick starts
### Don't ### Don't
- Use `detail: "full"` unless necessary (wastes tokens)
- Use get_node_info unless necessary (20% failure rate!) - Forget nodeType prefix (`nodes-base.*`)
- Forget nodeType prefix (nodes-base.*) - Skip validation profiles
- Skip validation profiles (use "runtime")
- Try to build workflows in one shot (iterate!) - Try to build workflows in one shot (iterate!)
- Ignore auto-sanitization behavior - Ignore auto-sanitization behavior
- Use full prefix (n8n-nodes-base.*) with search tools - Use full prefix (`n8n-nodes-base.*`) with search/validate tools
- Forget to activate workflows after building
--- ---
## Summary ## Summary
**Most Important**: **Most Important**:
1. Use **get_node_essentials**, not get_node_info (5KB vs 100KB, 91.7% vs 80%) 1. Use **get_node** with `detail: "standard"` (default) - covers 95% of use cases
2. nodeType formats differ: `nodes-base.*` (search) vs `n8n-nodes-base.*` (workflows) 2. nodeType formats differ: `nodes-base.*` (search/validate) vs `n8n-nodes-base.*` (workflows)
3. Specify **validation profiles** (runtime recommended) 3. Specify **validation profiles** (`runtime` recommended)
4. Use **smart parameters** (branch="true", case=0) 4. Use **smart parameters** (`branch="true"`, `case=0`)
5. **Auto-sanitization** runs on ALL nodes during updates 5. Include **intent parameter** in workflow updates
6. Workflows are built **iteratively** (56s avg between edits) 6. **Auto-sanitization** runs on ALL nodes during updates
7. Workflows can be **activated via API** (`activateWorkflow` operation)
8. Workflows are built **iteratively** (56s avg between edits)
**Common Workflow**: **Common Workflow**:
1. search_nodes find node 1. search_nodes find node
2. get_node_essentials understand config 2. get_node understand config
3. validate_node_operation check config 3. validate_node check config
4. n8n_create_workflow build 4. n8n_create_workflow build
5. n8n_validate_workflow verify 5. n8n_validate_workflow verify
6. n8n_update_partial_workflow iterate 6. n8n_update_partial_workflow iterate
7. activateWorkflow go live!
For details, see: For details, see:
- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery - [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery
@@ -502,3 +638,5 @@ For details, see:
- n8n Workflow Patterns - Architectural patterns from templates - n8n Workflow Patterns - Architectural patterns from templates
- n8n Validation Expert - Interpret validation errors - n8n Validation Expert - Interpret validation errors
- n8n Node Configuration - Operation-specific requirements - n8n Node Configuration - Operation-specific requirements
- n8n Code JavaScript - Write JavaScript in Code nodes
- n8n Code Python - Write Python in Code nodes

View File

@@ -12,17 +12,21 @@ Validation is typically iterative with validate → fix cycles
--- ---
## validate_node_minimal (QUICK CHECK) ## validate_node (UNIFIED VALIDATION)
**Success Rate**: 97.4% | **Speed**: <100ms The `validate_node` tool provides all validation capabilities with different modes.
### Quick Check (mode="minimal")
**Speed**: <50ms
**Use when**: Checking what fields are required **Use when**: Checking what fields are required
**Syntax**:
```javascript ```javascript
validate_node_minimal({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config: {} // Empty to see all required fields config: {}, // Empty to see all required fields
mode: "minimal"
}) })
``` ```
@@ -36,17 +40,14 @@ validate_node_minimal({
**When to use**: Planning configuration, seeing basic requirements **When to use**: Planning configuration, seeing basic requirements
--- ### Full Validation (mode="full", DEFAULT)
## validate_node_operation (FULL VALIDATION) **Speed**: <100ms
**Success Rate**: Varies | **Speed**: <100ms
**Use when**: Validating actual configuration before deployment **Use when**: Validating actual configuration before deployment
**Syntax**:
```javascript ```javascript
validate_node_operation({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config: { config: {
resource: "channel", resource: "channel",
@@ -55,9 +56,12 @@ validate_node_operation({
}, },
profile: "runtime" // Recommended! profile: "runtime" // Recommended!
}) })
// mode="full" is the default
``` ```
### Validation Profiles ---
## Validation Profiles
Choose based on your stage: Choose based on your stage:
@@ -81,10 +85,15 @@ Choose based on your stage:
- May have false positives - May have false positives
- Use: Production deployment - Use: Production deployment
### Returns ---
## Validation Response
```javascript ```javascript
{ {
"nodeType": "nodes-base.slack",
"workflowNodeType": "n8n-nodes-base.slack",
"displayName": "Slack",
"valid": false, "valid": false,
"errors": [ "errors": [
{ {
@@ -106,7 +115,8 @@ Choose based on your stage:
"summary": { "summary": {
"hasErrors": true, "hasErrors": true,
"errorCount": 1, "errorCount": 1,
"warningCount": 1 "warningCount": 1,
"suggestionCount": 0
} }
} }
``` ```
@@ -123,7 +133,7 @@ Choose based on your stage:
## validate_workflow (STRUCTURE VALIDATION) ## validate_workflow (STRUCTURE VALIDATION)
**Success Rate**: 95.5% | **Speed**: 100-500ms **Speed**: 100-500ms
**Use when**: Checking complete workflow before execution **Use when**: Checking complete workflow before execution
@@ -152,6 +162,21 @@ validate_workflow({
**Returns**: Comprehensive validation report with errors, warnings, suggestions **Returns**: Comprehensive validation report with errors, warnings, suggestions
### Validate by Workflow ID
```javascript
// Validate workflow already in n8n
n8n_validate_workflow({
id: "workflow-id",
options: {
validateNodes: true,
validateConnections: true,
validateExpressions: true,
profile: "runtime"
}
})
```
--- ---
## Validation Loop Pattern ## Validation Loop Pattern
@@ -161,11 +186,11 @@ validate_workflow({
``` ```
1. Configure node 1. Configure node
2. validate_node_operation (23s thinking about errors) 2. validate_node (23s thinking about errors)
3. Fix errors 3. Fix errors
4. validate_node_operation again (58s fixing) 4. validate_node again (58s fixing)
5. Repeat until valid 5. Repeat until valid
``` ```
@@ -178,7 +203,7 @@ let config = {
operation: "create" operation: "create"
}; };
const result1 = validate_node_operation({ const result1 = validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" profile: "runtime"
@@ -188,7 +213,7 @@ const result1 = validate_node_operation({
// Iteration 2 (~58s later) // Iteration 2 (~58s later)
config.name = "general"; config.name = "general";
const result2 = validate_node_operation({ const result2 = validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" profile: "runtime"
@@ -220,7 +245,7 @@ const result2 = validate_node_operation({
{ {
"type": "boolean", "type": "boolean",
"operation": "equals", "operation": "equals",
"singleValue": true // Binary operators shouldn't have this "singleValue": true // Binary operators shouldn't have this
} }
// After auto-sanitization (automatic!) // After auto-sanitization (automatic!)
@@ -233,7 +258,36 @@ const result2 = validate_node_operation({
**Recovery tools**: **Recovery tools**:
- `cleanStaleConnections` operation - removes broken connections - `cleanStaleConnections` operation - removes broken connections
- `n8n_autofix_workflow` - preview/apply fixes - `n8n_autofix_workflow({id})` - preview/apply fixes
---
## n8n_autofix_workflow (AUTO-FIX TOOL)
**Use when**: Validation errors need automatic fixes
```javascript
// Preview fixes (default - doesn't apply)
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: false, // Preview mode
confidenceThreshold: "medium" // high, medium, low
})
// Apply fixes
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: true
})
```
**Fix Types**:
- `expression-format` - Fix expression syntax
- `typeversion-correction` - Correct typeVersion
- `error-output-config` - Fix error output settings
- `webhook-missing-path` - Add missing webhook paths
- `typeversion-upgrade` - Upgrade to latest version
- `version-migration` - Apply version migrations
--- ---
@@ -270,7 +324,7 @@ const result2 = validate_node_operation({
Add the field with appropriate value Add the field with appropriate value
**"Invalid value"** **"Invalid value"**
Check allowed values in essentials/documentation Check allowed values in get_node output
**"Type mismatch"** **"Type mismatch"**
Convert to correct type (string/number/boolean) Convert to correct type (string/number/boolean)
@@ -294,17 +348,18 @@ Use **ai-friendly** profile to reduce false positives.
## Best Practices ## Best Practices
### Do ### Do
- Use **runtime** profile for pre-deployment - Use **runtime** profile for pre-deployment
- Validate after every configuration change - Validate after every configuration change
- Fix errors immediately (avg 58s) - Fix errors immediately (avg 58s)
- Iterate validation loop - Iterate validation loop
- Trust auto-sanitization for operator issues - Trust auto-sanitization for operator issues
- Use minimal profile for quick checks - Use `mode: "minimal"` for quick checks
- Complete workflow activation manually in n8n UI (API/MCP cannot activate workflows) - Use `n8n_autofix_workflow` for bulk fixes
- Activate workflows via API when ready (`activateWorkflow` operation)
### Don't ### Don't
- Skip validation before deployment - Skip validation before deployment
- Ignore error messages - Ignore error messages
@@ -317,10 +372,11 @@ Use **ai-friendly** profile to reduce false positives.
## Example: Complete Validation Workflow ## Example: Complete Validation Workflow
```javascript ```javascript
// Step 1: Get node requirements // Step 1: Get node requirements (quick check)
validate_node_minimal({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config: {} config: {},
mode: "minimal"
}); });
// → Know what's required // → Know what's required
@@ -332,8 +388,8 @@ const config = {
text: "Hello!" text: "Hello!"
}; };
// Step 3: Validate configuration // Step 3: Validate configuration (full validation)
const result = validate_node_operation({ const result = validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" profile: "runtime"
@@ -341,9 +397,9 @@ const result = validate_node_operation({
// Step 4: Check result // Step 4: Check result
if (result.valid) { if (result.valid) {
console.log("Configuration valid!"); console.log("Configuration valid!");
} else { } else {
console.log("Errors:", result.errors); console.log("Errors:", result.errors);
// Fix and validate again // Fix and validate again
} }
@@ -354,6 +410,12 @@ validate_workflow({
connections: {...} connections: {...}
} }
}); });
// Step 6: Apply auto-fixes if needed
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: true
});
``` ```
--- ---
@@ -366,11 +428,14 @@ validate_workflow({
3. Auto-sanitization fixes operator structures automatically 3. Auto-sanitization fixes operator structures automatically
4. Binary operators singleValue, Unary operators = singleValue: true 4. Binary operators singleValue, Unary operators = singleValue: true
5. Iterate until validation passes 5. Iterate until validation passes
6. Use `n8n_autofix_workflow` for automatic fixes
**Tool Selection**: **Tool Selection**:
- **validate_node_minimal**: Quick check - **validate_node({mode: "minimal"})**: Quick required fields check
- **validate_node_operation**: Full config validation (**use this!**) - **validate_node({profile: "runtime"})**: Full config validation (**use this!**)
- **validate_workflow**: Complete workflow check - **validate_workflow**: Complete workflow check
- **n8n_validate_workflow({id})**: Validate existing workflow
- **n8n_autofix_workflow({id})**: Auto-fix common issues
**Related**: **Related**:
- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes - [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes

View File

@@ -6,7 +6,7 @@ Complete guide for creating, updating, and managing n8n workflows.
## Tool Availability ## Tool Availability
**⚠️ Requires n8n API**: All tools in this guide need `N8N_API_URL` and `N8N_API_KEY` configured. **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. If unavailable, use template examples and validation-only workflows.
@@ -14,7 +14,7 @@ If unavailable, use template examples and validation-only workflows.
## n8n_create_workflow ## n8n_create_workflow
**Success Rate**: 96.8% | **Speed**: 100-500ms **Speed**: 100-500ms
**Use when**: Creating new workflows from scratch **Use when**: Creating new workflows from scratch
@@ -39,7 +39,7 @@ n8n_create_workflow({
id: "webhook-1", id: "webhook-1",
name: "Webhook", name: "Webhook",
type: "n8n-nodes-base.webhook", // Full prefix! type: "n8n-nodes-base.webhook", // Full prefix!
typeVersion: 1, typeVersion: 2,
position: [250, 300], position: [250, 300],
parameters: { parameters: {
path: "slack-notify", path: "slack-notify",
@@ -50,7 +50,7 @@ n8n_create_workflow({
id: "slack-1", id: "slack-1",
name: "Slack", name: "Slack",
type: "n8n-nodes-base.slack", type: "n8n-nodes-base.slack",
typeVersion: 1, typeVersion: 2,
position: [450, 300], position: [450, 300],
parameters: { parameters: {
resource: "message", resource: "message",
@@ -69,7 +69,7 @@ n8n_create_workflow({
``` ```
**Notes**: **Notes**:
- Workflows created **inactive** (must activate separately) - Workflows created **inactive** (activate with `activateWorkflow` operation)
- Auto-sanitization runs on creation - Auto-sanitization runs on creation
- Validate before creating for best results - Validate before creating for best results
@@ -77,26 +77,26 @@ n8n_create_workflow({
## n8n_update_partial_workflow (MOST USED!) ## n8n_update_partial_workflow (MOST USED!)
**Success Rate**: 99.0% | **Speed**: 50-200ms | **Uses**: 38,287 (most used tool!) **Speed**: 50-200ms | **Uses**: 38,287 (most used tool!)
**Use when**: Making incremental changes to workflows **Use when**: Making incremental changes to workflows
**Common pattern**: 56s average between edits (iterative building!) **Common pattern**: 56s average between edits (iterative building!)
### 15 Operation Types ### 17 Operation Types
**Node Operations** (6 types): **Node Operations** (6 types):
1. `addNode` - Add new node 1. `addNode` - Add new node
2. `removeNode` - Remove node by ID or name 2. `removeNode` - Remove node by ID or name
3. `updateNode` - Update node properties 3. `updateNode` - Update node properties (use dot notation)
4. `moveNode` - Change position 4. `moveNode` - Change position
5. `enableNode` - Enable disabled node 5. `enableNode` - Enable disabled node
6. `disableNode` - Disable active node 6. `disableNode` - Disable active node
**Connection Operations** (5 types): **Connection Operations** (5 types):
7. `addConnection` - Connect nodes 7. `addConnection` - Connect nodes (supports smart params)
8. `removeConnection` - Remove connection 8. `removeConnection` - Remove connection (supports ignoreErrors)
9. `rewireConnection` - Change target 9. `rewireConnection` - Change connection target
10. `cleanStaleConnections` - Auto-remove broken connections 10. `cleanStaleConnections` - Auto-remove broken connections
11. `replaceConnections` - Replace entire connections object 11. `replaceConnections` - Replace entire connections object
@@ -106,7 +106,23 @@ n8n_create_workflow({
14. `addTag` - Add tag 14. `addTag` - Add tag
15. `removeTag` - Remove tag 15. `removeTag` - Remove tag
### Smart Parameters (NEW!) **Activation Operations** (2 types):
16. `activateWorkflow` - Activate workflow for automatic execution
17. `deactivateWorkflow` - Deactivate workflow
### Intent Parameter (IMPORTANT!)
Always include `intent` for better responses:
```javascript
n8n_update_partial_workflow({
id: "workflow-id",
intent: "Add error handling for API failures", // Describe what you're doing
operations: [...]
})
```
### Smart Parameters
**IF nodes** - Use semantic branch names: **IF nodes** - Use semantic branch names:
```javascript ```javascript
@@ -182,11 +198,53 @@ n8n_create_workflow({
// - ai_textSplitter // - ai_textSplitter
``` ```
### Property Removal with undefined
Remove properties by setting them to `undefined`:
```javascript
// Remove a property
{
type: "updateNode",
nodeName: "HTTP Request",
updates: { onError: undefined }
}
// Migrate from deprecated property
{
type: "updateNode",
nodeName: "HTTP Request",
updates: {
continueOnFail: undefined, // Remove old
onError: "continueErrorOutput" // Add new
}
}
```
### Activation Operations
```javascript
// Activate workflow
n8n_update_partial_workflow({
id: "workflow-id",
intent: "Activate workflow for production",
operations: [{type: "activateWorkflow"}]
})
// Deactivate workflow
n8n_update_partial_workflow({
id: "workflow-id",
intent: "Deactivate workflow for maintenance",
operations: [{type: "deactivateWorkflow"}]
})
```
### Example Usage ### Example Usage
```javascript ```javascript
n8n_update_partial_workflow({ n8n_update_partial_workflow({
id: "workflow-id", id: "workflow-id",
intent: "Add transform node after IF condition",
operations: [ operations: [
// Add node // Add node
{ {
@@ -213,8 +271,16 @@ n8n_update_partial_workflow({
**cleanStaleConnections** - Remove broken connections: **cleanStaleConnections** - Remove broken connections:
```javascript ```javascript
{type: "cleanStaleConnections"}
```
**rewireConnection** - Change target atomically:
```javascript
{ {
type: "cleanStaleConnections" type: "rewireConnection",
source: "Webhook",
from: "Old Handler",
to: "New Handler"
} }
``` ```
@@ -227,15 +293,145 @@ n8n_update_partial_workflow({
}) })
``` ```
**Validate before applying**:
```javascript
n8n_update_partial_workflow({
id: "workflow-id",
operations: [...],
validateOnly: true // Preview without applying
})
```
---
## n8n_deploy_template (QUICK START!)
**Speed**: 200-500ms
**Use when**: Deploying a template directly to n8n instance
```javascript
n8n_deploy_template({
templateId: 2947, // Required: from n8n.io
name: "My Weather to Slack", // Optional: custom name
autoFix: true, // Default: auto-fix common issues
autoUpgradeVersions: true, // Default: upgrade node versions
stripCredentials: true // Default: remove credential refs
})
```
**Returns**:
- Workflow ID
- Required credentials
- Fixes applied
**Example**:
```javascript
// Deploy a webhook to Slack template
const result = n8n_deploy_template({
templateId: 2947,
name: "Production Slack Notifier"
});
// Result includes:
// - id: "new-workflow-id"
// - requiredCredentials: ["slack"]
// - fixesApplied: ["typeVersion upgraded", "expression format fixed"]
```
---
## n8n_workflow_versions (VERSION CONTROL)
**Use when**: Managing workflow history, rollback, cleanup
### List Versions
```javascript
n8n_workflow_versions({
mode: "list",
workflowId: "workflow-id",
limit: 10
})
```
### Get Specific Version
```javascript
n8n_workflow_versions({
mode: "get",
versionId: 123
})
```
### Rollback to Previous Version
```javascript
n8n_workflow_versions({
mode: "rollback",
workflowId: "workflow-id",
versionId: 123, // Optional: specific version
validateBefore: true // Default: validate before rollback
})
```
### Delete Versions
```javascript
// Delete specific version
n8n_workflow_versions({
mode: "delete",
workflowId: "workflow-id",
versionId: 123
})
// Delete all versions for workflow
n8n_workflow_versions({
mode: "delete",
workflowId: "workflow-id",
deleteAll: true
})
```
### Prune Old Versions
```javascript
n8n_workflow_versions({
mode: "prune",
workflowId: "workflow-id",
maxVersions: 10 // Keep 10 most recent
})
```
---
## n8n_test_workflow (TRIGGER EXECUTION)
**Use when**: Testing workflow execution
**Auto-detects** trigger type (webhook, form, chat)
```javascript
// Test webhook workflow
n8n_test_workflow({
workflowId: "workflow-id",
triggerType: "webhook", // Optional: auto-detected
httpMethod: "POST",
data: {message: "Hello!"},
waitForResponse: true,
timeout: 120000
})
// Test chat workflow
n8n_test_workflow({
workflowId: "workflow-id",
triggerType: "chat",
message: "Hello, AI agent!",
sessionId: "session-123" // For conversation continuity
})
```
--- ---
## n8n_validate_workflow (by ID) ## n8n_validate_workflow (by ID)
**Success Rate**: 99.7% | **Speed**: Network-dependent
**Use when**: Validating workflow stored in n8n **Use when**: Validating workflow stored in n8n
**Syntax**:
```javascript ```javascript
n8n_validate_workflow({ n8n_validate_workflow({
id: "workflow-id", id: "workflow-id",
@@ -248,7 +444,69 @@ n8n_validate_workflow({
}) })
``` ```
**Returns**: Same as validate_workflow (from validation guide) ---
## n8n_get_workflow
**Use when**: Retrieving workflow details
**Modes**:
- `full` (default) - Complete workflow JSON
- `details` - Full + execution stats
- `structure` - Nodes + connections only
- `minimal` - ID, name, active, tags
```javascript
// Full workflow
n8n_get_workflow({id: "workflow-id"})
// Just structure
n8n_get_workflow({id: "workflow-id", mode: "structure"})
// Minimal metadata
n8n_get_workflow({id: "workflow-id", mode: "minimal"})
```
---
## n8n_executions (EXECUTION MANAGEMENT)
**Use when**: Managing workflow executions
### Get Execution Details
```javascript
n8n_executions({
action: "get",
id: "execution-id",
mode: "summary" // preview, summary, filtered, full, error
})
// Error mode for debugging
n8n_executions({
action: "get",
id: "execution-id",
mode: "error",
includeStackTrace: true
})
```
### List Executions
```javascript
n8n_executions({
action: "list",
workflowId: "workflow-id",
status: "error", // success, error, waiting
limit: 100
})
```
### Delete Execution
```javascript
n8n_executions({
action: "delete",
id: "execution-id"
})
```
--- ---
@@ -265,61 +523,45 @@ n8n_validate_workflow({
→ Check for errors → Check for errors
3. EDIT (iterative! 56s avg between edits) 3. EDIT (iterative! 56s avg between edits)
n8n_update_partial_workflow({id, operations: [...]}) n8n_update_partial_workflow({id, intent: "...", operations: [...]})
→ Make changes → Make changes
4. VALIDATE AGAIN 4. VALIDATE AGAIN
n8n_validate_workflow({id}) n8n_validate_workflow({id})
→ Verify changes → Verify changes
5. ACTIVATE (when ready) 5. ACTIVATE
⚠️ **IMPORTANT LIMITATION**: Workflow activation is NOT supported via API or MCP. n8n_update_partial_workflow({
Users must activate workflows manually in the n8n UI. id,
intent: "Activate workflow",
The following operation will NOT activate the workflow: operations: [{type: "activateWorkflow"}]
n8n_update_partial_workflow({id, operations: [{ })
type: "updateSettings", → Workflow now runs on triggers!
settings: {active: true}
}]})
**Manual activation required**: Navigate to workflow in n8n UI and toggle activation.
6. MONITOR 6. MONITOR
n8n_list_executions({workflowId: id}) n8n_executions({action: "list", workflowId: id})
n8n_get_execution({id: execution_id}) n8n_executions({action: "get", 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 ## Common Patterns from Telemetry
### Pattern 1: Edit → Validate (7,841 occurrences) ### Pattern 1: Edit → Validate (7,841 occurrences)
```javascript ```javascript
// Edit
n8n_update_partial_workflow({...}) n8n_update_partial_workflow({...})
// ↓ 23s (thinking about what to validate) // ↓ 23s (thinking about what to validate)
// Validate
n8n_validate_workflow({id}) n8n_validate_workflow({id})
``` ```
### Pattern 2: Validate → Fix (7,266 occurrences) ### Pattern 2: Validate → Fix (7,266 occurrences)
```javascript ```javascript
// Validate
n8n_validate_workflow({id}) n8n_validate_workflow({id})
// ↓ 58s (fixing errors) // ↓ 58s (fixing errors)
// Fix
n8n_update_partial_workflow({...}) n8n_update_partial_workflow({...})
``` ```
### Pattern 3: Iterative Building (31,464 occurrences) ### Pattern 3: Iterative Building (31,464 occurrences)
```javascript ```javascript
update update update ... (56s avg between edits) update update update ... (56s avg between edits)
``` ```
@@ -328,51 +570,24 @@ update → update → update → ... (56s avg between edits)
--- ---
## 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 ## Best Practices
### Do ### Do
- Build workflows **iteratively** (avg 56s between edits) - Build workflows **iteratively** (avg 56s between edits)
- Include **intent** parameter for better responses
- Use **smart parameters** (branch, case) for clarity - Use **smart parameters** (branch, case) for clarity
- Validate **after** significant changes - Validate **after** significant changes
- Use **atomic mode** (default) for critical updates - Use **atomic mode** (default) for critical updates
- Specify **sourceOutput** for AI connections - Specify **sourceOutput** for AI connections
- Clean stale connections after node renames/deletions - Clean stale connections after node renames/deletions
- Use `n8n_deploy_template` for quick starts
- Activate workflows via API when ready
### Don't ### Don't
- Try to build workflows in one shot - Try to build workflows in one shot
- Skip the intent parameter
- Use sourceIndex when branch/case available - Use sourceIndex when branch/case available
- Skip validation before activation - Skip validation before activation
- Forget to test workflows after creation - Forget to test workflows after creation
@@ -383,12 +598,20 @@ n8n_list_workflows({
## Summary ## Summary
**Most Important**: **Most Important**:
1. **n8n_update_partial_workflow** is most-used tool (38,287 uses, 99.0% success) 1. **n8n_update_partial_workflow** is most-used tool (38,287 uses)
2. Workflows built **iteratively** (56s avg between edits) 2. Include **intent** parameter for better responses
3. Use **smart parameters** (branch="true", case=0) for clarity 3. Workflows built **iteratively** (56s avg between edits)
4. **AI connections** supported (8 types with sourceOutput) 4. Use **smart parameters** (branch="true", case=0) for clarity
5. **Auto-sanitization** runs on all operations 5. **AI connections** supported (8 types with sourceOutput)
6. Validate frequently (7,841 edit → validate patterns) 6. **Workflow activation** supported via API (`activateWorkflow` operation)
7. **Auto-sanitization** runs on all operations
8. Use **n8n_deploy_template** for quick starts
**New Tools**:
- `n8n_deploy_template` - Deploy templates directly
- `n8n_workflow_versions` - Version control & rollback
- `n8n_test_workflow` - Trigger execution
- `n8n_executions` - Manage executions
**Related**: **Related**:
- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes to add - [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Find nodes to add

View File

@@ -233,43 +233,27 @@ Deep dive into n8n property dependencies and displayOptions mechanism.
--- ---
## Using get_property_dependencies ## Finding Property Dependencies
### Basic Usage ### Using get_node with search_properties Mode
```javascript ```javascript
const deps = get_property_dependencies({ // Find properties related to "body"
nodeType: "nodes-base.httpRequest" get_node({
nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "body"
}); });
``` ```
### Example Response ### Using get_node with Full Detail
```javascript ```javascript
{ // Get complete schema with displayOptions
"nodeType": "n8n-nodes-base.httpRequest", get_node({
"dependencies": { nodeType: "nodes-base.httpRequest",
"body": { detail: "full"
"shows_when": { });
"sendBody": [true],
"method": ["POST", "PUT", "PATCH", "DELETE"]
},
"required_when_shown": true
},
"queryParameters": {
"shows_when": {
"sendQuery": [true]
},
"required_when_shown": false
},
"headerParameters": {
"shows_when": {
"sendHeaders": [true]
},
"required_when_shown": false
}
}
}
``` ```
### When to Use ### When to Use
@@ -281,7 +265,7 @@ const deps = get_property_dependencies({
- Building dynamic configuration tools - Building dynamic configuration tools
**❌ Don't use when**: **❌ Don't use when**:
- Simple configuration (use get_node_essentials) - Simple configuration (use `get_node` with standard detail)
- Just starting configuration - Just starting configuration
- Field requirements are obvious - Field requirements are obvious
@@ -564,9 +548,11 @@ method=POST
**Solution**: **Solution**:
```javascript ```javascript
// Check dependencies // Check field dependencies using search_properties
const deps = get_property_dependencies({ get_node({
nodeType: "nodes-base.httpRequest" nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "body"
}); });
// Find that body shows when sendBody=true // Find that body shows when sendBody=true
@@ -606,8 +592,8 @@ const deps = get_property_dependencies({
**Solution**: **Solution**:
```javascript ```javascript
// Check essentials for new operation // Check requirements for new operation
get_node_essentials({ get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack"
}); });
@@ -644,9 +630,11 @@ get_node_essentials({
**Solution**: Respect dependencies from the start **Solution**: Respect dependencies from the start
```javascript ```javascript
// Correct approach // Correct approach - check property dependencies
get_property_dependencies({ get_node({
nodeType: "nodes-base.httpRequest" nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "body"
}); });
// See that body only shows for POST/PUT/PATCH/DELETE // See that body only shows for POST/PUT/PATCH/DELETE
@@ -730,7 +718,7 @@ get_property_dependencies({
1. **Check dependencies when stuck** 1. **Check dependencies when stuck**
```javascript ```javascript
get_property_dependencies({nodeType: "..."}); get_node({nodeType: "...", mode: "search_properties", propertyQuery: "..."});
``` ```
2. **Configure parent properties first** 2. **Configure parent properties first**
@@ -742,7 +730,7 @@ get_property_dependencies({
3. **Validate after changing operation** 3. **Validate after changing operation**
```javascript ```javascript
// Operation changed → requirements changed // Operation changed → requirements changed
validate_node_operation({...}); validate_node({nodeType: "...", config: {...}, profile: "runtime"});
``` ```
4. **Read validation errors for dependency hints** 4. **Read validation errors for dependency hints**
@@ -791,8 +779,9 @@ get_property_dependencies({
- Field doesn't save → Hidden by dependencies - Field doesn't save → Hidden by dependencies
**Tools**: **Tools**:
- `get_property_dependencies` - See dependency rules - `get_node({mode: "search_properties"})` - Find property dependencies
- `get_node_essentials` - See operation requirements - `get_node({detail: "full"})` - See complete schema with displayOptions
- `get_node` - See operation requirements (standard detail)
- Validation errors - Hints about dependencies - Validation errors - Hints about dependencies
**Related Files**: **Related Files**:

View File

@@ -1,6 +1,6 @@
--- ---
name: n8n-node-configuration name: n8n-node-configuration
description: Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between get_node_essentials and get_node_info, or learning common configuration patterns by node type. description: Operation-aware node configuration guidance. Use when configuring nodes, understanding property dependencies, determining required fields, choosing between get_node detail levels, or learning common configuration patterns by node type.
--- ---
# n8n Node Configuration # n8n Node Configuration
@@ -14,11 +14,11 @@ Expert guidance for operation-aware node configuration with property dependencie
**Progressive disclosure**: Start minimal, add complexity as needed **Progressive disclosure**: Start minimal, add complexity as needed
Configuration best practices: Configuration best practices:
- get_node_essentials is the most used discovery pattern - `get_node` with `detail: "standard"` is the most used discovery pattern
- 56 seconds average between configuration edits - 56 seconds average between configuration edits
- 91.7% success rate with essentials-based configuration - Covers 95% of use cases with 1-2K tokens response
**Key insight**: Most configurations need only essentials, not full schema! **Key insight**: Most configurations need only standard detail, not full schema!
--- ---
@@ -79,23 +79,20 @@ Configuration best practices:
### 3. Progressive Discovery ### 3. Progressive Discovery
**Use the right tool for the right job**: **Use the right detail level**:
1. **get_node_essentials** (91.7% success rate) 1. **get_node({detail: "standard"})** - DEFAULT
- Quick overview - Quick overview (~1-2K tokens)
- Required fields - Required fields + common options
- Common options - **Use first** - covers 95% of needs
- **Use first** - covers 90% of needs
2. **get_property_dependencies** (for complex nodes) 2. **get_node({mode: "search_properties", propertyQuery: "..."})** (for finding specific fields)
- Shows what fields depend on others - Find properties by name
- Reveals conditional requirements - Use when looking for auth, body, headers, etc.
- Use when essentials isn't enough
3. **get_node_info** (full schema) 3. **get_node({detail: "full"})** (complete schema)
- Complete documentation - All properties (~3-8K tokens)
- All possible fields - Use only when standard detail is insufficient
- Use when essentials + dependencies insufficient
--- ---
@@ -106,13 +103,13 @@ Configuration best practices:
``` ```
1. Identify node type and operation 1. Identify node type and operation
2. Use get_node_essentials 2. Use get_node (standard detail is default)
3. Configure required fields 3. Configure required fields
4. Validate configuration 4. Validate configuration
5. If dependencies unclear → get_property_dependencies 5. If field unclear → get_node({mode: "search_properties"})
6. Add optional fields as needed 6. Add optional fields as needed
@@ -128,9 +125,9 @@ Configuration best practices:
// Goal: POST JSON to API // Goal: POST JSON to API
``` ```
**Step 2**: Get essentials **Step 2**: Get node info
```javascript ```javascript
const info = get_node_essentials({ const info = get_node({
nodeType: "nodes-base.httpRequest" nodeType: "nodes-base.httpRequest"
}); });
@@ -148,7 +145,7 @@ const info = get_node_essentials({
**Step 4**: Validate **Step 4**: Validate
```javascript ```javascript
validate_node_operation({ validate_node({
nodeType: "nodes-base.httpRequest", nodeType: "nodes-base.httpRequest",
config, config,
profile: "runtime" profile: "runtime"
@@ -168,7 +165,7 @@ validate_node_operation({
**Step 6**: Validate again **Step 6**: Validate again
```javascript ```javascript
validate_node_operation({...}); validate_node({...});
// → Error: "body required when sendBody=true" // → Error: "body required when sendBody=true"
``` ```
@@ -191,47 +188,61 @@ validate_node_operation({...});
**Step 8**: Final validation **Step 8**: Final validation
```javascript ```javascript
validate_node_operation({...}); validate_node({...});
// → Valid! ✅ // → Valid! ✅
``` ```
--- ---
## get_node_essentials vs get_node_info ## get_node Detail Levels
### Use get_node_essentials When: ### Standard Detail (DEFAULT - Use This!)
**✅ Starting configuration** (91.7% success rate) **✅ Starting configuration**
```javascript ```javascript
get_node_essentials({ get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack"
}); });
// detail="standard" is the default
``` ```
**Returns**: **Returns** (~1-2K tokens):
- Required fields - Required fields
- Common options - Common options
- Basic examples
- Operation list - Operation list
- Metadata
**Fast**: ~18 seconds average (from search → essentials) **Use**: 95% of configuration needs
### Use get_node_info When: ### Full Detail (Use Sparingly)
**Essentials insufficient** **When standard isn't enough**
```javascript ```javascript
get_node_info({ get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack",
detail: "full"
}); });
``` ```
**Returns**: **Returns** (~3-8K tokens):
- Full schema - Complete schema
- All properties - All properties
- Complete documentation - All nested options
- Advanced options
**Slower**: More data to process **Warning**: Large response, use only when standard insufficient
### Search Properties Mode
**✅ Looking for specific field**
```javascript
get_node({
nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "auth"
});
```
**Use**: Find authentication, headers, body fields, etc.
### Decision Tree ### Decision Tree
@@ -239,27 +250,27 @@ get_node_info({
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Starting new node config? │ │ Starting new node config? │
├─────────────────────────────────┤ ├─────────────────────────────────┤
│ YES → get_node_essentials │ YES → get_node (standard)
└─────────────────────────────────┘ └─────────────────────────────────┘
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
Essentials has what you need? │ Standard has what you need?
├─────────────────────────────────┤ ├─────────────────────────────────┤
│ YES → Configure with essentials │ YES → Configure with it
│ NO → Continue │ │ NO → Continue │
└─────────────────────────────────┘ └─────────────────────────────────┘
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
Need dependency info? Looking for specific field?
├─────────────────────────────────┤ ├─────────────────────────────────┤
│ YES → get_property_dependencies │ YES → search_properties mode
│ NO → Continue │ │ NO → Continue │
└─────────────────────────────────┘ └─────────────────────────────────┘
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Still need more details? │ │ Still need more details? │
├─────────────────────────────────┤ ├─────────────────────────────────┤
│ YES → get_node_info │ YES → get_node({detail: "full"})
└─────────────────────────────────┘ └─────────────────────────────────┘
``` ```
@@ -334,30 +345,27 @@ get_node_info({
} }
``` ```
### Using get_property_dependencies ### Finding Property Dependencies
**Example**: **Use get_node with search_properties mode**:
```javascript ```javascript
const deps = get_property_dependencies({ get_node({
nodeType: "nodes-base.httpRequest" nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "body"
}); });
// Returns dependency tree // Returns property paths matching "body" with descriptions
{ ```
"dependencies": {
"body": { **Or use full detail for complete schema**:
"shows_when": { ```javascript
"sendBody": [true], get_node({
"method": ["POST", "PUT", "PATCH", "DELETE"] nodeType: "nodes-base.httpRequest",
} detail: "full"
}, });
"queryParameters": {
"shows_when": { // Returns complete schema with displayOptions rules
"sendQuery": [true]
}
}
}
}
``` ```
**Use this when**: Validation fails and you don't understand why field is missing/required **Use this when**: Validation fails and you don't understand why field is missing/required
@@ -382,7 +390,7 @@ const deps = get_property_dependencies({
**How to configure**: **How to configure**:
1. Choose resource 1. Choose resource
2. Choose operation 2. Choose operation
3. Use get_node_essentials to see operation-specific requirements 3. Use get_node to see operation-specific requirements
4. Configure required fields 4. Configure required fields
### Pattern 2: HTTP-Based Nodes ### Pattern 2: HTTP-Based Nodes
@@ -573,14 +581,16 @@ body is required when:
**How to discover**: **How to discover**:
```javascript ```javascript
// Option 1: Read validation error // Option 1: Read validation error
validate_node_operation({...}); validate_node({...});
// Error: "body required when sendBody=true" // Error: "body required when sendBody=true"
// Option 2: Check dependencies // Option 2: Search for the property
get_property_dependencies({ get_node({
nodeType: "nodes-base.httpRequest" nodeType: "nodes-base.httpRequest",
mode: "search_properties",
propertyQuery: "body"
}); });
// Shows: body → shows_when: sendBody=[true], method=[POST,PUT,PATCH,DELETE] // Shows: body property with displayOptions rules
// Option 3: Try minimal config and iterate // Option 3: Try minimal config and iterate
// Start without body, validation will tell you if needed // Start without body, validation will tell you if needed
@@ -600,10 +610,11 @@ singleValue should be true when:
**Manual check**: **Manual check**:
```javascript ```javascript
get_property_dependencies({ get_node({
nodeType: "nodes-base.if" nodeType: "nodes-base.if",
detail: "full"
}); });
// Shows operator-specific dependencies // Shows complete schema with operator-specific rules
``` ```
--- ---
@@ -651,7 +662,7 @@ n8n_update_partial_workflow({...}); // YOLO
```javascript ```javascript
// Validate before deploying // Validate before deploying
const config = {...}; const config = {...};
const result = validate_node_operation({...}); const result = validate_node({...});
if (result.valid) { if (result.valid) {
n8n_update_partial_workflow({...}); n8n_update_partial_workflow({...});
} }
@@ -681,7 +692,7 @@ if (result.valid) {
**Good**: **Good**:
```javascript ```javascript
// Check requirements when changing operation // Check requirements when changing operation
get_node_essentials({ get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack"
}); });
// See what update operation needs (messageId, not channel) // See what update operation needs (messageId, not channel)
@@ -693,24 +704,24 @@ get_node_essentials({
### ✅ Do ### ✅ Do
1. **Start with get_node_essentials** 1. **Start with get_node (standard detail)**
- 91.7% success rate - ~1-2K tokens response
- Faster than get_node_info - Covers 95% of configuration needs
- Sufficient for most needs - Default detail level
2. **Validate iteratively** 2. **Validate iteratively**
- Configure → Validate → Fix → Repeat - Configure → Validate → Fix → Repeat
- Average 2-3 iterations is normal - Average 2-3 iterations is normal
- Read validation errors carefully - Read validation errors carefully
3. **Use property dependencies when stuck** 3. **Use search_properties mode when stuck**
- If field seems missing, check dependencies - If field seems missing, search for it
- Understand what controls field visibility - Understand what controls field visibility
- get_property_dependencies reveals rules - `get_node({mode: "search_properties", propertyQuery: "..."})`
4. **Respect operation context** 4. **Respect operation context**
- Different operations = different requirements - Different operations = different requirements
- Always check essentials when changing operation - Always check get_node when changing operation
- Don't assume configs are transferable - Don't assume configs are transferable
5. **Trust auto-sanitization** 5. **Trust auto-sanitization**
@@ -720,15 +731,15 @@ get_node_essentials({
### ❌ Don't ### ❌ Don't
1. **Jump to get_node_info immediately** 1. **Jump to detail="full" immediately**
- Try essentials first - Try standard detail first
- Only escalate if needed - Only escalate if needed
- Full schema is overwhelming - Full schema is 3-8K tokens
2. **Configure blindly** 2. **Configure blindly**
- Always validate before deploying - Always validate before deploying
- Understand why fields are required - Understand why fields are required
- Check dependencies for conditional fields - Use search_properties for conditional fields
3. **Copy configs without understanding** 3. **Copy configs without understanding**
- Different operations need different fields - Different operations need different fields
@@ -754,10 +765,10 @@ For comprehensive guides on specific topics:
## Summary ## Summary
**Configuration Strategy**: **Configuration Strategy**:
1. Start with get_node_essentials (91.7% success) 1. Start with `get_node` (standard detail is default)
2. Configure required fields for operation 2. Configure required fields for operation
3. Validate configuration 3. Validate configuration
4. Check dependencies if stuck 4. Search properties if stuck
5. Iterate until valid (avg 2-3 cycles) 5. Iterate until valid (avg 2-3 cycles)
6. Deploy with confidence 6. Deploy with confidence

View File

@@ -65,8 +65,8 @@ Common validation errors by priority:
**How to identify required fields**: **How to identify required fields**:
```javascript ```javascript
// Use get_node_essentials to see what's required // Use get_node to see what's required
const info = get_node_essentials({ const info = get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack"
}); });
// Check properties marked as "required": true // Check properties marked as "required": true
@@ -868,15 +868,15 @@ let config = {
text: "Hello" text: "Hello"
}; };
validate_node_operation({nodeType: "nodes-base.slack", config}); validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"});
// ✅ Valid // ✅ Valid
// Step 2: Add features one by one // Step 2: Add features one by one
config.attachments = [...]; config.attachments = [...];
validate_node_operation({nodeType: "nodes-base.slack", config}); validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"});
config.blocks = [...]; config.blocks = [...];
validate_node_operation({nodeType: "nodes-base.slack", config}); validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"});
``` ```
### Pattern 2: Error Triage ### Pattern 2: Error Triage
@@ -903,14 +903,14 @@ result.suggestions.forEach(sug => {
}); });
``` ```
### Pattern 3: Use get_node_essentials ### Pattern 3: Use get_node
**Problem**: Don't know what's required **Problem**: Don't know what's required
**Solution**: **Solution**:
```javascript ```javascript
// Before configuring, check requirements // Before configuring, check requirements
const info = get_node_essentials({ const info = get_node({
nodeType: "nodes-base.slack" nodeType: "nodes-base.slack"
}); });
@@ -927,7 +927,7 @@ info.properties.forEach(prop => {
## Summary ## Summary
**Most Common Errors**: **Most Common Errors**:
1. `missing_required` (45%) - Always check get_node_essentials 1. `missing_required` (45%) - Always check get_node
2. `invalid_value` (28%) - Check allowed values 2. `invalid_value` (28%) - Check allowed values
3. `type_mismatch` (12%) - Use correct data types 3. `type_mismatch` (12%) - Use correct data types
4. `invalid_expression` (8%) - Use Expression Syntax skill 4. `invalid_expression` (8%) - Use Expression Syntax skill

View File

@@ -530,7 +530,7 @@ Many warnings are context-dependent:
**Development**: **Development**:
```javascript ```javascript
validate_node_operation({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "ai-friendly" // Fewer warnings during development profile: "ai-friendly" // Fewer warnings during development
@@ -539,7 +539,7 @@ validate_node_operation({
**Pre-Production**: **Pre-Production**:
```javascript ```javascript
validate_node_operation({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" // Balanced validation profile: "runtime" // Balanced validation
@@ -548,7 +548,7 @@ validate_node_operation({
**Production Deployment**: **Production Deployment**:
```javascript ```javascript
validate_node_operation({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "strict" // All warnings, review each one profile: "strict" // All warnings, review each one

View File

@@ -79,13 +79,13 @@ Validation is typically iterative:
``` ```
1. Configure node 1. Configure node
2. validate_node_operation (23 seconds thinking about errors) 2. validate_node (23 seconds thinking about errors)
3. Read error messages carefully 3. Read error messages carefully
4. Fix errors 4. Fix errors
5. validate_node_operation again (58 seconds fixing) 5. validate_node again (58 seconds fixing)
6. Repeat until valid (usually 2-3 iterations) 6. Repeat until valid (usually 2-3 iterations)
``` ```
@@ -98,7 +98,7 @@ let config = {
operation: "create" operation: "create"
}; };
const result1 = validate_node_operation({ const result1 = validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" profile: "runtime"
@@ -110,7 +110,7 @@ const result1 = validate_node_operation({
// Iteration 2 // Iteration 2
config.name = "general"; config.name = "general";
const result2 = validate_node_operation({ const result2 = validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" profile: "runtime"
@@ -122,7 +122,7 @@ const result2 = validate_node_operation({
// Iteration 3 // Iteration 3
config.text = "Hello!"; config.text = "Hello!";
const result3 = validate_node_operation({ const result3 = validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config, config,
profile: "runtime" profile: "runtime"
@@ -193,7 +193,7 @@ Choose the right profile for your stage:
**What it means**: A required field is not provided **What it means**: A required field is not provided
**How to fix**: **How to fix**:
1. Use `get_node_essentials` to see required fields 1. Use `get_node` to see required fields
2. Add the missing field to your configuration 2. Add the missing field to your configuration
3. Provide an appropriate value 3. Provide an appropriate value
@@ -215,7 +215,7 @@ config.channel = "#general";
**How to fix**: **How to fix**:
1. Check error message for allowed values 1. Check error message for allowed values
2. Use `get_node_essentials` to see options 2. Use `get_node` to see options
3. Update to a valid value 3. Update to a valid value
**Example**: **Example**:
@@ -430,7 +430,7 @@ Validation warnings that are technically "wrong" but acceptable in your use case
**Use `ai-friendly` profile**: **Use `ai-friendly` profile**:
```javascript ```javascript
validate_node_operation({ validate_node({
nodeType: "nodes-base.slack", nodeType: "nodes-base.slack",
config: {...}, config: {...},
profile: "ai-friendly" // Fewer false positives profile: "ai-friendly" // Fewer false positives
@@ -585,7 +585,7 @@ validate_workflow({
**When**: Configuration is severely broken **When**: Configuration is severely broken
**Steps**: **Steps**:
1. Note required fields from `get_node_essentials` 1. Note required fields from `get_node`
2. Create minimal valid configuration 2. Create minimal valid configuration
3. Add features incrementally 3. Add features incrementally
4. Validate after each addition 4. Validate after each addition
@@ -642,7 +642,7 @@ n8n_autofix_workflow({
- Use `runtime` profile for pre-deployment - Use `runtime` profile for pre-deployment
- Check `valid` field before assuming success - Check `valid` field before assuming success
- Trust auto-sanitization for operator issues - Trust auto-sanitization for operator issues
- Use `get_node_essentials` when unclear about requirements - Use `get_node` when unclear about requirements
- Document false positives you accept - Document false positives you accept
### ❌ Don't ### ❌ Don't

View File

@@ -35,8 +35,9 @@ Teaches architectural patterns for building n8n workflows. Provides structure, b
**n8n-mcp tools**: **n8n-mcp tools**:
- search_nodes (find nodes for patterns) - search_nodes (find nodes for patterns)
- get_node_essentials (understand node operations) - get_node (understand node operations)
- search_templates (find example workflows) - search_templates (find example workflows)
- ai_agents_guide (AI pattern guidance)
**Related skills**: **Related skills**:
- n8n MCP Tools Expert (find and configure nodes) - n8n MCP Tools Expert (find and configure nodes)
@@ -230,7 +231,7 @@ Use `search_templates` to find examples for your use case!
**Node Discovery** (n8n MCP Tools Expert): **Node Discovery** (n8n MCP Tools Expert):
4. Find nodes for pattern (search_nodes) 4. Find nodes for pattern (search_nodes)
5. Understand node operations (get_node_essentials) 5. Understand node operations (get_node)
**Implementation** (n8n Expression Syntax + Node Configuration): **Implementation** (n8n Expression Syntax + Node Configuration):
6. Write expressions ({{$json.body.field}}) 6. Write expressions ({{$json.body.field}})

View File

@@ -126,14 +126,14 @@ When building ANY workflow, follow this checklist:
- [ ] Configure error handling - [ ] Configure error handling
### Validation Phase ### Validation Phase
- [ ] Validate each node configuration (validate_node_operation) - [ ] Validate each node configuration (validate_node)
- [ ] Validate complete workflow (validate_workflow) - [ ] Validate complete workflow (validate_workflow)
- [ ] Test with sample data - [ ] Test with sample data
- [ ] Handle edge cases (empty data, errors) - [ ] Handle edge cases (empty data, errors)
### Deployment Phase ### Deployment Phase
- [ ] Review workflow settings (execution order, timeout, error handling) - [ ] Review workflow settings (execution order, timeout, error handling)
- [ ] Activate workflow ⚠️ **Manual activation required in n8n UI** (API/MCP cannot activate) - [ ] Activate workflow using `activateWorkflow` operation
- [ ] Monitor first executions - [ ] Monitor first executions
- [ ] Document workflow purpose and data flow - [ ] Document workflow purpose and data flow
@@ -225,8 +225,10 @@ These skills work together with Workflow Patterns:
**n8n MCP Tools Expert** - Use to: **n8n MCP Tools Expert** - Use to:
- Find nodes for your pattern (search_nodes) - Find nodes for your pattern (search_nodes)
- Understand node operations (get_node_essentials) - Understand node operations (get_node)
- Create workflows (n8n_create_workflow) - Create workflows (n8n_create_workflow)
- Deploy templates (n8n_deploy_template)
- Use ai_agents_guide for AI pattern guidance
**n8n Expression Syntax** - Use to: **n8n Expression Syntax** - Use to:
- Write expressions in transformation nodes - Write expressions in transformation nodes