How to Use get_node with Compare, Breaking, and Migrations Modes for n8n Node Version Comparison

The get_node MCP tool in czlonkowski/n8n-mcp provides specialized compare, breaking, and migrations modes that analyze property-level differences between node versions to identify breaking changes and generate automated migration plans.

When managing n8n workflows across node version updates, understanding exactly what changed between versions is critical for maintaining stability. The get_node tool in the czlonkowski/n8n-mcp repository offers dedicated version comparison modes that analyze node schemas, detect breaking changes, and suggest migration strategies—directly from the MCP server implementation.

Understanding get_node Version Comparison Modes

The get_node tool supports four version-related modes beyond the default info mode. According to the tool schema defined in src/mcp/tools.ts (lines 76-95), each mode serves a specific purpose in the version analysis workflow.

The Four Version-Related Modes

• versions: Returns the complete version history of a node type.
• compare: Generates a full property-level diff between two versions, showing all changes including additions, removals, and modifications.
• breaking: Filters the comparison to show only breaking changes that could cause workflow failures.
• migrations: Identifies auto-migratable changes and provides a structured migration plan between specific versions.

Parameter Requirements by Mode

Each mode has specific parameter requirements as implemented in the request handler:

• compare and breaking: Require nodeType and fromVersion. The toVersion parameter is optional and defaults to the latest version if omitted.
• migrations: Requires both fromVersion and toVersion to generate a precise migration plan.
• versions: Only requires nodeType.

Implementation in n8n-mcp Source Code

The version comparison logic resides in src/mcp/server.ts, where the getNode() method validates parameters and routes requests to the appropriate handler.

When mode is set to anything other than info, the server calls handleVersionMode() (lines 73-81), which acts as a dispatcher:

private async handleVersionMode(
  nodeType: string,
  mode: string,
  fromVersion?: string,
  toVersion?: string,
): Promise<VersionHistoryInfo | VersionComparisonInfo> {
  switch (mode) {
    case 'versions':   return this.getVersionHistory(nodeType);
    case 'compare':    return this.compareVersions(nodeType, fromVersion!, toVersion);
    case 'breaking':   return this.getBreakingChanges(nodeType, fromVersion!, toVersion);
    case 'migrations': return this.getMigrations(nodeType, fromVersion!, toVersion);
    …
  }
}

Each helper method queries the node repository (this.repository) which stores per-version metadata:

• compareVersions(): Builds a comprehensive diff of property changes (lines 71-78).
• getBreakingChanges(): Filters the diff to highlight only breaking modifications, noting severity levels (lines 100-108).
• getMigrations(): Returns auto-migratable properties and flags manual interventions (lines 124-136).

Practical Usage Examples for Each Mode

Here are concrete implementations using the MCP client to interact with get_node in each version comparison mode.

Comparing Versions with compare Mode

Use the compare mode to generate a full audit of changes between versions:

const comparison = await client.callTool({
  name: 'get_node',
  arguments: {
    nodeType: 'nodes-base.httpRequest',
    mode: 'compare',
    fromVersion: '1.0',
    toVersion: '2.0'  // Optional: omit to compare against latest
  }
});

console.log(`Total changes: ${comparison.totalChanges}`);
console.log(`Breaking changes: ${comparison.breakingChanges}`);
comparison.changes.forEach(change => {
  console.log(`${change.property}: ${change.changeType} (Breaking: ${change.isBreaking})`);
});

The response includes totalChanges, breakingChanges, and a detailed changes array with property, changeType, and isBreaking flags.

Identifying Breaking Changes with breaking Mode

Use the breaking mode when planning upgrades to assess risk:

const riskAssessment = await client.callTool({
  name: 'get_node',
  arguments: {
    nodeType: 'nodes-base.httpRequest',
    mode: 'breaking',
    fromVersion: '1.0',
    toVersion: '2.0'
  }
});

