fix: address tools documentation gaps and outdated references (v2.26.3) (#443)

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.26.3] - 2025-11-26
+
+### 🔧 Fixed
+
+- **Tools Documentation Gaps**: Addressed remaining documentation issues after v2.26.2 tool consolidation
+  - Added missing `n8n_workflow_versions` documentation with all 6 modes (list, get, rollback, delete, prune, truncate)
+  - Removed non-existent tools (`n8n_diagnostic`, `n8n_list_available_tools`) from documentation exports
+  - Fixed 10+ outdated tool name references:
+    - `get_node_essentials` → `get_node({detail: "standard"})`
+    - `validate_node_operation` → `validate_node()`
+    - `get_minimal` → `n8n_get_workflow({mode: "minimal"})`
+  - Added missing `mode` and `verbose` parameters to `n8n_health_check` documentation
+  - Added missing `mode` parameter to `get_template` documentation (nodes_only, structure, full)
+  - Updated template count from "399+" to "2,700+" in `get_template`
+  - Updated node count from "525" to "500+" in `search_nodes`
+  - Fixed `relatedTools` arrays to remove references to non-existent tools
+
+**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
+
 ## [2.26.2] - 2025-11-25
 
 ### 🔧 Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.26.2",
+  "version": "2.26.3",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package.runtime.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp-runtime",
-  "version": "2.23.0",
+  "version": "2.26.3",
   "description": "n8n MCP Server Runtime Dependencies Only",
   "private": true,
   "dependencies": {

src/mcp/tool-docs/discovery/search-nodes.ts

@@ -4,7 +4,7 @@ export const searchNodesDoc: ToolDocumentation = {
   name: 'search_nodes',
   category: 'discovery',
   essentials: {
-    description: 'Text search across node names and descriptions. Returns most relevant nodes first, with frequently-used nodes (HTTP Request, Webhook, Set, Code, Slack) prioritized in results. Searches all 525 nodes in the database.',
+    description: 'Text search across node names and descriptions. Returns most relevant nodes first, with frequently-used nodes (HTTP Request, Webhook, Set, Code, Slack) prioritized in results. Searches all 500+ nodes in the database.',
     keyParameters: ['query', 'mode', 'limit'],
     example: 'search_nodes({query: "webhook"})',
     performance: '<20ms even for complex queries',
@@ -42,7 +42,7 @@ export const searchNodesDoc: ToolDocumentation = {
       'Start with single keywords for broadest results',
       'Use FUZZY mode when users might misspell node names',
       'AND mode works best for 2-3 word searches',
-      'Combine with get_node_essentials after finding the right node'
+      'Combine with get_node after finding the right node'
     ],
     pitfalls: [
       'AND mode searches all fields (name, description) not just node names',

src/mcp/tool-docs/index.ts

@@ -7,9 +7,7 @@ import { validateNodeDoc, validateWorkflowDoc } from './validation';
 import { getTemplateDoc, searchTemplatesDoc } from './templates';
 import {
   toolsDocumentationDoc,
-  n8nDiagnosticDoc,
+  n8nHealthCheckDoc
-  n8nHealthCheckDoc,
-  n8nListAvailableToolsDoc
 } from './system';
 import { aiAgentsGuide } from './guides';
 import {
@@ -22,7 +20,8 @@ import {
   n8nValidateWorkflowDoc,
   n8nAutofixWorkflowDoc,
   n8nTriggerWebhookWorkflowDoc,
-  n8nExecutionsDoc
+  n8nExecutionsDoc,
+  n8nWorkflowVersionsDoc
 } from './workflow_management';
 
 // Combine all tool documentations into a single object
@@ -30,9 +29,7 @@ import {
 export const toolsDocumentation: Record<string, ToolDocumentation> = {
   // System tools
   tools_documentation: toolsDocumentationDoc,
-  n8n_diagnostic: n8nDiagnosticDoc,
   n8n_health_check: n8nHealthCheckDoc,
-  n8n_list_available_tools: n8nListAvailableToolsDoc,
 
   // Guides
   ai_agents_guide: aiAgentsGuide,
@@ -61,7 +58,8 @@ export const toolsDocumentation: Record<string, ToolDocumentation> = {
   n8n_validate_workflow: n8nValidateWorkflowDoc,
   n8n_autofix_workflow: n8nAutofixWorkflowDoc,
   n8n_trigger_webhook_workflow: n8nTriggerWebhookWorkflowDoc,
-  n8n_executions: n8nExecutionsDoc  // Actions replace: n8n_get_execution, n8n_list_executions, n8n_delete_execution
+  n8n_executions: n8nExecutionsDoc,  // Actions replace: n8n_get_execution, n8n_list_executions, n8n_delete_execution
+  n8n_workflow_versions: n8nWorkflowVersionsDoc  // Modes: list, get, rollback, delete, prune, truncate
 };
 
 // Re-export types

src/mcp/tool-docs/system/index.ts

@@ -1,4 +1,2 @@
 export { toolsDocumentationDoc } from './tools-documentation';
-export { n8nDiagnosticDoc } from './n8n-diagnostic';
+export { n8nHealthCheckDoc } from './n8n-health-check';
-export { n8nHealthCheckDoc } from './n8n-health-check';
-export { n8nListAvailableToolsDoc } from './n8n-list-available-tools';

src/mcp/tool-docs/system/n8n-health-check.ts

@@ -5,8 +5,8 @@ export const n8nHealthCheckDoc: ToolDocumentation = {
   category: 'system',
   essentials: {
     description: 'Check n8n instance health, API connectivity, version status, and performance metrics',
-    keyParameters: [],
+    keyParameters: ['mode', 'verbose'],
-    example: 'n8n_health_check({})',
+    example: 'n8n_health_check({mode: "status"})',
     performance: 'Fast - single API call (~150-200ms median)',
     tips: [
       'Use before starting workflow operations to ensure n8n is responsive',
@@ -31,7 +31,21 @@ Health checks are crucial for:
 - Detecting performance degradation
 - Verifying API compatibility before operations
 - Ensuring authentication is working correctly`,
-    parameters: {},
+    parameters: {
+      mode: {
+        type: 'string',
+        required: false,
+        description: 'Operation mode: "status" (default) for quick health check, "diagnostic" for detailed debug info including env vars and tool status',
+        default: 'status',
+        enum: ['status', 'diagnostic']
+      },
+      verbose: {
+        type: 'boolean',
+        required: false,
+        description: 'Include extra details in diagnostic mode',
+        default: false
+      }
+    },
     returns: `Health status object containing:
 - status: Overall health status ('healthy', 'degraded', 'error')
 - n8nVersion: n8n instance version information
@@ -81,6 +95,6 @@ Health checks are crucial for:
       'Does not check individual workflow health',
       'Health endpoint might be cached - not real-time for all metrics'
     ],
-    relatedTools: ['n8n_diagnostic', 'n8n_list_available_tools', 'n8n_list_workflows']
+    relatedTools: ['n8n_list_workflows', 'n8n_validate_workflow', 'n8n_workflow_versions']
   }
 };

src/mcp/tool-docs/templates/get-template.ts

@@ -4,23 +4,30 @@ export const getTemplateDoc: ToolDocumentation = {
   name: 'get_template',
   category: 'templates',
   essentials: {
-    description: 'Get complete workflow JSON by ID. Ready to import. IDs from search_templates.',
+    description: 'Get workflow template by ID with configurable detail level. Ready to import. IDs from search_templates.',
-    keyParameters: ['templateId'],
+    keyParameters: ['templateId', 'mode'],
-    example: 'get_template({templateId: 1234})',
+    example: 'get_template({templateId: 1234, mode: "full"})',
     performance: 'Fast (<100ms) - single database lookup',
     tips: [
       'Get template IDs from search_templates first',
-      'Returns complete workflow JSON ready for import into n8n',
+      'Use mode="nodes_only" for quick overview, "structure" for topology, "full" for import',
-      'Includes all nodes, connections, and settings'
+      'Returns complete workflow JSON ready for import into n8n'
     ]
   },
   full: {
-    description: `Retrieves the complete workflow JSON for a specific template by its ID. The returned workflow can be directly imported into n8n through the UI or API. This tool fetches pre-built workflows from the community template library containing 399+ curated workflows.`,
+    description: `Retrieves the complete workflow JSON for a specific template by its ID. The returned workflow can be directly imported into n8n through the UI or API. This tool fetches pre-built workflows from the community template library containing 2,700+ curated workflows.`,
     parameters: {
       templateId: {
         type: 'number',
         required: true,
         description: 'The numeric ID of the template to retrieve. Get IDs from search_templates'
+      },
+      mode: {
+        type: 'string',
+        required: false,
+        description: 'Response detail level: "nodes_only" (minimal - just node list), "structure" (nodes + connections), "full" (complete workflow JSON, default)',
+        default: 'full',
+        enum: ['nodes_only', 'structure', 'full']
       }
     },
     returns: `Returns an object containing:
@@ -39,9 +46,10 @@ export const getTemplateDoc: ToolDocumentation = {
     - settings: Workflow configuration (timezone, error handling, etc.)
 - usage: Instructions for using the workflow`,
     examples: [
-      'get_template({templateId: 1234}) - Get Slack notification workflow',
+      'get_template({templateId: 1234}) - Get complete workflow (default mode="full")',
-      'get_template({templateId: 5678}) - Get data sync workflow',
+      'get_template({templateId: 1234, mode: "nodes_only"}) - Get just the node list',
-      'get_template({templateId: 9012}) - Get AI chatbot workflow'
+      'get_template({templateId: 1234, mode: "structure"}) - Get nodes and connections',
+      'get_template({templateId: 5678, mode: "full"}) - Get complete workflow JSON for import'
     ],
     useCases: [
       'Download workflows for direct import into n8n',

src/mcp/tool-docs/workflow_management/index.ts

@@ -8,3 +8,4 @@ export { n8nValidateWorkflowDoc } from './n8n-validate-workflow';
 export { n8nAutofixWorkflowDoc } from './n8n-autofix-workflow';
 export { n8nTriggerWebhookWorkflowDoc } from './n8n-trigger-webhook-workflow';
 export { n8nExecutionsDoc } from './n8n-executions';
+export { n8nWorkflowVersionsDoc } from './n8n-workflow-versions';

src/mcp/tool-docs/workflow_management/n8n-delete-workflow.ts

@@ -11,7 +11,7 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = {
     tips: [
       'Action is irreversible',
       'Deletes all execution history',
-      'Check workflow first with get_minimal'
+      'Check workflow first with n8n_get_workflow({mode: "minimal"})'
     ]
   },
   full: {
@@ -34,7 +34,7 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = {
     performance: 'Fast operation - typically 50-150ms. May take longer if workflow has extensive execution history.',
     bestPractices: [
       'Always confirm before deletion',
-      'Check workflow with get_minimal first',
+      'Check workflow with n8n_get_workflow({mode: "minimal"}) first',
       'Consider deactivating instead of deleting',
       'Export workflow before deletion for backup'
     ],

src/mcp/tool-docs/workflow_management/n8n-workflow-versions.ts

@@ -0,0 +1,168 @@
+import { ToolDocumentation } from '../types';
+
+export const n8nWorkflowVersionsDoc: ToolDocumentation = {
+  name: 'n8n_workflow_versions',
+  category: 'workflow_management',
+  essentials: {
+    description: 'Manage workflow version history, rollback to previous versions, and cleanup old versions',
+    keyParameters: ['mode', 'workflowId', 'versionId'],
+    example: 'n8n_workflow_versions({mode: "list", workflowId: "abc123"})',
+    performance: 'Fast for list/get (~100ms), moderate for rollback (~200-500ms)',
+    tips: [
+      'Use mode="list" to see all saved versions before rollback',
+      'Rollback creates a backup version automatically',
+      'Use prune to clean up old versions and save storage',
+      'truncate requires explicit confirmTruncate: true'
+    ]
+  },
+  full: {
+    description: `Comprehensive workflow version management system. Supports six operations:
+
+**list** - Show version history for a workflow
+- Returns all saved versions with timestamps, snapshot sizes, and metadata
+- Use limit parameter to control how many versions to return
+
+**get** - Get details of a specific version
+- Returns the complete workflow snapshot from that version
+- Use to compare versions or extract old configurations
+
+**rollback** - Restore workflow to a previous version
+- Creates a backup of the current workflow before rollback
+- Optionally validates the workflow structure before applying
+- Returns the restored workflow and backup version ID
+
+**delete** - Delete specific version(s)
+- Delete a single version by versionId
+- Delete all versions for a workflow with deleteAll: true
+
+**prune** - Clean up old versions
+- Keeps only the N most recent versions (default: 10)
+- Useful for managing storage and keeping history manageable
+
+**truncate** - Delete ALL versions for ALL workflows
+- Dangerous operation requiring explicit confirmation
+- Use for complete version history cleanup`,
+    parameters: {
+      mode: {
+        type: 'string',
+        required: true,
+        description: 'Operation mode: "list", "get", "rollback", "delete", "prune", or "truncate"',
+        enum: ['list', 'get', 'rollback', 'delete', 'prune', 'truncate']
+      },
+      workflowId: {
+        type: 'string',
+        required: false,
+        description: 'Workflow ID (required for list, rollback, delete, prune modes)'
+      },
+      versionId: {
+        type: 'number',
+        required: false,
+        description: 'Version ID (required for get mode, optional for rollback to specific version, required for single delete)'
+      },
+      limit: {
+        type: 'number',
+        required: false,
+        default: 10,
+        description: 'Maximum versions to return in list mode'
+      },
+      validateBefore: {
+        type: 'boolean',
+        required: false,
+        default: true,
+        description: 'Validate workflow structure before rollback (rollback mode only)'
+      },
+      deleteAll: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description: 'Delete all versions for workflow (delete mode only)'
+      },
+      maxVersions: {
+        type: 'number',
+        required: false,
+        default: 10,
+        description: 'Keep N most recent versions (prune mode only)'
+      },
+      confirmTruncate: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description: 'REQUIRED: Must be true to truncate all versions (truncate mode only)'
+      }
+    },
+    returns: `Response varies by mode:
+
+**list mode:**
+- versions: Array of version objects with id, workflowId, snapshotSize, createdAt
+- totalCount: Total number of versions
+
+**get mode:**
+- version: Complete version object including workflow snapshot
+
+**rollback mode:**
+- success: Boolean indicating success
+- restoredVersion: The version that was restored
+- backupVersionId: ID of the backup created before rollback
+
+**delete mode:**
+- deletedCount: Number of versions deleted
+
+**prune mode:**
+- prunedCount: Number of old versions removed
+- remainingCount: Number of versions kept
+
+**truncate mode:**
+- deletedCount: Total versions deleted across all workflows`,
+    examples: [
+      '// List version history\nn8n_workflow_versions({mode: "list", workflowId: "abc123", limit: 5})',
+      '// Get specific version details\nn8n_workflow_versions({mode: "get", versionId: 42})',
+      '// Rollback to latest saved version\nn8n_workflow_versions({mode: "rollback", workflowId: "abc123"})',
+      '// Rollback to specific version\nn8n_workflow_versions({mode: "rollback", workflowId: "abc123", versionId: 42})',
+      '// Delete specific version\nn8n_workflow_versions({mode: "delete", workflowId: "abc123", versionId: 42})',
+      '// Delete all versions for workflow\nn8n_workflow_versions({mode: "delete", workflowId: "abc123", deleteAll: true})',
+      '// Prune to keep only 5 most recent\nn8n_workflow_versions({mode: "prune", workflowId: "abc123", maxVersions: 5})',
+      '// Truncate all versions (dangerous!)\nn8n_workflow_versions({mode: "truncate", confirmTruncate: true})'
+    ],
+    useCases: [
+      'Recover from accidental workflow changes',
+      'Compare workflow versions to understand changes',
+      'Maintain audit trail of workflow modifications',
+      'Clean up old versions to save database storage',
+      'Roll back failed workflow deployments'
+    ],
+    performance: `Performance varies by operation:
+- list: Fast (~100ms) - simple database query
+- get: Fast (~100ms) - single row retrieval
+- rollback: Moderate (~200-500ms) - includes backup creation and workflow update
+- delete: Fast (~50-100ms) - database delete operation
+- prune: Moderate (~100-300ms) - depends on number of versions to delete
+- truncate: Slow (1-5s) - deletes all records across all workflows`,
+    modeComparison: `| Mode | Required Params | Optional Params | Risk Level |
+|------|-----------------|-----------------|------------|
+| list | workflowId | limit | Low |
+| get | versionId | - | Low |
+| rollback | workflowId | versionId, validateBefore | Medium |
+| delete | workflowId | versionId, deleteAll | High |
+| prune | workflowId | maxVersions | Medium |
+| truncate | confirmTruncate=true | - | Critical |`,
+    bestPractices: [
+      'Always list versions before rollback to pick the right one',
+      'Enable validateBefore for rollback to catch structural issues',
+      'Use prune regularly to keep version history manageable',
+      'Never use truncate in production without explicit need',
+      'Document why you are rolling back for audit purposes'
+    ],
+    pitfalls: [
+      'Rollback overwrites current workflow - backup is created automatically',
+      'Deleted versions cannot be recovered',
+      'Truncate affects ALL workflows - use with extreme caution',
+      'Version IDs are sequential but may have gaps after deletes',
+      'Large workflows may have significant version storage overhead'
+    ],
+    relatedTools: [
+      'n8n_get_workflow - View current workflow state',
+      'n8n_update_partial_workflow - Make incremental changes',
+      'n8n_validate_workflow - Validate before deployment'
+    ]
+  }
+};

src/mcp/tools-documentation.ts

@@ -422,8 +422,8 @@ try {
 5. Use descriptive variable names
 
 ## Related Tools
-- get_node_essentials("nodes-base.code")
+- get_node({nodeType: "nodes-base.code"}) - Get Code node configuration details
-- validate_node_operation()
+- validate_node({nodeType: "nodes-base.code", config: {...}}) - Validate Code node setup
 - python_code_node_guide (for Python syntax)`;
 }
 
@@ -691,7 +691,7 @@ except json.JSONDecodeError:
 \`\`\`
 
 ## Related Tools
-- get_node_essentials("nodes-base.code")
+- get_node({nodeType: "nodes-base.code"}) - Get Code node configuration details
-- validate_node_operation()
+- validate_node({nodeType: "nodes-base.code", config: {...}}) - Validate Code node setup
 - javascript_code_node_guide (for JavaScript syntax)`;
 }