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

feat: Tool consolidation v2.26.0 - reduce tools by 38% (31 → 19)

Browse Source 
Major consolidation of MCP tools using mode-based parameters for better
AI agent ergonomics:

Node Tools:
- get_node_documentation → get_node with mode='documentation'
- search_node_properties → get_node with mode='search_properties'
- get_property_dependencies → removed

Validation Tools:
- validate_node_operation + validate_node_minimal → validate_node with mode param

Template Tools:
- list_node_templates → search_templates with searchMode='nodes'
- search_templates_by_metadata → search_templates with searchMode='metadata'
- get_templates_for_task → search_templates with searchMode='task'

Workflow Getters:
- n8n_get_workflow_details/structure/minimal → n8n_get_workflow with mode param

Execution Tools:
- n8n_list/get/delete_execution → n8n_executions with action param

Test updates for all consolidated tools.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
This commit is contained in:
czlonkowski
2025-11-25 16:38:13 +01:00
parent 7f03f51e87
commit 96dfbc3a16
12 changed files with 534 additions and 590 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
CHANGELOG.md
View File

@@ -7,6 +7,161 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [2.26.0] - 2025-01-25
### ✨ Features
**Tool Consolidation - Reduced Tool Count by 38%**
Major consolidation of MCP tools from 31 tools to 19 tools, using mode-based parameters for better AI agent ergonomics. This reduces cognitive load for AI agents while maintaining full functionality.
#### Consolidated Tools
**1. Node Tools - `get_node` Enhanced**
The `get_node` tool now supports additional modes:
- `mode='docs'`: Replaces `get_node_documentation` - returns readable docs with examples
- `mode='search_properties'`: Replaces `search_node_properties` - search within node properties
```javascript
// Old: get_node_documentation
get_node_documentation({nodeType: "nodes-base.slack"})
// New: mode='docs'
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// Old: search_node_properties
search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"})
// New: mode='search_properties'
get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})
```
**2. Validation Tools - `validate_node` Unified**
Consolidated `validate_node_operation` and `validate_node_minimal` into single `validate_node`:
- `mode='full'`: Full validation (replaces `validate_node_operation`)
- `mode='minimal'`: Quick required fields check (replaces `validate_node_minimal`)
```javascript
// Old: validate_node_operation
validate_node_operation({nodeType: "nodes-base.slack", config: {...}})
// New: mode='full' (default)
validate_node({nodeType: "nodes-base.slack", config: {...}, mode: "full"})
// Old: validate_node_minimal
validate_node_minimal({nodeType: "nodes-base.slack", config: {}})
// New: mode='minimal'
validate_node({nodeType: "nodes-base.slack", config: {}, mode: "minimal"})
```
**3. Template Tools - `search_templates` Enhanced**
Consolidated `list_node_templates`, `search_templates_by_metadata`, and `get_templates_for_task`:
- `searchMode='keyword'`: Search by keywords (default, was `search_templates`)
- `searchMode='by_nodes'`: Search by node types (was `list_node_templates`)
- `searchMode='by_metadata'`: Search by AI metadata (was `search_templates_by_metadata`)
- `searchMode='by_task'`: Search by task type (was `get_templates_for_task`)
```javascript
// Old: list_node_templates
list_node_templates({nodeTypes: ["n8n-nodes-base.httpRequest"]})
// New: searchMode='by_nodes'
search_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest"]})
// Old: get_templates_for_task
get_templates_for_task({task: "webhook_processing"})
// New: searchMode='by_task'
search_templates({searchMode: "by_task", task: "webhook_processing"})
```
**4. Workflow Getters - `n8n_get_workflow` Enhanced**
Consolidated `n8n_get_workflow_details`, `n8n_get_workflow_structure`, `n8n_get_workflow_minimal`:
- `mode='full'`: Complete workflow data (default)
- `mode='details'`: Workflow with metadata (was `n8n_get_workflow_details`)
- `mode='structure'`: Nodes and connections only (was `n8n_get_workflow_structure`)
- `mode='minimal'`: ID, name, active status (was `n8n_get_workflow_minimal`)
```javascript
// Old: n8n_get_workflow_details
n8n_get_workflow_details({id: "123"})
// New: mode='details'
n8n_get_workflow({id: "123", mode: "details"})
// Old: n8n_get_workflow_minimal
n8n_get_workflow_minimal({id: "123"})
// New: mode='minimal'
n8n_get_workflow({id: "123", mode: "minimal"})
```
**5. Execution Tools - `n8n_executions` Unified**
Consolidated `n8n_list_executions`, `n8n_get_execution`, `n8n_delete_execution`:
- `action='list'`: List executions with filters
- `action='get'`: Get single execution details
- `action='delete'`: Delete an execution
```javascript
// Old: n8n_list_executions
n8n_list_executions({workflowId: "123", status: "success"})
// New: action='list'
n8n_executions({action: "list", workflowId: "123", status: "success"})
// Old: n8n_get_execution
n8n_get_execution({id: "456"})
// New: action='get'
n8n_executions({action: "get", id: "456"})
// Old: n8n_delete_execution
n8n_delete_execution({id: "456"})
// New: action='delete'
n8n_executions({action: "delete", id: "456"})
```
### 🗑️ Removed Tools
The following tools have been removed (use consolidated equivalents):
- `get_node_documentation` → `get_node` with `mode='docs'`
- `search_node_properties` → `get_node` with `mode='search_properties'`
- `get_property_dependencies` → Removed (use `validate_node` for dependency info)
- `validate_node_operation` → `validate_node` with `mode='full'`
- `validate_node_minimal` → `validate_node` with `mode='minimal'`
- `list_node_templates` → `search_templates` with `searchMode='by_nodes'`
- `search_templates_by_metadata` → `search_templates` with `searchMode='by_metadata'`
- `get_templates_for_task` → `search_templates` with `searchMode='by_task'`
- `n8n_get_workflow_details` → `n8n_get_workflow` with `mode='details'`
- `n8n_get_workflow_structure` → `n8n_get_workflow` with `mode='structure'`
- `n8n_get_workflow_minimal` → `n8n_get_workflow` with `mode='minimal'`
- `n8n_list_executions` → `n8n_executions` with `action='list'`
- `n8n_get_execution` → `n8n_executions` with `action='get'`
- `n8n_delete_execution` → `n8n_executions` with `action='delete'`
### 📊 Impact
**Tool Count**: 31 → 19 tools (38% reduction)
**For AI Agents:**
- Fewer tools to choose from reduces decision complexity
- Mode-based parameters provide clear action disambiguation
- Consistent patterns across tool categories
- Backward-compatible parameter handling
**For Users:**
- Simpler tool discovery and documentation
- Consistent API design patterns
- Reduced token usage in tool descriptions
### 🔧 Technical Details
**Files Modified:**
- `src/mcp/tools.ts` - Consolidated tool definitions
- `src/mcp/tools-n8n-manager.ts` - n8n manager tool consolidation
- `src/mcp/server.ts` - Handler consolidation and mode routing
- `tests/unit/mcp/parameter-validation.test.ts` - Updated for new tool names
- `tests/integration/mcp-protocol/tool-invocation.test.ts` - Updated test cases
- `tests/integration/mcp-protocol/error-handling.test.ts` - Updated error handling tests
**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
## [2.24.1] - 2025-01-24
### ✨ Features

2
package.json
View File

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

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

@@ -1787,8 +1787,8 @@ export async function handleDiagnostic(request: any, context?: InstanceContext):
}
// Check which tools are available
const documentationTools = 14; // Base documentation tools (after v2.25.0 cleanup)
const managementTools = apiConfigured ? 17 : 0; // Management tools requiring API (includes n8n_health_check)
const documentationTools = 7; // Base documentation tools (after v2.26.0 consolidation)
const managementTools = apiConfigured ? 12 : 0; // Management tools requiring API (after v2.26.0 consolidation)
const totalTools = documentationTools + managementTools;
// Check npm version