if (riskAssessment.upgradeSafe) {
  console.log('No breaking changes detected – safe to upgrade');
} else {
  console.warn(`Found ${riskAssessment.totalBreakingChanges} breaking changes:`);
  riskAssessment.changes.forEach(change => {
    console.warn(`- ${change.property}: ${change.changeType} (Severity: ${change.severity})`);
  });
}

This mode returns an upgradeSafe boolean and filters the changes to only those with breaking impact, including severity classifications.

Planning Migrations with migrations Mode

Use the migrations mode to automate workflow updates:

const migrationPlan = await client.callTool({
  name: 'get_node',
  arguments: {
    nodeType: 'nodes-base.httpRequest',
    mode: 'migrations',
    fromVersion: '1.0',
    toVersion: '2.0'  // Required for migrations mode
  }
});

console.log(`${migrationPlan.autoMigratableChanges} of ${migrationPlan.totalChanges} changes can be automated`);
if (migrationPlan.requiresManualMigration) {
  console.log('Manual intervention required for:');
  migrationPlan.migrations
    .filter(m => m.severity !== 'low')
    .forEach(m => console.log(`- ${m.property}: ${m.migrationStrategy}`));
}

The migrations mode requires both version parameters and returns autoMigratableChanges, requiresManualMigration, and a migrations array with migrationStrategy values such as addDefault or rename.

When to Use Each get_node Version Mode

Choose the appropriate mode based on your specific workflow maintenance scenario:

• Use compare mode when you need a complete audit trail of all property changes, additions, and removals between versions for documentation or compliance purposes.
• Use breaking mode when evaluating upgrade risks before deploying to production; this filters the noise to show only changes that could cause workflow failures.
• Use migrations mode when building automated migration scripts or CI/CD pipelines that need to update workflow JSON files programmatically.
• Use versions mode when you simply need to list available versions or check which version is current.

Summary

• The get_node tool in czlonkowski/n8n-mcp provides specialized version comparison modes (compare, breaking, migrations) beyond basic node information retrieval.
• Parameter requirements vary by mode: compare and breaking require fromVersion with optional toVersion, while migrations mandates both version parameters.
• Implementation resides in src/mcp/server.ts with handleVersionMode() dispatching to compareVersions(), getBreakingChanges(), and getMigrations() helpers.
• Response structures include detailed change arrays, severity classifications, and migration strategies to support both manual audits and automated tooling.
• Use compare for full diffs, breaking for risk assessment, and migrations for automated workflow updates.

Frequently Asked Questions

What is the difference between compare mode and breaking mode in get_node?

The compare mode returns a comprehensive diff showing all property changes between versions, including minor additions, renames, and removals, along with a count of total and breaking changes. The breaking mode filters this output to display only changes that could cause workflow execution failures, providing an upgradeSafe boolean and severity classifications to help assess deployment risks.

Why does migrations mode require both fromVersion and toVersion parameters?

Unlike compare and breaking modes, which default toVersion to the latest release when omitted, the migrations mode requires explicit version boundaries because it generates a precise migration plan with specific strategies for each property change. According to the implementation in src/mcp/server.ts, this strict requirement ensures the migration helper can accurately map auto-migratable changes and flag manual interventions between the specific source and target versions.

Where does get_node store the version metadata used for these comparisons?

The version-specific metadata used by compare, breaking, and migrations modes is stored in the node repository accessed via this.repository in src/mcp/server.ts. This repository aggregates per-version property changes, breaking-change lists, and migration strategies that are extracted during the database rebuild process and queried by the compareVersions(), getBreakingChanges(), and getMigrations() helper methods.

Can I use get_node to migrate workflow JSON files automatically?

While the get_node tool itself does not modify workflow files, the migrations mode provides the necessary data structure to build automated migration scripts. The response includes autoMigratableChanges with specific migrationStrategy values (such as addDefault or rename) that indicate how each property should be transformed, enabling you to programmatically update workflow JSON files using the migration plan as a blueprint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}