ros/n8n-mcp
1
0
Fork 0
mirror of https://github.com/czlonkowski/n8n-mcp.git synced 2026-02-07 22:13:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add auto-update node versions to autofixer

Browse Source 
Implemented comprehensive node version upgrade functionality with intelligent
migration and breaking change detection.

Key Features:
- Smart version upgrades (typeversion-upgrade fix type)
- Version migration guidance (version-migration fix type)
- Auto-migration for Execute Workflow v1.0→v1.1 (adds inputFieldMapping)
- Auto-migration for Webhook v2.0→v2.1 (generates webhookId)
- Breaking changes registry with extensible patterns
- AI-friendly post-update validation guidance
- Confidence-based application (HIGH/MEDIUM/LOW)

Architecture:
- NodeVersionService: Version discovery and comparison
- BreakingChangeDetector: Registry + dynamic schema comparison
- NodeMigrationService: Smart property migrations
- PostUpdateValidator: Step-by-step migration instructions
- Enhanced database schema: node_versions, version_property_changes tables

Services Created:
- src/services/breaking-changes-registry.ts
- src/services/breaking-change-detector.ts
- src/services/node-version-service.ts
- src/services/node-migration-service.ts
- src/services/post-update-validator.ts

Database Enhanced:
- src/database/schema.sql (new version tracking tables)
- src/database/node-repository.ts (15+ version query methods)

Autofixer Integration:
- src/services/workflow-auto-fixer.ts (async, new fix types)
- src/mcp/handlers-n8n-manager.ts (await generateFixes)
- src/mcp/tools-n8n-manager.ts (schema with new fix types)

Documentation:
- src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts
- CHANGELOG.md (comprehensive feature documentation)

Testing:
- Fixed all test scripts to await async generateFixes()
- Added test workflow for Execute Workflow v1.0 upgrade testing

Bug Fixes:
- Fixed MCP tool schema enum to include new fix types
- Fixed confidence type mapping (lowercase → uppercase)

Conceived by Romuald Członkowski - www.aiadvisors.pl/en
This commit is contained in:
czlonkowski
2025-10-24 08:34:47 +02:00
parent 5702a64a01
commit c7f8614de1
16 changed files with 2526 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/mcp/handlers-n8n-manager.ts
View File