197
src/mcp/server.ts
View File

@@ -830,36 +830,32 @@ export class N8NDocumentationMCPServer {
let validationResult;
switch (toolName) {
case 'validate_node_operation':
case 'validate_node':
// Consolidated tool handles both modes - validate as operation for now
validationResult = ToolValidation.validateNodeOperation(args);
break;
case 'validate_node_minimal':
validationResult = ToolValidation.validateNodeMinimal(args);
break;
case 'validate_workflow':
validationResult = ToolValidation.validateWorkflow(args);
break;
case 'search_nodes':
validationResult = ToolValidation.validateSearchNodes(args);
break;
case 'list_node_templates':
validationResult = ToolValidation.validateListNodeTemplates(args);
break;
case 'n8n_create_workflow':
validationResult = ToolValidation.validateCreateWorkflow(args);
break;
case 'n8n_get_workflow':
case 'n8n_get_workflow_details':
case 'n8n_get_workflow_structure':
case 'n8n_get_workflow_minimal':
case 'n8n_update_full_workflow':
case 'n8n_delete_workflow':
case 'n8n_validate_workflow':
case 'n8n_autofix_workflow':
case 'n8n_get_execution':
case 'n8n_delete_execution':
validationResult = ToolValidation.validateWorkflowId(args);
break;
case 'n8n_executions':
// Requires action parameter, id validation done in handler based on action
validationResult = args.action
? { valid: true, errors: [] }
: { valid: false, errors: [{ field: 'action', message: 'action is required' }] };
break;
default:
// For tools not yet migrated to schema validation, use basic validation
return this.validateToolParamsBasic(toolName, args, legacyRequiredParams || []);
@@ -1018,11 +1014,19 @@ export class N8NDocumentationMCPServer {
// Convert limit to number if provided, otherwise use default
const limit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
return this.searchNodes(args.query, limit, { mode: args.mode, includeExamples: args.includeExamples });
case 'get_node_documentation':
this.validateToolParams(name, args, ['nodeType']);
return this.getNodeDocumentation(args.nodeType);
case 'get_node':
this.validateToolParams(name, args, ['nodeType']);
// Handle consolidated modes: docs, search_properties
if (args.mode === 'docs') {
return this.getNodeDocumentation(args.nodeType);
}
if (args.mode === 'search_properties') {
if (!args.propertyQuery) {
throw new Error('propertyQuery is required for mode=search_properties');
}
const maxResults = args.maxPropertyResults !== undefined ? Number(args.maxPropertyResults) || 20 : 20;
return this.searchNodeProperties(args.nodeType, args.propertyQuery, maxResults);
}
return this.getNode(
args.nodeType,
args.detail,
@@ -1032,15 +1036,23 @@ export class N8NDocumentationMCPServer {
args.fromVersion,
args.toVersion
);
case 'search_node_properties':
this.validateToolParams(name, args, ['nodeType', 'query']);
const maxResults = args.maxResults !== undefined ? Number(args.maxResults) || 20 : 20;
return this.searchNodeProperties(args.nodeType, args.query, maxResults);
case 'validate_node_operation':
case 'validate_node':
this.validateToolParams(name, args, ['nodeType', 'config']);
// Ensure config is an object
if (typeof args.config !== 'object' || args.config === null) {
logger.warn(`validate_node_operation called with invalid config type: ${typeof args.config}`);
logger.warn(`validate_node called with invalid config type: ${typeof args.config}`);
const validationMode = args.mode || 'full';
if (validationMode === 'minimal') {
return {
nodeType: args.nodeType || 'unknown',
displayName: 'Unknown Node',
valid: false,
missingRequiredFields: [
'Invalid config format - expected object',
'🔧 RECOVERY: Use format { "resource": "...", "operation": "..." } or {} for empty config'
]
};
}
return {
nodeType: args.nodeType || 'unknown',
workflowNodeType: args.nodeType || 'unknown',
@@ -1056,7 +1068,7 @@ export class N8NDocumentationMCPServer {
suggestions: [
'🔧 RECOVERY: Invalid config detected. Fix with:',
' • Ensure config is an object: { "resource": "...", "operation": "..." }',
' • Use get_node_essentials to see required fields for this node type',
' • Use get_node to see required fields for this node type',
' • Check if the node type is correct before configuring it'
],
summary: {
@@ -1067,59 +1079,52 @@ export class N8NDocumentationMCPServer {
}
};
}
return this.validateNodeConfig(args.nodeType, args.config, 'operation', args.profile);
case 'validate_node_minimal':
this.validateToolParams(name, args, ['nodeType', 'config']);
// Ensure config is an object
if (typeof args.config !== 'object' || args.config === null) {
logger.warn(`validate_node_minimal called with invalid config type: ${typeof args.config}`);
return {
nodeType: args.nodeType || 'unknown',
displayName: 'Unknown Node',
valid: false,
missingRequiredFields: [
'Invalid config format - expected object',
'🔧 RECOVERY: Use format { "resource": "...", "operation": "..." } or {} for empty config'
]
};
// Handle mode parameter
const validationMode = args.mode || 'full';
if (validationMode === 'minimal') {
return this.validateNodeMinimal(args.nodeType, args.config);
}
return this.validateNodeMinimal(args.nodeType, args.config);
case 'get_property_dependencies':
this.validateToolParams(name, args, ['nodeType']);
return this.getPropertyDependencies(args.nodeType, args.config);
case 'list_node_templates':
this.validateToolParams(name, args, ['nodeTypes']);
const templateLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
const templateOffset = Math.max(Number(args.offset) || 0, 0);
return this.listNodeTemplates(args.nodeTypes, templateLimit, templateOffset);
return this.validateNodeConfig(args.nodeType, args.config, 'operation', args.profile);
case 'get_template':
this.validateToolParams(name, args, ['templateId']);
const templateId = Number(args.templateId);
const mode = args.mode || 'full';
return this.getTemplate(templateId, mode);
case 'search_templates':
this.validateToolParams(name, args, ['query']);
const templateMode = args.mode || 'full';
return this.getTemplate(templateId, templateMode);
case 'search_templates': {
// Consolidated tool with searchMode parameter
const searchMode = args.searchMode || 'keyword';
const searchLimit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
const searchOffset = Math.max(Number(args.offset) || 0, 0);
const searchFields = args.fields as string[] | undefined;
return this.searchTemplates(args.query, searchLimit, searchOffset, searchFields);
case 'get_templates_for_task':
this.validateToolParams(name, args, ['task']);
const taskLimit = Math.min(Math.max(Number(args.limit) || 10, 1), 100);
const taskOffset = Math.max(Number(args.offset) || 0, 0);
return this.getTemplatesForTask(args.task, taskLimit, taskOffset);
case 'search_templates_by_metadata':
// No required params - all filters are optional
const metadataLimit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
const metadataOffset = Math.max(Number(args.offset) || 0, 0);
return this.searchTemplatesByMetadata({
category: args.category,
complexity: args.complexity,
maxSetupMinutes: args.maxSetupMinutes ? Number(args.maxSetupMinutes) : undefined,
minSetupMinutes: args.minSetupMinutes ? Number(args.minSetupMinutes) : undefined,
requiredService: args.requiredService,
targetAudience: args.targetAudience
}, metadataLimit, metadataOffset);
switch (searchMode) {
case 'by_nodes':
if (!args.nodeTypes || !Array.isArray(args.nodeTypes) || args.nodeTypes.length === 0) {
throw new Error('nodeTypes array is required for searchMode=by_nodes');
}
return this.listNodeTemplates(args.nodeTypes, searchLimit, searchOffset);
case 'by_task':
if (!args.task) {
throw new Error('task is required for searchMode=by_task');
}
return this.getTemplatesForTask(args.task, searchLimit, searchOffset);
case 'by_metadata':
return this.searchTemplatesByMetadata({
category: args.category,
complexity: args.complexity,
maxSetupMinutes: args.maxSetupMinutes ? Number(args.maxSetupMinutes) : undefined,
minSetupMinutes: args.minSetupMinutes ? Number(args.minSetupMinutes) : undefined,
requiredService: args.requiredService,
targetAudience: args.targetAudience
}, searchLimit, searchOffset);
case 'keyword':
default:
if (!args.query) {
throw new Error('query is required for searchMode=keyword');
}
const searchFields = args.fields as string[] | undefined;
return this.searchTemplates(args.query, searchLimit, searchOffset, searchFields);
}
}
case 'validate_workflow':
this.validateToolParams(name, args, ['workflow']);
return this.validateWorkflow(args.workflow, args.options);
@@ -1128,18 +1133,21 @@ export class N8NDocumentationMCPServer {
case 'n8n_create_workflow':
this.validateToolParams(name, args, ['name', 'nodes', 'connections']);
return n8nHandlers.handleCreateWorkflow(args, this.instanceContext);
case 'n8n_get_workflow':
case 'n8n_get_workflow': {
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleGetWorkflow(args, this.instanceContext);
case 'n8n_get_workflow_details':
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleGetWorkflowDetails(args, this.instanceContext);
case 'n8n_get_workflow_structure':
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleGetWorkflowStructure(args, this.instanceContext);
case 'n8n_get_workflow_minimal':
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleGetWorkflowMinimal(args, this.instanceContext);
const workflowMode = args.mode || 'full';
switch (workflowMode) {
case 'details':
return n8nHandlers.handleGetWorkflowDetails(args, this.instanceContext);
case 'structure':
return n8nHandlers.handleGetWorkflowStructure(args, this.instanceContext);
case 'minimal':
return n8nHandlers.handleGetWorkflowMinimal(args, this.instanceContext);
case 'full':
default:
return n8nHandlers.handleGetWorkflow(args, this.instanceContext);
}
}
case 'n8n_update_full_workflow':
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleUpdateWorkflow(args, this.repository!, this.instanceContext);
@@ -1165,15 +1173,26 @@ export class N8NDocumentationMCPServer {
case 'n8n_trigger_webhook_workflow':
this.validateToolParams(name, args, ['webhookUrl']);
return n8nHandlers.handleTriggerWebhookWorkflow(args, this.instanceContext);
case 'n8n_get_execution':
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleGetExecution(args, this.instanceContext);
case 'n8n_list_executions':
// No required parameters
return n8nHandlers.handleListExecutions(args, this.instanceContext);
case 'n8n_delete_execution':
this.validateToolParams(name, args, ['id']);
return n8nHandlers.handleDeleteExecution(args, this.instanceContext);
case 'n8n_executions': {
this.validateToolParams(name, args, ['action']);
const execAction = args.action;
switch (execAction) {
case 'get':
if (!args.id) {
throw new Error('id is required for action=get');
}
return n8nHandlers.handleGetExecution(args, this.instanceContext);
case 'list':
return n8nHandlers.handleListExecutions(args, this.instanceContext);
case 'delete':
if (!args.id) {
throw new Error('id is required for action=delete');
}
return n8nHandlers.handleDeleteExecution(args, this.instanceContext);
default:
throw new Error(`Unknown action: ${execAction}. Valid actions: get, list, delete`);
}
}
case 'n8n_health_check':
// No required parameters - supports mode='status' (default) or mode='diagnostic'
if (args.mode === 'diagnostic') {

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

@@ -70,55 +70,19 @@ export const n8nManagementTools: ToolDefinition[] = [
},
{
name: 'n8n_get_workflow',
description: `Get a workflow by ID. Returns the complete workflow including nodes, connections, and settings.`,
description: `Get workflow by ID with different detail levels. Use mode='full' for complete workflow, 'details' for metadata+stats, 'structure' for nodes/connections only, 'minimal' for id/name/active/tags.`,
inputSchema: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Workflow ID'
}
},
required: ['id']
}
},
{
name: 'n8n_get_workflow_details',
description: `Get workflow details with metadata, version, execution stats. More info than get_workflow.`,
inputSchema: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Workflow ID'
}
},
required: ['id']
}
},
{
name: 'n8n_get_workflow_structure',
description: `Get workflow structure: nodes and connections only. No parameter details.`,
inputSchema: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Workflow ID'
}
},
required: ['id']
}
},
{
name: 'n8n_get_workflow_minimal',
description: `Get minimal info: ID, name, active status, tags. Fast for listings.`,
inputSchema: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Workflow ID'
id: {
type: 'string',
description: 'Workflow ID'
},
mode: {
type: 'string',
enum: ['full', 'details', 'structure', 'minimal'],
default: 'full',
description: 'Detail level: full=complete workflow, details=full+execution stats, structure=nodes/connections topology, minimal=metadata only'
}
},
required: ['id']
@@ -343,93 +307,68 @@ export const n8nManagementTools: ToolDefinition[] = [
}
},
{
name: 'n8n_get_execution',
description: `Get execution details with smart filtering. RECOMMENDED: Use mode='preview' first to assess data size.
Examples:
- {id, mode:'preview'} - Structure & counts (fast, no data)
- {id, mode:'summary'} - 2 samples per node (default)
- {id, mode:'filtered', itemsLimit:5} - 5 items per node
- {id, nodeNames:['HTTP Request']} - Specific node only
- {id, mode:'full'} - Complete data (use with caution)`,
name: 'n8n_executions',
description: `Manage workflow executions: get details, list, or delete. Use action='get' with id for execution details, action='list' for listing executions, action='delete' to remove execution record.`,
inputSchema: {
type: 'object',
properties: {
action: {
type: 'string',
enum: ['get', 'list', 'delete'],
description: 'Operation: get=get execution details, list=list executions, delete=delete execution'
},
// For action='get' and action='delete'
id: {
type: 'string',
description: 'Execution ID'
description: 'Execution ID (required for action=get or action=delete)'
},
// For action='get' - detail level
mode: {
type: 'string',
enum: ['preview', 'summary', 'filtered', 'full'],
description: 'Data retrieval mode: preview=structure only, summary=2 items, filtered=custom, full=all data'
description: 'For action=get: preview=structure only, summary=2 items (default), filtered=custom, full=all data'
},
nodeNames: {
type: 'array',
items: { type: 'string' },
description: 'Filter to specific nodes by name (for filtered mode)'
description: 'For action=get with mode=filtered: filter to specific nodes by name'
},
itemsLimit: {
type: 'number',
description: 'Items per node: 0=structure only, 2=default, -1=unlimited (for filtered mode)'
description: 'For action=get with mode=filtered: items per node (0=structure, 2=default, -1=unlimited)'
},
includeInputData: {
type: 'boolean',
description: 'Include input data in addition to output (default: false)'
description: 'For action=get: include input data in addition to output (default: false)'
},
// For action='list'
limit: {
type: 'number',
description: 'For action=list: number of executions to return (1-100, default: 100)'
},
cursor: {
type: 'string',
description: 'For action=list: pagination cursor from previous response'
},
workflowId: {
type: 'string',
description: 'For action=list: filter by workflow ID'
},
projectId: {
type: 'string',
description: 'For action=list: filter by project ID (enterprise feature)'
},
status: {
type: 'string',
enum: ['success', 'error', 'waiting'],
description: 'For action=list: filter by execution status'
},
includeData: {
type: 'boolean',
description: 'Legacy: Include execution data. Maps to mode=summary if true (deprecated, use mode instead)'
description: 'For action=list: include execution data (default: false)'
}
},
required: ['id']
}
},
{
name: 'n8n_list_executions',
description: `List workflow executions (returns up to limit). Check hasMore/nextCursor for pagination.`,
inputSchema: {
type: 'object',
properties: {
limit: {
type: 'number',
description: 'Number of executions to return (1-100, default: 100)'
},
cursor: {
type: 'string',
description: 'Pagination cursor from previous response'
},
workflowId: {
type: 'string',
description: 'Filter by workflow ID'
},
projectId: {
type: 'string',
description: 'Filter by project ID (enterprise feature)'
},
status: {
type: 'string',
enum: ['success', 'error', 'waiting'],
description: 'Filter by execution status'
},
includeData: {
type: 'boolean',
description: 'Include execution data (default: false)'
}
}
}
},
{
name: 'n8n_delete_execution',
description: `Delete an execution record. This only removes the execution history, not any data processed.`,
inputSchema: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Execution ID to delete'
}
},
required: ['id']
required: ['action']
}
},

