feat: add intelligent execution data filtering to n8n_get_execution tool

Implements comprehensive execution data filtering system to enable AI agents
to inspect large workflow executions without exceeding token limits.

Features:
- Preview mode: Shows structure, counts, and size estimates (~500 tokens)
- Summary mode: Returns 2 sample items per node (~2-5K tokens)
- Filtered mode: Granular control with itemsLimit and nodeNames
- Full mode: Complete data retrieval (explicit opt-in)
- Smart recommendations based on data size analysis
- Structure-only mode (itemsLimit: 0) for schema inspection
- 100% backward compatibility with legacy includeData parameter

Technical improvements:
- New ExecutionProcessor service with intelligent filtering logic
- Type-safe implementation with Record<string, unknown> over any
- Comprehensive validation and error handling
- 33 unit tests with 78% coverage
- Constants-based thresholds for easy tuning

Bug fixes:
- Fixed preview mode API data fetching to enable structure analysis
- Validates and caps itemsLimit to prevent abuse

Impact:
- Reduces token usage by 80-95% for large datasets (50+ items)
- Prevents token overflow when inspecting workflow executions
- Enables recommended workflow: preview → recommendation → targeted fetch

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-09-30 23:44:19 +02:00
parent a1db133a50
commit ec0d2e8a6e
10 changed files with 1991 additions and 60 deletions

View File

@@ -344,17 +344,41 @@ export const n8nManagementTools: ToolDefinition[] = [
},
{
name: 'n8n_get_execution',
description: `Get details of a specific execution by ID.`,
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)`,
inputSchema: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Execution ID'
id: {
type: 'string',
description: 'Execution ID'
},
includeData: {
type: 'boolean',
description: 'Include full execution data (default: false)'
mode: {
type: 'string',
enum: ['preview', 'summary', 'filtered', 'full'],
description: 'Data retrieval mode: preview=structure only, summary=2 items, filtered=custom, full=all data'
},
nodeNames: {
type: 'array',
items: { type: 'string' },
description: 'Filter to specific nodes by name (for filtered mode)'
},
itemsLimit: {
type: 'number',
description: 'Items per node: 0=structure only, 2=default, -1=unlimited (for filtered mode)'
},
includeInputData: {
type: 'boolean',
description: 'Include input data in addition to output (default: false)'
},
includeData: {
type: 'boolean',
description: 'Legacy: Include execution data. Maps to mode=summary if true (deprecated, use mode instead)'
}
},
required: ['id']