@@ -995,7 +995,7 @@ export async function handleAutofixWorkflow(
// Generate fixes using WorkflowAutoFixer
const autoFixer = new WorkflowAutoFixer(repository);
const fixResult = autoFixer.generateFixes(
const fixResult = await autoFixer.generateFixes(
workflow,
validationResult,
allFormatIssues,

58
src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts
View File

@@ -4,15 +4,17 @@ export const n8nAutofixWorkflowDoc: ToolDocumentation = {
name: 'n8n_autofix_workflow',
category: 'workflow_management',
essentials: {
description: 'Automatically fix common workflow validation errors - expression formats, typeVersions, error outputs, webhook paths',
description: 'Automatically fix common workflow validation errors - expression formats, typeVersions, error outputs, webhook paths, and smart version upgrades',
keyParameters: ['id', 'applyFixes'],
example: 'n8n_autofix_workflow({id: "wf_abc123", applyFixes: false})',
performance: 'Network-dependent (200-1000ms) - fetches, validates, and optionally updates workflow',
performance: 'Network-dependent (200-1500ms) - fetches, validates, and optionally updates workflow with smart migrations',
tips: [
'Use applyFixes: false to preview changes before applying',
'Set confidenceThreshold to control fix aggressiveness (high/medium/low)',
'Supports fixing expression formats, typeVersion issues, error outputs, node type corrections, and webhook paths',
'High-confidence fixes (≥90%) are safe for auto-application'
'Supports expression formats, typeVersion issues, error outputs, node corrections, webhook paths, AND version upgrades',
'High-confidence fixes (≥90%) are safe for auto-application',
'Version upgrades include smart migration with breaking change detection',
'Post-update guidance provides AI-friendly step-by-step instructions for manual changes'
]
},
full: {
@@ -39,6 +41,20 @@ The auto-fixer can resolve:
- Sets both 'path' parameter and 'webhookId' field to the same UUID
- Ensures webhook nodes become functional with valid endpoints
- High confidence fix as UUID generation is deterministic
6. **Smart Version Upgrades** (NEW): Proactively upgrades nodes to their latest versions:
- Detects outdated node versions and recommends upgrades
- Applies smart migrations with auto-migratable property changes
- Handles breaking changes intelligently (Execute Workflow v1.0→v1.1, Webhook v2.0→v2.1, etc.)
- Generates UUIDs for required fields (webhookId), sets sensible defaults
- HIGH confidence for non-breaking upgrades, MEDIUM for breaking changes with auto-migration
- Example: Execute Workflow v1.0→v1.1 adds inputFieldMapping automatically
7. **Version Migration Guidance** (NEW): Documents complex migrations requiring manual intervention:
- Identifies breaking changes that cannot be auto-migrated
- Provides AI-friendly post-update guidance with step-by-step instructions
- Lists required actions by priority (CRITICAL, HIGH, MEDIUM, LOW)
- Documents behavior changes and their impact
- Estimates time required for manual migration steps
- MEDIUM/LOW confidence - requires review before applying
The tool uses a confidence-based system to ensure safe fixes:
- **High (≥90%)**: Safe to auto-apply (exact matches, known patterns)
@@ -60,7 +76,7 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
fixTypes: {
type: 'array',
required: false,
description: 'Types of fixes to apply. Options: ["expression-format", "typeversion-correction", "error-output-config", "node-type-correction", "webhook-missing-path"]. Default: all types.'
description: 'Types of fixes to apply. Options: ["expression-format", "typeversion-correction", "error-output-config", "node-type-correction", "webhook-missing-path", "typeversion-upgrade", "version-migration"]. Default: all types. NEW: "typeversion-upgrade" for smart version upgrades, "version-migration" for complex migration guidance.'
},
confidenceThreshold: {
type: 'string',
@@ -78,13 +94,21 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
- fixes: Detailed list of individual fixes with before/after values
- summary: Human-readable summary of fixes
- stats: Statistics by fix type and confidence level
- applied: Boolean indicating if fixes were applied (when applyFixes: true)`,
- applied: Boolean indicating if fixes were applied (when applyFixes: true)
- postUpdateGuidance: (NEW) Array of AI-friendly migration guidance for version upgrades, including:
* Required actions by priority (CRITICAL, HIGH, MEDIUM, LOW)
* Deprecated properties to remove
* Behavior changes and their impact
* Step-by-step migration instructions
* Estimated time for manual changes`,
examples: [
'n8n_autofix_workflow({id: "wf_abc123"}) - Preview all possible fixes',
'n8n_autofix_workflow({id: "wf_abc123"}) - Preview all possible fixes including version upgrades',
'n8n_autofix_workflow({id: "wf_abc123", applyFixes: true}) - Apply all medium+ confidence fixes',
'n8n_autofix_workflow({id: "wf_abc123", applyFixes: true, confidenceThreshold: "high"}) - Only apply high-confidence fixes',
'n8n_autofix_workflow({id: "wf_abc123", fixTypes: ["expression-format"]}) - Only fix expression format issues',
'n8n_autofix_workflow({id: "wf_abc123", fixTypes: ["webhook-missing-path"]}) - Only fix webhook path issues',
'n8n_autofix_workflow({id: "wf_abc123", fixTypes: ["typeversion-upgrade"]}) - NEW: Only upgrade node versions with smart migrations',
'n8n_autofix_workflow({id: "wf_abc123", fixTypes: ["typeversion-upgrade", "version-migration"]}) - NEW: Upgrade versions and provide migration guidance',
'n8n_autofix_workflow({id: "wf_abc123", applyFixes: true, maxFixes: 10}) - Apply up to 10 fixes'
],
useCases: [
@@ -94,16 +118,23 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
'Cleaning up workflows before production deployment',
'Batch fixing common issues across multiple workflows',
'Migrating workflows between n8n instances with different versions',
'Repairing webhook nodes that lost their path configuration'
'Repairing webhook nodes that lost their path configuration',
'Upgrading Execute Workflow nodes from v1.0 to v1.1+ with automatic inputFieldMapping',
'Modernizing webhook nodes to v2.1+ with stable webhookId fields',
'Proactively keeping workflows up-to-date with latest node versions',
'Getting detailed migration guidance for complex breaking changes'
],
performance: 'Depends on workflow size and number of issues. Preview mode: 200-500ms. Apply mode: 500-1000ms for medium workflows. Node similarity matching is cached for 5 minutes for improved performance on repeated validations.',
performance: 'Depends on workflow size and number of issues. Preview mode: 200-500ms. Apply mode: 500-1500ms for medium workflows with version upgrades. Node similarity matching and version metadata are cached for 5 minutes for improved performance on repeated validations.',
bestPractices: [
'Always preview fixes first (applyFixes: false) before applying',
'Start with high confidence threshold for production workflows',
'Review the fix summary to understand what changed',
'Test workflows after auto-fixing to ensure expected behavior',
'Use fixTypes parameter to target specific issue categories',
'Keep maxFixes reasonable to avoid too many changes at once'
'Keep maxFixes reasonable to avoid too many changes at once',
'NEW: Review postUpdateGuidance for version upgrades - contains step-by-step migration instructions',
'NEW: Test workflows after version upgrades - behavior may change even with successful auto-migration',
'NEW: Apply version upgrades incrementally - start with high-confidence, non-breaking upgrades'
],
pitfalls: [
'Some fixes may change workflow behavior - always test after fixing',
@@ -112,7 +143,12 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
'Node type corrections only work for known node types in the database',
'Cannot fix structural issues like missing nodes or invalid connections',
'TypeVersion downgrades might remove node features added in newer versions',
'Generated webhook paths are new UUIDs - existing webhook URLs will change'
'Generated webhook paths are new UUIDs - existing webhook URLs will change',
'NEW: Version upgrades may introduce breaking changes - review postUpdateGuidance carefully',
'NEW: Auto-migrated properties use sensible defaults which may not match your use case',
'NEW: Execute Workflow v1.1+ requires explicit inputFieldMapping - automatic mapping uses empty array',
'NEW: Some breaking changes cannot be auto-migrated and require manual intervention',
'NEW: Version history is based on registry - unknown nodes cannot be upgraded'
],
relatedTools: [
'n8n_validate_workflow',

2
src/mcp/tools-n8n-manager.ts
View File

@@ -293,7 +293,7 @@ export const n8nManagementTools: ToolDefinition[] = [
description: 'Types of fixes to apply (default: all)',
items: {
type: 'string',
enum: ['expression-format', 'typeversion-correction', 'error-output-config', 'node-type-correction', 'webhook-missing-path']
enum: ['expression-format', 'typeversion-correction', 'error-output-config', 'node-type-correction', 'webhook-missing-path', 'typeversion-upgrade', 'version-migration']
}
},
confidenceThreshold: {