255
src/mcp/tools.ts
View File

@@ -56,23 +56,9 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
required: ['query'],
},
},
{
name: 'get_node_documentation',
description: `Get readable docs with examples/auth/patterns. Better than raw schema! 87% coverage. Format: "nodes-base.slack"`,
inputSchema: {
type: 'object',
properties: {
nodeType: {
type: 'string',
description: 'Full type with prefix: "nodes-base.slack"',
},
},
required: ['nodeType'],
},
},
{
name: 'get_node',
description: `Get node info with progressive detail levels. Detail: minimal (~200 tokens), standard (~1-2K, default), full (~3-8K). Version modes: versions (history), compare (diff), breaking (changes), migrations (auto-migrate). Supports includeTypeInfo and includeExamples. Use standard for most tasks.`,
description: `Get node info with progressive detail levels and multiple modes. Detail: minimal (~200 tokens), standard (~1-2K, default), full (~3-8K). Modes: info (default), docs (markdown documentation), search_properties (find properties), versions/compare/breaking/migrations (version info). Use format='docs' for readable documentation, mode='search_properties' with propertyQuery for finding specific fields.`,
inputSchema: {
type: 'object',
properties: {
@@ -88,9 +74,9 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
mode: {
type: 'string',
enum: ['info', 'versions', 'compare', 'breaking', 'migrations'],
enum: ['info', 'docs', 'search_properties', 'versions', 'compare', 'breaking', 'migrations'],
default: 'info',
description: 'Operation mode. info=node information, versions=version history, compare/breaking/migrations=version comparison',
description: 'Operation mode. info=node schema, docs=readable markdown documentation, search_properties=find specific properties, versions/compare/breaking/migrations=version info',
},
includeTypeInfo: {
type: 'boolean',
@@ -110,36 +96,22 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
type: 'string',
description: 'Target version for compare mode (e.g., "2.0"). Defaults to latest if omitted.',
},
propertyQuery: {
type: 'string',
description: 'For mode=search_properties: search term to find properties (e.g., "auth", "header", "body")',
},
maxPropertyResults: {
type: 'number',
description: 'For mode=search_properties: max results (default 20)',
default: 20,
},
},
required: ['nodeType'],
},
},
{
name: 'search_node_properties',
description: `Find specific properties in a node (auth, headers, body, etc). Returns paths and descriptions.`,
inputSchema: {
type: 'object',
properties: {
nodeType: {
type: 'string',
description: 'Full type with prefix',
},
query: {
type: 'string',
description: 'Property to find: "auth", "header", "body", "json"',
},
maxResults: {
type: 'number',
description: 'Max results (default 20)',
default: 20,
},
},
required: ['nodeType', 'query'],
},
},
{
name: 'validate_node_operation',
description: `Validate n8n node configuration. Pass nodeType as string and config as object. Example: nodeType="nodes-base.slack", config={resource:"channel",operation:"create"}`,
name: 'validate_node',
description: `Validate n8n node configuration. Use mode='full' for comprehensive validation with errors/warnings/suggestions, mode='minimal' for quick required fields check. Example: nodeType="nodes-base.slack", config={resource:"channel",operation:"create"}`,
inputSchema: {
type: 'object',
properties: {
@@ -151,10 +123,16 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
type: 'object',
description: 'Configuration as object. For simple nodes use {}. For complex nodes include fields like {resource:"channel",operation:"create"}',
},
mode: {
type: 'string',
enum: ['full', 'minimal'],
description: 'Validation mode. full=comprehensive validation with errors/warnings/suggestions, minimal=quick required fields check only. Default is "full"',
default: 'full',
},
profile: {
type: 'string',
enum: ['strict', 'runtime', 'ai-friendly', 'minimal'],
description: 'Profile string: "minimal", "runtime", "ai-friendly", or "strict". Default is "ai-friendly"',
description: 'Profile for mode=full: "minimal", "runtime", "ai-friendly", or "strict". Default is "ai-friendly"',
default: 'ai-friendly',
},
},
@@ -193,6 +171,11 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
}
},
suggestions: { type: 'array', items: { type: 'string' } },
missingRequiredFields: {
type: 'array',
items: { type: 'string' },
description: 'Only present in mode=minimal'
},
summary: {
type: 'object',
properties: {
@@ -203,85 +186,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
}
}
},
required: ['nodeType', 'displayName', 'valid', 'errors', 'warnings', 'suggestions', 'summary']
},
},
{
name: 'validate_node_minimal',
description: `Check n8n node required fields. Pass nodeType as string and config as empty object {}. Example: nodeType="nodes-base.webhook", config={}`,
inputSchema: {
type: 'object',
properties: {
nodeType: {
type: 'string',
description: 'Node type as string. Example: "nodes-base.slack"',
},
config: {
type: 'object',
description: 'Configuration object. Always pass {} for empty config',
},
},
required: ['nodeType', 'config'],
additionalProperties: false,
},
outputSchema: {
type: 'object',
properties: {
nodeType: { type: 'string' },
displayName: { type: 'string' },
valid: { type: 'boolean' },
missingRequiredFields: {
type: 'array',
items: { type: 'string' }
}
},
required: ['nodeType', 'displayName', 'valid', 'missingRequiredFields']
},
},
{
name: 'get_property_dependencies',
description: `Shows property dependencies and visibility rules. Example: sendBody=true reveals body fields. Test visibility with optional config.`,
inputSchema: {
type: 'object',
properties: {
nodeType: {
type: 'string',
description: 'The node type to analyze (e.g., "nodes-base.httpRequest")',
},
config: {
type: 'object',
description: 'Optional partial configuration to check visibility impact',
},
},
required: ['nodeType'],
},
},
{
name: 'list_node_templates',
description: `Find templates using specific nodes. Returns paginated results. Use FULL types: "n8n-nodes-base.httpRequest".`,
inputSchema: {
type: 'object',
properties: {
nodeTypes: {
type: 'array',
items: { type: 'string' },
description: 'Array of node types to search for (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.openAi"])',
},
limit: {
type: 'number',
description: 'Maximum number of templates to return. Default 10.',
default: 10,
minimum: 1,
maximum: 100,
},
offset: {
type: 'number',
description: 'Pagination offset. Default 0.',
default: 0,
minimum: 0,
},
},
required: ['nodeTypes'],
required: ['nodeType', 'displayName', 'valid']
},
},
{
@@ -306,13 +211,20 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
{
name: 'search_templates',
description: `Search templates by name/description keywords. Returns paginated results. NOT for node types! For nodes use list_node_templates.`,
description: `Search templates with multiple modes. Use searchMode='keyword' for text search, 'by_nodes' to find templates using specific nodes, 'by_task' for curated task-based templates, 'by_metadata' for filtering by complexity/setup time/services.`,
inputSchema: {
type: 'object',
properties: {
searchMode: {
type: 'string',
enum: ['keyword', 'by_nodes', 'by_task', 'by_metadata'],
description: 'Search mode. keyword=text search (default), by_nodes=find by node types, by_task=curated task templates, by_metadata=filter by complexity/services',
default: 'keyword',
},
// For searchMode='keyword'
query: {
type: 'string',
description: 'Search keyword as string. Example: "chatbot"',
description: 'For searchMode=keyword: search keyword (e.g., "chatbot")',
},
fields: {
type: 'array',
@@ -320,36 +232,20 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
type: 'string',
enum: ['id', 'name', 'description', 'author', 'nodes', 'views', 'created', 'url', 'metadata'],
},
description: 'Fields to include in response. Default: all fields. Example: ["id", "name"] for minimal response.',
description: 'For searchMode=keyword: fields to include in response. Default: all fields.',
},
limit: {
type: 'number',
description: 'Maximum number of results. Default 20.',
default: 20,
minimum: 1,
maximum: 100,
// For searchMode='by_nodes'
nodeTypes: {
type: 'array',
items: { type: 'string' },
description: 'For searchMode=by_nodes: array of node types (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"])',
},
offset: {
type: 'number',
description: 'Pagination offset. Default 0.',
default: 0,
minimum: 0,
},
},
required: ['query'],
},
},
{
name: 'get_templates_for_task',
description: `Curated templates by task. Returns paginated results sorted by popularity.`,
inputSchema: {
type: 'object',
properties: {
// For searchMode='by_task'
task: {
type: 'string',
enum: [
'ai_automation',
'data_sync',
'data_sync',
'webhook_processing',
'email_automation',
'slack_integration',
@@ -359,60 +255,39 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
'api_integration',
'database_operations'
],
description: 'The type of task to get templates for',
description: 'For searchMode=by_task: the type of task',
},
limit: {
type: 'number',
description: 'Maximum number of results. Default 10.',
default: 10,
minimum: 1,
maximum: 100,
},
offset: {
type: 'number',
description: 'Pagination offset. Default 0.',
default: 0,
minimum: 0,
},
},
required: ['task'],
},
},
{
name: 'search_templates_by_metadata',
description: `Search templates by AI-generated metadata. Filter by category, complexity, setup time, services, or audience. Returns rich metadata for smart template discovery.`,
inputSchema: {
type: 'object',
properties: {
// For searchMode='by_metadata'
category: {
type: 'string',
description: 'Filter by category (e.g., "automation", "integration", "data processing")',
description: 'For searchMode=by_metadata: filter by category (e.g., "automation", "integration")',
},
complexity: {
type: 'string',
enum: ['simple', 'medium', 'complex'],
description: 'Filter by complexity level',
description: 'For searchMode=by_metadata: filter by complexity level',
},
maxSetupMinutes: {
type: 'number',
description: 'Maximum setup time in minutes',
description: 'For searchMode=by_metadata: maximum setup time in minutes',
minimum: 5,
maximum: 480,
},
minSetupMinutes: {
type: 'number',
description: 'Minimum setup time in minutes',
description: 'For searchMode=by_metadata: minimum setup time in minutes',
minimum: 5,
maximum: 480,
},
requiredService: {
type: 'string',
description: 'Filter by required service (e.g., "openai", "slack", "google")',
description: 'For searchMode=by_metadata: filter by required service (e.g., "openai", "slack")',
},
targetAudience: {
type: 'string',
description: 'Filter by target audience (e.g., "developers", "marketers", "analysts")',
description: 'For searchMode=by_metadata: filter by target audience (e.g., "developers", "marketers")',
},
// Common pagination
limit: {
type: 'number',
description: 'Maximum number of results. Default 20.',
@@ -427,7 +302,6 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
minimum: 0,
},
},
additionalProperties: false,
},
},
{
@@ -519,36 +393,37 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
/**
* QUICK REFERENCE for AI Agents:
*
*
* 1. RECOMMENDED WORKFLOW:
* - Start: search_nodes → get_node → get_node_for_task → validate_node_operation
* - Start: search_nodes → get_node → validate_node
* - Discovery: search_nodes({query:"trigger"}) for finding nodes
* - Quick Config: get_node("nodes-base.httpRequest", {detail:"standard"}) - only essential properties
* - Documentation: get_node("nodes-base.httpRequest", {mode:"docs"}) - readable markdown docs
* - Find Properties: get_node("nodes-base.httpRequest", {mode:"search_properties", propertyQuery:"auth"})
* - Full Details: get_node with detail="full" only when standard isn't enough
* - Validation: Use validate_node_operation for complex nodes (Slack, Google Sheets, etc.)
*
* - Validation: Use validate_node for complex nodes (Slack, Google Sheets, etc.)
*
* 2. COMMON NODE TYPES:
* Triggers: webhook, schedule, emailReadImap, slackTrigger
* Core: httpRequest, code, set, if, merge, splitInBatches
* Integrations: slack, gmail, googleSheets, postgres, mongodb
* AI: agent, openAi, chainLlm, documentLoader
*
*
* 3. SEARCH TIPS:
* - search_nodes returns ANY word match (OR logic)
* - Single words more precise, multiple words broader
* - If no results: try different keywords or partial names
*
*
* 4. TEMPLATE SEARCHING:
* - search_templates("slack") searches template names/descriptions, NOT node types!
* - To find templates using Slack node: list_node_templates(["n8n-nodes-base.slack"])
* - For task-based templates: get_templates_for_task("slack_integration")
* - 399 templates available from the last year
*
* - To find templates using Slack node: search_templates({searchMode:"by_nodes", nodeTypes:["n8n-nodes-base.slack"]})
* - For task-based templates: search_templates({searchMode:"by_task", task:"slack_integration"})
*
* 5. KNOWN ISSUES:
* - Some nodes have duplicate properties with different conditions
* - Package names: use 'n8n-nodes-base' not '@n8n/n8n-nodes-base'
* - Check showWhen/hideWhen to identify the right property variant
*
*
* 6. PERFORMANCE:
* - get_node (detail=standard): Fast (<5KB)
* - get_node (detail=full): Slow (100KB+) - use sparingly

16
tests/integration/mcp-protocol/error-handling.test.ts
View File

@@ -135,11 +135,13 @@ describe('MCP Error Handling', () => {
});
describe('Validation Errors', () => {
// v2.26.0: validate_node_operation consolidated into validate_node
it('should handle invalid validation profile', async () => {
try {
await client.callTool({ name: 'validate_node_operation', arguments: {
await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: { method: 'GET', url: 'https://api.example.com' },
mode: 'full',
profile: 'invalid_profile' as any
} });
expect.fail('Should have thrown an error');
@@ -292,12 +294,14 @@ describe('MCP Error Handling', () => {
});
describe('Invalid JSON Handling', () => {
// v2.26.0: validate_node_operation consolidated into validate_node
it('should handle invalid JSON in tool parameters', async () => {
try {
// Config should be an object, not a string
await client.callTool({ name: 'validate_node_operation', arguments: {
await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: 'invalid json string' as any
config: 'invalid json string' as any,
mode: 'full'
} });
expect.fail('Should have thrown an error');
} catch (error: any) {
@@ -509,13 +513,15 @@ describe('MCP Error Handling', () => {
}
});
// v2.26.0: validate_node_operation consolidated into validate_node
it('should provide context for validation errors', async () => {
const response = await client.callTool({ name: 'validate_node_operation', arguments: {
const response = await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: {
// Missing required fields
method: 'INVALID_METHOD'
}
},
mode: 'full'
} });
const validation = JSON.parse((response as any).content[0].text);

5
tests/integration/mcp-protocol/protocol-compliance.test.ts
View File

@@ -217,13 +217,14 @@ describe('MCP Protocol Compliance', () => {
describe('Protocol Extensions', () => {
it('should handle tool-specific extensions', async () => {
// Test tool with complex params
const response = await client.callTool({ name: 'validate_node_operation', arguments: {
// Test tool with complex params (using consolidated validate_node from v2.26.0)
const response = await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: {
method: 'GET',
url: 'https://api.example.com'
},
mode: 'full',
profile: 'runtime'
} });

18
tests/integration/mcp-protocol/tool-invocation.test.ts
View File

@@ -151,14 +151,16 @@ describe('MCP Tool Invocation', () => {
});
describe('Validation Tools', () => {
describe('validate_node_operation', () => {
// v2.26.0: validate_node_operation consolidated into validate_node with mode parameter
describe('validate_node', () => {
it('should validate valid node configuration', async () => {
const response = await client.callTool({ name: 'validate_node_operation', arguments: {
const response = await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: {
method: 'GET',
url: 'https://api.example.com/data'
}
},
mode: 'full'
}});
const validation = JSON.parse(((response as any).content[0]).text);
@@ -168,12 +170,13 @@ describe('MCP Tool Invocation', () => {
});
it('should detect missing required fields', async () => {
const response = await client.callTool({ name: 'validate_node_operation', arguments: {
const response = await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: {
method: 'GET'
// Missing required 'url' field
}
},
mode: 'full'
}});
const validation = JSON.parse(((response as any).content[0]).text);
@@ -184,11 +187,12 @@ describe('MCP Tool Invocation', () => {
it('should support different validation profiles', async () => {
const profiles = ['minimal', 'runtime', 'ai-friendly', 'strict'];
for (const profile of profiles) {
const response = await client.callTool({ name: 'validate_node_operation', arguments: {
const response = await client.callTool({ name: 'validate_node', arguments: {
nodeType: 'nodes-base.httpRequest',
config: { method: 'GET', url: 'https://api.example.com' },
mode: 'full',
profile
}});

135
tests/unit/mcp/parameter-validation.test.ts
View File

@@ -201,63 +201,76 @@ describe('Parameter Validation', () => {
});
});
describe('validate_node_operation', () => {
describe('validate_node (consolidated)', () => {
it('should require nodeType and config parameters', async () => {
await expect(server.testExecuteTool('validate_node_operation', {}))
.rejects.toThrow('validate_node_operation: Validation failed:\n • nodeType: nodeType is required\n • config: config is required');
await expect(server.testExecuteTool('validate_node', {}))
.rejects.toThrow('validate_node: Validation failed:\n • nodeType: nodeType is required\n • config: config is required');
});
it('should require nodeType parameter when config is provided', async () => {
await expect(server.testExecuteTool('validate_node_operation', { config: {} }))
.rejects.toThrow('validate_node_operation: Validation failed:\n • nodeType: nodeType is required');
await expect(server.testExecuteTool('validate_node', { config: {} }))
.rejects.toThrow('validate_node: Validation failed:\n • nodeType: nodeType is required');
});
it('should require config parameter when nodeType is provided', async () => {
await expect(server.testExecuteTool('validate_node_operation', { nodeType: 'nodes-base.httpRequest' }))
.rejects.toThrow('validate_node_operation: Validation failed:\n • config: config is required');
await expect(server.testExecuteTool('validate_node', { nodeType: 'nodes-base.httpRequest' }))
.rejects.toThrow('validate_node: Validation failed:\n • config: config is required');
});
it('should succeed with valid parameters', async () => {
const result = await server.testExecuteTool('validate_node_operation', {
it('should succeed with valid parameters (full mode)', async () => {
const result = await server.testExecuteTool('validate_node', {
nodeType: 'nodes-base.httpRequest',
config: { method: 'GET', url: 'https://api.example.com' }
config: { method: 'GET', url: 'https://api.example.com' },
mode: 'full'
});
expect(result).toEqual({ valid: true });
});
it('should succeed with valid parameters (minimal mode)', async () => {
const result = await server.testExecuteTool('validate_node', {
nodeType: 'nodes-base.httpRequest',
config: {},
mode: 'minimal'
});
expect(result).toBeDefined();
});
});
describe('search_node_properties', () => {
it('should require nodeType and query parameters', async () => {
await expect(server.testExecuteTool('search_node_properties', {}))
.rejects.toThrow('Missing required parameters for search_node_properties: nodeType, query');
describe('get_node mode=search_properties (consolidated)', () => {
it('should require nodeType and propertyQuery parameters', async () => {
await expect(server.testExecuteTool('get_node', { mode: 'search_properties' }))
.rejects.toThrow('Missing required parameters for get_node: nodeType');
});
it('should succeed with valid parameters', async () => {
const result = await server.testExecuteTool('search_node_properties', {
const result = await server.testExecuteTool('get_node', {
nodeType: 'nodes-base.httpRequest',
query: 'auth'
mode: 'search_properties',
propertyQuery: 'auth'
});
expect(result).toEqual({ properties: [] });
});
it('should handle optional maxResults parameter', async () => {
const result = await server.testExecuteTool('search_node_properties', {
it('should handle optional maxPropertyResults parameter', async () => {
const result = await server.testExecuteTool('get_node', {
nodeType: 'nodes-base.httpRequest',
query: 'auth',
maxResults: 5
mode: 'search_properties',
propertyQuery: 'auth',
maxPropertyResults: 5
});
expect(result).toEqual({ properties: [] });
});
});
describe('list_node_templates', () => {
it('should require nodeTypes parameter', async () => {
await expect(server.testExecuteTool('list_node_templates', {}))
.rejects.toThrow('list_node_templates: Validation failed:\n • nodeTypes: nodeTypes is required');
describe('search_templates searchMode=by_nodes (consolidated)', () => {
it('should require nodeTypes parameter for by_nodes searchMode', async () => {
await expect(server.testExecuteTool('search_templates', { searchMode: 'by_nodes' }))
.rejects.toThrow('nodeTypes array is required for searchMode=by_nodes');
});
it('should succeed with valid nodeTypes array', async () => {
const result = await server.testExecuteTool('list_node_templates', {
const result = await server.testExecuteTool('search_templates', {
searchMode: 'by_nodes',
nodeTypes: ['nodes-base.httpRequest', 'nodes-base.slack']
});
expect(result).toEqual({ templates: [] });
@@ -320,45 +333,43 @@ describe('Parameter Validation', () => {
});
});
describe('maxResults parameter conversion', () => {
it('should convert string numbers to numbers', async () => {
describe('maxPropertyResults parameter conversion (v2.26.0 consolidated)', () => {
it('should pass numeric maxPropertyResults to searchNodeProperties', async () => {
const mockSearchNodeProperties = vi.spyOn(server as any, 'searchNodeProperties');
await server.testExecuteTool('search_node_properties', {
// v2.26.0: search_node_properties consolidated into get_node with mode='search_properties'
await server.testExecuteTool('get_node', {
nodeType: 'nodes-base.httpRequest',
query: 'auth',
maxResults: '5'
mode: 'search_properties',
propertyQuery: 'auth',
maxPropertyResults: 5
});
expect(mockSearchNodeProperties).toHaveBeenCalledWith('nodes-base.httpRequest', 'auth', 5);
});
it('should use default when maxResults is invalid', async () => {
it('should use default maxPropertyResults when not provided', async () => {
const mockSearchNodeProperties = vi.spyOn(server as any, 'searchNodeProperties');
await server.testExecuteTool('search_node_properties', {
// v2.26.0: search_node_properties consolidated into get_node with mode='search_properties'
await server.testExecuteTool('get_node', {
nodeType: 'nodes-base.httpRequest',
query: 'auth',
maxResults: 'invalid'
mode: 'search_properties',
propertyQuery: 'auth'
});
expect(mockSearchNodeProperties).toHaveBeenCalledWith('nodes-base.httpRequest', 'auth', 20);
});
});
describe('templateLimit parameter conversion', () => {
it('should reject string limit values', async () => {
await expect(server.testExecuteTool('list_node_templates', {
describe('templateLimit parameter conversion (v2.26.0 consolidated)', () => {
it('should handle search_templates with by_nodes mode', async () => {
// search_templates now handles list_node_templates functionality via searchMode='by_nodes'
await expect(server.testExecuteTool('search_templates', {
searchMode: 'by_nodes',
nodeTypes: ['nodes-base.httpRequest'],
limit: '5'
})).rejects.toThrow('list_node_templates: Validation failed:\n • limit: limit must be a number, got string');
});
it('should reject invalid string limit values', async () => {
await expect(server.testExecuteTool('list_node_templates', {
nodeTypes: ['nodes-base.httpRequest'],
limit: 'invalid'
})).rejects.toThrow('list_node_templates: Validation failed:\n • limit: limit must be a number, got string');
limit: 5
})).resolves.toEqual({ templates: [] });
});
});
@@ -416,8 +427,8 @@ describe('Parameter Validation', () => {
it('should list all missing parameters', () => {
expect(() => {
server.testValidateToolParams('validate_node_operation', { profile: 'strict' }, ['nodeType', 'config']);
}).toThrow('validate_node_operation: Validation failed:\n • nodeType: nodeType is required\n • config: config is required');
server.testValidateToolParams('validate_node', { profile: 'strict' }, ['nodeType', 'config']);
}).toThrow('validate_node: Validation failed:\n • nodeType: nodeType is required\n • config: config is required');
});
it('should include helpful guidance', () => {
@@ -442,8 +453,8 @@ describe('Parameter Validation', () => {
await expect(server.testExecuteTool('search_nodes', {}))
.rejects.toThrow('search_nodes: Validation failed:\n • query: query is required');
await expect(server.testExecuteTool('validate_node_operation', { nodeType: 'test' }))
.rejects.toThrow('validate_node_operation: Validation failed:\n • config: config is required');
await expect(server.testExecuteTool('validate_node', { nodeType: 'test' }))
.rejects.toThrow('validate_node: Validation failed:\n • config: config is required');
});
it('should handle edge cases in parameter validation gracefully', async () => {
@@ -460,11 +471,11 @@ describe('Parameter Validation', () => {
// Tools using legacy validation
const legacyValidationTools = [
{ name: 'get_node', args: {}, expected: 'Missing required parameters for get_node: nodeType' },
{ name: 'get_node_documentation', args: {}, expected: 'Missing required parameters for get_node_documentation: nodeType' },
{ name: 'search_node_properties', args: {}, expected: 'Missing required parameters for search_node_properties: nodeType, query' },
// v2.26.0: get_node_documentation consolidated into get_node with mode='docs'
// v2.26.0: search_node_properties consolidated into get_node with mode='search_properties'
// Note: get_node_for_task removed in v2.15.0
// Note: get_node_as_tool_info removed in v2.25.0
{ name: 'get_property_dependencies', args: {}, expected: 'Missing required parameters for get_property_dependencies: nodeType' },
// v2.26.0: get_property_dependencies removed (low usage)
{ name: 'get_template', args: {}, expected: 'Missing required parameters for get_template: templateId' },
];
@@ -474,11 +485,11 @@ describe('Parameter Validation', () => {
}
// Tools using new schema validation
// Updated for v2.26.0 tool consolidation
const schemaValidationTools = [
{ name: 'search_nodes', args: {}, expected: 'search_nodes: Validation failed:\n • query: query is required' },
{ name: 'validate_node_operation', args: {}, expected: 'validate_node_operation: Validation failed:\n • nodeType: nodeType is required\n • config: config is required' },
{ name: 'validate_node_minimal', args: {}, expected: 'validate_node_minimal: Validation failed:\n • nodeType: nodeType is required\n • config: config is required' },
{ name: 'list_node_templates', args: {}, expected: 'list_node_templates: Validation failed:\n • nodeTypes: nodeTypes is required' },
{ name: 'validate_node', args: {}, expected: 'validate_node: Validation failed:\n • nodeType: nodeType is required\n • config: config is required' },
// list_node_templates consolidated into search_templates with searchMode='by_nodes'
];
for (const tool of schemaValidationTools) {
@@ -513,17 +524,15 @@ describe('Parameter Validation', () => {
handleUpdatePartialWorkflow: vi.fn().mockResolvedValue({ success: true })
}));
// Updated for v2.26.0 tool consolidation:
// - n8n_get_workflow now supports mode parameter (full, details, structure, minimal)
// - n8n_executions now handles get/list/delete via action parameter
const n8nToolsWithRequiredParams = [
{ name: 'n8n_create_workflow', args: {}, expected: 'n8n_create_workflow: Validation failed:\n • name: name is required\n • nodes: nodes is required\n • connections: connections is required' },
{ name: 'n8n_get_workflow', args: {}, expected: 'n8n_get_workflow: Validation failed:\n • id: id is required' },
{ name: 'n8n_get_workflow_details', args: {}, expected: 'n8n_get_workflow_details: Validation failed:\n • id: id is required' },
{ name: 'n8n_get_workflow_structure', args: {}, expected: 'n8n_get_workflow_structure: Validation failed:\n • id: id is required' },
{ name: 'n8n_get_workflow_minimal', args: {}, expected: 'n8n_get_workflow_minimal: Validation failed:\n • id: id is required' },
{ name: 'n8n_update_full_workflow', args: {}, expected: 'n8n_update_full_workflow: Validation failed:\n • id: id is required' },
{ name: 'n8n_delete_workflow', args: {}, expected: 'n8n_delete_workflow: Validation failed:\n • id: id is required' },
{ name: 'n8n_validate_workflow', args: {}, expected: 'n8n_validate_workflow: Validation failed:\n • id: id is required' },
{ name: 'n8n_get_execution', args: {}, expected: 'n8n_get_execution: Validation failed:\n • id: id is required' },
{ name: 'n8n_delete_execution', args: {}, expected: 'n8n_delete_execution: Validation failed:\n • id: id is required' },
];
// n8n_update_partial_workflow and n8n_trigger_webhook_workflow use legacy validation

2
tests/unit/mcp/tools-documentation.test.ts
View File

@@ -81,7 +81,7 @@ vi.mock('@/mcp/tool-docs', () => ({
performance: 'Depends on workflow complexity',
bestPractices: ['Validate before saving', 'Fix errors first'],
pitfalls: ['Large workflows may take time'],
relatedTools: ['validate_node_operation']
relatedTools: ['validate_node']
}
},
get_node_essentials: {

178
tests/unit/mcp/tools.test.ts
View File

@@ -141,18 +141,23 @@ describe('n8nDocumentationToolsFinal', () => {
});
});
describe('get_templates_for_task', () => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'get_templates_for_task');
describe('search_templates (consolidated)', () => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'search_templates');
it('should exist', () => {
expect(tool).toBeDefined();
});
it('should have task as required parameter', () => {
expect(tool?.inputSchema.required).toContain('task');
it('should have searchMode parameter with correct enum values', () => {
const searchModeParam = tool?.inputSchema.properties?.searchMode;
expect(searchModeParam).toBeDefined();
expect(searchModeParam.enum).toEqual(['keyword', 'by_nodes', 'by_task', 'by_metadata']);
expect(searchModeParam.default).toBe('keyword');
});
it('should have correct task enum values', () => {
it('should have task parameter for by_task searchMode', () => {
const taskParam = tool?.inputSchema.properties?.task;
expect(taskParam).toBeDefined();
const expectedTasks = [
'ai_automation',
'data_sync',
@@ -165,30 +170,37 @@ describe('n8nDocumentationToolsFinal', () => {
'api_integration',
'database_operations'
];
expect(tool?.inputSchema.properties.task.enum).toEqual(expectedTasks);
expect(taskParam.enum).toEqual(expectedTasks);
});
it('should have nodeTypes parameter for by_nodes searchMode', () => {
const nodeTypesParam = tool?.inputSchema.properties?.nodeTypes;
expect(nodeTypesParam).toBeDefined();
expect(nodeTypesParam.type).toBe('array');
expect(nodeTypesParam.items.type).toBe('string');
});
});
});
describe('Tool Description Quality', () => {
it('should have concise descriptions that fit in one line', () => {
it('should have concise descriptions that fit within reasonable limits', () => {
n8nDocumentationToolsFinal.forEach(tool => {
// Descriptions should be informative but not overly long
expect(tool.description.length).toBeLessThan(300);
// Consolidated tools (v2.26.0) may have longer descriptions due to multiple modes
// Allow up to 500 chars for tools with mode-based functionality
expect(tool.description.length).toBeLessThan(500);
});
});
it('should include examples or key information in descriptions', () => {
const toolsWithExamples = [
'get_node',
'search_nodes',
'get_node_documentation'
'search_nodes'
];
toolsWithExamples.forEach(toolName => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === toolName);
// Should include either example usage, format information, or "nodes-base"
expect(tool?.description).toMatch(/example|Example|format|Format|nodes-base|Common:/i);
expect(tool?.description).toMatch(/example|Example|format|Format|nodes-base|Common:|mode/i);
});
});
});
@@ -223,11 +235,12 @@ describe('n8nDocumentationToolsFinal', () => {
describe('Tool Categories Coverage', () => {
it('should have tools for all major categories', () => {
// Updated for v2.26.0 consolidated tools
const categories = {
discovery: ['search_nodes'],
configuration: ['get_node', 'get_node_documentation'],
validation: ['validate_node_operation', 'validate_workflow', 'validate_node_minimal'],
templates: ['search_templates', 'get_template', 'list_node_templates', 'get_templates_for_task', 'search_templates_by_metadata'],
configuration: ['get_node'], // get_node now includes docs mode
validation: ['validate_node', 'validate_workflow'], // consolidated validate_node
templates: ['search_templates', 'get_template'], // search_templates now handles all search modes
documentation: ['tools_documentation']
};
@@ -281,20 +294,17 @@ describe('n8nDocumentationToolsFinal', () => {
});
it('should have array parameters defined correctly', () => {
const toolsWithArrays = ['list_node_templates'];
toolsWithArrays.forEach(toolName => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === toolName);
const arrayParam = tool?.inputSchema.properties.nodeTypes;
expect(arrayParam?.type).toBe('array');
expect(arrayParam?.items).toBeDefined();
expect(arrayParam?.items.type).toBe('string');
});
// search_templates now handles nodeTypes for by_nodes mode
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'search_templates');
const arrayParam = tool?.inputSchema.properties?.nodeTypes;
expect(arrayParam?.type).toBe('array');
expect(arrayParam?.items).toBeDefined();
expect(arrayParam?.items.type).toBe('string');
});
});
describe('New Template Tools', () => {
describe('get_template (enhanced)', () => {
describe('Consolidated Template Tools (v2.26.0)', () => {
describe('get_template', () => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'get_template');
it('should exist and support mode parameter', () => {
@@ -315,130 +325,56 @@ describe('n8nDocumentationToolsFinal', () => {
});
});
describe('search_templates_by_metadata', () => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'search_templates_by_metadata');
describe('search_templates (consolidated with searchMode)', () => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'search_templates');
it('should exist in the tools array', () => {
it('should exist with searchMode parameter', () => {
expect(tool).toBeDefined();
expect(tool?.name).toBe('search_templates_by_metadata');
expect(tool?.inputSchema.properties).toHaveProperty('searchMode');
});
it('should have proper description', () => {
expect(tool?.description).toContain('Search templates by AI-generated metadata');
expect(tool?.description).toContain('category');
expect(tool?.description).toContain('complexity');
});
it('should have correct input schema structure', () => {
expect(tool?.inputSchema.type).toBe('object');
expect(tool?.inputSchema.properties).toBeDefined();
expect(tool?.inputSchema.required).toBeUndefined(); // All parameters are optional
});
it('should have category parameter with proper schema', () => {
const categoryProp = tool?.inputSchema.properties?.category;
expect(categoryProp).toBeDefined();
expect(categoryProp.type).toBe('string');
expect(categoryProp.description).toContain('category');
});
it('should have complexity parameter with enum values', () => {
const complexityProp = tool?.inputSchema.properties?.complexity;
expect(complexityProp).toBeDefined();
expect(complexityProp.enum).toEqual(['simple', 'medium', 'complex']);
expect(complexityProp.description).toContain('complexity');
});
it('should have time-based parameters with numeric constraints', () => {
const maxTimeProp = tool?.inputSchema.properties?.maxSetupMinutes;
const minTimeProp = tool?.inputSchema.properties?.minSetupMinutes;
expect(maxTimeProp).toBeDefined();
expect(maxTimeProp.type).toBe('number');
expect(maxTimeProp.maximum).toBe(480);
expect(maxTimeProp.minimum).toBe(5);
expect(minTimeProp).toBeDefined();
expect(minTimeProp.type).toBe('number');
expect(minTimeProp.maximum).toBe(480);
expect(minTimeProp.minimum).toBe(5);
});
it('should have service and audience parameters', () => {
const serviceProp = tool?.inputSchema.properties?.requiredService;
const audienceProp = tool?.inputSchema.properties?.targetAudience;
expect(serviceProp).toBeDefined();
expect(serviceProp.type).toBe('string');
expect(serviceProp.description).toContain('service');
expect(audienceProp).toBeDefined();
expect(audienceProp.type).toBe('string');
expect(audienceProp.description).toContain('audience');
it('should support metadata filtering via by_metadata searchMode', () => {
// These properties are for by_metadata searchMode
const props = tool?.inputSchema.properties;
expect(props).toHaveProperty('category');
expect(props).toHaveProperty('complexity');
expect(props?.complexity?.enum).toEqual(['simple', 'medium', 'complex']);
});
it('should have pagination parameters', () => {
const limitProp = tool?.inputSchema.properties?.limit;
const offsetProp = tool?.inputSchema.properties?.offset;
expect(limitProp).toBeDefined();
expect(limitProp.type).toBe('number');
expect(limitProp.default).toBe(20);
expect(limitProp.maximum).toBe(100);
expect(limitProp.minimum).toBe(1);
expect(offsetProp).toBeDefined();
expect(offsetProp.type).toBe('number');
expect(offsetProp.default).toBe(0);
expect(offsetProp.minimum).toBe(0);
});
it('should include all expected properties', () => {
it('should include all search mode-specific properties', () => {
const properties = Object.keys(tool?.inputSchema.properties || {});
// Consolidated tool includes properties from all former tools
const expectedProperties = [
'category',
'complexity',
'maxSetupMinutes',
'minSetupMinutes',
'requiredService',
'targetAudience',
'searchMode', // New mode selector
'query', // For keyword search
'nodeTypes', // For by_nodes search (formerly list_node_templates)
'task', // For by_task search (formerly get_templates_for_task)
'category', // For by_metadata search
'complexity',
'limit',
'offset'
];
expectedProperties.forEach(prop => {
expect(properties).toContain(prop);
});
});
it('should have appropriate additionalProperties setting', () => {
expect(tool?.inputSchema.additionalProperties).toBe(false);
});
});
describe('Enhanced pagination support', () => {
const paginatedTools = ['list_node_templates', 'search_templates', 'get_templates_for_task', 'search_templates_by_metadata'];
paginatedTools.forEach(toolName => {
describe(toolName, () => {
const tool = n8nDocumentationToolsFinal.find(t => t.name === toolName);
it('should support limit parameter', () => {
expect(tool?.inputSchema.properties).toHaveProperty('limit');
const limitParam = tool?.inputSchema.properties.limit;
expect(limitParam.type).toBe('number');
expect(limitParam.minimum).toBeGreaterThanOrEqual(1);
expect(limitParam.maximum).toBeGreaterThanOrEqual(50);
});
it('should support offset parameter', () => {
expect(tool?.inputSchema.properties).toHaveProperty('offset');
const offsetParam = tool?.inputSchema.properties.offset;
expect(offsetParam.type).toBe('number');
expect(offsetParam.minimum).toBe(0);
});
});
});
});
});
});