Skip to content

Commit 130cf68

Browse files
alexk1919alexk1919
authored
Merge branch 'czlonkowski:main' into main
2 parents 6ed45f7 + 9050967 commit 130cf68

38 files changed

+7096
-169
lines changed

‎CHANGELOG.md‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,351 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [2.24.0] - 2025-01-24
11+
12+
### ✨ Features
13+
14+
**Unified Node Information Tool**
15+
16+
Introduced `get_node` - a unified tool that consolidates and enhances node information retrieval with multiple detail levels, version history, and type structure metadata.
17+
18+
#### What's New
19+
20+
**1. Progressive Detail Levels**
21+
- `minimal`: Basic metadata only (~200 tokens) - nodeType, displayName, description, category, version summary
22+
- `standard`: Essential properties and operations - AI-friendly default (~1000-2000 tokens)
23+
- `full`: Complete node information including all properties (~3000-8000 tokens)
24+
25+
**2. Version History & Management**
26+
- `versions` mode: List all versions with breaking changes summary
27+
- `compare` mode: Compare two versions with property-level changes
28+
- `breaking` mode: Show only breaking changes between versions
29+
- `migrations` mode: Show auto-migratable changes
30+
- Version summary always included in info mode responses
31+
32+
**3. Type Structure Metadata**
33+
- `includeTypeInfo` parameter exposes type structures from v2.23.0 validation system
34+
- Includes: type category, JS type, validation rules, structure hints
35+
- Helps AI agents understand complex types (filter, resourceMapper, resourceLocator, etc.)
36+
- Adds ~80-120 tokens per property when enabled
37+
- Works with all detail levels
38+
39+
**4. Real-World Examples**
40+
- `includeExamples` parameter includes configuration examples from templates
41+
- Shows popular workflow patterns
42+
- Includes metadata (views, complexity, use cases)
43+
44+
#### Usage Examples
45+
46+
```javascript
47+
// Standard detail (recommended for AI agents)
48+
get_node({nodeType: "nodes-base.httpRequest"})
49+
50+
// Standard with type info
51+
get_node({nodeType: "nodes-base.httpRequest", includeTypeInfo: true})
52+
53+
// Minimal (quick metadata check)
54+
get_node({nodeType: "nodes-base.httpRequest", detail: "minimal"})
55+
56+
// Full detail with examples
57+
get_node({nodeType: "nodes-base.httpRequest", detail: "full", includeExamples: true})
58+
59+
// Version history
60+
get_node({nodeType: "nodes-base.httpRequest", mode: "versions"})
61+
62+
// Compare versions
63+
get_node({
64+
nodeType: "nodes-base.httpRequest",
65+
mode: "compare",
66+
fromVersion: "3.0",
67+
toVersion: "4.1"
68+
})
69+
```
70+
71+
#### Benefits
72+
73+
- ✅ **Single Unified API**: One tool for all node information needs
74+
- ✅ **Token Efficient**: AI-friendly defaults (standard mode recommended)
75+
- ✅ **Progressive Disclosure**: minimal → standard → full as needed
76+
- ✅ **Type Aware**: Exposes v2.23.0 type structures for better configuration
77+
- ✅ **Version Aware**: Built-in version history and comparison
78+
- ✅ **Flexible**: Can combine detail levels with type info and examples
79+
- ✅ **Discoverable**: Version summary always visible in info mode
80+
81+
#### Token Costs
82+
83+
- `minimal`: ~200 tokens
84+
- `standard`: ~1000-2000 tokens (default)
85+
- `full`: ~3000-8000 tokens
86+
- `includeTypeInfo`: +80-120 tokens per property
87+
- `includeExamples`: +200-400 tokens per example
88+
- Version modes: ~400-1200 tokens
89+
90+
### 🗑️ Breaking Changes
91+
92+
**Removed Deprecated Tools**
93+
94+
Immediately removed `get_node_info` and `get_node_essentials` in favor of the unified `get_node` tool:
95+
- `get_node_info` → Use `get_node` with `detail='full'`
96+
- `get_node_essentials` → Use `get_node` with `detail='standard'` (default)
97+
98+
**Migration:**
99+
```javascript
100+
// Old
101+
get_node_info({nodeType: "nodes-base.httpRequest"})
102+
// New
103+
get_node({nodeType: "nodes-base.httpRequest", detail: "full"})
104+
105+
// Old
106+
get_node_essentials({nodeType: "nodes-base.httpRequest", includeExamples: true})
107+
// New
108+
get_node({nodeType: "nodes-base.httpRequest", includeExamples: true})
109+
// or
110+
get_node({nodeType: "nodes-base.httpRequest", detail: "standard", includeExamples: true})
111+
```
112+
113+
### 📊 Impact
114+
115+
**Tool Count**: 40 → 39 tools (-2 deprecated, +1 new unified)
116+
117+
**For AI Agents:**
118+
- Better understanding of complex n8n types through type metadata
119+
- Version upgrade planning with breaking change detection
120+
- Token-efficient defaults reduce costs
121+
- Progressive disclosure of information as needed
122+
123+
**For Users:**
124+
- Single tool to learn instead of two separate tools
125+
- Clear progression from minimal to full detail
126+
- Version history helps with node upgrades
127+
- Type-aware configuration assistance
128+
129+
### 🔧 Technical Details
130+
131+
**Files Added:**
132+
- Enhanced type structure exposure in node information
133+
134+
**Files Modified:**
135+
- `src/mcp/tools.ts` - Removed get_node_info and get_node_essentials, added get_node
136+
- `src/mcp/server.ts` - Added unified getNode() implementation with all modes
137+
- `package.json` - Version bump to 2.24.0
138+
139+
**Implementation:**
140+
- ~250 lines of new code
141+
- 7 new private methods for mode handling
142+
- Version repository methods utilized (previously unused)
143+
- TypeStructureService integrated for type metadata
144+
- 100% backward compatible in behavior (just different API)
145+
146+
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
147+
148+
## [2.23.0] - 2025-11-21
149+
150+
### ✨ Features
151+
152+
**Type Structure Validation System (Phases 1-4 Complete)**
153+
154+
Implemented comprehensive automatic validation system for complex n8n node configuration structures, ensuring workflows are correct before deployment.
155+
156+
#### Overview
157+
158+
Type Structure Validation is an automatic, zero-configuration validation system that validates complex node configurations (filter, resourceMapper, assignmentCollection, resourceLocator) during node validation. The system operates transparently - no special flags or configuration required.
159+
160+
#### Key Features
161+
162+
**1. Automatic Structure Validation**
163+
- Validates 4 special n8n types: filter, resourceMapper, assignmentCollection, resourceLocator
164+
- Zero configuration required - works automatically in all validation tools
165+
- Integrated in `validate_node_operation` and `validate_node_minimal` tools
166+
- 100% backward compatible - no breaking changes
167+
168+
**2. Comprehensive Type Coverage**
169+
- **filter** (FilterValue) - Complex filtering conditions with 40+ operations (equals, contains, regex, etc.)
170+
- **resourceMapper** (ResourceMapperValue) - Data mapping configuration for format transformation
171+
- **assignmentCollection** (AssignmentCollectionValue) - Variable assignments for setting multiple values
172+
- **resourceLocator** (INodeParameterResourceLocator) - Resource selection with multiple lookup modes (ID, name, URL)
173+
174+
**3. Production-Ready Performance**
175+
- **100% pass rate** on 776 real-world validations (91 templates, 616 nodes)
176+
- **0.01ms average** validation time (500x faster than 50ms target)
177+
- **0% false positive rate**
178+
- Tested against top n8n.io workflow templates
179+
180+
**4. Clear Error Messages**
181+
- Actionable error messages with property paths
182+
- Fix suggestions for common issues
183+
- Context-aware validation with node-specific logic
184+
- Educational feedback for AI agents
185+
186+
#### Implementation Phases
187+
188+
**Phase 1: Type Structure Definitions** ✅
189+
- 22 complete type structures defined in `src/constants/type-structures.ts` (741 lines)
190+
- Type definitions in `src/types/type-structures.ts` (301 lines)
191+
- Complete coverage of filter, resourceMapper, assignmentCollection, resourceLocator
192+
- TypeScript interfaces with validation schemas
193+
194+
**Phase 2: Validation Integration** ✅
195+
- Integrated in `EnhancedConfigValidator` service (427 lines)
196+
- Automatic validation in all MCP tools (validate_node_operation, validate_node_minimal)
197+
- Four validation profiles: minimal, runtime, ai-friendly, strict
198+
- Node-specific validation logic for edge cases
199+
200+
**Phase 3: Real-World Validation** ✅
201+
- 100% pass rate on 776 validations across 91 templates
202+
- 616 nodes tested from top n8n.io workflows
203+
- Type-specific results:
204+
- filter: 93/93 passed (100.00%)
205+
- resourceMapper: 69/69 passed (100.00%)
206+
- assignmentCollection: 213/213 passed (100.00%)
207+
- resourceLocator: 401/401 passed (100.00%)
208+
- Performance: 0.01ms average (500x better than target)
209+
210+
**Phase 4: Documentation & Polish** ✅
211+
- Comprehensive technical documentation (`docs/TYPE_STRUCTURE_VALIDATION.md`)
212+
- Updated internal documentation (CLAUDE.md)
213+
- Progressive discovery maintained (minimal tool documentation changes)
214+
- Production readiness checklist completed
215+
216+
#### Edge Cases Handled
217+
218+
**1. Credential-Provided Fields**
219+
- Fields like Google Sheets `sheetId` that come from credentials at runtime
220+
- No false positives for credential-populated fields
221+
222+
**2. Filter Operations**
223+
- Universal operations (exists, notExists, isNotEmpty) work across all data types
224+
- Type-specific operations validated (regex for strings, gt/lt for numbers)
225+
226+
**3. Node-Specific Logic**
227+
- Custom validation for specific nodes (Google Sheets, Slack, etc.)
228+
- Context-aware error messages based on node operation
229+
230+
#### Technical Details
231+
232+
**Files Added:**
233+
- `src/types/type-structures.ts` (301 lines) - Type definitions
234+
- `src/constants/type-structures.ts` (741 lines) - 22 complete type structures
235+
- `src/services/type-structure-service.ts` (427 lines) - Validation service
236+
- `docs/TYPE_STRUCTURE_VALIDATION.md` (239 lines) - Technical documentation
237+
238+
**Files Modified:**
239+
- `src/services/enhanced-config-validator.ts` - Integrated structure validation
240+
- `src/mcp/tools-documentation.ts` - Minimal progressive discovery notes
241+
- `CLAUDE.md` - Updated architecture and Phase 1-3 completion
242+
243+
**Test Coverage:**
244+
- `tests/unit/types/type-structures.test.ts` (14 tests)
245+
- `tests/unit/constants/type-structures.test.ts` (39 tests)
246+
- `tests/unit/services/type-structure-service.test.ts` (64 tests)
247+
- `tests/unit/services/enhanced-config-validator-type-structures.test.ts` (comprehensive)
248+
- `tests/integration/validation/real-world-structure-validation.test.ts` (8 tests, 388ms)
249+
- `scripts/test-structure-validation.ts` - Standalone validation script
250+
251+
#### Usage
252+
253+
No changes required - structure validation works automatically:
254+
255+
```javascript
256+
// Validation works automatically with structure validation
257+
validate_node_operation("nodes-base.if", {
258+
conditions: {
259+
combinator: "and",
260+
conditions: [{
261+
leftValue: "={{ $json.status }}",
262+
rightValue: "active",
263+
operator: { type: "string", operation: "equals" }
264+
}]
265+
}
266+
})
267+
268+
// Structure errors are caught and reported clearly
269+
// Invalid operation → Clear error with valid operations list
270+
// Missing required fields → Actionable fix suggestions
271+
```
272+
273+
#### Benefits
274+
275+
**For Users:**
276+
- ✅ Prevents configuration errors before deployment
277+
- ✅ Clear, actionable error messages
278+
- ✅ Faster workflow development with immediate feedback
279+
- ✅ Confidence in workflow correctness
280+
281+
**For AI Agents:**
282+
- ✅ Better understanding of complex n8n types
283+
- ✅ Self-correction based on clear error messages
284+
- ✅ Reduced validation errors and retry loops
285+
- ✅ Educational feedback for learning n8n patterns
286+
287+
**Technical:**
288+
- ✅ Zero breaking changes (100% backward compatible)
289+
- ✅ Automatic integration (no configuration needed)
290+
- ✅ High performance (0.01ms average)
291+
- ✅ Production-ready (100% pass rate on real workflows)
292+
293+
#### Documentation
294+
295+
**User Documentation:**
296+
- `docs/TYPE_STRUCTURE_VALIDATION.md` - Complete technical reference
297+
- Includes: Overview, supported types, performance metrics, examples, developer guide
298+
299+
**Internal Documentation:**
300+
- `CLAUDE.md` - Architecture updates and Phase 1-3 results
301+
- `src/mcp/tools-documentation.ts` - Progressive discovery notes
302+
303+
**Implementation Details:**
304+
- `docs/local/v3/implementation-plan-final.md` - Complete technical specifications
305+
- All 4 phases documented with success criteria and results
306+
307+
#### Version History
308+
309+
- **v2.23.0** (2025-11-21): Type structure validation system completed (Phases 1-4)
310+
- Phase 1: 22 complete type structures defined
311+
- Phase 2: Validation integrated in all MCP tools
312+
- Phase 3: 100% pass rate on 776 real-world validations
313+
- Phase 4: Documentation and polish completed
314+
- Zero false positives, 0.01ms average validation time
315+
316+
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
317+
318+
## [2.22.21] - 2025-11-20
319+
320+
### 🐛 Bug Fixes
321+
322+
**Fix Empty Settings Object Validation Error (#431)**
323+
324+
Fixed critical bug where `n8n_update_partial_workflow` tool failed with "request/body must NOT have additional properties" error when workflows had no settings or only non-whitelisted settings properties.
325+
326+
#### Root Cause
327+
- `cleanWorkflowForUpdate()` in `src/services/n8n-validation.ts` was sending empty `settings: {}` objects to the n8n API
328+
- n8n API rejects empty settings objects as "additional properties" violation
329+
- Issue occurred when:
330+
- Workflow had no settings property
331+
- Workflow had only non-whitelisted settings (e.g., only `callerPolicy`)
332+
333+
#### Changes
334+
- **Primary Fix**: Modified `cleanWorkflowForUpdate()` to delete `settings` property when empty after filtering
335+
- Instead of sending `settings: {}`, the property is now omitted entirely
336+
- Added safeguards in lines 193-199 and 201-204
337+
- **Secondary Fix**: Enhanced `applyUpdateSettings()` in `workflow-diff-engine.ts` to prevent creating empty settings objects
338+
- Only creates/updates settings if operation provides actual properties
339+
- **Test Updates**: Fixed 3 incorrect tests that expected empty settings objects
340+
- Updated to expect settings property to be omitted instead
341+
- Added 2 new comprehensive tests for edge cases
342+
343+
#### Testing
344+
- All 75 unit tests in `n8n-validation.test.ts` passing
345+
- New tests cover:
346+
- Workflows with no settings → omits property
347+
- Workflows with only non-whitelisted settings → omits property
348+
- Workflows with mixed settings → keeps only whitelisted properties
349+
350+
**Related Issues**: #431, #248 (n8n API design limitation)
351+
**Related n8n Issue**: n8n-io/n8n#19587 (closed as NOT_PLANNED - MCP server issue)
352+
353+
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
354+
10355
## [2.22.20] - 2025-11-19
11356

12357
### 🔄 Dependencies

‎CLAUDE.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,13 @@ src/
2828
│ ├── enhanced-config-validator.ts # Operation-aware validation (NEW in v2.4.2)
2929
│ ├── node-specific-validators.ts # Node-specific validation logic (NEW in v2.4.2)
3030
│ ├── property-dependencies.ts # Dependency analysis (NEW in v2.4)
31+
│ ├── type-structure-service.ts # Type structure validation (NEW in v2.22.21)
3132
│ ├── expression-validator.ts # n8n expression syntax validation (NEW in v2.5.0)
3233
│ └── workflow-validator.ts # Complete workflow validation (NEW in v2.5.0)
34+
├── types/
35+
│ └── type-structures.ts # Type structure definitions (NEW in v2.22.21)
36+
├── constants/
37+
│ └── type-structures.ts # 22 complete type structures (NEW in v2.22.21)
3338
├── templates/
3439
│ ├── template-fetcher.ts # Fetches templates from n8n.io API (NEW in v2.4.1)
3540
│ ├── template-repository.ts # Template database operations (NEW in v2.4.1)
@@ -40,6 +45,7 @@ src/
4045
│ ├── test-nodes.ts # Critical node tests
4146
│ ├── test-essentials.ts # Test new essentials tools (NEW in v2.4)
4247
│ ├── test-enhanced-validation.ts # Test enhanced validation (NEW in v2.4.2)
48+
│ ├── test-structure-validation.ts # Test type structure validation (NEW in v2.22.21)
4349
│ ├── test-workflow-validation.ts # Test workflow validation (NEW in v2.5.0)
4450
│ ├── test-ai-workflow-validation.ts # Test AI workflow validation (NEW in v2.5.1)
4551
│ ├── test-mcp-tools.ts # Test MCP tool enhancements (NEW in v2.5.1)
@@ -76,6 +82,7 @@ npm run test:unit # Run unit tests only
7682
npm run test:integration # Run integration tests
7783
npm run test:coverage # Run tests with coverage report
7884
npm run test:watch # Run tests in watch mode
85+
npm run test:structure-validation # Test type structure validation (Phase 3)
7986

8087
# Run a single test file
8188
npm test -- tests/unit/services/property-filter.test.ts
@@ -126,6 +133,7 @@ npm run test:templates # Test template functionality
126133
4. **Service Layer** (`services/`)
127134
- **Property Filter**: Reduces node properties to AI-friendly essentials
128135
- **Config Validator**: Multi-profile validation system
136+
- **Type Structure Service**: Validates complex type structures (filter, resourceMapper, etc.)
129137
- **Expression Validator**: Validates n8n expression syntax
130138
- **Workflow Validator**: Complete workflow structure validation
131139

0 commit comments

Comments
 (0)