mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-01-30 06:22:04 +00:00
chore: remove outdated documentation files
Remove outdated development documentation that is no longer relevant: - Phase 1-2 summaries and test scenarios - Testing strategy documents - Validation improvement notes - Release notes and PR summaries docs/local/ is already gitignored for local development notes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
@@ -1,62 +0,0 @@
|
||||
# PR #104 Test Suite Improvements Summary
|
||||
|
||||
## Overview
|
||||
Based on comprehensive review feedback from PR #104, we've significantly improved the test suite quality, organization, and coverage.
|
||||
|
||||
## Test Results
|
||||
- **Before:** 78 failing tests
|
||||
- **After:** 0 failing tests (1,356 passed, 19 skipped)
|
||||
- **Coverage:** 85.34% statements, 85.3% branches
|
||||
|
||||
## Key Improvements
|
||||
|
||||
### 1. Fixed All Test Failures
|
||||
- Fixed logger test spy issues by properly handling DEBUG environment variable
|
||||
- Fixed MSW configuration test by restoring environment variables
|
||||
- Fixed workflow validator tests by adding proper node connections
|
||||
- Fixed mock setup issues in edge case tests
|
||||
|
||||
### 2. Improved Test Organization
|
||||
- Split large config-validator.test.ts (1,075 lines) into 4 focused files:
|
||||
- config-validator-basic.test.ts
|
||||
- config-validator-node-specific.test.ts
|
||||
- config-validator-security.test.ts
|
||||
- config-validator-edge-cases.test.ts
|
||||
|
||||
### 3. Enhanced Test Coverage
|
||||
- Added comprehensive edge case tests for all major validators
|
||||
- Added null/undefined handling tests
|
||||
- Added boundary value tests
|
||||
- Added performance tests with CI-aware timeouts
|
||||
- Added security validation tests
|
||||
|
||||
### 4. Improved Test Quality
|
||||
- Fixed test naming conventions (100% compliance with "should X when Y" pattern)
|
||||
- Added JSDoc comments to test utilities and factories
|
||||
- Created comprehensive test documentation (tests/README.md)
|
||||
- Improved test isolation to prevent cross-test pollution
|
||||
|
||||
### 5. New Features
|
||||
- Implemented validateBatch method for ConfigValidator
|
||||
- Added test factories for better test data management
|
||||
- Created test utilities for common scenarios
|
||||
|
||||
## Files Modified
|
||||
- 7 existing test files fixed
|
||||
- 8 new test files created
|
||||
- 1 source file enhanced (ConfigValidator)
|
||||
- 4 debug files removed before commit
|
||||
|
||||
## Skipped Tests
|
||||
19 tests remain skipped with documented reasons:
|
||||
- FTS5 search sync test (database corruption in CI)
|
||||
- Template clearing (not implemented)
|
||||
- Mock API configuration tests
|
||||
- Duplicate edge case tests with mocking issues (working versions exist)
|
||||
|
||||
## Next Steps
|
||||
The only remaining task from the improvement plan is:
|
||||
- Add performance regression tests and boundaries (low priority, future sprint)
|
||||
|
||||
## Conclusion
|
||||
The test suite is now robust, well-organized, and provides excellent coverage. All critical issues have been resolved, and the codebase is ready for merge.
|
||||
@@ -1,314 +0,0 @@
|
||||
# Template Metadata Generation
|
||||
|
||||
This document describes the template metadata generation system introduced in n8n-MCP v2.10.0, which uses OpenAI's batch API to automatically analyze and categorize workflow templates.
|
||||
|
||||
## Overview
|
||||
|
||||
The template metadata system analyzes n8n workflow templates to extract structured information about their purpose, complexity, requirements, and target audience. This enables intelligent template discovery through advanced filtering capabilities.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
1. **MetadataGenerator** (`src/templates/metadata-generator.ts`)
|
||||
- Interfaces with OpenAI API
|
||||
- Generates structured metadata using JSON schemas
|
||||
- Provides fallback defaults for error cases
|
||||
|
||||
2. **BatchProcessor** (`src/templates/batch-processor.ts`)
|
||||
- Manages OpenAI batch API operations
|
||||
- Handles parallel batch submission
|
||||
- Monitors batch status and retrieves results
|
||||
|
||||
3. **Template Repository** (`src/templates/template-repository.ts`)
|
||||
- Stores metadata in SQLite database
|
||||
- Provides advanced search capabilities
|
||||
- Supports JSON extraction queries
|
||||
|
||||
## Metadata Schema
|
||||
|
||||
Each template's metadata contains:
|
||||
|
||||
```typescript
|
||||
{
|
||||
categories: string[] // Max 5 categories (e.g., "automation", "integration")
|
||||
complexity: "simple" | "medium" | "complex"
|
||||
use_cases: string[] // Max 5 primary use cases
|
||||
estimated_setup_minutes: number // 5-480 minutes
|
||||
required_services: string[] // External services needed
|
||||
key_features: string[] // Max 5 main capabilities
|
||||
target_audience: string[] // Max 3 target user types
|
||||
}
|
||||
```
|
||||
|
||||
## Generation Process
|
||||
|
||||
### 1. Initial Setup
|
||||
|
||||
```bash
|
||||
# Set OpenAI API key in .env
|
||||
OPENAI_API_KEY=your-api-key-here
|
||||
```
|
||||
|
||||
### 2. Generate Metadata for Existing Templates
|
||||
|
||||
```bash
|
||||
# Generate metadata only (no template fetching)
|
||||
npm run fetch:templates -- --metadata-only
|
||||
|
||||
# Generate metadata during update
|
||||
npm run fetch:templates -- --mode=update --generate-metadata
|
||||
```
|
||||
|
||||
### 3. Batch Processing
|
||||
|
||||
The system uses OpenAI's batch API for cost-effective processing:
|
||||
|
||||
- **50% cost reduction** compared to synchronous API calls
|
||||
- **24-hour processing window** for batch completion
|
||||
- **Parallel batch submission** for faster processing
|
||||
- **Automatic retry** for failed items
|
||||
|
||||
### Configuration Options
|
||||
|
||||
Environment variables:
|
||||
- `OPENAI_API_KEY`: Required for metadata generation
|
||||
- `OPENAI_MODEL`: Model to use (default: "gpt-4o-mini")
|
||||
- `OPENAI_BATCH_SIZE`: Templates per batch (default: 100, max: 500)
|
||||
- `METADATA_LIMIT`: Limit templates to process (for testing)
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Template Analysis
|
||||
|
||||
For each template, the generator analyzes:
|
||||
- Template name and description
|
||||
- Node types and their frequency
|
||||
- Workflow structure and connections
|
||||
- Overall complexity
|
||||
|
||||
### 2. Node Summarization
|
||||
|
||||
Nodes are grouped into categories:
|
||||
- HTTP/Webhooks
|
||||
- Database operations
|
||||
- Communication (Slack, Email)
|
||||
- AI/ML operations
|
||||
- Spreadsheets
|
||||
- Service-specific nodes
|
||||
|
||||
### 3. Metadata Generation
|
||||
|
||||
The AI model receives:
|
||||
```
|
||||
Template: [name]
|
||||
Description: [description]
|
||||
Nodes Used (X): [summarized node list]
|
||||
Workflow has X nodes with Y connections
|
||||
```
|
||||
|
||||
And generates structured metadata following the JSON schema.
|
||||
|
||||
### 4. Storage and Indexing
|
||||
|
||||
Metadata is stored as JSON in SQLite and indexed for fast querying:
|
||||
|
||||
```sql
|
||||
-- Example query for simple automation templates
|
||||
SELECT * FROM templates
|
||||
WHERE json_extract(metadata, '$.complexity') = 'simple'
|
||||
AND json_extract(metadata, '$.categories') LIKE '%automation%'
|
||||
```
|
||||
|
||||
## MCP Tool Integration
|
||||
|
||||
### search_templates_by_metadata
|
||||
|
||||
Advanced filtering tool with multiple parameters:
|
||||
|
||||
```typescript
|
||||
search_templates_by_metadata({
|
||||
category: "automation", // Filter by category
|
||||
complexity: "simple", // Skill level
|
||||
maxSetupMinutes: 30, // Time constraint
|
||||
targetAudience: "marketers", // Role-based
|
||||
requiredService: "slack" // Service dependency
|
||||
})
|
||||
```
|
||||
|
||||
### list_templates
|
||||
|
||||
Enhanced to include metadata:
|
||||
|
||||
```typescript
|
||||
list_templates({
|
||||
includeMetadata: true, // Include full metadata
|
||||
limit: 20,
|
||||
offset: 0
|
||||
})
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Finding Beginner-Friendly Templates
|
||||
|
||||
```typescript
|
||||
const templates = await search_templates_by_metadata({
|
||||
complexity: "simple",
|
||||
maxSetupMinutes: 15
|
||||
});
|
||||
```
|
||||
|
||||
### Role-Specific Templates
|
||||
|
||||
```typescript
|
||||
const marketingTemplates = await search_templates_by_metadata({
|
||||
targetAudience: "marketers",
|
||||
category: "communication"
|
||||
});
|
||||
```
|
||||
|
||||
### Service Integration Templates
|
||||
|
||||
```typescript
|
||||
const openaiTemplates = await search_templates_by_metadata({
|
||||
requiredService: "openai",
|
||||
complexity: "medium"
|
||||
});
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
- **Coverage**: 97.5% of templates have metadata (2,534/2,598)
|
||||
- **Generation Time**: ~2-4 hours for full database (using batch API)
|
||||
- **Query Performance**: <100ms for metadata searches
|
||||
- **Storage Overhead**: ~2MB additional database size
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Batch Processing Stuck**
|
||||
- Check batch status: The API provides status updates
|
||||
- Batches auto-expire after 24 hours
|
||||
- Monitor using the batch ID in logs
|
||||
|
||||
2. **Missing Metadata**
|
||||
- ~2.5% of templates may fail metadata generation
|
||||
- Fallback defaults are provided
|
||||
- Can regenerate with `--metadata-only` flag
|
||||
|
||||
3. **API Rate Limits**
|
||||
- Batch API has generous limits (50,000 requests/batch)
|
||||
- Cost is 50% of synchronous API
|
||||
- Processing happens within 24-hour window
|
||||
|
||||
### Monitoring Batch Status
|
||||
|
||||
```bash
|
||||
# Check current batch status (if logged)
|
||||
curl https://api.openai.com/v1/batches/[batch-id] \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
## Cost Analysis
|
||||
|
||||
### Batch API Pricing (gpt-4o-mini)
|
||||
|
||||
- Input: $0.075 per 1M tokens (50% of standard)
|
||||
- Output: $0.30 per 1M tokens (50% of standard)
|
||||
- Average template: ~300 input tokens, ~200 output tokens
|
||||
- Total cost for 2,500 templates: ~$0.50
|
||||
|
||||
### Comparison with Synchronous API
|
||||
|
||||
- Synchronous cost: ~$1.00 for same volume
|
||||
- Time saved: Parallel processing vs sequential
|
||||
- Reliability: Automatic retries included
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
|
||||
1. **Incremental Updates**
|
||||
- Only generate metadata for new templates
|
||||
- Track metadata version for updates
|
||||
|
||||
2. **Enhanced Analysis**
|
||||
- Workflow complexity scoring
|
||||
- Dependency graph analysis
|
||||
- Performance impact estimates
|
||||
|
||||
3. **User Feedback Loop**
|
||||
- Collect accuracy feedback
|
||||
- Refine categorization over time
|
||||
- Community-driven corrections
|
||||
|
||||
4. **Alternative Models**
|
||||
- Support for local LLMs
|
||||
- Claude API integration
|
||||
- Configurable model selection
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Database Schema
|
||||
|
||||
```sql
|
||||
-- Metadata stored as JSON column
|
||||
ALTER TABLE templates ADD COLUMN metadata TEXT;
|
||||
|
||||
-- Indexes for common queries
|
||||
CREATE INDEX idx_templates_complexity ON templates(
|
||||
json_extract(metadata, '$.complexity')
|
||||
);
|
||||
CREATE INDEX idx_templates_setup_time ON templates(
|
||||
json_extract(metadata, '$.estimated_setup_minutes')
|
||||
);
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
The system provides robust error handling:
|
||||
|
||||
1. **API Failures**: Fallback to default metadata
|
||||
2. **Parsing Errors**: Logged with template ID
|
||||
3. **Batch Failures**: Individual item retry
|
||||
4. **Validation Errors**: Zod schema enforcement
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regenerating Metadata
|
||||
|
||||
```bash
|
||||
# Full regeneration (caution: costs ~$0.50)
|
||||
npm run fetch:templates -- --mode=rebuild --generate-metadata
|
||||
|
||||
# Partial regeneration (templates without metadata)
|
||||
npm run fetch:templates -- --metadata-only
|
||||
```
|
||||
|
||||
### Database Backup
|
||||
|
||||
```bash
|
||||
# Backup before regeneration
|
||||
cp data/nodes.db data/nodes.db.backup
|
||||
|
||||
# Restore if needed
|
||||
cp data/nodes.db.backup data/nodes.db
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **API Key Management**
|
||||
- Store in `.env` file (gitignored)
|
||||
- Never commit API keys
|
||||
- Use environment variables in CI/CD
|
||||
|
||||
2. **Data Privacy**
|
||||
- Only template structure is sent to API
|
||||
- No user data or credentials included
|
||||
- Processing happens in OpenAI's secure environment
|
||||
|
||||
## Conclusion
|
||||
|
||||
The template metadata system transforms template discovery from simple text search to intelligent, multi-dimensional filtering. By leveraging OpenAI's batch API, we achieve cost-effective, scalable metadata generation that significantly improves the user experience for finding relevant workflow templates.
|
||||
@@ -1,162 +0,0 @@
|
||||
# Issue #90: "propertyValues[itemName] is not iterable" Error - Research Findings
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The error "propertyValues[itemName] is not iterable" occurs when AI agents create workflows with incorrect data structures for n8n nodes that use `fixedCollection` properties. This primarily affects Switch Node v2, If Node, and Filter Node. The error prevents workflows from loading in the n8n UI, resulting in empty canvases.
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
### 1. Data Structure Mismatch
|
||||
|
||||
The error occurs when n8n's validation engine expects an iterable array but encounters a non-iterable object. This happens with nodes using `fixedCollection` type properties.
|
||||
|
||||
**Incorrect Structure (causes error):**
|
||||
```json
|
||||
{
|
||||
"rules": {
|
||||
"conditions": {
|
||||
"values": [
|
||||
{
|
||||
"value1": "={{$json.status}}",
|
||||
"operation": "equals",
|
||||
"value2": "active"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Correct Structure:**
|
||||
```json
|
||||
{
|
||||
"rules": {
|
||||
"conditions": [
|
||||
{
|
||||
"value1": "={{$json.status}}",
|
||||
"operation": "equals",
|
||||
"value2": "active"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Affected Nodes
|
||||
|
||||
Based on the research and issue comments, the following nodes are affected:
|
||||
|
||||
1. **Switch Node v2** (`n8n-nodes-base.switch` with typeVersion: 2)
|
||||
- Uses `rules` parameter with `conditions` fixedCollection
|
||||
- v3 doesn't have this issue due to restructured schema
|
||||
|
||||
2. **If Node** (`n8n-nodes-base.if` with typeVersion: 1)
|
||||
- Uses `conditions` parameter with nested conditions array
|
||||
- Similar structure to Switch v2
|
||||
|
||||
3. **Filter Node** (`n8n-nodes-base.filter`)
|
||||
- Uses `conditions` parameter
|
||||
- Same fixedCollection pattern
|
||||
|
||||
### 3. Why AI Agents Create Incorrect Structures
|
||||
|
||||
1. **Training Data Issues**: AI models may have been trained on outdated or incorrect n8n workflow examples
|
||||
2. **Nested Object Inference**: AI tends to create unnecessarily nested structures when it sees collection-type parameters
|
||||
3. **Legacy Format Confusion**: Mixing v2 and v3 Switch node formats
|
||||
4. **Schema Misinterpretation**: The term "fixedCollection" may lead AI to create object wrappers
|
||||
|
||||
## Current Impact
|
||||
|
||||
From issue #90 comments:
|
||||
- Multiple users experiencing the issue
|
||||
- Workflows fail to load completely (empty canvas)
|
||||
- Users resort to using Switch Node v3 or direct API calls
|
||||
- The issue appears in "most MCPs" according to user feedback
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
### 1. Immediate Validation Enhancement
|
||||
|
||||
Add specific validation for fixedCollection properties in the workflow validator:
|
||||
|
||||
```typescript
|
||||
// In workflow-validator.ts or enhanced-config-validator.ts
|
||||
function validateFixedCollectionParameters(node, result) {
|
||||
const problematicNodes = {
|
||||
'n8n-nodes-base.switch': { version: 2, fields: ['rules'] },
|
||||
'n8n-nodes-base.if': { version: 1, fields: ['conditions'] },
|
||||
'n8n-nodes-base.filter': { version: 1, fields: ['conditions'] }
|
||||
};
|
||||
|
||||
const nodeConfig = problematicNodes[node.type];
|
||||
if (nodeConfig && node.typeVersion === nodeConfig.version) {
|
||||
// Validate structure
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Enhanced MCP Tool Validation
|
||||
|
||||
Update the validation tools to detect and prevent this specific error pattern:
|
||||
|
||||
1. **In `validate_node_operation` tool**: Add checks for fixedCollection structures
|
||||
2. **In `validate_workflow` tool**: Include specific validation for Switch/If nodes
|
||||
3. **In `n8n_create_workflow` tool**: Pre-validate parameters before submission
|
||||
|
||||
### 3. AI-Friendly Examples
|
||||
|
||||
Update workflow examples to show correct structures:
|
||||
|
||||
```typescript
|
||||
// In workflow-examples.ts
|
||||
export const SWITCH_NODE_EXAMPLE = {
|
||||
name: "Switch",
|
||||
type: "n8n-nodes-base.switch",
|
||||
typeVersion: 3, // Prefer v3 over v2
|
||||
parameters: {
|
||||
// Correct v3 structure
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 4. Migration Strategy
|
||||
|
||||
For existing workflows with Switch v2:
|
||||
1. Detect Switch v2 nodes in validation
|
||||
2. Suggest migration to v3
|
||||
3. Provide automatic conversion utility
|
||||
|
||||
### 5. Documentation Updates
|
||||
|
||||
1. Add warnings about fixedCollection structures in tool documentation
|
||||
2. Include specific examples of correct vs incorrect structures
|
||||
3. Document the Switch v2 to v3 migration path
|
||||
|
||||
## Proposed Implementation Priority
|
||||
|
||||
1. **High Priority**: Add validation to prevent creation of invalid structures
|
||||
2. **High Priority**: Update existing validation tools to catch this error
|
||||
3. **Medium Priority**: Add auto-fix capabilities to correct structures
|
||||
4. **Medium Priority**: Update examples and documentation
|
||||
5. **Low Priority**: Create migration utilities for v2 to v3
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
1. Create test cases for each affected node type
|
||||
2. Test both correct and incorrect structures
|
||||
3. Verify validation catches all variants of the error
|
||||
4. Test auto-fix suggestions work correctly
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- Zero instances of "propertyValues[itemName] is not iterable" in newly created workflows
|
||||
- Clear error messages that guide users to correct structures
|
||||
- Successful validation of all Switch/If node configurations before workflow creation
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Implement validation enhancements in the workflow validator
|
||||
2. Update MCP tools to include these validations
|
||||
3. Add comprehensive tests
|
||||
4. Update documentation with clear examples
|
||||
5. Consider adding a migration tool for existing workflows
|
||||
@@ -1,712 +0,0 @@
|
||||
# MCP Tools Documentation for LLMs
|
||||
|
||||
This document provides comprehensive documentation for the most commonly used MCP tools in the n8n-mcp server. Each tool includes parameters, return formats, examples, and best practices.
|
||||
|
||||
## Table of Contents
|
||||
1. [search_nodes](#search_nodes)
|
||||
2. [get_node_essentials](#get_node_essentials)
|
||||
3. [list_nodes](#list_nodes)
|
||||
4. [validate_node_minimal](#validate_node_minimal)
|
||||
5. [validate_node_operation](#validate_node_operation)
|
||||
6. [get_node_for_task](#get_node_for_task)
|
||||
7. [n8n_create_workflow](#n8n_create_workflow)
|
||||
8. [n8n_update_partial_workflow](#n8n_update_partial_workflow)
|
||||
|
||||
---
|
||||
|
||||
## search_nodes
|
||||
|
||||
**Brief Description**: Search for n8n nodes by keywords in names and descriptions.
|
||||
|
||||
### Parameters
|
||||
- `query` (string, required): Search term - single word recommended for best results
|
||||
- `limit` (number, optional): Maximum results to return (default: 20)
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"nodeType": "nodes-base.slack",
|
||||
"displayName": "Slack",
|
||||
"description": "Send messages to Slack channels"
|
||||
}
|
||||
],
|
||||
"totalFound": 5
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Finding integration nodes**: `search_nodes("slack")` to find Slack integration
|
||||
2. **Finding HTTP nodes**: `search_nodes("http")` for HTTP/webhook nodes
|
||||
3. **Finding database nodes**: `search_nodes("postgres")` for PostgreSQL nodes
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Search for Slack-related nodes
|
||||
{
|
||||
"query": "slack",
|
||||
"limit": 10
|
||||
}
|
||||
|
||||
// Search for webhook nodes
|
||||
{
|
||||
"query": "webhook",
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Fast operation (cached results)
|
||||
- Single-word queries are more precise
|
||||
- Returns results with OR logic (any word matches)
|
||||
|
||||
### Best Practices
|
||||
- Use single words for precise results: "slack" not "send slack message"
|
||||
- Try shorter terms if no results: "sheet" instead of "spreadsheet"
|
||||
- Search is case-insensitive
|
||||
- Common searches: "http", "webhook", "email", "database", "slack"
|
||||
|
||||
### Common Pitfalls
|
||||
- Multi-word searches return too many results (OR logic)
|
||||
- Searching for exact phrases doesn't work
|
||||
- Node types aren't searchable here (use exact type with get_node_info)
|
||||
|
||||
### Related Tools
|
||||
- `list_nodes` - Browse nodes by category
|
||||
- `get_node_essentials` - Get node configuration after finding it
|
||||
- `list_ai_tools` - Find AI-capable nodes specifically
|
||||
|
||||
---
|
||||
|
||||
## get_node_essentials
|
||||
|
||||
**Brief Description**: Get only the 10-20 most important properties for a node with working examples.
|
||||
|
||||
### Parameters
|
||||
- `nodeType` (string, required): Full node type with prefix (e.g., "nodes-base.httpRequest")
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"nodeType": "nodes-base.httpRequest",
|
||||
"displayName": "HTTP Request",
|
||||
"essentialProperties": [
|
||||
{
|
||||
"name": "method",
|
||||
"type": "options",
|
||||
"default": "GET",
|
||||
"options": ["GET", "POST", "PUT", "DELETE"],
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "url",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"placeholder": "https://api.example.com/endpoint"
|
||||
}
|
||||
],
|
||||
"examples": [
|
||||
{
|
||||
"name": "Simple GET Request",
|
||||
"configuration": {
|
||||
"method": "GET",
|
||||
"url": "https://api.example.com/users"
|
||||
}
|
||||
}
|
||||
],
|
||||
"tips": [
|
||||
"Use expressions like {{$json.url}} to make URLs dynamic",
|
||||
"Enable 'Split Into Items' for array responses"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Quick node configuration**: Get just what you need without parsing 100KB+ of data
|
||||
2. **Learning node basics**: Understand essential properties with examples
|
||||
3. **Building workflows efficiently**: 95% smaller responses than get_node_info
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Get essentials for HTTP Request node
|
||||
{
|
||||
"nodeType": "nodes-base.httpRequest"
|
||||
}
|
||||
|
||||
// Get essentials for Slack node
|
||||
{
|
||||
"nodeType": "nodes-base.slack"
|
||||
}
|
||||
|
||||
// Get essentials for OpenAI node
|
||||
{
|
||||
"nodeType": "nodes-langchain.openAi"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Very fast (<5KB responses vs 100KB+ for full info)
|
||||
- Curated for 20+ common nodes
|
||||
- Automatic fallback for unconfigured nodes
|
||||
|
||||
### Best Practices
|
||||
- Always use this before get_node_info
|
||||
- Node type must include prefix: "nodes-base.slack" not "slack"
|
||||
- Check examples section for working configurations
|
||||
- Use tips section for common patterns
|
||||
|
||||
### Common Pitfalls
|
||||
- Forgetting the prefix in node type
|
||||
- Using wrong package name (n8n-nodes-base vs @n8n/n8n-nodes-langchain)
|
||||
- Case sensitivity in node types
|
||||
|
||||
### Related Tools
|
||||
- `get_node_info` - Full schema when essentials aren't enough
|
||||
- `search_node_properties` - Find specific properties
|
||||
- `get_node_for_task` - Pre-configured for common tasks
|
||||
|
||||
---
|
||||
|
||||
## list_nodes
|
||||
|
||||
**Brief Description**: List available n8n nodes with optional filtering by package, category, or capabilities.
|
||||
|
||||
### Parameters
|
||||
- `package` (string, optional): Filter by exact package name
|
||||
- `category` (string, optional): Filter by category (trigger, transform, output, input)
|
||||
- `developmentStyle` (string, optional): Filter by implementation style
|
||||
- `isAITool` (boolean, optional): Filter for AI-capable nodes
|
||||
- `limit` (number, optional): Maximum results (default: 50, max: 500)
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"nodeType": "nodes-base.webhook",
|
||||
"displayName": "Webhook",
|
||||
"description": "Receive HTTP requests",
|
||||
"categories": ["trigger"],
|
||||
"version": 2
|
||||
}
|
||||
],
|
||||
"total": 104,
|
||||
"hasMore": false
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Browse all triggers**: `list_nodes({category: "trigger", limit: 200})`
|
||||
2. **List all nodes**: `list_nodes({limit: 500})`
|
||||
3. **Find AI nodes**: `list_nodes({isAITool: true})`
|
||||
4. **Browse core nodes**: `list_nodes({package: "n8n-nodes-base"})`
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// List all trigger nodes
|
||||
{
|
||||
"category": "trigger",
|
||||
"limit": 200
|
||||
}
|
||||
|
||||
// List all AI-capable nodes
|
||||
{
|
||||
"isAITool": true,
|
||||
"limit": 100
|
||||
}
|
||||
|
||||
// List nodes from core package
|
||||
{
|
||||
"package": "n8n-nodes-base",
|
||||
"limit": 200
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Fast operation (cached results)
|
||||
- Default limit of 50 may miss nodes - use 200+
|
||||
- Returns metadata only, not full schemas
|
||||
|
||||
### Best Practices
|
||||
- Always set limit to 200+ for complete results
|
||||
- Use exact package names: "n8n-nodes-base" not "@n8n/n8n-nodes-base"
|
||||
- Categories are singular: "trigger" not "triggers"
|
||||
- Common categories: trigger (104), transform, output, input
|
||||
|
||||
### Common Pitfalls
|
||||
- Default limit (50) misses many nodes
|
||||
- Using wrong package name format
|
||||
- Multiple filters may return empty results
|
||||
|
||||
### Related Tools
|
||||
- `search_nodes` - Search by keywords
|
||||
- `list_ai_tools` - Specifically for AI nodes
|
||||
- `get_database_statistics` - Overview of all nodes
|
||||
|
||||
---
|
||||
|
||||
## validate_node_minimal
|
||||
|
||||
**Brief Description**: Quick validation checking only for missing required fields.
|
||||
|
||||
### Parameters
|
||||
- `nodeType` (string, required): Node type to validate (e.g., "nodes-base.slack")
|
||||
- `config` (object, required): Node configuration to check
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"missingRequired": ["channel", "messageType"],
|
||||
"message": "Missing 2 required fields"
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Quick validation**: Check if all required fields are present
|
||||
2. **Pre-flight check**: Validate before creating workflow
|
||||
3. **Minimal overhead**: Fastest validation option
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Validate Slack message configuration
|
||||
{
|
||||
"nodeType": "nodes-base.slack",
|
||||
"config": {
|
||||
"resource": "message",
|
||||
"operation": "send",
|
||||
"text": "Hello World"
|
||||
// Missing: channel
|
||||
}
|
||||
}
|
||||
|
||||
// Validate HTTP Request
|
||||
{
|
||||
"nodeType": "nodes-base.httpRequest",
|
||||
"config": {
|
||||
"method": "POST"
|
||||
// Missing: url
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Fastest validation option
|
||||
- No schema loading overhead
|
||||
- Returns only missing fields
|
||||
|
||||
### Best Practices
|
||||
- Use for quick checks during workflow building
|
||||
- Follow up with validate_node_operation for complex nodes
|
||||
- Check operation-specific requirements
|
||||
|
||||
### Common Pitfalls
|
||||
- Doesn't validate field values or types
|
||||
- Doesn't check operation-specific requirements
|
||||
- Won't catch configuration errors beyond missing fields
|
||||
|
||||
### Related Tools
|
||||
- `validate_node_operation` - Comprehensive validation
|
||||
- `validate_workflow` - Full workflow validation
|
||||
|
||||
---
|
||||
|
||||
## validate_node_operation
|
||||
|
||||
**Brief Description**: Comprehensive node configuration validation with operation awareness and helpful error messages.
|
||||
|
||||
### Parameters
|
||||
- `nodeType` (string, required): Node type to validate
|
||||
- `config` (object, required): Complete node configuration including operation fields
|
||||
- `profile` (string, optional): Validation profile (minimal, runtime, ai-friendly, strict)
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"valid": false,
|
||||
"errors": [
|
||||
{
|
||||
"field": "channel",
|
||||
"message": "Channel is required to send Slack message",
|
||||
"suggestion": "Add channel: '#general' or '@username'"
|
||||
}
|
||||
],
|
||||
"warnings": [
|
||||
{
|
||||
"field": "unfurl_links",
|
||||
"message": "Consider setting unfurl_links: false for better performance"
|
||||
}
|
||||
],
|
||||
"examples": {
|
||||
"minimal": {
|
||||
"resource": "message",
|
||||
"operation": "send",
|
||||
"channel": "#general",
|
||||
"text": "Hello World"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Complex node validation**: Slack, Google Sheets, databases
|
||||
2. **Operation-specific checks**: Different rules per operation
|
||||
3. **Getting fix suggestions**: Helpful error messages with solutions
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Validate Slack configuration
|
||||
{
|
||||
"nodeType": "nodes-base.slack",
|
||||
"config": {
|
||||
"resource": "message",
|
||||
"operation": "send",
|
||||
"text": "Hello team!"
|
||||
},
|
||||
"profile": "ai-friendly"
|
||||
}
|
||||
|
||||
// Validate Google Sheets operation
|
||||
{
|
||||
"nodeType": "nodes-base.googleSheets",
|
||||
"config": {
|
||||
"operation": "append",
|
||||
"sheetId": "1234567890",
|
||||
"range": "Sheet1!A:Z"
|
||||
},
|
||||
"profile": "runtime"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Slower than minimal validation
|
||||
- Loads full node schema
|
||||
- Operation-aware validation rules
|
||||
|
||||
### Best Practices
|
||||
- Use "ai-friendly" profile for balanced validation
|
||||
- Check examples in response for working configurations
|
||||
- Follow suggestions to fix errors
|
||||
- Essential for complex nodes (Slack, databases, APIs)
|
||||
|
||||
### Common Pitfalls
|
||||
- Forgetting operation fields (resource, operation, action)
|
||||
- Using wrong profile (too strict or too lenient)
|
||||
- Ignoring warnings that could cause runtime issues
|
||||
|
||||
### Related Tools
|
||||
- `validate_node_minimal` - Quick required field check
|
||||
- `get_property_dependencies` - Understand field relationships
|
||||
- `validate_workflow` - Validate entire workflow
|
||||
|
||||
---
|
||||
|
||||
## get_node_for_task
|
||||
|
||||
**Brief Description**: Get pre-configured node settings for common automation tasks.
|
||||
|
||||
### Parameters
|
||||
- `task` (string, required): Task identifier (e.g., "post_json_request", "receive_webhook")
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"task": "post_json_request",
|
||||
"nodeType": "nodes-base.httpRequest",
|
||||
"displayName": "HTTP Request",
|
||||
"configuration": {
|
||||
"method": "POST",
|
||||
"url": "={{ $json.api_endpoint }}",
|
||||
"responseFormat": "json",
|
||||
"options": {
|
||||
"bodyContentType": "json"
|
||||
},
|
||||
"bodyParametersJson": "={{ JSON.stringify($json) }}"
|
||||
},
|
||||
"userMustProvide": [
|
||||
"url - The API endpoint URL",
|
||||
"bodyParametersJson - The JSON data to send"
|
||||
],
|
||||
"tips": [
|
||||
"Use expressions to make values dynamic",
|
||||
"Enable 'Split Into Items' for batch processing"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Quick task setup**: Configure nodes for specific tasks instantly
|
||||
2. **Learning patterns**: See how to configure nodes properly
|
||||
3. **Common workflows**: Standard patterns like webhooks, API calls, database queries
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Get configuration for JSON POST request
|
||||
{
|
||||
"task": "post_json_request"
|
||||
}
|
||||
|
||||
// Get webhook receiver configuration
|
||||
{
|
||||
"task": "receive_webhook"
|
||||
}
|
||||
|
||||
// Get AI chat configuration
|
||||
{
|
||||
"task": "chat_with_ai"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- Instant response (pre-configured templates)
|
||||
- No database lookups required
|
||||
- Includes working examples
|
||||
|
||||
### Best Practices
|
||||
- Use list_tasks first to see available options
|
||||
- Check userMustProvide section
|
||||
- Follow tips for best results
|
||||
- Common tasks: API calls, webhooks, database queries, AI chat
|
||||
|
||||
### Common Pitfalls
|
||||
- Not all tasks available (use list_tasks)
|
||||
- Configuration needs customization
|
||||
- Some fields still need user input
|
||||
|
||||
### Related Tools
|
||||
- `list_tasks` - See all available tasks
|
||||
- `get_node_essentials` - Alternative approach
|
||||
- `search_templates` - Find complete workflow templates
|
||||
|
||||
---
|
||||
|
||||
## n8n_create_workflow
|
||||
|
||||
**Brief Description**: Create a new workflow in n8n with nodes and connections.
|
||||
|
||||
### Parameters
|
||||
- `name` (string, required): Workflow name
|
||||
- `nodes` (array, required): Array of node definitions
|
||||
- `connections` (object, required): Node connections mapping
|
||||
- `settings` (object, optional): Workflow settings
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"id": "workflow-uuid",
|
||||
"name": "My Workflow",
|
||||
"active": false,
|
||||
"createdAt": "2024-01-15T10:30:00Z",
|
||||
"updatedAt": "2024-01-15T10:30:00Z",
|
||||
"nodes": [...],
|
||||
"connections": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Automated workflow creation**: Build workflows programmatically
|
||||
2. **Template deployment**: Deploy pre-built workflow patterns
|
||||
3. **Multi-workflow systems**: Create interconnected workflows
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Create simple webhook → HTTP request workflow
|
||||
{
|
||||
"name": "Webhook to API",
|
||||
"nodes": [
|
||||
{
|
||||
"id": "webhook-1",
|
||||
"name": "Webhook",
|
||||
"type": "n8n-nodes-base.webhook",
|
||||
"typeVersion": 2,
|
||||
"position": [250, 300],
|
||||
"parameters": {
|
||||
"path": "/my-webhook",
|
||||
"httpMethod": "POST"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "http-1",
|
||||
"name": "HTTP Request",
|
||||
"type": "n8n-nodes-base.httpRequest",
|
||||
"typeVersion": 4.2,
|
||||
"position": [450, 300],
|
||||
"parameters": {
|
||||
"method": "POST",
|
||||
"url": "https://api.example.com/process",
|
||||
"responseFormat": "json"
|
||||
}
|
||||
}
|
||||
],
|
||||
"connections": {
|
||||
"Webhook": {
|
||||
"main": [[{"node": "HTTP Request", "type": "main", "index": 0}]]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- API call to n8n instance required
|
||||
- Workflow created in inactive state
|
||||
- Must be manually activated in UI
|
||||
|
||||
### Best Practices
|
||||
- Always include typeVersion for nodes
|
||||
- Use node names (not IDs) in connections
|
||||
- Position nodes logically ([x, y] coordinates)
|
||||
- Test with validate_workflow first
|
||||
- Start simple, add complexity gradually
|
||||
|
||||
### Common Pitfalls
|
||||
- Missing typeVersion causes errors
|
||||
- Using node IDs instead of names in connections
|
||||
- Forgetting required node properties
|
||||
- Creating cycles in connections
|
||||
- Workflow can't be activated via API
|
||||
|
||||
### Related Tools
|
||||
- `validate_workflow` - Validate before creating
|
||||
- `n8n_update_partial_workflow` - Modify existing workflows
|
||||
- `n8n_trigger_webhook_workflow` - Execute workflows
|
||||
|
||||
---
|
||||
|
||||
## n8n_update_partial_workflow
|
||||
|
||||
**Brief Description**: Update workflows using diff operations for precise, incremental changes without sending the entire workflow.
|
||||
|
||||
### Parameters
|
||||
- `id` (string, required): Workflow ID to update
|
||||
- `operations` (array, required): Array of diff operations (max 5)
|
||||
- `validateOnly` (boolean, optional): Test without applying changes
|
||||
|
||||
### Return Format
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"workflow": {
|
||||
"id": "workflow-uuid",
|
||||
"name": "Updated Workflow",
|
||||
"nodes": [...],
|
||||
"connections": {...}
|
||||
},
|
||||
"appliedOperations": 3
|
||||
}
|
||||
```
|
||||
|
||||
### Common Use Cases
|
||||
1. **Add nodes to existing workflows**: Insert new functionality
|
||||
2. **Update node configurations**: Change parameters without full replacement
|
||||
3. **Manage connections**: Add/remove node connections
|
||||
4. **Quick edits**: Rename, enable/disable nodes, update settings
|
||||
|
||||
### Examples
|
||||
```json
|
||||
// Add a new node and connect it
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
{
|
||||
"type": "addNode",
|
||||
"node": {
|
||||
"id": "set-1",
|
||||
"name": "Set Data",
|
||||
"type": "n8n-nodes-base.set",
|
||||
"typeVersion": 3,
|
||||
"position": [600, 300],
|
||||
"parameters": {
|
||||
"values": {
|
||||
"string": [{
|
||||
"name": "status",
|
||||
"value": "processed"
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "addConnection",
|
||||
"source": "HTTP Request",
|
||||
"target": "Set Data"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
// Update multiple properties
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
{
|
||||
"type": "updateName",
|
||||
"name": "Production Workflow v2"
|
||||
},
|
||||
{
|
||||
"type": "updateNode",
|
||||
"nodeName": "Webhook",
|
||||
"changes": {
|
||||
"parameters.path": "/v2/webhook"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "addTag",
|
||||
"tag": "production"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Notes
|
||||
- 80-90% token savings vs full updates
|
||||
- Maximum 5 operations per request
|
||||
- Two-pass processing handles dependencies
|
||||
- Transactional: all or nothing
|
||||
|
||||
### Best Practices
|
||||
- Use validateOnly: true to test first
|
||||
- Keep operations under 5 for reliability
|
||||
- Operations can be in any order (v2.7.0+)
|
||||
- Use node names, not IDs in operations
|
||||
- For updateNode, use dot notation for nested paths
|
||||
|
||||
### Common Pitfalls
|
||||
- Exceeding 5 operations limit
|
||||
- Using node IDs instead of names
|
||||
- Forgetting required node properties in addNode
|
||||
- Not testing with validateOnly first
|
||||
|
||||
### Related Tools
|
||||
- `n8n_update_full_workflow` - Complete workflow replacement
|
||||
- `n8n_get_workflow` - Fetch current workflow state
|
||||
- `validate_workflow` - Validate changes before applying
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Workflow Building Process
|
||||
1. **Discovery**: `search_nodes` → `list_nodes`
|
||||
2. **Configuration**: `get_node_essentials` → `get_node_for_task`
|
||||
3. **Validation**: `validate_node_minimal` → `validate_node_operation`
|
||||
4. **Creation**: `validate_workflow` → `n8n_create_workflow`
|
||||
5. **Updates**: `n8n_update_partial_workflow`
|
||||
|
||||
### Performance Tips
|
||||
- Use `get_node_essentials` instead of `get_node_info` (95% smaller)
|
||||
- Set high limits on `list_nodes` (200+)
|
||||
- Use single words in `search_nodes`
|
||||
- Validate incrementally while building
|
||||
|
||||
### 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
|
||||
|
||||
### Error Prevention
|
||||
- Always include node type prefixes: "nodes-base.slack"
|
||||
- Use node names (not IDs) in connections
|
||||
- Include typeVersion in all nodes
|
||||
- Test with validateOnly before applying changes
|
||||
- Check userMustProvide sections in templates
|
||||
@@ -1,514 +0,0 @@
|
||||
# n8n MCP Client Tool Integration - Implementation Plan (Simplified)
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a **simplified** implementation plan for making n8n-mcp compatible with n8n's MCP Client Tool (v1.1). Based on expert review, we're taking a minimal approach that extends the existing single-session server rather than creating new architecture.
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **Minimal Changes**: Extend existing single-session server with n8n compatibility mode
|
||||
2. **No Overengineering**: No complex session management or multi-session architecture
|
||||
3. **Docker-Native**: Separate Docker image for n8n deployment
|
||||
4. **Remote Deployment**: Designed to run alongside n8n in production
|
||||
5. **Backward Compatible**: Existing functionality remains unchanged
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose
|
||||
- n8n version 1.104.2 or higher (with MCP Client Tool v1.1)
|
||||
- Basic understanding of Docker networking
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
Instead of creating new multi-session architecture, we'll extend the existing single-session server with an n8n compatibility mode. This approach was recommended by all three expert reviewers as simpler and more maintainable.
|
||||
|
||||
## Architecture Changes
|
||||
|
||||
```
|
||||
src/
|
||||
├── http-server-single-session.ts # MODIFY: Add n8n mode flag
|
||||
└── mcp/
|
||||
└── server.ts # NO CHANGES NEEDED
|
||||
|
||||
Docker/
|
||||
├── Dockerfile.n8n # NEW: n8n-specific image
|
||||
├── docker-compose.n8n.yml # NEW: Simplified stack
|
||||
└── .github/workflows/
|
||||
└── docker-build-n8n.yml # NEW: Build workflow
|
||||
```
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Step 1: Modify Existing Single-Session Server
|
||||
|
||||
#### 1.1 Update `src/http-server-single-session.ts`
|
||||
|
||||
Add n8n compatibility mode to the existing server with minimal changes:
|
||||
|
||||
```typescript
|
||||
// Add these constants at the top (after imports)
|
||||
const PROTOCOL_VERSION = "2024-11-05";
|
||||
const N8N_MODE = process.env.N8N_MODE === 'true';
|
||||
|
||||
// In the constructor or start method, add logging
|
||||
if (N8N_MODE) {
|
||||
logger.info('Running in n8n compatibility mode');
|
||||
}
|
||||
|
||||
// In setupRoutes method, add the protocol version endpoint
|
||||
if (N8N_MODE) {
|
||||
app.get('/mcp', (req, res) => {
|
||||
res.json({
|
||||
protocolVersion: PROTOCOL_VERSION,
|
||||
serverInfo: {
|
||||
name: "n8n-mcp",
|
||||
version: PROJECT_VERSION,
|
||||
capabilities: {
|
||||
tools: true,
|
||||
resources: false,
|
||||
prompts: false,
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// In handleMCPRequest method, add session header
|
||||
if (N8N_MODE && this.session) {
|
||||
res.setHeader('Mcp-Session-Id', this.session.sessionId);
|
||||
}
|
||||
|
||||
// Update error handling to use JSON-RPC format
|
||||
catch (error) {
|
||||
logger.error('MCP request error:', error);
|
||||
|
||||
if (N8N_MODE) {
|
||||
res.status(500).json({
|
||||
jsonrpc: '2.0',
|
||||
error: {
|
||||
code: -32603,
|
||||
message: 'Internal error',
|
||||
data: error instanceof Error ? error.message : 'Unknown error',
|
||||
},
|
||||
id: null,
|
||||
});
|
||||
} else {
|
||||
// Keep existing error handling for backward compatibility
|
||||
res.status(500).json({
|
||||
error: 'Internal server error',
|
||||
details: error instanceof Error ? error.message : 'Unknown error'
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
That's it! No new files, no complex session management. Just a few lines of code.
|
||||
|
||||
### Step 2: Update Package Scripts
|
||||
|
||||
#### 2.1 Update `package.json`
|
||||
|
||||
Add a simple script for n8n mode:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"start:n8n": "N8N_MODE=true MCP_MODE=http node dist/mcp/index.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Create Docker Infrastructure for n8n
|
||||
|
||||
#### 3.1 Create `Dockerfile.n8n`
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile.n8n - Optimized for n8n integration
|
||||
FROM node:22-alpine AS builder
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install build dependencies
|
||||
RUN apk add --no-cache python3 make g++
|
||||
|
||||
# Copy package files
|
||||
COPY package*.json tsconfig*.json ./
|
||||
|
||||
# Install ALL dependencies
|
||||
RUN npm ci --no-audit --no-fund
|
||||
|
||||
# Copy source and build
|
||||
COPY src ./src
|
||||
RUN npm run build && npm run rebuild
|
||||
|
||||
# Runtime stage
|
||||
FROM node:22-alpine
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install runtime dependencies
|
||||
RUN apk add --no-cache curl dumb-init
|
||||
|
||||
# Create non-root user
|
||||
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
|
||||
|
||||
# Copy application from builder
|
||||
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
|
||||
COPY --from=builder --chown=nodejs:nodejs /app/data ./data
|
||||
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
|
||||
COPY --chown=nodejs:nodejs package.json ./
|
||||
|
||||
USER nodejs
|
||||
|
||||
EXPOSE 3001
|
||||
|
||||
HEALTHCHECK CMD curl -f http://localhost:3001/health || exit 1
|
||||
|
||||
ENTRYPOINT ["dumb-init", "--"]
|
||||
CMD ["node", "dist/mcp/index.js"]
|
||||
```
|
||||
|
||||
#### 3.2 Create `docker-compose.n8n.yml`
|
||||
|
||||
```yaml
|
||||
# docker-compose.n8n.yml - Simple stack for n8n + n8n-mcp
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
n8n:
|
||||
image: n8nio/n8n:latest
|
||||
container_name: n8n
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "5678:5678"
|
||||
environment:
|
||||
- N8N_BASIC_AUTH_ACTIVE=${N8N_BASIC_AUTH_ACTIVE:-true}
|
||||
- N8N_BASIC_AUTH_USER=${N8N_USER:-admin}
|
||||
- N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD:-changeme}
|
||||
- N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
|
||||
volumes:
|
||||
- n8n_data:/home/node/.n8n
|
||||
networks:
|
||||
- n8n-net
|
||||
depends_on:
|
||||
n8n-mcp:
|
||||
condition: service_healthy
|
||||
|
||||
n8n-mcp:
|
||||
image: ghcr.io/${GITHUB_USER:-czlonkowski}/n8n-mcp-n8n:latest
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile.n8n
|
||||
container_name: n8n-mcp
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- MCP_MODE=http
|
||||
- N8N_MODE=true
|
||||
- AUTH_TOKEN=${MCP_AUTH_TOKEN}
|
||||
- NODE_ENV=production
|
||||
- HTTP_PORT=3001
|
||||
networks:
|
||||
- n8n-net
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
|
||||
networks:
|
||||
n8n-net:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
n8n_data:
|
||||
```
|
||||
|
||||
#### 3.3 Create `.env.n8n.example`
|
||||
|
||||
```bash
|
||||
# .env.n8n.example - Copy to .env and configure
|
||||
|
||||
# n8n Configuration
|
||||
N8N_USER=admin
|
||||
N8N_PASSWORD=changeme
|
||||
N8N_BASIC_AUTH_ACTIVE=true
|
||||
|
||||
# MCP Configuration
|
||||
# Generate with: openssl rand -base64 32
|
||||
MCP_AUTH_TOKEN=your-secure-token-minimum-32-characters
|
||||
|
||||
# GitHub username for image registry
|
||||
GITHUB_USER=czlonkowski
|
||||
```
|
||||
|
||||
### Step 4: Create GitHub Actions Workflow
|
||||
|
||||
#### 4.1 Create `.github/workflows/docker-build-n8n.yml`
|
||||
|
||||
```yaml
|
||||
name: Build n8n Docker Image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
tags: ['v*']
|
||||
paths:
|
||||
- 'src/**'
|
||||
- 'package*.json'
|
||||
- 'Dockerfile.n8n'
|
||||
workflow_dispatch:
|
||||
|
||||
env:
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}-n8n
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
|
||||
- uses: docker/login-action@v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- uses: docker/metadata-action@v5
|
||||
id: meta
|
||||
with:
|
||||
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
|
||||
tags: |
|
||||
type=ref,event=branch
|
||||
type=semver,pattern={{version}}
|
||||
type=raw,value=latest,enable={{is_default_branch}}
|
||||
|
||||
- uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
file: ./Dockerfile.n8n
|
||||
push: true
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
```
|
||||
|
||||
### Step 5: Testing
|
||||
|
||||
#### 5.1 Unit Tests for n8n Mode
|
||||
|
||||
Create `tests/unit/http-server-n8n-mode.test.ts`:
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from 'vitest';
|
||||
import request from 'supertest';
|
||||
|
||||
describe('n8n Mode', () => {
|
||||
it('should return protocol version on GET /mcp', async () => {
|
||||
process.env.N8N_MODE = 'true';
|
||||
const app = await createTestApp();
|
||||
|
||||
const response = await request(app)
|
||||
.get('/mcp')
|
||||
.expect(200);
|
||||
|
||||
expect(response.body.protocolVersion).toBe('2024-11-05');
|
||||
expect(response.body.serverInfo.capabilities.tools).toBe(true);
|
||||
});
|
||||
|
||||
it('should include session ID in response headers', async () => {
|
||||
process.env.N8N_MODE = 'true';
|
||||
const app = await createTestApp();
|
||||
|
||||
const response = await request(app)
|
||||
.post('/mcp')
|
||||
.set('Authorization', 'Bearer test-token')
|
||||
.send({ jsonrpc: '2.0', method: 'initialize', id: 1 });
|
||||
|
||||
expect(response.headers['mcp-session-id']).toBeDefined();
|
||||
});
|
||||
|
||||
it('should format errors as JSON-RPC', async () => {
|
||||
process.env.N8N_MODE = 'true';
|
||||
const app = await createTestApp();
|
||||
|
||||
const response = await request(app)
|
||||
.post('/mcp')
|
||||
.send({ invalid: 'request' })
|
||||
.expect(500);
|
||||
|
||||
expect(response.body.jsonrpc).toBe('2.0');
|
||||
expect(response.body.error.code).toBe(-32603);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### 5.2 Quick Deployment Script
|
||||
|
||||
Create `deploy/quick-deploy-n8n.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🚀 Quick Deploy n8n + n8n-mcp"
|
||||
|
||||
# Check prerequisites
|
||||
command -v docker >/dev/null 2>&1 || { echo "Docker required"; exit 1; }
|
||||
command -v docker-compose >/dev/null 2>&1 || { echo "Docker Compose required"; exit 1; }
|
||||
|
||||
# Generate auth token if not exists
|
||||
if [ ! -f .env ]; then
|
||||
cp .env.n8n.example .env
|
||||
TOKEN=$(openssl rand -base64 32)
|
||||
sed -i "s/your-secure-token-minimum-32-characters/$TOKEN/" .env
|
||||
echo "Generated MCP_AUTH_TOKEN: $TOKEN"
|
||||
fi
|
||||
|
||||
# Deploy
|
||||
docker-compose -f docker-compose.n8n.yml up -d
|
||||
|
||||
echo ""
|
||||
echo "✅ Deployment complete!"
|
||||
echo ""
|
||||
echo "📋 Next steps:"
|
||||
echo "1. Access n8n at http://localhost:5678"
|
||||
echo " Username: admin (or check .env)"
|
||||
echo " Password: changeme (or check .env)"
|
||||
echo ""
|
||||
echo "2. Create a workflow with MCP Client Tool:"
|
||||
echo " - Server URL: http://n8n-mcp:3001/mcp"
|
||||
echo " - Authentication: Bearer Token"
|
||||
echo " - Token: Check .env file for MCP_AUTH_TOKEN"
|
||||
echo ""
|
||||
echo "📊 View logs: docker-compose -f docker-compose.n8n.yml logs -f"
|
||||
echo "🛑 Stop: docker-compose -f docker-compose.n8n.yml down"
|
||||
```
|
||||
|
||||
## Implementation Checklist (Simplified)
|
||||
|
||||
### Code Changes
|
||||
- [ ] Add N8N_MODE flag to `http-server-single-session.ts`
|
||||
- [ ] Add protocol version endpoint (GET /mcp) when N8N_MODE=true
|
||||
- [ ] Add Mcp-Session-Id header to responses
|
||||
- [ ] Update error responses to JSON-RPC format when N8N_MODE=true
|
||||
- [ ] Add npm script `start:n8n` to package.json
|
||||
|
||||
### Docker Infrastructure
|
||||
- [ ] Create `Dockerfile.n8n` for n8n-specific image
|
||||
- [ ] Create `docker-compose.n8n.yml` for simple deployment
|
||||
- [ ] Create `.env.n8n.example` template
|
||||
- [ ] Create GitHub Actions workflow `docker-build-n8n.yml`
|
||||
- [ ] Create `deploy/quick-deploy-n8n.sh` script
|
||||
|
||||
### Testing
|
||||
- [ ] Write unit tests for n8n mode functionality
|
||||
- [ ] Test with actual n8n MCP Client Tool
|
||||
- [ ] Verify protocol version endpoint
|
||||
- [ ] Test authentication flow
|
||||
- [ ] Validate error formatting
|
||||
|
||||
### Documentation
|
||||
- [ ] Update README with n8n deployment section
|
||||
- [ ] Document N8N_MODE environment variable
|
||||
- [ ] Add troubleshooting guide for common issues
|
||||
|
||||
## Quick Start Guide
|
||||
|
||||
### 1. One-Command Deployment
|
||||
|
||||
```bash
|
||||
# Clone and deploy
|
||||
git clone https://github.com/czlonkowski/n8n-mcp.git
|
||||
cd n8n-mcp
|
||||
./deploy/quick-deploy-n8n.sh
|
||||
```
|
||||
|
||||
### 2. Manual Configuration in n8n
|
||||
|
||||
After deployment, configure the MCP Client Tool in n8n:
|
||||
|
||||
1. Open n8n at `http://localhost:5678`
|
||||
2. Create a new workflow
|
||||
3. Add "MCP Client Tool" node (under AI category)
|
||||
4. Configure:
|
||||
- **Server URL**: `http://n8n-mcp:3001/mcp`
|
||||
- **Authentication**: Bearer Token
|
||||
- **Token**: Check your `.env` file for MCP_AUTH_TOKEN
|
||||
5. Select a tool (e.g., `list_nodes`)
|
||||
6. Execute the workflow
|
||||
|
||||
### 3. Production Deployment
|
||||
|
||||
For production with SSL, use a reverse proxy:
|
||||
|
||||
```nginx
|
||||
# nginx configuration
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name n8n.yourdomain.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:5678;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The MCP server should remain internal only - n8n connects via Docker network.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The implementation is successful when:
|
||||
|
||||
1. **Minimal Code Changes**: Only ~20 lines added to existing server
|
||||
2. **Protocol Compliance**: GET /mcp returns correct protocol version
|
||||
3. **n8n Connection**: MCP Client Tool connects successfully
|
||||
4. **Tool Execution**: Tools work without modification
|
||||
5. **Backward Compatible**: Existing Claude Desktop usage unaffected
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"Protocol version mismatch"**
|
||||
- Ensure N8N_MODE=true is set
|
||||
- Check GET /mcp returns "2024-11-05"
|
||||
|
||||
2. **"Authentication failed"**
|
||||
- Verify AUTH_TOKEN matches in .env and n8n
|
||||
- Token must be 32+ characters
|
||||
- Use "Bearer Token" auth type in n8n
|
||||
|
||||
3. **"Connection refused"**
|
||||
- Check containers are on same network
|
||||
- Use internal hostname: `http://n8n-mcp:3001/mcp`
|
||||
- Verify health check passes
|
||||
|
||||
4. **Testing the Setup**
|
||||
```bash
|
||||
# Check protocol version
|
||||
docker exec n8n-mcp curl http://localhost:3001/mcp
|
||||
|
||||
# View logs
|
||||
docker-compose -f docker-compose.n8n.yml logs -f n8n-mcp
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
This simplified approach:
|
||||
- **Extends existing code** rather than creating new architecture
|
||||
- **Adds n8n compatibility** with minimal changes
|
||||
- **Uses separate Docker image** for clean deployment
|
||||
- **Maintains backward compatibility** for existing users
|
||||
- **Avoids overengineering** with simple, practical solutions
|
||||
|
||||
Total implementation effort: ~2-3 hours (vs. 2-3 days for multi-session approach)
|
||||
@@ -1,146 +0,0 @@
|
||||
# Test Artifacts Documentation
|
||||
|
||||
This document describes the comprehensive test result artifact storage system implemented in the n8n-mcp project.
|
||||
|
||||
## Overview
|
||||
|
||||
The test artifact system captures, stores, and presents test results in multiple formats to facilitate debugging, analysis, and historical tracking of test performance.
|
||||
|
||||
## Artifact Types
|
||||
|
||||
### 1. Test Results
|
||||
- **JUnit XML** (`test-results/junit.xml`): Standard format for CI integration
|
||||
- **JSON Results** (`test-results/results.json`): Detailed test data for analysis
|
||||
- **HTML Report** (`test-results/html/index.html`): Interactive test report
|
||||
- **Test Summary** (`test-summary.md`): Markdown summary for PR comments
|
||||
|
||||
### 2. Coverage Reports
|
||||
- **LCOV** (`coverage/lcov.info`): Standard coverage format
|
||||
- **HTML Coverage** (`coverage/html/index.html`): Interactive coverage browser
|
||||
- **Coverage Summary** (`coverage/coverage-summary.json`): JSON coverage data
|
||||
|
||||
### 3. Benchmark Results
|
||||
- **Benchmark JSON** (`benchmark-results.json`): Raw benchmark data
|
||||
- **Comparison Reports** (`benchmark-comparison.md`): PR benchmark comparisons
|
||||
|
||||
### 4. Detailed Reports
|
||||
- **HTML Report** (`test-reports/report.html`): Comprehensive styled report
|
||||
- **Markdown Report** (`test-reports/report.md`): Full markdown report
|
||||
- **JSON Report** (`test-reports/report.json`): Complete test data
|
||||
|
||||
## GitHub Actions Integration
|
||||
|
||||
### Test Workflow (`test.yml`)
|
||||
|
||||
The main test workflow:
|
||||
1. Runs tests with coverage using multiple reporters
|
||||
2. Generates test summaries and detailed reports
|
||||
3. Uploads artifacts with metadata
|
||||
4. Posts summaries to PRs
|
||||
5. Creates a combined artifact index
|
||||
|
||||
### Benchmark PR Workflow (`benchmark-pr.yml`)
|
||||
|
||||
For pull requests:
|
||||
1. Runs benchmarks on PR branch
|
||||
2. Runs benchmarks on base branch
|
||||
3. Compares results
|
||||
4. Posts comparison to PR
|
||||
5. Sets status checks for regressions
|
||||
|
||||
## Artifact Retention
|
||||
|
||||
- **Test Results**: 30 days
|
||||
- **Coverage Reports**: 30 days
|
||||
- **Benchmark Results**: 30 days
|
||||
- **Combined Results**: 90 days
|
||||
- **Test Metadata**: 30 days
|
||||
|
||||
## PR Comment Integration
|
||||
|
||||
The system automatically:
|
||||
- Posts test summaries to PR comments
|
||||
- Updates existing comments instead of creating duplicates
|
||||
- Includes links to full artifacts
|
||||
- Shows coverage and benchmark changes
|
||||
|
||||
## Job Summary
|
||||
|
||||
Each workflow run includes a job summary with:
|
||||
- Test results overview
|
||||
- Coverage summary
|
||||
- Benchmark results
|
||||
- Direct links to download artifacts
|
||||
|
||||
## Local Development
|
||||
|
||||
### Running Tests with Reports
|
||||
|
||||
```bash
|
||||
# Run tests with all reporters
|
||||
CI=true npm run test:coverage
|
||||
|
||||
# Generate detailed reports
|
||||
node scripts/generate-detailed-reports.js
|
||||
|
||||
# Generate test summary
|
||||
node scripts/generate-test-summary.js
|
||||
|
||||
# Compare benchmarks
|
||||
node scripts/compare-benchmarks.js benchmark-results.json benchmark-baseline.json
|
||||
```
|
||||
|
||||
### Report Locations
|
||||
|
||||
When running locally, reports are generated in:
|
||||
- `test-results/` - Vitest outputs
|
||||
- `test-reports/` - Detailed reports
|
||||
- `coverage/` - Coverage reports
|
||||
- Root directory - Summary files
|
||||
|
||||
## Report Formats
|
||||
|
||||
### HTML Report Features
|
||||
- Responsive design
|
||||
- Test suite breakdown
|
||||
- Failed test details with error messages
|
||||
- Coverage visualization with progress bars
|
||||
- Benchmark performance metrics
|
||||
- Sortable tables
|
||||
|
||||
### Markdown Report Features
|
||||
- GitHub-compatible formatting
|
||||
- Summary statistics
|
||||
- Failed test listings
|
||||
- Coverage breakdown
|
||||
- Benchmark comparisons
|
||||
|
||||
### JSON Report Features
|
||||
- Complete test data
|
||||
- Programmatic access
|
||||
- Historical comparison
|
||||
- CI/CD integration
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always Check Artifacts**: When tests fail in CI, download and review the HTML report
|
||||
2. **Monitor Coverage**: Use the coverage reports to identify untested code
|
||||
3. **Track Benchmarks**: Review benchmark comparisons on performance-critical PRs
|
||||
4. **Archive Important Runs**: Download artifacts from significant releases
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Missing Artifacts
|
||||
- Check if tests ran to completion
|
||||
- Verify artifact upload steps executed
|
||||
- Check retention period hasn't expired
|
||||
|
||||
### Report Generation Failures
|
||||
- Ensure all dependencies are installed
|
||||
- Check for valid test/coverage output files
|
||||
- Review workflow logs for errors
|
||||
|
||||
### PR Comment Issues
|
||||
- Verify GitHub Actions permissions
|
||||
- Check bot authentication
|
||||
- Review comment posting logs
|
||||
@@ -1,935 +0,0 @@
|
||||
# n8n-MCP Testing Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the comprehensive testing infrastructure implemented for the n8n-MCP project. The testing suite includes 3,336 tests split between unit and integration tests, benchmarks, and a complete CI/CD pipeline ensuring code quality and reliability.
|
||||
|
||||
### Test Suite Statistics (October 2025)
|
||||
|
||||
- **Total Tests**: 3,336 tests
|
||||
- **Unit Tests**: 2,766 tests - Isolated component testing with mocks
|
||||
- **Integration Tests**: 570 tests - Full system behavior validation
|
||||
- n8n API Integration: 172 tests (all 18 MCP handler tools)
|
||||
- MCP Protocol: 119 tests (protocol compliance, session management)
|
||||
- Database: 226 tests (repository operations, transactions, FTS5)
|
||||
- Templates: 35 tests (fetching, storage, metadata)
|
||||
- Docker: 18 tests (configuration, security)
|
||||
- **Test Files**:
|
||||
- 106 unit test files
|
||||
- 41 integration test files
|
||||
- Total: 147 test files
|
||||
- **Test Execution Time**:
|
||||
- Unit tests: ~2 minutes with coverage
|
||||
- Integration tests: ~30 seconds
|
||||
- Total CI time: ~3 minutes
|
||||
- **Success Rate**: 100% (all tests passing in CI)
|
||||
- **CI/CD Pipeline**: Fully automated with GitHub Actions
|
||||
- **Test Artifacts**: JUnit XML, coverage reports, benchmark results
|
||||
- **Parallel Execution**: Configurable with thread pool
|
||||
|
||||
## Testing Framework: Vitest
|
||||
|
||||
We use **Vitest** as our primary testing framework, chosen for its:
|
||||
- **Speed**: Native ESM support and fast execution
|
||||
- **TypeScript Integration**: First-class TypeScript support
|
||||
- **Watch Mode**: Instant feedback during development
|
||||
- **Jest Compatibility**: Easy migration from Jest
|
||||
- **Built-in Mocking**: Powerful mocking capabilities
|
||||
- **Coverage**: Integrated code coverage with v8
|
||||
|
||||
### Configuration
|
||||
|
||||
```typescript
|
||||
// vitest.config.ts
|
||||
export default defineConfig({
|
||||
test: {
|
||||
globals: true,
|
||||
environment: 'node',
|
||||
setupFiles: ['./tests/setup/global-setup.ts'],
|
||||
pool: 'threads',
|
||||
poolOptions: {
|
||||
threads: {
|
||||
singleThread: process.env.TEST_PARALLEL !== 'true',
|
||||
maxThreads: parseInt(process.env.TEST_MAX_WORKERS || '4', 10)
|
||||
}
|
||||
},
|
||||
coverage: {
|
||||
provider: 'v8',
|
||||
reporter: ['lcov', 'html', 'text-summary'],
|
||||
exclude: ['node_modules/', 'tests/', '**/*.test.ts', 'scripts/']
|
||||
}
|
||||
},
|
||||
resolve: {
|
||||
alias: {
|
||||
'@': path.resolve(__dirname, './src'),
|
||||
'@tests': path.resolve(__dirname, './tests')
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── unit/ # Unit tests with mocks (2,766 tests, 106 files)
|
||||
│ ├── __mocks__/ # Mock implementations
|
||||
│ │ └── n8n-nodes-base.test.ts
|
||||
│ ├── database/ # Database layer tests
|
||||
│ │ ├── database-adapter-unit.test.ts
|
||||
│ │ ├── node-repository-core.test.ts
|
||||
│ │ └── template-repository-core.test.ts
|
||||
│ ├── docker/ # Docker configuration tests
|
||||
│ │ ├── config-security.test.ts
|
||||
│ │ ├── edge-cases.test.ts
|
||||
│ │ ├── parse-config.test.ts
|
||||
│ │ └── serve-command.test.ts
|
||||
│ ├── http-server/ # HTTP server tests
|
||||
│ │ └── multi-tenant-support.test.ts
|
||||
│ ├── loaders/ # Node loader tests
|
||||
│ │ └── node-loader.test.ts
|
||||
│ ├── mappers/ # Data mapper tests
|
||||
│ │ └── docs-mapper.test.ts
|
||||
│ ├── mcp/ # MCP server and tools tests
|
||||
│ │ ├── handlers-n8n-manager.test.ts
|
||||
│ │ ├── handlers-workflow-diff.test.ts
|
||||
│ │ ├── tools-documentation.test.ts
|
||||
│ │ └── tools.test.ts
|
||||
│ ├── parsers/ # Parser tests
|
||||
│ │ ├── node-parser.test.ts
|
||||
│ │ ├── property-extractor.test.ts
|
||||
│ │ └── simple-parser.test.ts
|
||||
│ ├── scripts/ # Script tests
|
||||
│ │ └── fetch-templates-extraction.test.ts
|
||||
│ ├── services/ # Service layer tests (largest test suite)
|
||||
│ │ ├── config-validator.test.ts
|
||||
│ │ ├── enhanced-config-validator.test.ts
|
||||
│ │ ├── example-generator.test.ts
|
||||
│ │ ├── expression-validator.test.ts
|
||||
│ │ ├── n8n-api-client.test.ts
|
||||
│ │ ├── n8n-validation.test.ts
|
||||
│ │ ├── node-specific-validators.test.ts
|
||||
│ │ ├── property-dependencies.test.ts
|
||||
│ │ ├── property-filter.test.ts
|
||||
│ │ ├── task-templates.test.ts
|
||||
│ │ ├── workflow-diff-engine.test.ts
|
||||
│ │ ├── workflow-validator-comprehensive.test.ts
|
||||
│ │ └── workflow-validator.test.ts
|
||||
│ ├── telemetry/ # Telemetry tests
|
||||
│ │ └── telemetry-manager.test.ts
|
||||
│ └── utils/ # Utility function tests
|
||||
│ ├── cache-utils.test.ts
|
||||
│ └── database-utils.test.ts
|
||||
├── integration/ # Integration tests (570 tests, 41 files)
|
||||
│ ├── n8n-api/ # n8n API integration tests (172 tests, 18 files)
|
||||
│ │ ├── executions/ # Execution management tests
|
||||
│ │ │ ├── get-execution.test.ts
|
||||
│ │ │ └── list-executions.test.ts
|
||||
│ │ ├── system/ # System tool tests
|
||||
│ │ │ ├── diagnostic.test.ts
|
||||
│ │ │ ├── health-check.test.ts
|
||||
│ │ │ └── list-tools.test.ts
|
||||
│ │ ├── utils/ # Test utilities
|
||||
│ │ │ ├── mcp-context.ts
|
||||
│ │ │ └── response-types.ts
|
||||
│ │ └── workflows/ # Workflow management tests
|
||||
│ │ ├── autofix-workflow.test.ts
|
||||
│ │ ├── create-workflow.test.ts
|
||||
│ │ ├── delete-workflow.test.ts
|
||||
│ │ ├── get-workflow-details.test.ts
|
||||
│ │ ├── get-workflow-minimal.test.ts
|
||||
│ │ ├── get-workflow-structure.test.ts
|
||||
│ │ ├── get-workflow.test.ts
|
||||
│ │ ├── list-workflows.test.ts
|
||||
│ │ ├── update-full-workflow.test.ts
|
||||
│ │ ├── update-partial-workflow.test.ts
|
||||
│ │ └── validate-workflow.test.ts
|
||||
│ ├── database/ # Database integration tests (226 tests)
|
||||
│ │ ├── connection-management.test.ts
|
||||
│ │ ├── fts5-search.test.ts
|
||||
│ │ ├── node-repository.test.ts
|
||||
│ │ ├── performance.test.ts
|
||||
│ │ ├── template-node-configs.test.ts
|
||||
│ │ ├── template-repository.test.ts
|
||||
│ │ └── transactions.test.ts
|
||||
│ ├── docker/ # Docker integration tests (18 tests)
|
||||
│ │ ├── docker-config.test.ts
|
||||
│ │ └── docker-entrypoint.test.ts
|
||||
│ ├── mcp-protocol/ # MCP protocol tests (119 tests)
|
||||
│ │ ├── basic-connection.test.ts
|
||||
│ │ ├── error-handling.test.ts
|
||||
│ │ ├── performance.test.ts
|
||||
│ │ ├── protocol-compliance.test.ts
|
||||
│ │ ├── session-management.test.ts
|
||||
│ │ ├── tool-invocation.test.ts
|
||||
│ │ └── workflow-error-validation.test.ts
|
||||
│ ├── templates/ # Template tests (35 tests)
|
||||
│ │ └── metadata-operations.test.ts
|
||||
│ └── setup/ # Integration test setup
|
||||
│ ├── integration-setup.ts
|
||||
│ └── msw-test-server.ts
|
||||
├── benchmarks/ # Performance benchmarks
|
||||
│ ├── database-queries.bench.ts
|
||||
│ └── sample.bench.ts
|
||||
├── setup/ # Global test configuration
|
||||
│ ├── global-setup.ts # Global test setup
|
||||
│ ├── msw-setup.ts # Mock Service Worker setup
|
||||
│ └── test-env.ts # Test environment configuration
|
||||
├── utils/ # Test utilities
|
||||
│ ├── assertions.ts # Custom assertions
|
||||
│ ├── builders/ # Test data builders
|
||||
│ │ └── workflow.builder.ts
|
||||
│ ├── data-generators.ts # Test data generators
|
||||
│ ├── database-utils.ts # Database test utilities
|
||||
│ └── test-helpers.ts # General test helpers
|
||||
├── mocks/ # Mock implementations
|
||||
│ └── n8n-api/ # n8n API mocks
|
||||
│ ├── handlers.ts # MSW request handlers
|
||||
│ └── data/ # Mock data
|
||||
└── fixtures/ # Test fixtures
|
||||
├── database/ # Database fixtures
|
||||
├── factories/ # Data factories
|
||||
└── workflows/ # Workflow fixtures
|
||||
```
|
||||
|
||||
## Mock Strategy
|
||||
|
||||
### 1. Mock Service Worker (MSW) for API Mocking
|
||||
|
||||
We use MSW for intercepting and mocking HTTP requests:
|
||||
|
||||
```typescript
|
||||
// tests/mocks/n8n-api/handlers.ts
|
||||
import { http, HttpResponse } from 'msw';
|
||||
|
||||
export const handlers = [
|
||||
// Workflow endpoints
|
||||
http.get('*/workflows/:id', ({ params }) => {
|
||||
const workflow = mockWorkflows.find(w => w.id === params.id);
|
||||
if (!workflow) {
|
||||
return new HttpResponse(null, { status: 404 });
|
||||
}
|
||||
return HttpResponse.json(workflow);
|
||||
}),
|
||||
|
||||
// Execution endpoints
|
||||
http.post('*/workflows/:id/run', async ({ params, request }) => {
|
||||
const body = await request.json();
|
||||
return HttpResponse.json({
|
||||
executionId: generateExecutionId(),
|
||||
status: 'running'
|
||||
});
|
||||
})
|
||||
];
|
||||
```
|
||||
|
||||
### 2. Database Mocking
|
||||
|
||||
For unit tests, we mock the database layer:
|
||||
|
||||
```typescript
|
||||
// tests/unit/__mocks__/better-sqlite3.ts
|
||||
import { vi } from 'vitest';
|
||||
|
||||
export default vi.fn(() => ({
|
||||
prepare: vi.fn(() => ({
|
||||
all: vi.fn().mockReturnValue([]),
|
||||
get: vi.fn().mockReturnValue(undefined),
|
||||
run: vi.fn().mockReturnValue({ changes: 1 }),
|
||||
finalize: vi.fn()
|
||||
})),
|
||||
exec: vi.fn(),
|
||||
close: vi.fn(),
|
||||
pragma: vi.fn()
|
||||
}));
|
||||
```
|
||||
|
||||
### 3. MCP SDK Mocking
|
||||
|
||||
For testing MCP protocol interactions:
|
||||
|
||||
```typescript
|
||||
// tests/integration/mcp-protocol/test-helpers.ts
|
||||
export class TestableN8NMCPServer extends N8NMCPServer {
|
||||
private transports = new Set<Transport>();
|
||||
|
||||
async connectToTransport(transport: Transport): Promise<void> {
|
||||
this.transports.add(transport);
|
||||
await this.connect(transport);
|
||||
}
|
||||
|
||||
async close(): Promise<void> {
|
||||
for (const transport of this.transports) {
|
||||
await transport.close();
|
||||
}
|
||||
this.transports.clear();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Test Patterns and Utilities
|
||||
|
||||
### 1. Database Test Utilities
|
||||
|
||||
```typescript
|
||||
// tests/utils/database-utils.ts
|
||||
export class TestDatabase {
|
||||
constructor(options: TestDatabaseOptions = {}) {
|
||||
this.options = {
|
||||
mode: 'memory',
|
||||
enableFTS5: true,
|
||||
...options
|
||||
};
|
||||
}
|
||||
|
||||
async initialize(): Promise<Database.Database> {
|
||||
const db = this.options.mode === 'memory'
|
||||
? new Database(':memory:')
|
||||
: new Database(this.dbPath);
|
||||
|
||||
if (this.options.enableFTS5) {
|
||||
await this.enableFTS5(db);
|
||||
}
|
||||
|
||||
return db;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Data Generators
|
||||
|
||||
```typescript
|
||||
// tests/utils/data-generators.ts
|
||||
export class TestDataGenerator {
|
||||
static generateNode(overrides: Partial<ParsedNode> = {}): ParsedNode {
|
||||
return {
|
||||
nodeType: `test.node${faker.number.int()}`,
|
||||
displayName: faker.commerce.productName(),
|
||||
description: faker.lorem.sentence(),
|
||||
properties: this.generateProperties(5),
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
static generateWorkflow(nodeCount = 3): any {
|
||||
const nodes = Array.from({ length: nodeCount }, (_, i) => ({
|
||||
id: `node_${i}`,
|
||||
type: 'test.node',
|
||||
position: [i * 100, 0],
|
||||
parameters: {}
|
||||
}));
|
||||
|
||||
return { nodes, connections: {} };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Custom Assertions
|
||||
|
||||
```typescript
|
||||
// tests/utils/assertions.ts
|
||||
export function expectValidMCPResponse(response: any): void {
|
||||
expect(response).toBeDefined();
|
||||
expect(response.content).toBeDefined();
|
||||
expect(Array.isArray(response.content)).toBe(true);
|
||||
expect(response.content[0]).toHaveProperty('type', 'text');
|
||||
expect(response.content[0]).toHaveProperty('text');
|
||||
}
|
||||
|
||||
export function expectNodeStructure(node: any): void {
|
||||
expect(node).toHaveProperty('nodeType');
|
||||
expect(node).toHaveProperty('displayName');
|
||||
expect(node).toHaveProperty('properties');
|
||||
expect(Array.isArray(node.properties)).toBe(true);
|
||||
}
|
||||
```
|
||||
|
||||
## Unit Testing
|
||||
|
||||
Our unit tests focus on testing individual components in isolation with mocked dependencies:
|
||||
|
||||
### Service Layer Tests
|
||||
|
||||
The bulk of our unit tests (400+ tests) are in the services layer:
|
||||
|
||||
```typescript
|
||||
// tests/unit/services/workflow-validator-comprehensive.test.ts
|
||||
describe('WorkflowValidator Comprehensive Tests', () => {
|
||||
it('should validate complex workflow with AI nodes', () => {
|
||||
const workflow = {
|
||||
nodes: [
|
||||
{
|
||||
id: 'ai_agent',
|
||||
type: '@n8n/n8n-nodes-langchain.agent',
|
||||
parameters: { prompt: 'Analyze data' }
|
||||
}
|
||||
],
|
||||
connections: {}
|
||||
};
|
||||
|
||||
const result = validator.validateWorkflow(workflow);
|
||||
expect(result.valid).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Parser Tests
|
||||
|
||||
Testing the node parsing logic:
|
||||
|
||||
```typescript
|
||||
// tests/unit/parsers/property-extractor.test.ts
|
||||
describe('PropertyExtractor', () => {
|
||||
it('should extract nested properties correctly', () => {
|
||||
const node = {
|
||||
properties: [
|
||||
{
|
||||
displayName: 'Options',
|
||||
name: 'options',
|
||||
type: 'collection',
|
||||
options: [
|
||||
{ name: 'timeout', type: 'number' }
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
const extracted = extractor.extractProperties(node);
|
||||
expect(extracted).toHaveProperty('options.timeout');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Mock Testing
|
||||
|
||||
Testing our mock implementations:
|
||||
|
||||
```typescript
|
||||
// tests/unit/__mocks__/n8n-nodes-base.test.ts
|
||||
describe('n8n-nodes-base mock', () => {
|
||||
it('should provide mocked node definitions', () => {
|
||||
const httpNode = mockNodes['n8n-nodes-base.httpRequest'];
|
||||
expect(httpNode).toBeDefined();
|
||||
expect(httpNode.description.displayName).toBe('HTTP Request');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Integration Testing
|
||||
|
||||
Our integration tests verify the complete system behavior across 570 tests in four major categories:
|
||||
|
||||
### n8n API Integration Testing (172 tests)
|
||||
|
||||
The n8n API integration tests verify all 18 MCP handler tools against a real n8n instance. These tests ensure our product layer (MCP handlers) work correctly end-to-end, not just the raw API client.
|
||||
|
||||
**Test Organization:**
|
||||
- **Workflows** (11 handlers): Create, read, update (full/partial), delete, list, validate, autofix
|
||||
- **Executions** (2 handlers): Get execution details, list executions
|
||||
- **System** (3 handlers): Health check, list available tools, diagnostics
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// tests/integration/n8n-api/workflows/create-workflow.test.ts
|
||||
describe('Integration: handleCreateWorkflow', () => {
|
||||
it('should create a simple two-node workflow', async () => {
|
||||
const response = await handleCreateWorkflow(
|
||||
{
|
||||
params: {
|
||||
arguments: {
|
||||
name: 'Test Workflow',
|
||||
nodes: [webhook, setNode],
|
||||
connections: { Webhook: { main: [[{ node: 'Set', type: 'main', index: 0 }]] } }
|
||||
}
|
||||
}
|
||||
},
|
||||
mcpContext
|
||||
);
|
||||
|
||||
expect(response.success).toBe(true);
|
||||
const workflow = response.data as WorkflowData;
|
||||
expect(workflow.id).toBeDefined();
|
||||
expect(workflow.nodes).toHaveLength(2);
|
||||
|
||||
// Cleanup
|
||||
await handleDeleteWorkflow({ params: { arguments: { id: workflow.id } } }, mcpContext);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Key Features Tested:**
|
||||
- Real workflow creation, modification, deletion with cleanup
|
||||
- TypeScript type safety with response interfaces
|
||||
- Complete coverage of all 18 n8n API tools
|
||||
- Proper error handling and edge cases
|
||||
- Response format validation
|
||||
|
||||
### MCP Protocol Testing (119 tests)
|
||||
|
||||
```typescript
|
||||
// tests/integration/mcp-protocol/tool-invocation.test.ts
|
||||
describe('MCP Tool Invocation', () => {
|
||||
let mcpServer: TestableN8NMCPServer;
|
||||
let client: Client;
|
||||
|
||||
beforeEach(async () => {
|
||||
mcpServer = new TestableN8NMCPServer();
|
||||
await mcpServer.initialize();
|
||||
|
||||
const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
|
||||
await mcpServer.connectToTransport(serverTransport);
|
||||
|
||||
client = new Client({ name: 'test-client', version: '1.0.0' }, {});
|
||||
await client.connect(clientTransport);
|
||||
});
|
||||
|
||||
it('should list nodes with filtering', async () => {
|
||||
const response = await client.callTool({
|
||||
name: 'list_nodes',
|
||||
arguments: { category: 'trigger', limit: 10 }
|
||||
});
|
||||
|
||||
expectValidMCPResponse(response);
|
||||
const result = JSON.parse(response.content[0].text);
|
||||
expect(result.nodes).toHaveLength(10);
|
||||
expect(result.nodes.every(n => n.category === 'trigger')).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Database Integration Testing (226 tests)
|
||||
|
||||
```typescript
|
||||
// tests/integration/database/fts5-search.test.ts
|
||||
describe('FTS5 Search Integration', () => {
|
||||
it('should perform fuzzy search', async () => {
|
||||
const results = await nodeRepo.searchNodes('HTT', 'FUZZY');
|
||||
|
||||
expect(results.some(n => n.nodeType.includes('httpRequest'))).toBe(true);
|
||||
expect(results.some(n => n.displayName.includes('HTTP'))).toBe(true);
|
||||
});
|
||||
|
||||
it('should handle complex boolean queries', async () => {
|
||||
const results = await nodeRepo.searchNodes('webhook OR http', 'OR');
|
||||
|
||||
expect(results.length).toBeGreaterThan(0);
|
||||
expect(results.some(n =>
|
||||
n.description?.includes('webhook') ||
|
||||
n.description?.includes('http')
|
||||
)).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Template Integration Testing (35 tests)
|
||||
|
||||
Tests template fetching, storage, and metadata operations against the n8n.io API and local database.
|
||||
|
||||
### Docker Integration Testing (18 tests)
|
||||
|
||||
Tests Docker configuration parsing, entrypoint script, and security validation.
|
||||
|
||||
## Test Distribution and Coverage
|
||||
|
||||
### Test Distribution by Component
|
||||
|
||||
Based on our 3,336 tests:
|
||||
|
||||
**Integration Tests (570 tests):**
|
||||
1. **n8n API Integration** (172 tests)
|
||||
- Workflow management handlers: 11 tools with comprehensive scenarios
|
||||
- Execution management handlers: 2 tools
|
||||
- System tool handlers: 3 tools
|
||||
- TypeScript type safety with response interfaces
|
||||
|
||||
2. **Database Integration** (226 tests)
|
||||
- Repository operations and transactions
|
||||
- FTS5 full-text search with fuzzy matching
|
||||
- Performance and concurrent access tests
|
||||
- Template node configurations
|
||||
|
||||
3. **MCP Protocol** (119 tests)
|
||||
- Protocol compliance and session management
|
||||
- Tool invocation and error handling
|
||||
- Performance and stress testing
|
||||
- Workflow error validation
|
||||
|
||||
4. **Templates & Docker** (53 tests)
|
||||
- Template fetching and metadata operations
|
||||
- Docker configuration and security validation
|
||||
|
||||
**Unit Tests (2,766 tests):**
|
||||
1. **Services Layer** (largest suite)
|
||||
- `workflow-validator-comprehensive.test.ts`: 150+ tests
|
||||
- `enhanced-config-validator.test.ts`: 120+ tests
|
||||
- `node-specific-validators.test.ts`: 100+ tests
|
||||
- `n8n-api-client.test.ts`: 80+ tests
|
||||
- Config validation, property filtering, workflow diff engine
|
||||
|
||||
2. **Parsers** (~200 tests)
|
||||
- Node parsing with version support
|
||||
- Property extraction and documentation mapping
|
||||
- Simple parser for basic node information
|
||||
|
||||
3. **Database Layer** (~150 tests)
|
||||
- Repository core functionality with mocks
|
||||
- Database adapter unit tests
|
||||
- Template repository operations
|
||||
|
||||
4. **MCP Tools & HTTP Server** (~300 tests)
|
||||
- Tool definitions and documentation system
|
||||
- Multi-tenant support and security
|
||||
- Configuration validation
|
||||
|
||||
5. **Utils, Docker, Scripts, Telemetry** (remaining tests)
|
||||
- Cache utilities, database helpers
|
||||
- Docker config security and parsing
|
||||
- Template extraction scripts
|
||||
- Telemetry tracking
|
||||
|
||||
### Test Execution Performance
|
||||
|
||||
From our CI runs:
|
||||
- **Fastest tests**: Unit tests with mocks (<1ms each)
|
||||
- **Slowest tests**: Integration tests with real database and n8n API (100-5000ms)
|
||||
- **Average test time**: ~20ms per test
|
||||
- **Total suite execution**: ~3 minutes in CI (with coverage)
|
||||
- **Parallel execution**: Configurable thread pool for optimal performance
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
Our GitHub Actions workflow runs all tests automatically:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test.yml
|
||||
name: Test Suite
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run unit tests with coverage
|
||||
run: npm run test:unit -- --coverage
|
||||
|
||||
- name: Run integration tests
|
||||
run: npm run test:integration
|
||||
|
||||
- name: Upload coverage to Codecov
|
||||
uses: codecov/codecov-action@v4
|
||||
```
|
||||
|
||||
### Test Execution Scripts
|
||||
|
||||
```json
|
||||
// package.json
|
||||
{
|
||||
"scripts": {
|
||||
"test": "vitest",
|
||||
"test:unit": "vitest run tests/unit",
|
||||
"test:integration": "vitest run tests/integration --config vitest.config.integration.ts",
|
||||
"test:coverage": "vitest run --coverage",
|
||||
"test:watch": "vitest watch",
|
||||
"test:bench": "vitest bench --config vitest.config.benchmark.ts",
|
||||
"benchmark:ci": "CI=true node scripts/run-benchmarks-ci.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### CI Test Results Summary
|
||||
|
||||
From our latest CI run (#41):
|
||||
|
||||
```
|
||||
UNIT TESTS:
|
||||
Test Files 30 passed (30)
|
||||
Tests 932 passed | 1 skipped (933)
|
||||
|
||||
INTEGRATION TESTS:
|
||||
Test Files 14 passed (14)
|
||||
Tests 245 passed | 4 skipped (249)
|
||||
|
||||
TOTAL: 1,177 passed | 5 skipped | 0 failed
|
||||
```
|
||||
|
||||
## Performance Testing
|
||||
|
||||
We use Vitest's built-in benchmark functionality:
|
||||
|
||||
```typescript
|
||||
// tests/benchmarks/database-queries.bench.ts
|
||||
import { bench, describe } from 'vitest';
|
||||
|
||||
describe('Database Query Performance', () => {
|
||||
bench('search nodes by category', async () => {
|
||||
await nodeRepo.getNodesByCategory('trigger');
|
||||
});
|
||||
|
||||
bench('FTS5 search performance', async () => {
|
||||
await nodeRepo.searchNodes('webhook http request', 'AND');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Test environment is configured via `.env.test`:
|
||||
|
||||
```bash
|
||||
# Test Environment Configuration
|
||||
NODE_ENV=test
|
||||
TEST_DB_PATH=:memory:
|
||||
TEST_PARALLEL=false
|
||||
TEST_MAX_WORKERS=4
|
||||
FEATURE_TEST_COVERAGE=true
|
||||
MSW_ENABLED=true
|
||||
```
|
||||
|
||||
## Key Patterns and Lessons Learned
|
||||
|
||||
### 1. Response Structure Consistency
|
||||
|
||||
All MCP responses follow a specific structure that must be handled correctly:
|
||||
|
||||
```typescript
|
||||
// Common pattern for handling MCP responses
|
||||
const response = await client.callTool({ name: 'list_nodes', arguments: {} });
|
||||
|
||||
// MCP responses have content array with text objects
|
||||
expect(response.content).toBeDefined();
|
||||
expect(response.content[0].type).toBe('text');
|
||||
|
||||
// Parse the actual data
|
||||
const data = JSON.parse(response.content[0].text);
|
||||
```
|
||||
|
||||
### 2. MSW Integration Setup
|
||||
|
||||
Proper MSW setup is crucial for integration tests:
|
||||
|
||||
```typescript
|
||||
// tests/integration/setup/integration-setup.ts
|
||||
import { setupServer } from 'msw/node';
|
||||
import { handlers } from '@tests/mocks/n8n-api/handlers';
|
||||
|
||||
// Create server but don't start it globally
|
||||
const server = setupServer(...handlers);
|
||||
|
||||
beforeAll(async () => {
|
||||
// Only start MSW for integration tests
|
||||
if (process.env.MSW_ENABLED === 'true') {
|
||||
server.listen({ onUnhandledRequest: 'bypass' });
|
||||
}
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
server.close();
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Database Isolation for Parallel Tests
|
||||
|
||||
Each test gets its own database to enable parallel execution:
|
||||
|
||||
```typescript
|
||||
// tests/utils/database-utils.ts
|
||||
export function createTestDatabaseAdapter(
|
||||
db?: Database.Database,
|
||||
options: TestDatabaseOptions = {}
|
||||
): DatabaseAdapter {
|
||||
const database = db || new Database(':memory:');
|
||||
|
||||
// Enable FTS5 if needed
|
||||
if (options.enableFTS5) {
|
||||
database.exec('PRAGMA main.compile_options;');
|
||||
}
|
||||
|
||||
return new DatabaseAdapter(database);
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Environment-Aware Performance Thresholds
|
||||
|
||||
CI environments are slower, so we adjust expectations:
|
||||
|
||||
```typescript
|
||||
// Environment-aware thresholds
|
||||
const getThreshold = (local: number, ci: number) =>
|
||||
process.env.CI ? ci : local;
|
||||
|
||||
it('should respond quickly', async () => {
|
||||
const start = performance.now();
|
||||
await someOperation();
|
||||
const duration = performance.now() - start;
|
||||
|
||||
expect(duration).toBeLessThan(getThreshold(50, 200));
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Test Isolation
|
||||
- Each test creates its own database instance
|
||||
- Tests clean up after themselves
|
||||
- No shared state between tests
|
||||
|
||||
### 2. Proper Cleanup Order
|
||||
```typescript
|
||||
afterEach(async () => {
|
||||
// Close client first to ensure no pending requests
|
||||
await client.close();
|
||||
|
||||
// Give time for client to fully close
|
||||
await new Promise(resolve => setTimeout(resolve, 50));
|
||||
|
||||
// Then close server
|
||||
await mcpServer.close();
|
||||
|
||||
// Finally cleanup database
|
||||
await testDb.cleanup();
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Handle Async Operations Carefully
|
||||
```typescript
|
||||
// Avoid race conditions in cleanup
|
||||
it('should handle disconnection', async () => {
|
||||
// ... test code ...
|
||||
|
||||
// Ensure operations complete before cleanup
|
||||
await transport.close();
|
||||
await new Promise(resolve => setTimeout(resolve, 100));
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Meaningful Test Organization
|
||||
- Group related tests using `describe` blocks
|
||||
- Use descriptive test names that explain the behavior
|
||||
- Follow AAA pattern: Arrange, Act, Assert
|
||||
- Keep tests focused on single behaviors
|
||||
|
||||
## Debugging Tests
|
||||
|
||||
### Running Specific Tests
|
||||
```bash
|
||||
# Run a single test file
|
||||
npm test tests/integration/mcp-protocol/tool-invocation.test.ts
|
||||
|
||||
# Run tests matching a pattern
|
||||
npm test -- --grep "should list nodes"
|
||||
|
||||
# Run with debugging output
|
||||
DEBUG=* npm test
|
||||
```
|
||||
|
||||
### VSCode Integration
|
||||
```json
|
||||
// .vscode/launch.json
|
||||
{
|
||||
"configurations": [
|
||||
{
|
||||
"type": "node",
|
||||
"request": "launch",
|
||||
"name": "Debug Tests",
|
||||
"program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
|
||||
"args": ["run", "${file}"],
|
||||
"console": "integratedTerminal"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Test Coverage
|
||||
|
||||
While we don't enforce strict coverage thresholds yet, the infrastructure is in place:
|
||||
- Coverage reports generated in `lcov`, `html`, and `text` formats
|
||||
- Integration with Codecov for tracking coverage over time
|
||||
- Per-file coverage visible in VSCode with extensions
|
||||
|
||||
## Future Improvements
|
||||
|
||||
1. **E2E Testing**: Add Playwright for testing the full MCP server interaction
|
||||
2. **Load Testing**: Implement k6 or Artillery for stress testing
|
||||
3. **Contract Testing**: Add Pact for ensuring API compatibility
|
||||
4. **Visual Regression**: For any UI components that may be added
|
||||
5. **Mutation Testing**: Use Stryker to ensure test quality
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### 1. Tests Hanging in CI
|
||||
|
||||
**Problem**: Tests would hang indefinitely in CI due to `process.exit()` calls.
|
||||
|
||||
**Solution**: Remove all `process.exit()` calls from test code and use proper cleanup:
|
||||
```typescript
|
||||
// Bad
|
||||
afterAll(() => {
|
||||
process.exit(0); // This causes Vitest to hang
|
||||
});
|
||||
|
||||
// Good
|
||||
afterAll(async () => {
|
||||
await cleanup();
|
||||
// Let Vitest handle process termination
|
||||
});
|
||||
```
|
||||
|
||||
### 2. MCP Response Structure
|
||||
|
||||
**Problem**: Tests expecting wrong response format from MCP tools.
|
||||
|
||||
**Solution**: Always access responses through `content[0].text`:
|
||||
```typescript
|
||||
// Wrong
|
||||
const data = response[0].text;
|
||||
|
||||
// Correct
|
||||
const data = JSON.parse(response.content[0].text);
|
||||
```
|
||||
|
||||
### 3. Database Not Found Errors
|
||||
|
||||
**Problem**: Tests failing with "node not found" when database is empty.
|
||||
|
||||
**Solution**: Check for empty databases before assertions:
|
||||
```typescript
|
||||
const stats = await server.executeTool('get_database_statistics', {});
|
||||
if (stats.totalNodes > 0) {
|
||||
expect(result.nodes.length).toBeGreaterThan(0);
|
||||
} else {
|
||||
expect(result.nodes).toHaveLength(0);
|
||||
}
|
||||
```
|
||||
|
||||
### 4. MSW Loading Globally
|
||||
|
||||
**Problem**: MSW interfering with unit tests when loaded globally.
|
||||
|
||||
**Solution**: Only load MSW in integration test setup:
|
||||
```typescript
|
||||
// vitest.config.integration.ts
|
||||
setupFiles: [
|
||||
'./tests/setup/global-setup.ts',
|
||||
'./tests/integration/setup/integration-setup.ts' // MSW only here
|
||||
]
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Vitest Documentation](https://vitest.dev/)
|
||||
- [MSW Documentation](https://mswjs.io/)
|
||||
- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
|
||||
- [MCP SDK Documentation](https://modelcontextprotocol.io/)
|
||||
@@ -1,276 +0,0 @@
|
||||
# n8n-MCP Testing Implementation Checklist
|
||||
|
||||
## Test Suite Development Status
|
||||
|
||||
### Context
|
||||
- **Situation**: Building comprehensive test suite from scratch
|
||||
- **Branch**: feat/comprehensive-testing-suite (separate from main)
|
||||
- **Main Branch Status**: Working in production without tests
|
||||
- **Goal**: Add test coverage without disrupting development
|
||||
|
||||
## Immediate Actions (Day 1)
|
||||
|
||||
- [x] ~~Fix failing tests (Phase 0)~~ ✅ COMPLETED
|
||||
- [x] ~~Create GitHub Actions workflow file~~ ✅ COMPLETED
|
||||
- [x] ~~Install Vitest and remove Jest~~ ✅ COMPLETED
|
||||
- [x] ~~Create vitest.config.ts~~ ✅ COMPLETED
|
||||
- [x] ~~Setup global test configuration~~ ✅ COMPLETED
|
||||
- [x] ~~Migrate existing tests to Vitest syntax~~ ✅ COMPLETED
|
||||
- [x] ~~Setup coverage reporting with Codecov~~ ✅ COMPLETED
|
||||
|
||||
## Phase 1: Vitest Migration ✅ COMPLETED
|
||||
|
||||
All tests have been successfully migrated from Jest to Vitest:
|
||||
- ✅ Removed Jest and installed Vitest
|
||||
- ✅ Created vitest.config.ts with path aliases
|
||||
- ✅ Set up global test configuration
|
||||
- ✅ Migrated all 6 test files (68 tests passing)
|
||||
- ✅ Updated TypeScript configuration
|
||||
- ✅ Cleaned up Jest configuration files
|
||||
|
||||
## Week 1: Foundation
|
||||
|
||||
### Testing Infrastructure ✅ COMPLETED (Phase 2)
|
||||
- [x] ~~Create test directory structure~~ ✅ COMPLETED
|
||||
- [x] ~~Setup mock infrastructure for better-sqlite3~~ ✅ COMPLETED
|
||||
- [x] ~~Create mock for n8n-nodes-base package~~ ✅ COMPLETED
|
||||
- [x] ~~Setup test database utilities~~ ✅ COMPLETED
|
||||
- [x] ~~Create factory pattern for nodes~~ ✅ COMPLETED
|
||||
- [x] ~~Create builder pattern for workflows~~ ✅ COMPLETED
|
||||
- [x] ~~Setup global test utilities~~ ✅ COMPLETED
|
||||
- [x] ~~Configure test environment variables~~ ✅ COMPLETED
|
||||
|
||||
### CI/CD Pipeline ✅ COMPLETED (Phase 3.8)
|
||||
- [x] ~~GitHub Actions for test execution~~ ✅ COMPLETED & VERIFIED
|
||||
- Successfully running with Vitest
|
||||
- 1021 tests passing in CI
|
||||
- Build time: ~2 minutes
|
||||
- [x] ~~Coverage reporting integration~~ ✅ COMPLETED (Codecov setup)
|
||||
- [x] ~~Performance benchmark tracking~~ ✅ COMPLETED
|
||||
- [x] ~~Test result artifacts~~ ✅ COMPLETED
|
||||
- [ ] Branch protection rules
|
||||
- [ ] Required status checks
|
||||
|
||||
## Week 2: Mock Infrastructure
|
||||
|
||||
### Database Mocking
|
||||
- [ ] Complete better-sqlite3 mock implementation
|
||||
- [ ] Mock prepared statements
|
||||
- [ ] Mock transactions
|
||||
- [ ] Mock FTS5 search functionality
|
||||
- [ ] Test data seeding utilities
|
||||
|
||||
### External Dependencies
|
||||
- [ ] Mock axios for API calls
|
||||
- [ ] Mock file system operations
|
||||
- [ ] Mock MCP SDK
|
||||
- [ ] Mock Express server
|
||||
- [ ] Mock WebSocket connections
|
||||
|
||||
## Week 3-4: Unit Tests ✅ COMPLETED (Phase 3)
|
||||
|
||||
### Core Services (Priority 1) ✅ COMPLETED
|
||||
- [x] ~~`config-validator.ts` - 95% coverage~~ ✅ 96.9%
|
||||
- [x] ~~`enhanced-config-validator.ts` - 95% coverage~~ ✅ 94.55%
|
||||
- [x] ~~`workflow-validator.ts` - 90% coverage~~ ✅ 97.59%
|
||||
- [x] ~~`expression-validator.ts` - 90% coverage~~ ✅ 97.22%
|
||||
- [x] ~~`property-filter.ts` - 90% coverage~~ ✅ 95.25%
|
||||
- [x] ~~`example-generator.ts` - 85% coverage~~ ✅ 94.34%
|
||||
|
||||
### Parsers (Priority 2) ✅ COMPLETED
|
||||
- [x] ~~`node-parser.ts` - 90% coverage~~ ✅ 97.42%
|
||||
- [x] ~~`property-extractor.ts` - 90% coverage~~ ✅ 95.49%
|
||||
|
||||
### MCP Layer (Priority 3) ✅ COMPLETED
|
||||
- [x] ~~`tools.ts` - 90% coverage~~ ✅ 94.11%
|
||||
- [x] ~~`handlers-n8n-manager.ts` - 85% coverage~~ ✅ 92.71%
|
||||
- [x] ~~`handlers-workflow-diff.ts` - 85% coverage~~ ✅ 96.34%
|
||||
- [x] ~~`tools-documentation.ts` - 80% coverage~~ ✅ 94.12%
|
||||
|
||||
### Database Layer (Priority 4) ✅ COMPLETED
|
||||
- [x] ~~`node-repository.ts` - 85% coverage~~ ✅ 91.48%
|
||||
- [x] ~~`database-adapter.ts` - 85% coverage~~ ✅ 89.29%
|
||||
- [x] ~~`template-repository.ts` - 80% coverage~~ ✅ 86.78%
|
||||
|
||||
### Loaders and Mappers (Priority 5) ✅ COMPLETED
|
||||
- [x] ~~`node-loader.ts` - 85% coverage~~ ✅ 91.89%
|
||||
- [x] ~~`docs-mapper.ts` - 80% coverage~~ ✅ 95.45%
|
||||
|
||||
### Additional Critical Services Tested ✅ COMPLETED (Phase 3.5)
|
||||
- [x] ~~`n8n-api-client.ts`~~ ✅ 83.87%
|
||||
- [x] ~~`workflow-diff-engine.ts`~~ ✅ 90.06%
|
||||
- [x] ~~`n8n-validation.ts`~~ ✅ 97.14%
|
||||
- [x] ~~`node-specific-validators.ts`~~ ✅ 98.7%
|
||||
|
||||
## Week 5-6: Integration Tests 🚧 IN PROGRESS
|
||||
|
||||
### Real Status (July 29, 2025)
|
||||
**Context**: Building test suite from scratch on testing branch. Main branch has no tests.
|
||||
|
||||
**Overall Status**: 187/246 tests passing (76% pass rate)
|
||||
**Critical Issue**: CI shows green despite 58 failing tests due to `|| true` in workflow
|
||||
|
||||
### MCP Protocol Tests 🔄 MIXED STATUS
|
||||
- [x] ~~Full MCP server initialization~~ ✅ COMPLETED
|
||||
- [x] ~~Tool invocation flow~~ ✅ FIXED (30 tests in tool-invocation.test.ts)
|
||||
- [ ] Error handling and recovery ⚠️ 16 FAILING (error-handling.test.ts)
|
||||
- [x] ~~Concurrent request handling~~ ✅ COMPLETED
|
||||
- [ ] Session management ⚠️ 5 FAILING (timeout issues)
|
||||
|
||||
### n8n API Integration 🔄 PENDING
|
||||
- [ ] Workflow CRUD operations (MSW mocks ready)
|
||||
- [ ] Webhook triggering
|
||||
- [ ] Execution monitoring
|
||||
- [ ] Authentication handling
|
||||
- [ ] Error scenarios
|
||||
|
||||
### Database Integration ⚠️ ISSUES FOUND
|
||||
- [x] ~~SQLite operations with real DB~~ ✅ BASIC TESTS PASS
|
||||
- [ ] FTS5 search functionality ⚠️ 7 FAILING (syntax errors)
|
||||
- [ ] Transaction handling ⚠️ 1 FAILING (isolation issues)
|
||||
- [ ] Migration testing 🔄 NOT STARTED
|
||||
- [ ] Performance under load ⚠️ 4 FAILING (slower than thresholds)
|
||||
|
||||
## Week 7-8: E2E & Performance
|
||||
|
||||
### End-to-End Scenarios
|
||||
- [ ] Complete workflow creation flow
|
||||
- [ ] AI agent workflow setup
|
||||
- [ ] Template import and validation
|
||||
- [ ] Workflow execution monitoring
|
||||
- [ ] Error recovery scenarios
|
||||
|
||||
### Performance Benchmarks
|
||||
- [ ] Node loading speed (< 50ms per node)
|
||||
- [ ] Search performance (< 100ms for 1000 nodes)
|
||||
- [ ] Validation speed (< 10ms simple, < 100ms complex)
|
||||
- [ ] Database query performance
|
||||
- [ ] Memory usage profiling
|
||||
- [ ] Concurrent request handling
|
||||
|
||||
### Load Testing
|
||||
- [ ] 100 concurrent MCP requests
|
||||
- [ ] 10,000 nodes in database
|
||||
- [ ] 1,000 workflow validations/minute
|
||||
- [ ] Memory leak detection
|
||||
- [ ] Resource cleanup verification
|
||||
|
||||
## Testing Quality Gates
|
||||
|
||||
### Coverage Requirements
|
||||
- [ ] Overall: 80%+ (Currently: 62.67%)
|
||||
- [x] ~~Core services: 90%+~~ ✅ COMPLETED
|
||||
- [x] ~~MCP tools: 90%+~~ ✅ COMPLETED
|
||||
- [x] ~~Critical paths: 95%+~~ ✅ COMPLETED
|
||||
- [x] ~~New code: 90%+~~ ✅ COMPLETED
|
||||
|
||||
### Performance Requirements
|
||||
- [x] ~~All unit tests < 10ms~~ ✅ COMPLETED
|
||||
- [ ] Integration tests < 1s
|
||||
- [ ] E2E tests < 10s
|
||||
- [x] ~~Full suite < 5 minutes~~ ✅ COMPLETED (~2 minutes)
|
||||
- [x] ~~No memory leaks~~ ✅ COMPLETED
|
||||
|
||||
### Code Quality
|
||||
- [x] ~~No ESLint errors~~ ✅ COMPLETED
|
||||
- [x] ~~No TypeScript errors~~ ✅ COMPLETED
|
||||
- [x] ~~No console.log in tests~~ ✅ COMPLETED
|
||||
- [x] ~~All tests have descriptions~~ ✅ COMPLETED
|
||||
- [x] ~~No hardcoded values~~ ✅ COMPLETED
|
||||
|
||||
## Monitoring & Maintenance
|
||||
|
||||
### Daily
|
||||
- [ ] Check CI pipeline status
|
||||
- [ ] Review failed tests
|
||||
- [ ] Monitor flaky tests
|
||||
|
||||
### Weekly
|
||||
- [ ] Review coverage reports
|
||||
- [ ] Update test documentation
|
||||
- [ ] Performance benchmark review
|
||||
- [ ] Team sync on testing progress
|
||||
|
||||
### Monthly
|
||||
- [ ] Update baseline benchmarks
|
||||
- [ ] Review and refactor tests
|
||||
- [ ] Update testing strategy
|
||||
- [ ] Training/knowledge sharing
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Technical Risks
|
||||
- [ ] Mock complexity - Use simple, maintainable mocks
|
||||
- [ ] Test brittleness - Focus on behavior, not implementation
|
||||
- [ ] Performance impact - Run heavy tests in parallel
|
||||
- [ ] Flaky tests - Proper async handling and isolation
|
||||
|
||||
### Process Risks
|
||||
- [ ] Slow adoption - Provide training and examples
|
||||
- [ ] Coverage gaming - Review test quality, not just numbers
|
||||
- [ ] Maintenance burden - Automate what's possible
|
||||
- [ ] Integration complexity - Use test containers
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Current Reality Check
|
||||
- **Unit Tests**: ✅ SOLID (932 passing, 87.8% coverage)
|
||||
- **Integration Tests**: ⚠️ NEEDS WORK (58 failing, 76% pass rate)
|
||||
- **E2E Tests**: 🔄 NOT STARTED
|
||||
- **CI/CD**: ⚠️ BROKEN (hiding failures with || true)
|
||||
|
||||
### Revised Technical Metrics
|
||||
- Coverage: Currently 87.8% for unit tests ✅
|
||||
- Integration test pass rate: Target 100% (currently 76%)
|
||||
- Performance: Adjust thresholds based on reality
|
||||
- Reliability: Fix flaky tests during repair
|
||||
- Speed: CI pipeline < 5 minutes ✅ (~2 minutes)
|
||||
|
||||
### Team Metrics
|
||||
- All developers writing tests ✅
|
||||
- Tests reviewed in PRs ✅
|
||||
- No production bugs from tested code
|
||||
- Improved development velocity ✅
|
||||
|
||||
## Phases Completed
|
||||
|
||||
- **Phase 0**: Immediate Fixes ✅ COMPLETED
|
||||
- **Phase 1**: Vitest Migration ✅ COMPLETED
|
||||
- **Phase 2**: Test Infrastructure ✅ COMPLETED
|
||||
- **Phase 3**: Unit Tests (All 943 tests) ✅ COMPLETED
|
||||
- **Phase 3.5**: Critical Service Testing ✅ COMPLETED
|
||||
- **Phase 3.8**: CI/CD & Infrastructure ✅ COMPLETED
|
||||
- **Phase 4**: Integration Tests 🚧 IN PROGRESS
|
||||
- **Status**: 58 out of 246 tests failing (23.6% failure rate)
|
||||
- **CI Issue**: Tests appear green due to `|| true` error suppression
|
||||
- **Categories of Failures**:
|
||||
- Database: 9 tests (state isolation, FTS5 syntax)
|
||||
- MCP Protocol: 16 tests (response structure in error-handling.test.ts)
|
||||
- MSW: 6 tests (not initialized properly)
|
||||
- FTS5 Search: 7 tests (query syntax issues)
|
||||
- Session Management: 5 tests (async cleanup)
|
||||
- Performance: 15 tests (threshold mismatches)
|
||||
- **Next Steps**:
|
||||
1. Get team buy-in for "red" CI
|
||||
2. Remove `|| true` from workflow
|
||||
3. Fix tests systematically by category
|
||||
- **Phase 5**: E2E Tests 🔄 PENDING
|
||||
|
||||
## Resources & Tools
|
||||
|
||||
### Documentation
|
||||
- Vitest: https://vitest.dev/
|
||||
- Testing Library: https://testing-library.com/
|
||||
- MSW: https://mswjs.io/
|
||||
- Testcontainers: https://www.testcontainers.com/
|
||||
|
||||
### Monitoring
|
||||
- Codecov: https://codecov.io/
|
||||
- GitHub Actions: https://github.com/features/actions
|
||||
- Benchmark Action: https://github.com/benchmark-action/github-action-benchmark
|
||||
|
||||
### Team Resources
|
||||
- Testing best practices guide
|
||||
- Example test implementations
|
||||
- Mock usage patterns
|
||||
- Performance optimization tips
|
||||
@@ -1,472 +0,0 @@
|
||||
# n8n-MCP Testing Implementation Guide
|
||||
|
||||
## Phase 1: Foundation Setup (Week 1-2)
|
||||
|
||||
### 1.1 Install Vitest and Dependencies
|
||||
|
||||
```bash
|
||||
# Remove Jest
|
||||
npm uninstall jest ts-jest @types/jest
|
||||
|
||||
# Install Vitest and related packages
|
||||
npm install -D vitest @vitest/ui @vitest/coverage-v8
|
||||
npm install -D @testing-library/jest-dom
|
||||
npm install -D msw # For API mocking
|
||||
npm install -D @faker-js/faker # For test data
|
||||
npm install -D fishery # For factories
|
||||
```
|
||||
|
||||
### 1.2 Update package.json Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// Testing
|
||||
"test": "vitest",
|
||||
"test:ui": "vitest --ui",
|
||||
"test:unit": "vitest run tests/unit",
|
||||
"test:integration": "vitest run tests/integration",
|
||||
"test:e2e": "vitest run tests/e2e",
|
||||
"test:watch": "vitest watch",
|
||||
"test:coverage": "vitest run --coverage",
|
||||
"test:coverage:check": "vitest run --coverage --coverage.thresholdAutoUpdate=false",
|
||||
|
||||
// Benchmarks
|
||||
"bench": "vitest bench",
|
||||
"bench:compare": "vitest bench --compare",
|
||||
|
||||
// CI specific
|
||||
"test:ci": "vitest run --reporter=junit --reporter=default",
|
||||
"test:ci:coverage": "vitest run --coverage --reporter=junit --reporter=default"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 Migrate Existing Tests
|
||||
|
||||
```typescript
|
||||
// Before (Jest)
|
||||
import { describe, test, expect } from '@jest/globals';
|
||||
|
||||
// After (Vitest)
|
||||
import { describe, it, expect, vi } from 'vitest';
|
||||
|
||||
// Update mock syntax
|
||||
// Jest: jest.mock('module')
|
||||
// Vitest: vi.mock('module')
|
||||
|
||||
// Update timer mocks
|
||||
// Jest: jest.useFakeTimers()
|
||||
// Vitest: vi.useFakeTimers()
|
||||
```
|
||||
|
||||
### 1.4 Create Test Database Setup
|
||||
|
||||
```typescript
|
||||
// tests/setup/test-database.ts
|
||||
import Database from 'better-sqlite3';
|
||||
import { readFileSync } from 'fs';
|
||||
import { join } from 'path';
|
||||
|
||||
export class TestDatabase {
|
||||
private db: Database.Database;
|
||||
|
||||
constructor() {
|
||||
this.db = new Database(':memory:');
|
||||
this.initialize();
|
||||
}
|
||||
|
||||
private initialize() {
|
||||
const schema = readFileSync(
|
||||
join(__dirname, '../../src/database/schema.sql'),
|
||||
'utf8'
|
||||
);
|
||||
this.db.exec(schema);
|
||||
}
|
||||
|
||||
seedNodes(nodes: any[]) {
|
||||
const stmt = this.db.prepare(`
|
||||
INSERT INTO nodes (type, displayName, name, group, version, description, properties)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?)
|
||||
`);
|
||||
|
||||
const insertMany = this.db.transaction((nodes) => {
|
||||
for (const node of nodes) {
|
||||
stmt.run(
|
||||
node.type,
|
||||
node.displayName,
|
||||
node.name,
|
||||
node.group,
|
||||
node.version,
|
||||
node.description,
|
||||
JSON.stringify(node.properties)
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
insertMany(nodes);
|
||||
}
|
||||
|
||||
close() {
|
||||
this.db.close();
|
||||
}
|
||||
|
||||
getDb() {
|
||||
return this.db;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 2: Core Unit Tests (Week 3-4)
|
||||
|
||||
### 2.1 Test Organization Template
|
||||
|
||||
```typescript
|
||||
// tests/unit/services/[service-name].test.ts
|
||||
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
|
||||
import { ServiceName } from '@/services/service-name';
|
||||
|
||||
describe('ServiceName', () => {
|
||||
let service: ServiceName;
|
||||
let mockDependency: any;
|
||||
|
||||
beforeEach(() => {
|
||||
// Setup mocks
|
||||
mockDependency = {
|
||||
method: vi.fn()
|
||||
};
|
||||
|
||||
// Create service instance
|
||||
service = new ServiceName(mockDependency);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
describe('methodName', () => {
|
||||
it('should handle happy path', async () => {
|
||||
// Arrange
|
||||
const input = { /* test data */ };
|
||||
mockDependency.method.mockResolvedValue({ /* mock response */ });
|
||||
|
||||
// Act
|
||||
const result = await service.methodName(input);
|
||||
|
||||
// Assert
|
||||
expect(result).toEqual(/* expected output */);
|
||||
expect(mockDependency.method).toHaveBeenCalledWith(/* expected args */);
|
||||
});
|
||||
|
||||
it('should handle errors gracefully', async () => {
|
||||
// Arrange
|
||||
mockDependency.method.mockRejectedValue(new Error('Test error'));
|
||||
|
||||
// Act & Assert
|
||||
await expect(service.methodName({})).rejects.toThrow('Expected error message');
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 2.2 Mock Strategies by Layer
|
||||
|
||||
#### Database Layer
|
||||
```typescript
|
||||
// tests/unit/database/node-repository.test.ts
|
||||
import { vi } from 'vitest';
|
||||
|
||||
vi.mock('better-sqlite3', () => ({
|
||||
default: vi.fn(() => ({
|
||||
prepare: vi.fn(() => ({
|
||||
all: vi.fn(() => mockData),
|
||||
get: vi.fn((id) => mockData.find(d => d.id === id)),
|
||||
run: vi.fn(() => ({ changes: 1 }))
|
||||
})),
|
||||
exec: vi.fn(),
|
||||
close: vi.fn()
|
||||
}))
|
||||
}));
|
||||
```
|
||||
|
||||
#### External APIs
|
||||
```typescript
|
||||
// tests/unit/services/__mocks__/axios.ts
|
||||
export default {
|
||||
create: vi.fn(() => ({
|
||||
get: vi.fn(() => Promise.resolve({ data: {} })),
|
||||
post: vi.fn(() => Promise.resolve({ data: { id: '123' } })),
|
||||
put: vi.fn(() => Promise.resolve({ data: {} })),
|
||||
delete: vi.fn(() => Promise.resolve({ data: {} }))
|
||||
}))
|
||||
};
|
||||
```
|
||||
|
||||
#### File System
|
||||
```typescript
|
||||
// Use memfs for file system mocking
|
||||
import { vol } from 'memfs';
|
||||
|
||||
vi.mock('fs', () => vol);
|
||||
|
||||
beforeEach(() => {
|
||||
vol.reset();
|
||||
vol.fromJSON({
|
||||
'/test/file.json': JSON.stringify({ test: 'data' })
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 2.3 Critical Path Tests
|
||||
|
||||
```typescript
|
||||
// Priority 1: Node Loading and Parsing
|
||||
// tests/unit/loaders/node-loader.test.ts
|
||||
|
||||
// Priority 2: Configuration Validation
|
||||
// tests/unit/services/config-validator.test.ts
|
||||
|
||||
// Priority 3: MCP Tools
|
||||
// tests/unit/mcp/tools.test.ts
|
||||
|
||||
// Priority 4: Database Operations
|
||||
// tests/unit/database/node-repository.test.ts
|
||||
|
||||
// Priority 5: Workflow Validation
|
||||
// tests/unit/services/workflow-validator.test.ts
|
||||
```
|
||||
|
||||
## Phase 3: Integration Tests (Week 5-6)
|
||||
|
||||
### 3.1 Test Container Setup
|
||||
|
||||
```typescript
|
||||
// tests/setup/test-containers.ts
|
||||
import { GenericContainer, StartedTestContainer } from 'testcontainers';
|
||||
|
||||
export class N8nTestContainer {
|
||||
private container: StartedTestContainer;
|
||||
|
||||
async start() {
|
||||
this.container = await new GenericContainer('n8nio/n8n:latest')
|
||||
.withExposedPorts(5678)
|
||||
.withEnv('N8N_BASIC_AUTH_ACTIVE', 'false')
|
||||
.withEnv('N8N_ENCRYPTION_KEY', 'test-key')
|
||||
.start();
|
||||
|
||||
return {
|
||||
url: `http://localhost:${this.container.getMappedPort(5678)}`,
|
||||
stop: () => this.container.stop()
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Integration Test Pattern
|
||||
|
||||
```typescript
|
||||
// tests/integration/n8n-api/workflow-crud.test.ts
|
||||
import { N8nTestContainer } from '@tests/setup/test-containers';
|
||||
import { N8nAPIClient } from '@/services/n8n-api-client';
|
||||
|
||||
describe('n8n API Integration', () => {
|
||||
let container: any;
|
||||
let apiClient: N8nAPIClient;
|
||||
|
||||
beforeAll(async () => {
|
||||
container = await new N8nTestContainer().start();
|
||||
apiClient = new N8nAPIClient(container.url);
|
||||
}, 30000);
|
||||
|
||||
afterAll(async () => {
|
||||
await container.stop();
|
||||
});
|
||||
|
||||
it('should create and retrieve workflow', async () => {
|
||||
// Create workflow
|
||||
const workflow = createTestWorkflow();
|
||||
const created = await apiClient.createWorkflow(workflow);
|
||||
|
||||
expect(created.id).toBeDefined();
|
||||
|
||||
// Retrieve workflow
|
||||
const retrieved = await apiClient.getWorkflow(created.id);
|
||||
expect(retrieved.name).toBe(workflow.name);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Phase 4: E2E & Performance (Week 7-8)
|
||||
|
||||
### 4.1 E2E Test Setup
|
||||
|
||||
```typescript
|
||||
// tests/e2e/workflows/complete-workflow.test.ts
|
||||
import { MCPClient } from '@tests/utils/mcp-client';
|
||||
import { N8nTestContainer } from '@tests/setup/test-containers';
|
||||
|
||||
describe('Complete Workflow E2E', () => {
|
||||
let mcpServer: any;
|
||||
let n8nContainer: any;
|
||||
let mcpClient: MCPClient;
|
||||
|
||||
beforeAll(async () => {
|
||||
// Start n8n
|
||||
n8nContainer = await new N8nTestContainer().start();
|
||||
|
||||
// Start MCP server
|
||||
mcpServer = await startMCPServer({
|
||||
n8nUrl: n8nContainer.url
|
||||
});
|
||||
|
||||
// Create MCP client
|
||||
mcpClient = new MCPClient(mcpServer.url);
|
||||
}, 60000);
|
||||
|
||||
it('should execute complete workflow creation flow', async () => {
|
||||
// 1. Search for nodes
|
||||
const searchResult = await mcpClient.call('search_nodes', {
|
||||
query: 'webhook http slack'
|
||||
});
|
||||
|
||||
// 2. Get node details
|
||||
const webhookInfo = await mcpClient.call('get_node_info', {
|
||||
nodeType: 'nodes-base.webhook'
|
||||
});
|
||||
|
||||
// 3. Create workflow
|
||||
const workflow = new WorkflowBuilder('E2E Test')
|
||||
.addWebhookNode()
|
||||
.addHttpRequestNode()
|
||||
.addSlackNode()
|
||||
.connectSequentially()
|
||||
.build();
|
||||
|
||||
// 4. Validate workflow
|
||||
const validation = await mcpClient.call('validate_workflow', {
|
||||
workflow
|
||||
});
|
||||
|
||||
expect(validation.isValid).toBe(true);
|
||||
|
||||
// 5. Deploy to n8n
|
||||
const deployed = await mcpClient.call('n8n_create_workflow', {
|
||||
...workflow
|
||||
});
|
||||
|
||||
expect(deployed.id).toBeDefined();
|
||||
expect(deployed.active).toBe(false);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 4.2 Performance Benchmarks
|
||||
|
||||
```typescript
|
||||
// vitest.benchmark.config.ts
|
||||
export default {
|
||||
test: {
|
||||
benchmark: {
|
||||
// Output benchmark results
|
||||
outputFile: './benchmark-results.json',
|
||||
|
||||
// Compare with baseline
|
||||
compare: './benchmark-baseline.json',
|
||||
|
||||
// Fail if performance degrades by more than 10%
|
||||
threshold: {
|
||||
p95: 1.1, // 110% of baseline
|
||||
p99: 1.2 // 120% of baseline
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Testing Best Practices
|
||||
|
||||
### 1. Test Naming Convention
|
||||
```typescript
|
||||
// Format: should [expected behavior] when [condition]
|
||||
it('should return user data when valid ID is provided')
|
||||
it('should throw ValidationError when email is invalid')
|
||||
it('should retry 3 times when network fails')
|
||||
```
|
||||
|
||||
### 2. Test Data Builders
|
||||
```typescript
|
||||
// Use builders for complex test data
|
||||
const user = new UserBuilder()
|
||||
.withEmail('test@example.com')
|
||||
.withRole('admin')
|
||||
.build();
|
||||
```
|
||||
|
||||
### 3. Custom Matchers
|
||||
```typescript
|
||||
// tests/utils/matchers.ts
|
||||
export const toBeValidNode = (received: any) => {
|
||||
const pass =
|
||||
received.type &&
|
||||
received.displayName &&
|
||||
received.properties &&
|
||||
Array.isArray(received.properties);
|
||||
|
||||
return {
|
||||
pass,
|
||||
message: () => `expected ${received} to be a valid node`
|
||||
};
|
||||
};
|
||||
|
||||
// Usage
|
||||
expect(node).toBeValidNode();
|
||||
```
|
||||
|
||||
### 4. Snapshot Testing
|
||||
```typescript
|
||||
// For complex structures
|
||||
it('should generate correct node schema', () => {
|
||||
const schema = generateNodeSchema(node);
|
||||
expect(schema).toMatchSnapshot();
|
||||
});
|
||||
```
|
||||
|
||||
### 5. Test Isolation
|
||||
```typescript
|
||||
// Always clean up after tests
|
||||
afterEach(async () => {
|
||||
await cleanup();
|
||||
vi.clearAllMocks();
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
```
|
||||
|
||||
## Coverage Goals by Module
|
||||
|
||||
| Module | Target | Priority | Notes |
|
||||
|--------|--------|----------|-------|
|
||||
| services/config-validator | 95% | High | Critical for reliability |
|
||||
| services/workflow-validator | 90% | High | Core functionality |
|
||||
| mcp/tools | 90% | High | User-facing API |
|
||||
| database/node-repository | 85% | Medium | Well-tested DB layer |
|
||||
| loaders/node-loader | 85% | Medium | External dependencies |
|
||||
| parsers/* | 90% | High | Data transformation |
|
||||
| utils/* | 80% | Low | Helper functions |
|
||||
| scripts/* | 50% | Low | One-time scripts |
|
||||
|
||||
## Continuous Improvement
|
||||
|
||||
1. **Weekly Reviews**: Review test coverage and identify gaps
|
||||
2. **Performance Baselines**: Update benchmarks monthly
|
||||
3. **Flaky Test Detection**: Monitor and fix within 48 hours
|
||||
4. **Test Documentation**: Keep examples updated
|
||||
5. **Developer Training**: Pair programming on tests
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- [ ] All tests pass in CI (0 failures)
|
||||
- [ ] Coverage > 80% overall
|
||||
- [ ] No flaky tests
|
||||
- [ ] CI runs < 5 minutes
|
||||
- [ ] Performance benchmarks stable
|
||||
- [ ] Zero production bugs from tested code
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,66 +0,0 @@
|
||||
# Token Efficiency Improvements Summary
|
||||
|
||||
## Overview
|
||||
Made all MCP tool descriptions concise and token-efficient while preserving essential information.
|
||||
|
||||
## Key Improvements
|
||||
|
||||
### Before vs After Examples
|
||||
|
||||
1. **search_nodes**
|
||||
- Before: ~350 chars with verbose explanation
|
||||
- After: 165 chars
|
||||
- `Search nodes by keywords. Modes: OR (any word), AND (all words), FUZZY (typos OK). Primary nodes ranked first. Examples: "webhook"→Webhook, "http call"→HTTP Request.`
|
||||
|
||||
2. **get_node_info**
|
||||
- Before: ~450 chars with warnings about size
|
||||
- After: 174 chars
|
||||
- `Get FULL node schema (100KB+). TIP: Use get_node_essentials first! Returns all properties/operations/credentials. Prefix required: "nodes-base.httpRequest" not "httpRequest".`
|
||||
|
||||
3. **validate_node_minimal**
|
||||
- Before: ~350 chars explaining what it doesn't do
|
||||
- After: 102 chars
|
||||
- `Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.`
|
||||
|
||||
4. **get_property_dependencies**
|
||||
- Before: ~400 chars with full example
|
||||
- After: 131 chars
|
||||
- `Shows property dependencies and visibility rules. Example: sendBody=true reveals body fields. Test visibility with optional config.`
|
||||
|
||||
## Statistics
|
||||
|
||||
### Documentation Tools (22 tools)
|
||||
- Average description length: **129 characters**
|
||||
- Total characters: 2,836
|
||||
- Tools over 200 chars: 1 (list_nodes at 204)
|
||||
|
||||
### Management Tools (17 tools)
|
||||
- Average description length: **93 characters**
|
||||
- Total characters: 1,578
|
||||
- Tools over 200 chars: 1 (n8n_update_partial_workflow at 284)
|
||||
|
||||
## Strategy Used
|
||||
|
||||
1. **Remove redundancy**: Eliminated repeated information available in parameter descriptions
|
||||
2. **Use abbreviations**: "vs" instead of "versus", "&" instead of "and" where appropriate
|
||||
3. **Compact examples**: `"webhook"→Webhook` instead of verbose explanations
|
||||
4. **Direct language**: "Fast check" instead of "Quick validation that only checks"
|
||||
5. **Move details to documentation**: Complex tools reference `tools_documentation()` for full details
|
||||
6. **Essential info only**: Focus on what the tool does, not how it works internally
|
||||
|
||||
## Special Cases
|
||||
|
||||
### n8n_update_partial_workflow
|
||||
This tool's description is necessarily longer (284 chars) because:
|
||||
- Lists all 13 operation types
|
||||
- Critical for users to know available operations
|
||||
- Directs to full documentation for details
|
||||
|
||||
### Complex Documentation Preserved
|
||||
For tools like `n8n_update_partial_workflow`, detailed documentation was moved to `tools-documentation.ts` rather than deleted, ensuring users can still access comprehensive information when needed.
|
||||
|
||||
## Impact
|
||||
- **Token savings**: ~65-70% reduction in description tokens
|
||||
- **Faster AI responses**: Less context used for tool descriptions
|
||||
- **Better UX**: Clearer, more scannable tool list
|
||||
- **Maintained functionality**: All essential information preserved
|
||||
@@ -1,118 +0,0 @@
|
||||
# Transactional Updates Example
|
||||
|
||||
This example demonstrates the new transactional update capabilities in v2.7.0.
|
||||
|
||||
## Before (v2.6.x and earlier)
|
||||
|
||||
Previously, you had to carefully order operations to ensure nodes existed before connecting them:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
// 1. First add all nodes
|
||||
{ "type": "addNode", "node": { "name": "Process", "type": "n8n-nodes-base.set", ... }},
|
||||
{ "type": "addNode", "node": { "name": "Notify", "type": "n8n-nodes-base.slack", ... }},
|
||||
|
||||
// 2. Then add connections (would fail if done before nodes)
|
||||
{ "type": "addConnection", "source": "Webhook", "target": "Process" },
|
||||
{ "type": "addConnection", "source": "Process", "target": "Notify" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## After (v2.7.0+)
|
||||
|
||||
Now you can write operations in any order - the engine automatically handles dependencies:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
// Connections can come first!
|
||||
{ "type": "addConnection", "source": "Webhook", "target": "Process" },
|
||||
{ "type": "addConnection", "source": "Process", "target": "Notify" },
|
||||
|
||||
// Nodes added later - still works!
|
||||
{ "type": "addNode", "node": { "name": "Process", "type": "n8n-nodes-base.set", "position": [400, 300] }},
|
||||
{ "type": "addNode", "node": { "name": "Notify", "type": "n8n-nodes-base.slack", "position": [600, 300] }}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Two-Pass Processing**:
|
||||
- Pass 1: All node operations (add, remove, update, move, enable, disable)
|
||||
- Pass 2: All other operations (connections, settings, metadata)
|
||||
|
||||
2. **Operation Limit**: Maximum 5 operations per request keeps complexity manageable
|
||||
|
||||
3. **Atomic Updates**: All operations succeed or all fail - no partial updates
|
||||
|
||||
## Benefits for AI Agents
|
||||
|
||||
- **Intuitive**: Write operations in the order that makes sense logically
|
||||
- **Reliable**: No need to track dependencies manually
|
||||
- **Simple**: Focus on what to change, not how to order changes
|
||||
- **Safe**: Built-in limits prevent overly complex operations
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a real-world example of adding error handling to a workflow:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "workflow-123",
|
||||
"operations": [
|
||||
// Define the flow first (makes logical sense)
|
||||
{
|
||||
"type": "removeConnection",
|
||||
"source": "HTTP Request",
|
||||
"target": "Save to DB"
|
||||
},
|
||||
{
|
||||
"type": "addConnection",
|
||||
"source": "HTTP Request",
|
||||
"target": "Error Handler"
|
||||
},
|
||||
{
|
||||
"type": "addConnection",
|
||||
"source": "Error Handler",
|
||||
"target": "Send Alert"
|
||||
},
|
||||
|
||||
// Then add the nodes
|
||||
{
|
||||
"type": "addNode",
|
||||
"node": {
|
||||
"name": "Error Handler",
|
||||
"type": "n8n-nodes-base.if",
|
||||
"position": [500, 400],
|
||||
"parameters": {
|
||||
"conditions": {
|
||||
"boolean": [{
|
||||
"value1": "={{$json.error}}",
|
||||
"value2": true
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "addNode",
|
||||
"node": {
|
||||
"name": "Send Alert",
|
||||
"type": "n8n-nodes-base.emailSend",
|
||||
"position": [700, 400],
|
||||
"parameters": {
|
||||
"to": "alerts@company.com",
|
||||
"subject": "Workflow Error Alert"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
All operations will be processed correctly, even though connections reference nodes that don't exist yet!
|
||||
@@ -1,92 +0,0 @@
|
||||
# Validation Improvements v2.4.2
|
||||
|
||||
Based on AI agent feedback, we've implemented several improvements to the `validate_node_operation` tool:
|
||||
|
||||
## 🎯 Issues Addressed
|
||||
|
||||
### 1. **@version Warnings** ✅ FIXED
|
||||
- **Issue**: Showed confusing warnings about `@version` property not being used
|
||||
- **Fix**: Filter out internal properties starting with `@` or `_`
|
||||
- **Result**: No more false warnings about internal n8n properties
|
||||
|
||||
### 2. **Duplicate Errors** ✅ FIXED
|
||||
- **Issue**: Same error shown multiple times (e.g., missing `ts` field)
|
||||
- **Fix**: Implemented deduplication that keeps the most specific error message
|
||||
- **Result**: Each error shown only once with the best description
|
||||
|
||||
### 3. **Basic Code Validation** ✅ ADDED
|
||||
- **Issue**: No syntax validation for Code node
|
||||
- **Fix**: Added basic syntax checks for JavaScript and Python
|
||||
- **Features**:
|
||||
- Unbalanced braces/parentheses detection
|
||||
- Python indentation consistency check
|
||||
- n8n-specific patterns (return statement, input access)
|
||||
- Security warnings (eval/exec usage)
|
||||
|
||||
## 📊 Before & After
|
||||
|
||||
### Before (v2.4.1):
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{ "property": "ts", "message": "Required property 'Message Timestamp' is missing" },
|
||||
{ "property": "ts", "message": "Message timestamp (ts) is required to update a message" }
|
||||
],
|
||||
"warnings": [
|
||||
{ "property": "@version", "message": "Property '@version' is configured but won't be used" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### After (v2.4.2):
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{ "property": "ts", "message": "Message timestamp (ts) is required to update a message",
|
||||
"fix": "Provide the timestamp of the message to update" }
|
||||
],
|
||||
"warnings": [] // No @version warning
|
||||
}
|
||||
```
|
||||
|
||||
## 🆕 Code Validation Examples
|
||||
|
||||
### JavaScript Syntax Check:
|
||||
```javascript
|
||||
// Missing closing brace
|
||||
if (true) {
|
||||
return items;
|
||||
// Error: "Unbalanced braces detected"
|
||||
```
|
||||
|
||||
### Python Indentation Check:
|
||||
```python
|
||||
def process():
|
||||
if True: # Tab
|
||||
return items # Spaces
|
||||
# Error: "Mixed tabs and spaces in indentation"
|
||||
```
|
||||
|
||||
### n8n Pattern Check:
|
||||
```javascript
|
||||
const result = items.map(item => item.json);
|
||||
// Warning: "No return statement found"
|
||||
// Suggestion: "Add: return items;"
|
||||
```
|
||||
|
||||
## 🚀 Impact
|
||||
|
||||
- **Cleaner validation results** - No more noise from internal properties
|
||||
- **Clearer error messages** - Each issue reported once with best description
|
||||
- **Better code quality** - Basic syntax validation catches common mistakes
|
||||
- **n8n best practices** - Warns about missing return statements and input handling
|
||||
|
||||
## 📝 Summary
|
||||
|
||||
The `validate_node_operation` tool is now even more helpful for AI agents and developers:
|
||||
- 95% reduction in false positives (operation-aware)
|
||||
- No duplicate or confusing warnings
|
||||
- Basic code validation for common syntax errors
|
||||
- n8n-specific pattern checking
|
||||
|
||||
**Rating improved from 9/10 to 9.5/10!** 🎉
|
||||
Reference in New Issue
Block a user