mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-02-07 14:03:08 +00:00
feat: add error mode for execution debugging with AI suggestions (#505)
* feat: add error mode for execution debugging with AI suggestions Add a new `mode='error'` option to n8n_executions action=get that's optimized for AI agents debugging workflow failures. This mode provides intelligent error extraction with 80-99% token savings compared to `mode='full'`. Key features: - Error Analysis: Extracts error message, type, node name, and parameters - Upstream Context: Samples input data from upstream node (configurable limit) - Execution Path: Shows node execution sequence from trigger to error - AI Suggestions: Pattern-based fix suggestions for common errors - Workflow Fetch: Optionally fetches workflow for accurate upstream detection New parameters for mode='error': - errorItemsLimit (default: 2) - Sample items from upstream node - includeStackTrace (default: false) - Full vs truncated stack trace - includeExecutionPath (default: true) - Include node execution path - fetchWorkflow (default: true) - Fetch workflow for upstream detection Token efficiency: - 11 items: ~11KB full vs ~3KB error (73% savings) - 1001 items: ~354KB full vs ~3KB error (99% savings) Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: add security hardening to error-execution-processor - Add prototype pollution protection (block __proto__, constructor, prototype) - Expand sensitive data patterns (20+ patterns including JWT, OAuth, certificates) - Create recursive sanitizeData function for deep object sanitization - Apply sanitization to both nodeParameters and upstream sampleItems - Add comprehensive unit tests (42 tests, 96% coverage) Security improvements address code review findings: - Critical: Prototype pollution protection - Warning: Expanded sensitive data filtering - Warning: Nested data sanitization Concieved by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Romuald Członkowski <romualdczlonkowski@MacBook-Pro-Romuald.local> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Romuald Członkowski
committed by
GitHub
GitHub
parent
a40f6a5077
commit
d60182eeb8
@@ -1421,17 +1421,33 @@ export async function handleGetExecution(args: unknown, context?: InstanceContex
|
||||
// Parse and validate input with new parameters
|
||||
const schema = z.object({
|
||||
id: z.string(),
|
||||
// New filtering parameters
|
||||
mode: z.enum(['preview', 'summary', 'filtered', 'full']).optional(),
|
||||
// Filtering parameters
|
||||
mode: z.enum(['preview', 'summary', 'filtered', 'full', 'error']).optional(),
|
||||
nodeNames: z.array(z.string()).optional(),
|
||||
itemsLimit: z.number().optional(),
|
||||
includeInputData: z.boolean().optional(),
|
||||
// Legacy parameter (backward compatibility)
|
||||
includeData: z.boolean().optional()
|
||||
includeData: z.boolean().optional(),
|
||||
// Error mode specific parameters
|
||||
errorItemsLimit: z.number().min(0).max(100).optional(),
|
||||
includeStackTrace: z.boolean().optional(),
|
||||
includeExecutionPath: z.boolean().optional(),
|
||||
fetchWorkflow: z.boolean().optional()
|
||||
});
|
||||
|
||||
const params = schema.parse(args);
|
||||
const { id, mode, nodeNames, itemsLimit, includeInputData, includeData } = params;
|
||||
const {
|
||||
id,
|
||||
mode,
|
||||
nodeNames,
|
||||
itemsLimit,
|
||||
includeInputData,
|
||||
includeData,
|
||||
errorItemsLimit,
|
||||
includeStackTrace,
|
||||
includeExecutionPath,
|
||||
fetchWorkflow
|
||||
} = params;
|
||||
|
||||
/**
|
||||
* Map legacy includeData parameter to mode for backward compatibility
|
||||
@@ -1470,15 +1486,33 @@ export async function handleGetExecution(args: unknown, context?: InstanceContex
|
||||
};
|
||||
}
|
||||
|
||||
// For error mode, optionally fetch workflow for accurate upstream detection
|
||||
let workflow: Workflow | undefined;
|
||||
if (effectiveMode === 'error' && fetchWorkflow !== false && execution.workflowId) {
|
||||
try {
|
||||
workflow = await client.getWorkflow(execution.workflowId);
|
||||
} catch (e) {
|
||||
// Workflow fetch failed - continue without it (use heuristics)
|
||||
logger.debug('Could not fetch workflow for error analysis', {
|
||||
workflowId: execution.workflowId,
|
||||
error: e instanceof Error ? e.message : 'Unknown error'
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Apply filtering using ExecutionProcessor
|
||||
const filterOptions: ExecutionFilterOptions = {
|
||||
mode: effectiveMode,
|
||||
nodeNames,
|
||||
itemsLimit,
|
||||
includeInputData
|
||||
includeInputData,
|
||||
// Error mode specific options
|
||||
errorItemsLimit,
|
||||
includeStackTrace,
|
||||
includeExecutionPath
|
||||
};
|
||||
|
||||
const processedExecution = processExecution(execution, filterOptions);
|
||||
const processedExecution = processExecution(execution, filterOptions, workflow);
|
||||
|
||||
return {
|
||||
success: true,
|
||||
|
||||
@@ -5,13 +5,14 @@ export const n8nExecutionsDoc: ToolDocumentation = {
|
||||
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"})',
|
||||
keyParameters: ['action', 'id', 'workflowId', 'status', 'mode'],
|
||||
example: 'n8n_executions({action: "get", id: "exec_456", mode: "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="error" for efficient failure debugging (80-90% token savings)',
|
||||
'Use mode parameter for action=get to control detail level'
|
||||
]
|
||||
},
|
||||
@@ -25,14 +26,26 @@ export const n8nExecutionsDoc: ToolDocumentation = {
|
||||
- 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)`,
|
||||
- full: All execution data (can be very large)
|
||||
- error: Optimized for debugging failures - extracts error info, upstream context, and AI suggestions
|
||||
|
||||
**Error Mode Features:**
|
||||
- Extracts error message, type, and node configuration
|
||||
- Samples input data from upstream node (configurable limit)
|
||||
- Shows execution path leading to error
|
||||
- Provides AI-friendly fix suggestions based on error patterns
|
||||
- Token-efficient (80-90% smaller than full mode)`,
|
||||
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"' },
|
||||
mode: { type: 'string', required: false, description: 'For action=get: "preview", "summary" (default), "filtered", "full", "error"' },
|
||||
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)' },
|
||||
errorItemsLimit: { type: 'number', required: false, description: 'For action=get with mode=error: Sample items from upstream (default: 2, max: 100)' },
|
||||
includeStackTrace: { type: 'boolean', required: false, description: 'For action=get with mode=error: Include full stack trace (default: false, shows truncated)' },
|
||||
includeExecutionPath: { type: 'boolean', required: false, description: 'For action=get with mode=error: Include execution path (default: true)' },
|
||||
fetchWorkflow: { type: 'boolean', required: false, description: 'For action=get with mode=error: Fetch workflow for accurate upstream detection (default: true)' },
|
||||
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)' },
|
||||
@@ -41,10 +54,15 @@ export const n8nExecutionsDoc: ToolDocumentation = {
|
||||
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
|
||||
- get (error mode): { errorInfo: { primaryError, upstreamContext, executionPath, suggestions }, summary }
|
||||
- get (other modes): Execution object with data based on mode
|
||||
- list: { data: [...executions], nextCursor?: string }
|
||||
- delete: { success: boolean, message: string }`,
|
||||
examples: [
|
||||
'// Debug a failed execution (recommended for errors)\nn8n_executions({action: "get", id: "exec_456", mode: "error"})',
|
||||
'// Debug with more sample data from upstream\nn8n_executions({action: "get", id: "exec_456", mode: "error", errorItemsLimit: 5})',
|
||||
'// Debug with full stack trace\nn8n_executions({action: "get", id: "exec_456", mode: "error", includeStackTrace: true})',
|
||||
'// Debug without workflow fetch (faster but less accurate)\nn8n_executions({action: "get", id: "exec_456", mode: "error", fetchWorkflow: false})',
|
||||
'// 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"})',
|
||||
@@ -53,7 +71,10 @@ export const n8nExecutionsDoc: ToolDocumentation = {
|
||||
'// Delete an execution\nn8n_executions({action: "delete", id: "exec_456"})'
|
||||
],
|
||||
useCases: [
|
||||
'Debug workflow failures (get with mode=full)',
|
||||
'Debug workflow failures efficiently (mode=error) - 80-90% token savings',
|
||||
'Get AI suggestions for fixing common errors',
|
||||
'Analyze input data that caused failure',
|
||||
'Debug workflow failures with full data (mode=full)',
|
||||
'Monitor workflow health (list with status filter)',
|
||||
'Audit execution history',
|
||||
'Clean up old execution records',
|
||||
@@ -62,18 +83,22 @@ export const n8nExecutionsDoc: ToolDocumentation = {
|
||||
performance: `Response times:
|
||||
- list: 50-150ms depending on filters
|
||||
- get (preview/summary): 30-100ms
|
||||
- get (error): 50-200ms (includes optional workflow fetch)
|
||||
- get (full): 100-500ms+ depending on data size
|
||||
- delete: 30-80ms`,
|
||||
bestPractices: [
|
||||
'Use mode="summary" (default) for debugging - shows enough data',
|
||||
'Use mode="error" for debugging failed executions - 80-90% token savings vs full',
|
||||
'Use mode="summary" (default) for quick inspection',
|
||||
'Use mode="filtered" with nodeNames for large workflows',
|
||||
'Filter by workflowId when listing to reduce results',
|
||||
'Use cursor for pagination through large result sets',
|
||||
'Set fetchWorkflow=false if you already know the workflow structure',
|
||||
'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',
|
||||
'mode="error" fetches workflow by default (adds ~50-100ms), disable with fetchWorkflow=false',
|
||||
'Execution must exist or returns 404',
|
||||
'Delete is permanent - cannot undo'
|
||||
],
|
||||
|
||||
@@ -349,8 +349,8 @@ export const n8nManagementTools: ToolDefinition[] = [
|
||||
// For action='get' - detail level
|
||||
mode: {
|
||||
type: 'string',
|
||||
enum: ['preview', 'summary', 'filtered', 'full'],
|
||||
description: 'For action=get: preview=structure only, summary=2 items (default), filtered=custom, full=all data'
|
||||
enum: ['preview', 'summary', 'filtered', 'full', 'error'],
|
||||
description: 'For action=get: preview=structure only, summary=2 items (default), filtered=custom, full=all data, error=optimized error debugging'
|
||||
},
|
||||
nodeNames: {
|
||||
type: 'array',
|
||||
@@ -365,6 +365,23 @@ export const n8nManagementTools: ToolDefinition[] = [
|
||||
type: 'boolean',
|
||||
description: 'For action=get: include input data in addition to output (default: false)'
|
||||
},
|
||||
// Error mode specific parameters
|
||||
errorItemsLimit: {
|
||||
type: 'number',
|
||||
description: 'For action=get with mode=error: sample items from upstream node (default: 2, max: 100)'
|
||||
},
|
||||
includeStackTrace: {
|
||||
type: 'boolean',
|
||||
description: 'For action=get with mode=error: include full stack trace (default: false, shows truncated)'
|
||||
},
|
||||
includeExecutionPath: {
|
||||
type: 'boolean',
|
||||
description: 'For action=get with mode=error: include execution path leading to error (default: true)'
|
||||
},
|
||||
fetchWorkflow: {
|
||||
type: 'boolean',
|
||||
description: 'For action=get with mode=error: fetch workflow for accurate upstream detection (default: true)'
|
||||
},
|
||||
// For action='list'
|
||||
limit: {
|
||||
type: 'number',
|
||||
|
||||
Reference in New Issue
Block a user