mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-03-23 10:53:07 +00:00
fix: synchronize tool documentation with v2.26.0 tool consolidation (v2.26.2) (#442)
* fix: synchronize tool documentation with v2.26.0 tool consolidation (v2.26.2) - Delete 23 obsolete documentation files for removed tools - Create consolidated documentation for get_node, validate_node, n8n_executions - Update search_templates with all searchModes - Update n8n_get_workflow with all modes - Fix stale relatedTools references - Update tools-documentation.ts overview to reflect 19 consolidated tools Conceived by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: address code review - fix remaining stale tool references - Fix relatedTools in system/tools-documentation.ts (get_node_for_task → search_templates) - Fix relatedTools in validation/validate-workflow.ts (remove references to removed tools) - Fix relatedTools in n8n-autofix-workflow.ts (remove references to removed tools) - Update tools-n8n-friendly.ts with consolidated tools (validate_node, get_node, search_templates) Conceived by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: address final code review - fix remaining stale references - Fix ai-agents-guide.ts: get_node_essentials → get_node, remove list_ai_tools - Fix get-template.ts: list_node_templates → search_templates, remove get_templates_for_task - Fix n8n-list-workflows.ts: n8n_get_workflow_minimal → n8n_get_workflow, n8n_list_executions → n8n_executions - Fix n8n-trigger-webhook-workflow.ts: n8n_get_execution/n8n_list_executions → n8n_executions - Fix n8n-delete-workflow.ts: n8n_get_workflow_minimal → n8n_get_workflow, n8n_delete_execution → n8n_executions - Fix CHANGELOG date typo: 2025-01-25 → 2025-11-25 Conceived by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * test: adjust comprehensive docs threshold after tool consolidation Reduce expected character count from 5000 to 4000 in tool-invocation.test.ts to account for reduced documentation after v2.26.0 tool consolidation (31→19 tools, actual output is ~4645 chars). Conceived by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Romuald Członkowski
committed by
GitHub
GitHub
parent
c974947c84
commit
1be06c217f
@@ -1,8 +1,5 @@
|
||||
export { n8nCreateWorkflowDoc } from './n8n-create-workflow';
|
||||
export { n8nGetWorkflowDoc } from './n8n-get-workflow';
|
||||
export { n8nGetWorkflowDetailsDoc } from './n8n-get-workflow-details';
|
||||
export { n8nGetWorkflowStructureDoc } from './n8n-get-workflow-structure';
|
||||
export { n8nGetWorkflowMinimalDoc } from './n8n-get-workflow-minimal';
|
||||
export { n8nUpdateFullWorkflowDoc } from './n8n-update-full-workflow';
|
||||
export { n8nUpdatePartialWorkflowDoc } from './n8n-update-partial-workflow';
|
||||
export { n8nDeleteWorkflowDoc } from './n8n-delete-workflow';
|
||||
@@ -10,6 +7,4 @@ export { n8nListWorkflowsDoc } from './n8n-list-workflows';
|
||||
export { n8nValidateWorkflowDoc } from './n8n-validate-workflow';
|
||||
export { n8nAutofixWorkflowDoc } from './n8n-autofix-workflow';
|
||||
export { n8nTriggerWebhookWorkflowDoc } from './n8n-trigger-webhook-workflow';
|
||||
export { n8nGetExecutionDoc } from './n8n-get-execution';
|
||||
export { n8nListExecutionsDoc } from './n8n-list-executions';
|
||||
export { n8nDeleteExecutionDoc } from './n8n-delete-execution';
|
||||
export { n8nExecutionsDoc } from './n8n-executions';
|
||||
|
||||
@@ -153,9 +153,8 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`,
|
||||
relatedTools: [
|
||||
'n8n_validate_workflow',
|
||||
'validate_workflow',
|
||||
'n8n_update_partial_workflow',
|
||||
'validate_workflow_expressions',
|
||||
'validate_node_operation'
|
||||
'validate_node',
|
||||
'n8n_update_partial_workflow'
|
||||
]
|
||||
}
|
||||
};
|
||||
@@ -1,57 +0,0 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nDeleteExecutionDoc: ToolDocumentation = {
|
||||
name: 'n8n_delete_execution',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Delete an execution record. This only removes the execution history, not any data processed.',
|
||||
keyParameters: ['id'],
|
||||
example: 'n8n_delete_execution({id: "12345"})',
|
||||
performance: 'Immediate deletion, no undo available',
|
||||
tips: [
|
||||
'Deletion is permanent - execution cannot be recovered',
|
||||
'Only removes execution history, not external data changes',
|
||||
'Use for cleanup of test executions or sensitive data'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: `Permanently deletes a workflow execution record from n8n's history. This removes the execution metadata, logs, and any stored input/output data. However, it does NOT undo any actions the workflow performed (API calls, database changes, file operations, etc.). Use this for cleaning up test executions, removing sensitive data, or managing storage.`,
|
||||
parameters: {
|
||||
id: {
|
||||
type: 'string',
|
||||
required: true,
|
||||
description: 'The execution ID to delete. This action cannot be undone'
|
||||
}
|
||||
},
|
||||
returns: `Confirmation of deletion or error if execution not found. No data is returned about the deleted execution.`,
|
||||
examples: [
|
||||
'n8n_delete_execution({id: "12345"}) - Delete a specific execution',
|
||||
'n8n_delete_execution({id: "test-run-567"}) - Clean up test execution',
|
||||
'n8n_delete_execution({id: "sensitive-data-890"}) - Remove execution with sensitive data',
|
||||
'n8n_delete_execution({id: "failed-execution-123"}) - Delete failed execution after debugging'
|
||||
],
|
||||
useCases: [
|
||||
'Clean up test or development execution history',
|
||||
'Remove executions containing sensitive or personal data',
|
||||
'Manage storage by deleting old execution records',
|
||||
'Clean up after debugging failed workflows',
|
||||
'Comply with data retention policies'
|
||||
],
|
||||
performance: `Deletion is immediate and permanent. The operation is fast (< 100ms) as it only removes database records. No external systems or data are affected.`,
|
||||
bestPractices: [
|
||||
'Verify execution ID before deletion - action cannot be undone',
|
||||
'Consider exporting execution data before deletion if needed',
|
||||
'Use list_executions to find executions to delete',
|
||||
'Document why executions were deleted for audit trails',
|
||||
'Remember deletion only affects n8n records, not external changes'
|
||||
],
|
||||
pitfalls: [
|
||||
'Deletion is PERMANENT - no undo or recovery possible',
|
||||
'Does NOT reverse workflow actions (API calls, DB changes, etc.)',
|
||||
'Deleting executions breaks audit trails and debugging history',
|
||||
'Cannot delete currently running executions (waiting status)',
|
||||
'Bulk deletion not supported - must delete one at a time'
|
||||
],
|
||||
relatedTools: ['n8n_list_executions', 'n8n_get_execution', 'n8n_trigger_webhook_workflow']
|
||||
}
|
||||
};
|
||||
@@ -45,6 +45,6 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = {
|
||||
'Active workflows can be deleted',
|
||||
'No built-in confirmation'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow_minimal', 'n8n_list_workflows', 'n8n_update_partial_workflow', 'n8n_delete_execution']
|
||||
relatedTools: ['n8n_get_workflow', 'n8n_list_workflows', 'n8n_update_partial_workflow', 'n8n_executions']
|
||||
}
|
||||
};
|
||||
84
src/mcp/tool-docs/workflow_management/n8n-executions.ts
Normal file
84
src/mcp/tool-docs/workflow_management/n8n-executions.ts
Normal file
@@ -0,0 +1,84 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nExecutionsDoc: ToolDocumentation = {
|
||||
name: 'n8n_executions',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Manage workflow executions: get details, list, or delete. Unified tool for all execution operations.',
|
||||
keyParameters: ['action', 'id', 'workflowId', 'status'],
|
||||
example: 'n8n_executions({action: "list", workflowId: "abc123", status: "error"})',
|
||||
performance: 'Fast (50-200ms)',
|
||||
tips: [
|
||||
'action="get": Get execution details by ID',
|
||||
'action="list": List executions with filters',
|
||||
'action="delete": Delete execution record',
|
||||
'Use mode parameter for action=get to control detail level'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: `Unified execution management tool. Replaces n8n_get_execution, n8n_list_executions, and n8n_delete_execution.
|
||||
|
||||
**Actions:**
|
||||
- get: Retrieve execution details by ID with configurable detail level
|
||||
- list: List executions with filtering and pagination
|
||||
- delete: Remove an execution record from history
|
||||
|
||||
**Detail Modes for action="get":**
|
||||
- preview: Structure only, no data
|
||||
- summary: 2 items per node (default)
|
||||
- filtered: Custom items limit, optionally filter by node names
|
||||
- full: All execution data (can be very large)`,
|
||||
parameters: {
|
||||
action: { type: 'string', required: true, description: 'Operation: "get", "list", or "delete"' },
|
||||
id: { type: 'string', required: false, description: 'Execution ID (required for action=get or action=delete)' },
|
||||
mode: { type: 'string', required: false, description: 'For action=get: "preview", "summary" (default), "filtered", "full"' },
|
||||
nodeNames: { type: 'array', required: false, description: 'For action=get with mode=filtered: Filter to specific nodes by name' },
|
||||
itemsLimit: { type: 'number', required: false, description: 'For action=get with mode=filtered: Items per node (0=structure, 2=default, -1=unlimited)' },
|
||||
includeInputData: { type: 'boolean', required: false, description: 'For action=get: Include input data in addition to output (default: false)' },
|
||||
workflowId: { type: 'string', required: false, description: 'For action=list: Filter by workflow ID' },
|
||||
status: { type: 'string', required: false, description: 'For action=list: Filter by status ("success", "error", "waiting")' },
|
||||
limit: { type: 'number', required: false, description: 'For action=list: Number of results (1-100, default: 100)' },
|
||||
cursor: { type: 'string', required: false, description: 'For action=list: Pagination cursor from previous response' },
|
||||
projectId: { type: 'string', required: false, description: 'For action=list: Filter by project ID (enterprise)' },
|
||||
includeData: { type: 'boolean', required: false, description: 'For action=list: Include execution data (default: false)' }
|
||||
},
|
||||
returns: `Depends on action:
|
||||
- get: Execution object with data based on mode
|
||||
- list: { data: [...executions], nextCursor?: string }
|
||||
- delete: { success: boolean, message: string }`,
|
||||
examples: [
|
||||
'// List recent executions for a workflow\nn8n_executions({action: "list", workflowId: "abc123", limit: 10})',
|
||||
'// List failed executions\nn8n_executions({action: "list", status: "error"})',
|
||||
'// Get execution summary\nn8n_executions({action: "get", id: "exec_456"})',
|
||||
'// Get full execution data\nn8n_executions({action: "get", id: "exec_456", mode: "full"})',
|
||||
'// Get specific nodes from execution\nn8n_executions({action: "get", id: "exec_456", mode: "filtered", nodeNames: ["HTTP Request", "Slack"]})',
|
||||
'// Delete an execution\nn8n_executions({action: "delete", id: "exec_456"})'
|
||||
],
|
||||
useCases: [
|
||||
'Debug workflow failures (get with mode=full)',
|
||||
'Monitor workflow health (list with status filter)',
|
||||
'Audit execution history',
|
||||
'Clean up old execution records',
|
||||
'Analyze specific node outputs'
|
||||
],
|
||||
performance: `Response times:
|
||||
- list: 50-150ms depending on filters
|
||||
- get (preview/summary): 30-100ms
|
||||
- get (full): 100-500ms+ depending on data size
|
||||
- delete: 30-80ms`,
|
||||
bestPractices: [
|
||||
'Use mode="summary" (default) for debugging - shows enough data',
|
||||
'Use mode="filtered" with nodeNames for large workflows',
|
||||
'Filter by workflowId when listing to reduce results',
|
||||
'Use cursor for pagination through large result sets',
|
||||
'Delete old executions to save storage'
|
||||
],
|
||||
pitfalls: [
|
||||
'Requires N8N_API_URL and N8N_API_KEY configured',
|
||||
'mode="full" can return very large responses for complex workflows',
|
||||
'Execution must exist or returns 404',
|
||||
'Delete is permanent - cannot undo'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow', 'n8n_trigger_webhook_workflow', 'n8n_validate_workflow']
|
||||
}
|
||||
};
|
||||
@@ -1,283 +0,0 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nGetExecutionDoc: ToolDocumentation = {
|
||||
name: 'n8n_get_execution',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Get execution details with smart filtering to avoid token limits. Use preview mode first to assess data size, then fetch appropriately.',
|
||||
keyParameters: ['id', 'mode', 'itemsLimit', 'nodeNames'],
|
||||
example: `
|
||||
// RECOMMENDED WORKFLOW:
|
||||
// 1. Preview first
|
||||
n8n_get_execution({id: "12345", mode: "preview"})
|
||||
// Returns: structure, counts, size estimate, recommendation
|
||||
|
||||
// 2. Based on recommendation, fetch data:
|
||||
n8n_get_execution({id: "12345", mode: "summary"}) // 2 items per node
|
||||
n8n_get_execution({id: "12345", mode: "filtered", itemsLimit: 5}) // 5 items
|
||||
n8n_get_execution({id: "12345", nodeNames: ["HTTP Request"]}) // Specific node
|
||||
`,
|
||||
performance: 'Preview: <50ms, Summary: <200ms, Full: depends on data size',
|
||||
tips: [
|
||||
'ALWAYS use preview mode first for large datasets',
|
||||
'Preview shows structure + counts without consuming tokens for data',
|
||||
'Summary mode (2 items per node) is safe default',
|
||||
'Use nodeNames to focus on specific nodes only',
|
||||
'itemsLimit: 0 = structure only, -1 = unlimited',
|
||||
'Check recommendation.suggestedMode from preview'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: `Retrieves and intelligently filters execution data to enable inspection without exceeding token limits. This tool provides multiple modes for different use cases, from quick previews to complete data retrieval.
|
||||
|
||||
**The Problem**: Workflows processing large datasets (50+ database records) generate execution data that exceeds token/response limits, making traditional full-data fetching impossible.
|
||||
|
||||
**The Solution**: Four retrieval modes with smart filtering:
|
||||
1. **Preview**: Structure + counts only (no actual data)
|
||||
2. **Summary**: 2 sample items per node (safe default)
|
||||
3. **Filtered**: Custom limits and node selection
|
||||
4. **Full**: Complete data (use with caution)
|
||||
|
||||
**Recommended Workflow**:
|
||||
1. Start with preview mode to assess size
|
||||
2. Use recommendation to choose appropriate mode
|
||||
3. Fetch filtered data as needed`,
|
||||
|
||||
parameters: {
|
||||
id: {
|
||||
type: 'string',
|
||||
required: true,
|
||||
description: 'The execution ID to retrieve. Obtained from list_executions or webhook trigger responses'
|
||||
},
|
||||
mode: {
|
||||
type: 'string',
|
||||
required: false,
|
||||
description: `Retrieval mode (default: auto-detect from other params):
|
||||
- 'preview': Structure, counts, size estimates - NO actual data (fastest)
|
||||
- 'summary': Metadata + 2 sample items per node (safe default)
|
||||
- 'filtered': Custom filtering with itemsLimit/nodeNames
|
||||
- 'full': Complete execution data (use with caution)`
|
||||
},
|
||||
nodeNames: {
|
||||
type: 'array',
|
||||
required: false,
|
||||
description: 'Filter to specific nodes by name. Example: ["HTTP Request", "Filter"]. Useful when you only need to inspect specific nodes.'
|
||||
},
|
||||
itemsLimit: {
|
||||
type: 'number',
|
||||
required: false,
|
||||
description: `Items to return per node (default: 2):
|
||||
- 0: Structure only (see data shape without values)
|
||||
- 1-N: Return N items per node
|
||||
- -1: Unlimited (return all items)
|
||||
|
||||
Note: Structure-only mode (0) shows JSON schema without actual values.`
|
||||
},
|
||||
includeInputData: {
|
||||
type: 'boolean',
|
||||
required: false,
|
||||
description: 'Include input data in addition to output data (default: false). Useful for debugging data transformations.'
|
||||
},
|
||||
includeData: {
|
||||
type: 'boolean',
|
||||
required: false,
|
||||
description: 'DEPRECATED: Legacy parameter. Use mode instead. If true, maps to mode="summary" for backward compatibility.'
|
||||
}
|
||||
},
|
||||
|
||||
returns: `**Preview Mode Response**:
|
||||
{
|
||||
mode: 'preview',
|
||||
preview: {
|
||||
totalNodes: number,
|
||||
executedNodes: number,
|
||||
estimatedSizeKB: number,
|
||||
nodes: {
|
||||
[nodeName]: {
|
||||
status: 'success' | 'error',
|
||||
itemCounts: { input: number, output: number },
|
||||
dataStructure: {...}, // JSON schema
|
||||
estimatedSizeKB: number
|
||||
}
|
||||
}
|
||||
},
|
||||
recommendation: {
|
||||
canFetchFull: boolean,
|
||||
suggestedMode: 'preview'|'summary'|'filtered'|'full',
|
||||
suggestedItemsLimit?: number,
|
||||
reason: string
|
||||
}
|
||||
}
|
||||
|
||||
**Summary/Filtered/Full Mode Response**:
|
||||
{
|
||||
mode: 'summary' | 'filtered' | 'full',
|
||||
summary: {
|
||||
totalNodes: number,
|
||||
executedNodes: number,
|
||||
totalItems: number,
|
||||
hasMoreData: boolean // true if truncated
|
||||
},
|
||||
nodes: {
|
||||
[nodeName]: {
|
||||
executionTime: number,
|
||||
itemsInput: number,
|
||||
itemsOutput: number,
|
||||
status: 'success' | 'error',
|
||||
error?: string,
|
||||
data: {
|
||||
output: [...], // Actual data items
|
||||
metadata: {
|
||||
totalItems: number,
|
||||
itemsShown: number,
|
||||
truncated: boolean
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}`,
|
||||
|
||||
examples: [
|
||||
`// Example 1: Preview workflow (RECOMMENDED FIRST STEP)
|
||||
n8n_get_execution({id: "exec_123", mode: "preview"})
|
||||
// Returns structure, counts, size, recommendation
|
||||
// Use this to decide how to fetch data`,
|
||||
|
||||
`// Example 2: Follow recommendation
|
||||
const preview = n8n_get_execution({id: "exec_123", mode: "preview"});
|
||||
if (preview.recommendation.canFetchFull) {
|
||||
n8n_get_execution({id: "exec_123", mode: "full"});
|
||||
} else {
|
||||
n8n_get_execution({
|
||||
id: "exec_123",
|
||||
mode: "filtered",
|
||||
itemsLimit: preview.recommendation.suggestedItemsLimit
|
||||
});
|
||||
}`,
|
||||
|
||||
`// Example 3: Summary mode (safe default for unknown datasets)
|
||||
n8n_get_execution({id: "exec_123", mode: "summary"})
|
||||
// Gets 2 items per node - safe for most cases`,
|
||||
|
||||
`// Example 4: Filter to specific node
|
||||
n8n_get_execution({
|
||||
id: "exec_123",
|
||||
mode: "filtered",
|
||||
nodeNames: ["HTTP Request"],
|
||||
itemsLimit: 5
|
||||
})
|
||||
// Gets only HTTP Request node, 5 items`,
|
||||
|
||||
`// Example 5: Structure only (see data shape)
|
||||
n8n_get_execution({
|
||||
id: "exec_123",
|
||||
mode: "filtered",
|
||||
itemsLimit: 0
|
||||
})
|
||||
// Returns JSON schema without actual values`,
|
||||
|
||||
`// Example 6: Debug with input data
|
||||
n8n_get_execution({
|
||||
id: "exec_123",
|
||||
mode: "filtered",
|
||||
nodeNames: ["Transform"],
|
||||
itemsLimit: 2,
|
||||
includeInputData: true
|
||||
})
|
||||
// See both input and output for debugging`,
|
||||
|
||||
`// Example 7: Backward compatibility (legacy)
|
||||
n8n_get_execution({id: "exec_123"}) // Minimal data
|
||||
n8n_get_execution({id: "exec_123", includeData: true}) // Maps to summary mode`
|
||||
],
|
||||
|
||||
useCases: [
|
||||
'Monitor status of triggered workflows',
|
||||
'Debug failed workflows by examining error messages and partial data',
|
||||
'Inspect large datasets without exceeding token limits',
|
||||
'Validate data transformations between nodes',
|
||||
'Understand execution flow and timing',
|
||||
'Track workflow performance metrics',
|
||||
'Verify successful completion before proceeding',
|
||||
'Extract specific data from execution results'
|
||||
],
|
||||
|
||||
performance: `**Response Times** (approximate):
|
||||
- Preview mode: <50ms (no data, just structure)
|
||||
- Summary mode: <200ms (2 items per node)
|
||||
- Filtered mode: 50-500ms (depends on filters)
|
||||
- Full mode: 200ms-5s (depends on data size)
|
||||
|
||||
**Token Consumption**:
|
||||
- Preview: ~500 tokens (no data values)
|
||||
- Summary (2 items): ~2-5K tokens
|
||||
- Filtered (5 items): ~5-15K tokens
|
||||
- Full (50+ items): 50K+ tokens (may exceed limits)
|
||||
|
||||
**Optimization Tips**:
|
||||
- Use preview for all large datasets
|
||||
- Use nodeNames to focus on relevant nodes only
|
||||
- Start with small itemsLimit and increase if needed
|
||||
- Use itemsLimit: 0 to see structure without data`,
|
||||
|
||||
bestPractices: [
|
||||
'ALWAYS use preview mode first for unknown datasets',
|
||||
'Trust the recommendation.suggestedMode from preview',
|
||||
'Use nodeNames to filter to relevant nodes only',
|
||||
'Start with summary mode if preview indicates moderate size',
|
||||
'Use itemsLimit: 0 to understand data structure',
|
||||
'Check hasMoreData to know if results are truncated',
|
||||
'Store execution IDs from triggers for later inspection',
|
||||
'Use mode="filtered" with custom limits for large datasets',
|
||||
'Include input data only when debugging transformations',
|
||||
'Monitor summary.totalItems to understand dataset size'
|
||||
],
|
||||
|
||||
pitfalls: [
|
||||
'DON\'T fetch full mode without previewing first - may timeout',
|
||||
'DON\'T assume all data fits - always check hasMoreData',
|
||||
'DON\'T ignore the recommendation from preview mode',
|
||||
'Execution data is retained based on n8n settings - old executions may be purged',
|
||||
'Binary data (files, images) is not fully included - only metadata',
|
||||
'Status "waiting" indicates execution is still running',
|
||||
'Error executions may have partial data from successful nodes',
|
||||
'Very large individual items (>1MB) may be truncated',
|
||||
'Preview mode estimates may be off by 10-20% for complex structures',
|
||||
'Node names are case-sensitive in nodeNames filter'
|
||||
],
|
||||
|
||||
modeComparison: `**When to use each mode**:
|
||||
|
||||
**Preview**:
|
||||
- ALWAYS use first for unknown datasets
|
||||
- When you need to know if data is safe to fetch
|
||||
- To see data structure without consuming tokens
|
||||
- To get size estimates and recommendations
|
||||
|
||||
**Summary** (default):
|
||||
- Safe default for most cases
|
||||
- When you need representative samples
|
||||
- When preview recommends it
|
||||
- For quick data inspection
|
||||
|
||||
**Filtered**:
|
||||
- When you need specific nodes only
|
||||
- When you need more than 2 items but not all
|
||||
- When preview recommends it with itemsLimit
|
||||
- For targeted data extraction
|
||||
|
||||
**Full**:
|
||||
- ONLY when preview says canFetchFull: true
|
||||
- For small executions (< 20 items total)
|
||||
- When you genuinely need all data
|
||||
- When you're certain data fits in token limit`,
|
||||
|
||||
relatedTools: [
|
||||
'n8n_list_executions - Find execution IDs',
|
||||
'n8n_trigger_webhook_workflow - Trigger and get execution ID',
|
||||
'n8n_delete_execution - Clean up old executions',
|
||||
'n8n_get_workflow - Get workflow structure',
|
||||
'validate_workflow - Validate before executing'
|
||||
]
|
||||
}
|
||||
};
|
||||
@@ -1,49 +0,0 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nGetWorkflowDetailsDoc: ToolDocumentation = {
|
||||
name: 'n8n_get_workflow_details',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Get workflow details with metadata, version, execution stats. More info than get_workflow.',
|
||||
keyParameters: ['id'],
|
||||
example: 'n8n_get_workflow_details({id: "workflow_123"})',
|
||||
performance: 'Fast (100-300ms)',
|
||||
tips: [
|
||||
'Includes execution statistics',
|
||||
'Shows version history info',
|
||||
'Contains metadata like tags'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Retrieves comprehensive workflow details including metadata, execution statistics, version information, and usage analytics. Provides more information than get_workflow, including data not typically needed for editing but useful for monitoring and analysis.',
|
||||
parameters: {
|
||||
id: { type: 'string', required: true, description: 'Workflow ID to retrieve details for' }
|
||||
},
|
||||
returns: 'Extended workflow object with: id, name, nodes, connections, settings, plus metadata (tags, owner, shared users), execution stats (success/error counts, average runtime), version info, created/updated timestamps',
|
||||
examples: [
|
||||
'n8n_get_workflow_details({id: "abc123"}) - Get workflow with stats',
|
||||
'const details = n8n_get_workflow_details({id: "xyz789"}); // Analyze performance'
|
||||
],
|
||||
useCases: [
|
||||
'Monitor workflow performance',
|
||||
'Analyze execution patterns',
|
||||
'View workflow metadata',
|
||||
'Check version information',
|
||||
'Audit workflow usage'
|
||||
],
|
||||
performance: 'Slightly slower than get_workflow due to additional metadata - typically 100-300ms. Stats may be cached.',
|
||||
bestPractices: [
|
||||
'Use for monitoring and analysis',
|
||||
'Check execution stats before optimization',
|
||||
'Review error counts for debugging',
|
||||
'Monitor average execution times'
|
||||
],
|
||||
pitfalls: [
|
||||
'Requires N8N_API_URL and N8N_API_KEY configured',
|
||||
'More data than needed for simple edits',
|
||||
'Stats may have slight delay',
|
||||
'Not all n8n versions support all fields'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow', 'n8n_list_executions', 'n8n_get_execution', 'n8n_list_workflows']
|
||||
}
|
||||
};
|
||||
@@ -1,49 +0,0 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nGetWorkflowMinimalDoc: ToolDocumentation = {
|
||||
name: 'n8n_get_workflow_minimal',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Get minimal info: ID, name, active status, tags. Fast for listings.',
|
||||
keyParameters: ['id'],
|
||||
example: 'n8n_get_workflow_minimal({id: "workflow_123"})',
|
||||
performance: 'Very fast (<50ms)',
|
||||
tips: [
|
||||
'Fastest way to check workflow exists',
|
||||
'Perfect for status checks',
|
||||
'Use in list displays'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Retrieves only essential workflow information without nodes or connections. Returns minimal data needed for listings, status checks, and quick lookups. Optimized for performance when full workflow data is not needed.',
|
||||
parameters: {
|
||||
id: { type: 'string', required: true, description: 'Workflow ID to retrieve minimal info for' }
|
||||
},
|
||||
returns: 'Minimal workflow object with: id, name, active status, tags array, createdAt, updatedAt. No nodes, connections, or settings included.',
|
||||
examples: [
|
||||
'n8n_get_workflow_minimal({id: "abc123"}) - Quick existence check',
|
||||
'const info = n8n_get_workflow_minimal({id: "xyz789"}); // Check if active'
|
||||
],
|
||||
useCases: [
|
||||
'Quick workflow existence checks',
|
||||
'Display workflow lists',
|
||||
'Check active/inactive status',
|
||||
'Get workflow tags',
|
||||
'Performance-critical operations'
|
||||
],
|
||||
performance: 'Extremely fast - typically under 50ms. Returns only database metadata without loading workflow definition.',
|
||||
bestPractices: [
|
||||
'Use for list displays and dashboards',
|
||||
'Ideal for existence checks before operations',
|
||||
'Cache results for UI responsiveness',
|
||||
'Combine with list_workflows for bulk checks'
|
||||
],
|
||||
pitfalls: [
|
||||
'Requires N8N_API_URL and N8N_API_KEY configured',
|
||||
'No workflow content - cannot edit or validate',
|
||||
'Tags may be empty array',
|
||||
'Must use get_workflow for actual workflow data'
|
||||
],
|
||||
relatedTools: ['n8n_list_workflows', 'n8n_get_workflow', 'n8n_get_workflow_structure', 'n8n_update_partial_workflow']
|
||||
}
|
||||
};
|
||||
@@ -1,49 +0,0 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nGetWorkflowStructureDoc: ToolDocumentation = {
|
||||
name: 'n8n_get_workflow_structure',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Get workflow structure: nodes and connections only. No parameter details.',
|
||||
keyParameters: ['id'],
|
||||
example: 'n8n_get_workflow_structure({id: "workflow_123"})',
|
||||
performance: 'Fast (75-150ms)',
|
||||
tips: [
|
||||
'Shows workflow topology',
|
||||
'Node types without parameters',
|
||||
'Perfect for visualization'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Retrieves workflow structural information including node types, positions, and connections, but without detailed node parameters. Ideal for understanding workflow topology, creating visualizations, or analyzing workflow complexity without the overhead of full parameter data.',
|
||||
parameters: {
|
||||
id: { type: 'string', required: true, description: 'Workflow ID to retrieve structure for' }
|
||||
},
|
||||
returns: 'Workflow structure with: id, name, nodes array (id, name, type, position only), connections object. No node parameters, credentials, or settings included.',
|
||||
examples: [
|
||||
'n8n_get_workflow_structure({id: "abc123"}) - Visualize workflow',
|
||||
'const structure = n8n_get_workflow_structure({id: "xyz789"}); // Analyze complexity'
|
||||
],
|
||||
useCases: [
|
||||
'Generate workflow visualizations',
|
||||
'Analyze workflow complexity',
|
||||
'Understand node relationships',
|
||||
'Create workflow diagrams',
|
||||
'Quick topology validation'
|
||||
],
|
||||
performance: 'Fast retrieval - typically 75-150ms. Faster than get_workflow as parameters are stripped.',
|
||||
bestPractices: [
|
||||
'Use for visualization tools',
|
||||
'Ideal for workflow analysis',
|
||||
'Good for connection validation',
|
||||
'Cache for UI diagram rendering'
|
||||
],
|
||||
pitfalls: [
|
||||
'Requires N8N_API_URL and N8N_API_KEY configured',
|
||||
'No parameter data for configuration',
|
||||
'Cannot validate node settings',
|
||||
'Must use get_workflow for editing'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow', 'n8n_validate_workflow_connections', 'n8n_get_workflow_minimal', 'validate_workflow_connections']
|
||||
}
|
||||
};
|
||||
@@ -4,46 +4,65 @@ export const n8nGetWorkflowDoc: ToolDocumentation = {
|
||||
name: 'n8n_get_workflow',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'Get a workflow by ID. Returns the complete workflow including nodes, connections, and settings.',
|
||||
keyParameters: ['id'],
|
||||
example: 'n8n_get_workflow({id: "workflow_123"})',
|
||||
description: 'Get workflow by ID with different detail levels. Use mode to control response size and content.',
|
||||
keyParameters: ['id', 'mode'],
|
||||
example: 'n8n_get_workflow({id: "workflow_123", mode: "structure"})',
|
||||
performance: 'Fast (50-200ms)',
|
||||
tips: [
|
||||
'Returns complete workflow JSON',
|
||||
'Includes all node parameters',
|
||||
'Use get_workflow_minimal for faster listings'
|
||||
'mode="full" (default): Complete workflow with all data',
|
||||
'mode="details": Full workflow + execution stats',
|
||||
'mode="structure": Just nodes and connections (topology)',
|
||||
'mode="minimal": Only id, name, active status, tags'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: 'Retrieves a complete workflow from n8n by its ID. Returns full workflow definition including all nodes with their parameters, connections between nodes, and workflow settings. This is the primary tool for fetching workflows for viewing, editing, or cloning.',
|
||||
description: `Unified workflow retrieval with configurable detail levels. Replaces n8n_get_workflow, n8n_get_workflow_details, n8n_get_workflow_structure, and n8n_get_workflow_minimal.
|
||||
|
||||
**Modes:**
|
||||
- full (default): Complete workflow including all nodes with parameters, connections, and settings
|
||||
- details: Full workflow plus execution statistics (success/error counts, last execution time)
|
||||
- structure: Nodes and connections only - useful for topology analysis
|
||||
- minimal: Just id, name, active status, and tags - fastest response`,
|
||||
parameters: {
|
||||
id: { type: 'string', required: true, description: 'Workflow ID to retrieve' }
|
||||
id: { type: 'string', required: true, description: 'Workflow ID to retrieve' },
|
||||
mode: { type: 'string', required: false, description: 'Detail level: "full" (default), "details", "structure", "minimal"' }
|
||||
},
|
||||
returns: 'Complete workflow object containing: id, name, active status, nodes array (with full parameters), connections object, settings, createdAt, updatedAt',
|
||||
returns: `Depends on mode:
|
||||
- full: Complete workflow object (id, name, active, nodes[], connections{}, settings, createdAt, updatedAt)
|
||||
- details: Full workflow + executionStats (successCount, errorCount, lastExecution, etc.)
|
||||
- structure: { nodes: [...], connections: {...} } - topology only
|
||||
- minimal: { id, name, active, tags, createdAt, updatedAt }`,
|
||||
examples: [
|
||||
'n8n_get_workflow({id: "abc123"}) - Get workflow for editing',
|
||||
'const wf = n8n_get_workflow({id: "xyz789"}); // Clone workflow structure'
|
||||
'// Get complete workflow (default)\nn8n_get_workflow({id: "abc123"})',
|
||||
'// Get workflow with execution stats\nn8n_get_workflow({id: "abc123", mode: "details"})',
|
||||
'// Get just the topology\nn8n_get_workflow({id: "abc123", mode: "structure"})',
|
||||
'// Quick metadata check\nn8n_get_workflow({id: "abc123", mode: "minimal"})'
|
||||
],
|
||||
useCases: [
|
||||
'View workflow configuration',
|
||||
'Export workflow for backup',
|
||||
'Clone workflow structure',
|
||||
'Debug workflow issues',
|
||||
'Prepare for updates'
|
||||
'View and edit workflow (mode=full)',
|
||||
'Analyze workflow performance (mode=details)',
|
||||
'Clone or compare workflow structure (mode=structure)',
|
||||
'List workflows with status (mode=minimal)',
|
||||
'Debug workflow issues'
|
||||
],
|
||||
performance: 'Fast retrieval - typically 50-200ms depending on workflow size. Cached by n8n for performance.',
|
||||
performance: `Response times vary by mode:
|
||||
- minimal: ~20-50ms (smallest response)
|
||||
- structure: ~30-80ms (nodes + connections only)
|
||||
- full: ~50-200ms (complete workflow)
|
||||
- details: ~100-300ms (includes execution queries)`,
|
||||
bestPractices: [
|
||||
'Check workflow exists before updating',
|
||||
'Use for complete workflow data needs',
|
||||
'Cache results when making multiple operations',
|
||||
'Validate after retrieving if modifying'
|
||||
'Use mode="minimal" when listing or checking status',
|
||||
'Use mode="structure" for workflow analysis or cloning',
|
||||
'Use mode="full" (default) when editing',
|
||||
'Use mode="details" for debugging execution issues',
|
||||
'Validate workflow after retrieval if planning modifications'
|
||||
],
|
||||
pitfalls: [
|
||||
'Requires N8N_API_URL and N8N_API_KEY configured',
|
||||
'Returns all data - use minimal/structure for performance',
|
||||
'Workflow must exist or returns 404',
|
||||
'Credentials are referenced but not included'
|
||||
'mode="details" adds database queries for execution stats',
|
||||
'Workflow must exist or returns 404 error',
|
||||
'Credentials are referenced by ID but values not included'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow_minimal', 'n8n_get_workflow_structure', 'n8n_update_full_workflow', 'n8n_validate_workflow']
|
||||
relatedTools: ['n8n_list_workflows', 'n8n_update_full_workflow', 'n8n_update_partial_workflow', 'n8n_validate_workflow']
|
||||
}
|
||||
};
|
||||
@@ -1,84 +0,0 @@
|
||||
import { ToolDocumentation } from '../types';
|
||||
|
||||
export const n8nListExecutionsDoc: ToolDocumentation = {
|
||||
name: 'n8n_list_executions',
|
||||
category: 'workflow_management',
|
||||
essentials: {
|
||||
description: 'List workflow executions with optional filters. Supports pagination for large result sets.',
|
||||
keyParameters: ['workflowId', 'status', 'limit'],
|
||||
example: 'n8n_list_executions({workflowId: "abc123", status: "error"})',
|
||||
performance: 'Fast metadata retrieval, use pagination for large datasets',
|
||||
tips: [
|
||||
'Filter by status (success/error/waiting) to find specific execution types',
|
||||
'Use workflowId to see all executions for a specific workflow',
|
||||
'Pagination via cursor allows retrieving large execution histories'
|
||||
]
|
||||
},
|
||||
full: {
|
||||
description: `Lists workflow executions with powerful filtering options. This tool is essential for monitoring workflow performance, finding failed executions, and tracking workflow activity. Supports pagination for retrieving large execution histories and filtering by workflow, status, and project.`,
|
||||
parameters: {
|
||||
limit: {
|
||||
type: 'number',
|
||||
required: false,
|
||||
description: 'Number of executions to return (1-100, default: 100). Use with cursor for pagination'
|
||||
},
|
||||
cursor: {
|
||||
type: 'string',
|
||||
required: false,
|
||||
description: 'Pagination cursor from previous response. Used to retrieve next page of results'
|
||||
},
|
||||
workflowId: {
|
||||
type: 'string',
|
||||
required: false,
|
||||
description: 'Filter executions by specific workflow ID. Shows all executions for that workflow'
|
||||
},
|
||||
projectId: {
|
||||
type: 'string',
|
||||
required: false,
|
||||
description: 'Filter by project ID (enterprise feature). Groups executions by project'
|
||||
},
|
||||
status: {
|
||||
type: 'string',
|
||||
required: false,
|
||||
enum: ['success', 'error', 'waiting'],
|
||||
description: 'Filter by execution status. Success = completed, Error = failed, Waiting = running'
|
||||
},
|
||||
includeData: {
|
||||
type: 'boolean',
|
||||
required: false,
|
||||
description: 'Include execution data in results (default: false). Significantly increases response size'
|
||||
}
|
||||
},
|
||||
returns: `Array of execution objects with metadata, pagination cursor for next page, and optionally execution data. Each execution includes ID, status, start/end times, and workflow reference.`,
|
||||
examples: [
|
||||
'n8n_list_executions({limit: 10}) - Get 10 most recent executions',
|
||||
'n8n_list_executions({workflowId: "abc123"}) - All executions for specific workflow',
|
||||
'n8n_list_executions({status: "error", limit: 50}) - Find failed executions',
|
||||
'n8n_list_executions({status: "waiting"}) - Monitor currently running workflows',
|
||||
'n8n_list_executions({cursor: "next-page-token"}) - Get next page of results'
|
||||
],
|
||||
useCases: [
|
||||
'Monitor workflow execution history and patterns',
|
||||
'Find and debug failed workflow executions',
|
||||
'Track currently running workflows (waiting status)',
|
||||
'Analyze workflow performance and execution frequency',
|
||||
'Generate execution reports for specific workflows'
|
||||
],
|
||||
performance: `Listing executions is fast for metadata only. Including data (includeData: true) significantly impacts performance. Use pagination (limit + cursor) for large result sets. Default limit of 100 balances performance with usability.`,
|
||||
bestPractices: [
|
||||
'Use status filters to focus on specific execution types',
|
||||
'Implement pagination for large execution histories',
|
||||
'Avoid includeData unless you need execution details',
|
||||
'Filter by workflowId when monitoring specific workflows',
|
||||
'Check for cursor in response to detect more pages'
|
||||
],
|
||||
pitfalls: [
|
||||
'Large limits with includeData can cause timeouts',
|
||||
'Execution retention depends on n8n configuration',
|
||||
'Cursor tokens expire - use them promptly',
|
||||
'Status "waiting" includes both running and queued executions',
|
||||
'Deleted workflows still show in execution history'
|
||||
],
|
||||
relatedTools: ['n8n_get_execution', 'n8n_trigger_webhook_workflow', 'n8n_delete_execution', 'n8n_list_workflows']
|
||||
}
|
||||
};
|
||||
@@ -50,6 +50,6 @@ export const n8nListWorkflowsDoc: ToolDocumentation = {
|
||||
'Server may return fewer than requested limit',
|
||||
'returned field is count of current page only, not system total'
|
||||
],
|
||||
relatedTools: ['n8n_get_workflow_minimal', 'n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_list_executions']
|
||||
relatedTools: ['n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_executions']
|
||||
}
|
||||
};
|
||||
@@ -64,13 +64,13 @@ export const n8nTriggerWebhookWorkflowDoc: ToolDocumentation = {
|
||||
When a webhook trigger fails, the error response now includes specific guidance to help debug the issue:
|
||||
|
||||
**Error with Execution ID** (workflow started but failed):
|
||||
- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error."
|
||||
- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_executions({action: 'get', id: '{executionId}', mode: 'preview'}) to investigate the error."
|
||||
- Response includes: executionId and workflowId fields for direct access
|
||||
- Recommended action: Use n8n_get_execution with mode='preview' for fast, efficient error inspection
|
||||
- Recommended action: Use n8n_executions with action='get' and mode='preview' for fast, efficient error inspection
|
||||
|
||||
**Error without Execution ID** (workflow didn't start):
|
||||
- Format: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate."
|
||||
- Recommended action: Check recent executions with n8n_list_executions
|
||||
- Format: "Workflow failed to execute. Use n8n_executions({action: 'list'}) to find recent executions, then n8n_executions({action: 'get', mode: 'preview'}) to investigate."
|
||||
- Recommended action: Check recent executions with n8n_executions({action: 'list'})
|
||||
|
||||
**Why mode='preview'?**
|
||||
- Fast: <50ms response time
|
||||
@@ -92,7 +92,7 @@ When a webhook trigger fails, the error response now includes specific guidance
|
||||
|
||||
**Investigation Workflow**:
|
||||
1. Trigger returns error with execution ID
|
||||
2. Call n8n_get_execution({id: executionId, mode: 'preview'}) to see structure and error
|
||||
2. Call n8n_executions({action: 'get', id: executionId, mode: 'preview'}) to see structure and error
|
||||
3. Based on preview recommendation, fetch more data if needed
|
||||
4. Fix issues in workflow and retry`,
|
||||
bestPractices: [
|
||||
@@ -101,7 +101,7 @@ When a webhook trigger fails, the error response now includes specific guidance
|
||||
'Use async mode (waitForResponse: false) for long-running workflows',
|
||||
'Include authentication headers when webhook requires them',
|
||||
'Test webhook URL manually first to ensure it works',
|
||||
'When errors occur, use n8n_get_execution with mode="preview" first for efficient debugging',
|
||||
'When errors occur, use n8n_executions with action="get" and mode="preview" first for efficient debugging',
|
||||
'Store execution IDs from error responses for later investigation'
|
||||
],
|
||||
pitfalls: [
|
||||
@@ -110,9 +110,9 @@ When a webhook trigger fails, the error response now includes specific guidance
|
||||
'Webhook node must be the trigger node in the workflow',
|
||||
'Timeout errors occur with long workflows in sync mode',
|
||||
'Data format must match webhook node expectations',
|
||||
'Error messages always include n8n_get_execution guidance - follow the suggested steps for efficient debugging',
|
||||
'Error messages always include n8n_executions guidance - follow the suggested steps for efficient debugging',
|
||||
'Execution IDs in error responses are crucial for debugging - always check for and use them'
|
||||
],
|
||||
relatedTools: ['n8n_get_execution', 'n8n_list_executions', 'n8n_get_workflow', 'n8n_create_workflow']
|
||||
relatedTools: ['n8n_executions', 'n8n_get_workflow', 'n8n_create_workflow']
|
||||
}
|
||||
};
|
||||
Reference in New Issue
Block a user