mirror of
https://github.com/czlonkowski/n8n-mcp.git
synced 2026-01-30 22:42:04 +00:00
Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
05424f66af | ||
|
|
9050967cd6 |
195
CHANGELOG.md
195
CHANGELOG.md
@@ -7,6 +7,201 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [2.24.1] - 2025-01-24
|
||||
|
||||
### ✨ Features
|
||||
|
||||
**Session Persistence API**
|
||||
|
||||
Added export/restore functionality for MCP sessions to enable zero-downtime deployments in container environments (Kubernetes, Docker Swarm, etc.).
|
||||
|
||||
#### What's New
|
||||
|
||||
**1. Export Session State**
|
||||
- `exportSessionState()` method in `SingleSessionHTTPServer` and `N8NMCPEngine`
|
||||
- Exports all active sessions with metadata and instance context
|
||||
- Automatically filters expired sessions
|
||||
- Returns serializable `SessionState[]` array
|
||||
|
||||
**2. Restore Session State**
|
||||
- `restoreSessionState(sessions)` method for session recovery
|
||||
- Validates session structure using existing `validateInstanceContext()`
|
||||
- Handles null/invalid sessions gracefully with warnings
|
||||
- Enforces MAX_SESSIONS limit (100 concurrent sessions)
|
||||
- Skips expired sessions during restore
|
||||
|
||||
**3. SessionState Type**
|
||||
- New type definition in `src/types/session-state.ts`
|
||||
- Fully documented with JSDoc comments
|
||||
- Includes metadata (timestamps) and context (credentials)
|
||||
- Exported from main package index
|
||||
|
||||
**4. Dormant Session Behavior**
|
||||
- Restored sessions are "dormant" until first request
|
||||
- Transport and server objects recreated on-demand
|
||||
- Memory-efficient session recovery
|
||||
|
||||
#### Security Considerations
|
||||
|
||||
⚠️ **IMPORTANT:** Exported session data contains plaintext n8n API keys. Downstream applications MUST encrypt session data before persisting to disk using AES-256-GCM or equivalent.
|
||||
|
||||
#### Use Cases
|
||||
- Zero-downtime deployments in container orchestration
|
||||
- Session recovery after crashes or restarts
|
||||
- Multi-tenant platform session management
|
||||
- Rolling updates without user disruption
|
||||
|
||||
#### Testing
|
||||
- 22 comprehensive unit tests (100% passing)
|
||||
- Tests cover export, restore, edge cases, and round-trip cycles
|
||||
- Validation of expired session filtering and error handling
|
||||
|
||||
#### Implementation Details
|
||||
- Only exports sessions with valid `n8nApiUrl` and `n8nApiKey` in context
|
||||
- Respects `sessionTimeout` setting (default 30 minutes)
|
||||
- Session metadata and context persisted; transport/server recreated on-demand
|
||||
- Comprehensive error handling with detailed logging
|
||||
|
||||
**Conceived by Romuald Członkowski - [AiAdvisors](https://www.aiadvisors.pl/en)**
|
||||
|
||||
## [2.24.0] - 2025-01-24
|
||||
|
||||
### ✨ Features
|
||||
|
||||
**Unified Node Information Tool**
|
||||
|
||||
Introduced `get_node` - a unified tool that consolidates and enhances node information retrieval with multiple detail levels, version history, and type structure metadata.
|
||||
|
||||
#### What's New
|
||||
|
||||
**1. Progressive Detail Levels**
|
||||
- `minimal`: Basic metadata only (~200 tokens) - nodeType, displayName, description, category, version summary
|
||||
- `standard`: Essential properties and operations - AI-friendly default (~1000-2000 tokens)
|
||||
- `full`: Complete node information including all properties (~3000-8000 tokens)
|
||||
|
||||
**2. Version History & Management**
|
||||
- `versions` mode: List all versions with breaking changes summary
|
||||
- `compare` mode: Compare two versions with property-level changes
|
||||
- `breaking` mode: Show only breaking changes between versions
|
||||
- `migrations` mode: Show auto-migratable changes
|
||||
- Version summary always included in info mode responses
|
||||
|
||||
**3. Type Structure Metadata**
|
||||
- `includeTypeInfo` parameter exposes type structures from v2.23.0 validation system
|
||||
- Includes: type category, JS type, validation rules, structure hints
|
||||
- Helps AI agents understand complex types (filter, resourceMapper, resourceLocator, etc.)
|
||||
- Adds ~80-120 tokens per property when enabled
|
||||
- Works with all detail levels
|
||||
|
||||
**4. Real-World Examples**
|
||||
- `includeExamples` parameter includes configuration examples from templates
|
||||
- Shows popular workflow patterns
|
||||
- Includes metadata (views, complexity, use cases)
|
||||
|
||||
#### Usage Examples
|
||||
|
||||
```javascript
|
||||
// Standard detail (recommended for AI agents)
|
||||
get_node({nodeType: "nodes-base.httpRequest"})
|
||||
|
||||
// Standard with type info
|
||||
get_node({nodeType: "nodes-base.httpRequest", includeTypeInfo: true})
|
||||
|
||||
// Minimal (quick metadata check)
|
||||
get_node({nodeType: "nodes-base.httpRequest", detail: "minimal"})
|
||||
|
||||
// Full detail with examples
|
||||
get_node({nodeType: "nodes-base.httpRequest", detail: "full", includeExamples: true})
|
||||
|
||||
// Version history
|
||||
get_node({nodeType: "nodes-base.httpRequest", mode: "versions"})
|
||||
|
||||
// Compare versions
|
||||
get_node({
|
||||
nodeType: "nodes-base.httpRequest",
|
||||
mode: "compare",
|
||||
fromVersion: "3.0",
|
||||
toVersion: "4.1"
|
||||
})
|
||||
```
|
||||
|
||||
#### Benefits
|
||||
|
||||
- ✅ **Single Unified API**: One tool for all node information needs
|
||||
- ✅ **Token Efficient**: AI-friendly defaults (standard mode recommended)
|
||||
- ✅ **Progressive Disclosure**: minimal → standard → full as needed
|
||||
- ✅ **Type Aware**: Exposes v2.23.0 type structures for better configuration
|
||||
- ✅ **Version Aware**: Built-in version history and comparison
|
||||
- ✅ **Flexible**: Can combine detail levels with type info and examples
|
||||
- ✅ **Discoverable**: Version summary always visible in info mode
|
||||
|
||||
#### Token Costs
|
||||
|
||||
- `minimal`: ~200 tokens
|
||||
- `standard`: ~1000-2000 tokens (default)
|
||||
- `full`: ~3000-8000 tokens
|
||||
- `includeTypeInfo`: +80-120 tokens per property
|
||||
- `includeExamples`: +200-400 tokens per example
|
||||
- Version modes: ~400-1200 tokens
|
||||
|
||||
### 🗑️ Breaking Changes
|
||||
|
||||
**Removed Deprecated Tools**
|
||||
|
||||
Immediately removed `get_node_info` and `get_node_essentials` in favor of the unified `get_node` tool:
|
||||
- `get_node_info` → Use `get_node` with `detail='full'`
|
||||
- `get_node_essentials` → Use `get_node` with `detail='standard'` (default)
|
||||
|
||||
**Migration:**
|
||||
```javascript
|
||||
// Old
|
||||
get_node_info({nodeType: "nodes-base.httpRequest"})
|
||||
// New
|
||||
get_node({nodeType: "nodes-base.httpRequest", detail: "full"})
|
||||
|
||||
// Old
|
||||
get_node_essentials({nodeType: "nodes-base.httpRequest", includeExamples: true})
|
||||
// New
|
||||
get_node({nodeType: "nodes-base.httpRequest", includeExamples: true})
|
||||
// or
|
||||
get_node({nodeType: "nodes-base.httpRequest", detail: "standard", includeExamples: true})
|
||||
```
|
||||
|
||||
### 📊 Impact
|
||||
|
||||
**Tool Count**: 40 → 39 tools (-2 deprecated, +1 new unified)
|
||||
|
||||
**For AI Agents:**
|
||||
- Better understanding of complex n8n types through type metadata
|
||||
- Version upgrade planning with breaking change detection
|
||||
- Token-efficient defaults reduce costs
|
||||
- Progressive disclosure of information as needed
|
||||
|
||||
**For Users:**
|
||||
- Single tool to learn instead of two separate tools
|
||||
- Clear progression from minimal to full detail
|
||||
- Version history helps with node upgrades
|
||||
- Type-aware configuration assistance
|
||||
|
||||
### 🔧 Technical Details
|
||||
|
||||
**Files Added:**
|
||||
- Enhanced type structure exposure in node information
|
||||
|
||||
**Files Modified:**
|
||||
- `src/mcp/tools.ts` - Removed get_node_info and get_node_essentials, added get_node
|
||||
- `src/mcp/server.ts` - Added unified getNode() implementation with all modes
|
||||
- `package.json` - Version bump to 2.24.0
|
||||
|
||||
**Implementation:**
|
||||
- ~250 lines of new code
|
||||
- 7 new private methods for mode handling
|
||||
- Version repository methods utilized (previously unused)
|
||||
- TypeStructureService integrated for type metadata
|
||||
- 100% backward compatible in behavior (just different API)
|
||||
|
||||
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
|
||||
|
||||
## [2.23.0] - 2025-11-21
|
||||
|
||||
### ✨ Features
|
||||
|
||||
35
CLAUDE.md
35
CLAUDE.md
@@ -32,7 +32,9 @@ src/
|
||||
│ ├── expression-validator.ts # n8n expression syntax validation (NEW in v2.5.0)
|
||||
│ └── workflow-validator.ts # Complete workflow validation (NEW in v2.5.0)
|
||||
├── types/
|
||||
│ └── type-structures.ts # Type structure definitions (NEW in v2.22.21)
|
||||
│ ├── type-structures.ts # Type structure definitions (NEW in v2.22.21)
|
||||
│ ├── instance-context.ts # Multi-tenant instance configuration
|
||||
│ └── session-state.ts # Session persistence types (NEW in v2.24.1)
|
||||
├── constants/
|
||||
│ └── type-structures.ts # 22 complete type structures (NEW in v2.22.21)
|
||||
├── templates/
|
||||
@@ -64,7 +66,9 @@ src/
|
||||
│ ├── console-manager.ts # Console output isolation (NEW in v2.3.1)
|
||||
│ └── logger.ts # Logging utility with HTTP awareness
|
||||
├── http-server-single-session.ts # Single-session HTTP server (NEW in v2.3.1)
|
||||
│ # Session persistence API (NEW in v2.24.1)
|
||||
├── mcp-engine.ts # Clean API for service integration (NEW in v2.3.1)
|
||||
│ # Session persistence wrappers (NEW in v2.24.1)
|
||||
└── index.ts # Library exports
|
||||
```
|
||||
|
||||
@@ -191,6 +195,35 @@ The MCP server exposes tools in several categories:
|
||||
### Development Best Practices
|
||||
- Run typecheck and lint after every code change
|
||||
|
||||
### Session Persistence Feature (v2.24.1)
|
||||
|
||||
**Location:**
|
||||
- Types: `src/types/session-state.ts`
|
||||
- Implementation: `src/http-server-single-session.ts` (lines 698-702, 1444-1584)
|
||||
- Wrapper: `src/mcp-engine.ts` (lines 123-169)
|
||||
- Tests: `tests/unit/http-server/session-persistence.test.ts`, `tests/unit/mcp-engine/session-persistence.test.ts`
|
||||
|
||||
**Key Features:**
|
||||
- **Export/Restore API**: `exportSessionState()` and `restoreSessionState()` methods
|
||||
- **Multi-tenant support**: Enables zero-downtime deployments for SaaS platforms
|
||||
- **Security-first**: API keys exported as plaintext - downstream MUST encrypt
|
||||
- **Dormant sessions**: Restored sessions recreate transports on first request
|
||||
- **Automatic expiration**: Respects `sessionTimeout` setting (default 30 min)
|
||||
- **MAX_SESSIONS limit**: Caps at 100 concurrent sessions
|
||||
|
||||
**Important Implementation Notes:**
|
||||
- Only exports sessions with valid n8nApiUrl and n8nApiKey in context
|
||||
- Skips expired sessions during both export and restore
|
||||
- Uses `validateInstanceContext()` for data integrity checks
|
||||
- Handles null/invalid session gracefully with warnings
|
||||
- Session metadata (timestamps) and context (credentials) are persisted
|
||||
- Transport and server objects are NOT persisted (recreated on-demand)
|
||||
|
||||
**Testing:**
|
||||
- 22 unit tests covering export, restore, edge cases, and round-trip cycles
|
||||
- Tests use current timestamps to avoid expiration issues
|
||||
- Integration with multi-tenant backends documented in README.md
|
||||
|
||||
# important-instruction-reminders
|
||||
Do what has been asked; nothing more, nothing less.
|
||||
NEVER create files unless they're absolutely necessary for achieving your goal.
|
||||
|
||||
62
README.md
62
README.md
@@ -565,7 +565,9 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
|
||||
- `list_ai_tools()` - AI-capable nodes
|
||||
|
||||
4. **Configuration Phase** (parallel for multiple nodes)
|
||||
- `get_node_essentials(nodeType, {includeExamples: true})` - 10-20 key properties
|
||||
- `get_node(nodeType, {detail: 'standard', includeExamples: true})` - Essential properties (default)
|
||||
- `get_node(nodeType, {detail: 'minimal'})` - Basic metadata only (~200 tokens)
|
||||
- `get_node(nodeType, {detail: 'full'})` - Complete information (~3000-8000 tokens)
|
||||
- `search_node_properties(nodeType, 'auth')` - Find specific properties
|
||||
- `get_node_documentation(nodeType)` - Human-readable docs
|
||||
- Show workflow architecture to user for approval before proceeding
|
||||
@@ -612,7 +614,7 @@ Default values cause runtime failures. Example:
|
||||
### ⚠️ Example Availability
|
||||
`includeExamples: true` returns real configurations from workflow templates.
|
||||
- Coverage varies by node popularity
|
||||
- When no examples available, use `get_node_essentials` + `validate_node_minimal`
|
||||
- When no examples available, use `get_node` + `validate_node_minimal`
|
||||
|
||||
## Validation Strategy
|
||||
|
||||
@@ -802,8 +804,8 @@ list_nodes({category: 'communication'})
|
||||
|
||||
// STEP 2: Configuration (parallel execution)
|
||||
[Silent execution]
|
||||
get_node_essentials('n8n-nodes-base.slack', {includeExamples: true})
|
||||
get_node_essentials('n8n-nodes-base.webhook', {includeExamples: true})
|
||||
get_node('n8n-nodes-base.slack', {detail: 'standard', includeExamples: true})
|
||||
get_node('n8n-nodes-base.webhook', {detail: 'standard', includeExamples: true})
|
||||
|
||||
// STEP 3: Validation (parallel execution)
|
||||
[Silent execution]
|
||||
@@ -860,7 +862,7 @@ n8n_update_partial_workflow({
|
||||
- **Only when necessary** - Use code node as last resort
|
||||
- **AI tool capability** - ANY node can be an AI tool (not just marked ones)
|
||||
|
||||
### Most Popular n8n Nodes (for get_node_essentials):
|
||||
### Most Popular n8n Nodes (for get_node):
|
||||
|
||||
1. **n8n-nodes-base.code** - JavaScript/Python scripting
|
||||
2. **n8n-nodes-base.httpRequest** - HTTP API calls
|
||||
@@ -924,7 +926,7 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
|
||||
|
||||
**Without MCP:** "I was basically playing a guessing game. 'Is it `scheduleTrigger` or `schedule`? Does it take `interval` or `rule`?' I'd write what seemed logical, but n8n has its own conventions that you can't just intuit. I made six different configuration errors in a simple HackerNews scraper."
|
||||
|
||||
**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node_essentials()` and get exactly what I needed - not a 100KB JSON dump, but the actual 5-10 properties that matter. What took 45 minutes now takes 3 minutes."
|
||||
**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node()` and get exactly what I needed - not a 100KB JSON dump, but the actual properties that matter. What took 45 minutes now takes 3 minutes."
|
||||
|
||||
**The Real Value:** "It's about confidence. When you're building automation workflows, uncertainty is expensive. One wrong parameter and your workflow fails at 3 AM. With MCP, I could validate my configuration before deployment. That's not just time saved - that's peace of mind."
|
||||
|
||||
@@ -937,8 +939,14 @@ Once connected, Claude can use these powerful tools:
|
||||
### Core Tools
|
||||
- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
|
||||
- **`list_nodes`** - List all n8n nodes with filtering options
|
||||
- **`get_node_info`** - Get comprehensive information about a specific node
|
||||
- **`get_node_essentials`** - Get only essential properties (10-20 instead of 200+). Use `includeExamples: true` to get top 3 real-world configurations from popular templates
|
||||
- **`get_node`** - Unified node information tool with multiple detail levels:
|
||||
- `detail: 'minimal'` - Basic metadata only (~200 tokens)
|
||||
- `detail: 'standard'` - Essential properties (default, ~1000-2000 tokens)
|
||||
- `detail: 'full'` - Complete information (~3000-8000 tokens)
|
||||
- `includeExamples: true` - Include real-world configurations from popular templates
|
||||
- `mode: 'versions'` - View version history and breaking changes
|
||||
- `mode: 'compare'` - Compare two versions with property-level changes
|
||||
- `includeTypeInfo: true` - Add type structure metadata (NEW!)
|
||||
- **`search_nodes`** - Full-text search across all node documentation. Use `includeExamples: true` to get top 2 real-world configurations per node from templates
|
||||
- **`search_node_properties`** - Find specific properties within nodes
|
||||
- **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!)
|
||||
@@ -999,23 +1007,51 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
|
||||
### Example Usage
|
||||
|
||||
```typescript
|
||||
// Get essentials with real-world examples from templates
|
||||
get_node_essentials({
|
||||
// Get node info with different detail levels
|
||||
get_node({
|
||||
nodeType: "nodes-base.httpRequest",
|
||||
includeExamples: true // Returns top 3 configs from popular templates
|
||||
detail: "standard", // Default: Essential properties
|
||||
includeExamples: true // Include real-world examples from templates
|
||||
})
|
||||
|
||||
// Minimal info for quick reference
|
||||
get_node({
|
||||
nodeType: "nodes-base.slack",
|
||||
detail: "minimal" // ~200 tokens: just basic metadata
|
||||
})
|
||||
|
||||
// Full documentation
|
||||
get_node({
|
||||
nodeType: "nodes-base.webhook",
|
||||
detail: "full", // Complete information
|
||||
includeTypeInfo: true // Include type structure metadata
|
||||
})
|
||||
|
||||
// Version history and breaking changes
|
||||
get_node({
|
||||
nodeType: "nodes-base.httpRequest",
|
||||
mode: "versions" // View all versions with summary
|
||||
})
|
||||
|
||||
// Compare versions
|
||||
get_node({
|
||||
nodeType: "nodes-base.slack",
|
||||
mode: "compare",
|
||||
fromVersion: "2.1",
|
||||
toVersion: "2.2"
|
||||
})
|
||||
|
||||
// Search nodes with configuration examples
|
||||
search_nodes({
|
||||
query: "send email gmail",
|
||||
includeExamples: true // Returns top 2 configs per node
|
||||
includeExamples: true // Returns top 2 configs per node
|
||||
})
|
||||
|
||||
// Validate before deployment
|
||||
validate_node_operation({
|
||||
nodeType: "nodes-base.httpRequest",
|
||||
config: { method: "POST", url: "..." },
|
||||
profile: "runtime" // or "minimal", "ai-friendly", "strict"
|
||||
profile: "runtime" // or "minimal", "ai-friendly", "strict"
|
||||
})
|
||||
|
||||
// Quick required field check
|
||||
|
||||
BIN
data/nodes.db
BIN
data/nodes.db
Binary file not shown.
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "n8n-mcp",
|
||||
"version": "2.23.0",
|
||||
"version": "2.24.1",
|
||||
"description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
|
||||
"main": "dist/index.js",
|
||||
"types": "dist/index.d.ts",
|
||||
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
STANDARD_PROTOCOL_VERSION
|
||||
} from './utils/protocol-version';
|
||||
import { InstanceContext, validateInstanceContext } from './types/instance-context';
|
||||
import { SessionState } from './types/session-state';
|
||||
|
||||
dotenv.config();
|
||||
|
||||
@@ -71,6 +72,30 @@ function extractMultiTenantHeaders(req: express.Request): MultiTenantHeaders {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Security logging helper for audit trails
|
||||
* Provides structured logging for security-relevant events
|
||||
*/
|
||||
function logSecurityEvent(
|
||||
event: 'session_export' | 'session_restore' | 'session_restore_failed' | 'max_sessions_reached',
|
||||
details: {
|
||||
sessionId?: string;
|
||||
reason?: string;
|
||||
count?: number;
|
||||
instanceId?: string;
|
||||
}
|
||||
): void {
|
||||
const timestamp = new Date().toISOString();
|
||||
const logEntry = {
|
||||
timestamp,
|
||||
event,
|
||||
...details
|
||||
};
|
||||
|
||||
// Log to standard logger with [SECURITY] prefix for easy filtering
|
||||
logger.info(`[SECURITY] ${event}`, logEntry);
|
||||
}
|
||||
|
||||
export class SingleSessionHTTPServer {
|
||||
// Map to store transports by session ID (following SDK pattern)
|
||||
private transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
|
||||
@@ -687,7 +712,20 @@ export class SingleSessionHTTPServer {
|
||||
if (!this.session) return true;
|
||||
return Date.now() - this.session.lastAccess.getTime() > this.sessionTimeout;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Check if a specific session is expired based on sessionId
|
||||
* Used for multi-session expiration checks during export/restore
|
||||
*
|
||||
* @param sessionId - The session ID to check
|
||||
* @returns true if session is expired or doesn't exist
|
||||
*/
|
||||
private isSessionExpired(sessionId: string): boolean {
|
||||
const metadata = this.sessionMetadata[sessionId];
|
||||
if (!metadata) return true;
|
||||
return Date.now() - metadata.lastAccess.getTime() > this.sessionTimeout;
|
||||
}
|
||||
|
||||
/**
|
||||
* Start the HTTP server
|
||||
*/
|
||||
@@ -1406,6 +1444,197 @@ export class SingleSessionHTTPServer {
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Export all active session state for persistence
|
||||
*
|
||||
* Used by multi-tenant backends to dump sessions before container restart.
|
||||
* This method exports the minimal state needed to restore sessions after
|
||||
* a restart: session metadata (timing) and instance context (credentials).
|
||||
*
|
||||
* Transport and server objects are NOT persisted - they will be recreated
|
||||
* on the first request after restore.
|
||||
*
|
||||
* SECURITY WARNING: The exported data contains plaintext n8n API keys.
|
||||
* The downstream application MUST encrypt this data before persisting to disk.
|
||||
*
|
||||
* @returns Array of session state objects, excluding expired sessions
|
||||
*
|
||||
* @example
|
||||
* // Before shutdown
|
||||
* const sessions = server.exportSessionState();
|
||||
* await saveToEncryptedStorage(sessions);
|
||||
*/
|
||||
public exportSessionState(): SessionState[] {
|
||||
const sessions: SessionState[] = [];
|
||||
const seenSessionIds = new Set<string>();
|
||||
|
||||
// Iterate over all sessions with metadata (source of truth for active sessions)
|
||||
for (const sessionId of Object.keys(this.sessionMetadata)) {
|
||||
// Check for duplicates (defensive programming)
|
||||
if (seenSessionIds.has(sessionId)) {
|
||||
logger.warn(`Duplicate sessionId detected during export: ${sessionId}`);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Skip expired sessions - they're not worth persisting
|
||||
if (this.isSessionExpired(sessionId)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const metadata = this.sessionMetadata[sessionId];
|
||||
const context = this.sessionContexts[sessionId];
|
||||
|
||||
// Skip sessions without context - these can't be restored meaningfully
|
||||
// (Context is required to reconnect to the correct n8n instance)
|
||||
if (!context || !context.n8nApiUrl || !context.n8nApiKey) {
|
||||
logger.debug(`Skipping session ${sessionId} - missing required context`);
|
||||
continue;
|
||||
}
|
||||
|
||||
seenSessionIds.add(sessionId);
|
||||
sessions.push({
|
||||
sessionId,
|
||||
metadata: {
|
||||
createdAt: metadata.createdAt.toISOString(),
|
||||
lastAccess: metadata.lastAccess.toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: context.n8nApiUrl,
|
||||
n8nApiKey: context.n8nApiKey,
|
||||
instanceId: context.instanceId || sessionId, // Use sessionId as fallback
|
||||
sessionId: context.sessionId,
|
||||
metadata: context.metadata
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
logger.info(`Exported ${sessions.length} session(s) for persistence`);
|
||||
logSecurityEvent('session_export', { count: sessions.length });
|
||||
return sessions;
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore session state from previously exported data
|
||||
*
|
||||
* Used by multi-tenant backends to restore sessions after container restart.
|
||||
* This method restores only the session metadata and instance context.
|
||||
* Transport and server objects will be recreated on the first request.
|
||||
*
|
||||
* Restored sessions are "dormant" until a client makes a request, at which
|
||||
* point the transport and server will be initialized normally.
|
||||
*
|
||||
* @param sessions - Array of session state objects from exportSessionState()
|
||||
* @returns Number of sessions successfully restored
|
||||
*
|
||||
* @example
|
||||
* // After startup
|
||||
* const sessions = await loadFromEncryptedStorage();
|
||||
* const count = server.restoreSessionState(sessions);
|
||||
* console.log(`Restored ${count} sessions`);
|
||||
*/
|
||||
public restoreSessionState(sessions: SessionState[]): number {
|
||||
let restoredCount = 0;
|
||||
|
||||
for (const sessionState of sessions) {
|
||||
try {
|
||||
// Skip null or invalid session objects
|
||||
if (!sessionState || typeof sessionState !== 'object' || !sessionState.sessionId) {
|
||||
logger.warn('Skipping invalid session state object');
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check if we've hit the MAX_SESSIONS limit (check real-time count)
|
||||
if (Object.keys(this.sessionMetadata).length >= MAX_SESSIONS) {
|
||||
logger.warn(
|
||||
`Reached MAX_SESSIONS limit (${MAX_SESSIONS}), skipping remaining sessions`
|
||||
);
|
||||
logSecurityEvent('max_sessions_reached', { count: MAX_SESSIONS });
|
||||
break;
|
||||
}
|
||||
|
||||
// Skip if session already exists (duplicate sessionId)
|
||||
if (this.sessionMetadata[sessionState.sessionId]) {
|
||||
logger.debug(`Skipping session ${sessionState.sessionId} - already exists`);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Parse and validate dates first
|
||||
const createdAt = new Date(sessionState.metadata.createdAt);
|
||||
const lastAccess = new Date(sessionState.metadata.lastAccess);
|
||||
|
||||
if (isNaN(createdAt.getTime()) || isNaN(lastAccess.getTime())) {
|
||||
logger.warn(
|
||||
`Skipping session ${sessionState.sessionId} - invalid date format`
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Validate session isn't expired
|
||||
const age = Date.now() - lastAccess.getTime();
|
||||
if (age > this.sessionTimeout) {
|
||||
logger.debug(
|
||||
`Skipping session ${sessionState.sessionId} - expired (age: ${Math.round(age / 1000)}s)`
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Validate context exists (TypeScript null narrowing)
|
||||
if (!sessionState.context) {
|
||||
logger.warn(`Skipping session ${sessionState.sessionId} - missing context`);
|
||||
continue;
|
||||
}
|
||||
|
||||
// Validate context structure using existing validation
|
||||
const validation = validateInstanceContext(sessionState.context);
|
||||
if (!validation.valid) {
|
||||
const reason = validation.errors?.join(', ') || 'invalid context';
|
||||
logger.warn(
|
||||
`Skipping session ${sessionState.sessionId} - invalid context: ${reason}`
|
||||
);
|
||||
logSecurityEvent('session_restore_failed', {
|
||||
sessionId: sessionState.sessionId,
|
||||
reason
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
// Restore session metadata
|
||||
this.sessionMetadata[sessionState.sessionId] = {
|
||||
createdAt,
|
||||
lastAccess
|
||||
};
|
||||
|
||||
// Restore session context
|
||||
this.sessionContexts[sessionState.sessionId] = {
|
||||
n8nApiUrl: sessionState.context.n8nApiUrl,
|
||||
n8nApiKey: sessionState.context.n8nApiKey,
|
||||
instanceId: sessionState.context.instanceId,
|
||||
sessionId: sessionState.context.sessionId,
|
||||
metadata: sessionState.context.metadata
|
||||
};
|
||||
|
||||
logger.debug(`Restored session ${sessionState.sessionId}`);
|
||||
logSecurityEvent('session_restore', {
|
||||
sessionId: sessionState.sessionId,
|
||||
instanceId: sessionState.context.instanceId
|
||||
});
|
||||
restoredCount++;
|
||||
} catch (error) {
|
||||
logger.error(`Failed to restore session ${sessionState.sessionId}:`, error);
|
||||
logSecurityEvent('session_restore_failed', {
|
||||
sessionId: sessionState.sessionId,
|
||||
reason: error instanceof Error ? error.message : 'unknown error'
|
||||
});
|
||||
// Continue with next session - don't let one failure break the entire restore
|
||||
}
|
||||
}
|
||||
|
||||
logger.info(
|
||||
`Restored ${restoredCount}/${sessions.length} session(s) from persistence`
|
||||
);
|
||||
return restoredCount;
|
||||
}
|
||||
}
|
||||
|
||||
// Start if called directly
|
||||
|
||||
@@ -18,6 +18,9 @@ export {
|
||||
validateInstanceContext,
|
||||
isInstanceContext
|
||||
} from './types/instance-context';
|
||||
export type {
|
||||
SessionState
|
||||
} from './types/session-state';
|
||||
|
||||
// Re-export MCP SDK types for convenience
|
||||
export type {
|
||||
|
||||
@@ -9,6 +9,7 @@ import { Request, Response } from 'express';
|
||||
import { SingleSessionHTTPServer } from './http-server-single-session';
|
||||
import { logger } from './utils/logger';
|
||||
import { InstanceContext } from './types/instance-context';
|
||||
import { SessionState } from './types/session-state';
|
||||
|
||||
export interface EngineHealth {
|
||||
status: 'healthy' | 'unhealthy';
|
||||
@@ -97,7 +98,7 @@ export class N8NMCPEngine {
|
||||
total: Math.round(memoryUsage.heapTotal / 1024 / 1024),
|
||||
unit: 'MB'
|
||||
},
|
||||
version: '2.3.2'
|
||||
version: '2.24.1'
|
||||
};
|
||||
} catch (error) {
|
||||
logger.error('Health check failed:', error);
|
||||
@@ -106,7 +107,7 @@ export class N8NMCPEngine {
|
||||
uptime: 0,
|
||||
sessionActive: false,
|
||||
memoryUsage: { used: 0, total: 0, unit: 'MB' },
|
||||
version: '2.3.2'
|
||||
version: '2.24.1'
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -118,10 +119,58 @@ export class N8NMCPEngine {
|
||||
getSessionInfo(): { active: boolean; sessionId?: string; age?: number } {
|
||||
return this.server.getSessionInfo();
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Export all active session state for persistence
|
||||
*
|
||||
* Used by multi-tenant backends to dump sessions before container restart.
|
||||
* Returns an array of session state objects containing metadata and credentials.
|
||||
*
|
||||
* SECURITY WARNING: Exported data contains plaintext n8n API keys.
|
||||
* Encrypt before persisting to disk.
|
||||
*
|
||||
* @returns Array of session state objects
|
||||
*
|
||||
* @example
|
||||
* // Before shutdown
|
||||
* const sessions = engine.exportSessionState();
|
||||
* await saveToEncryptedStorage(sessions);
|
||||
*/
|
||||
exportSessionState(): SessionState[] {
|
||||
if (!this.server) {
|
||||
logger.warn('Cannot export sessions: server not initialized');
|
||||
return [];
|
||||
}
|
||||
return this.server.exportSessionState();
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore session state from previously exported data
|
||||
*
|
||||
* Used by multi-tenant backends to restore sessions after container restart.
|
||||
* Restores session metadata and instance context. Transports/servers are
|
||||
* recreated on first request.
|
||||
*
|
||||
* @param sessions - Array of session state objects from exportSessionState()
|
||||
* @returns Number of sessions successfully restored
|
||||
*
|
||||
* @example
|
||||
* // After startup
|
||||
* const sessions = await loadFromEncryptedStorage();
|
||||
* const count = engine.restoreSessionState(sessions);
|
||||
* console.log(`Restored ${count} sessions`);
|
||||
*/
|
||||
restoreSessionState(sessions: SessionState[]): number {
|
||||
if (!this.server) {
|
||||
logger.warn('Cannot restore sessions: server not initialized');
|
||||
return 0;
|
||||
}
|
||||
return this.server.restoreSessionState(sessions);
|
||||
}
|
||||
|
||||
/**
|
||||
* Graceful shutdown for service lifecycle
|
||||
*
|
||||
*
|
||||
* @example
|
||||
* process.on('SIGTERM', async () => {
|
||||
* await engine.shutdown();
|
||||
|
||||
@@ -19,6 +19,7 @@ import { TaskTemplates } from '../services/task-templates';
|
||||
import { ConfigValidator } from '../services/config-validator';
|
||||
import { EnhancedConfigValidator, ValidationMode, ValidationProfile } from '../services/enhanced-config-validator';
|
||||
import { PropertyDependencies } from '../services/property-dependencies';
|
||||
import { TypeStructureService } from '../services/type-structure-service';
|
||||
import { SimpleCache } from '../utils/simple-cache';
|
||||
import { TemplateService } from '../templates/template-service';
|
||||
import { WorkflowValidator } from '../services/workflow-validator';
|
||||
@@ -58,6 +59,67 @@ interface NodeRow {
|
||||
credentials_required?: string;
|
||||
}
|
||||
|
||||
interface VersionSummary {
|
||||
currentVersion: string;
|
||||
totalVersions: number;
|
||||
hasVersionHistory: boolean;
|
||||
}
|
||||
|
||||
interface NodeMinimalInfo {
|
||||
nodeType: string;
|
||||
workflowNodeType: string;
|
||||
displayName: string;
|
||||
description: string;
|
||||
category: string;
|
||||
package: string;
|
||||
isAITool: boolean;
|
||||
isTrigger: boolean;
|
||||
isWebhook: boolean;
|
||||
}
|
||||
|
||||
interface NodeStandardInfo {
|
||||
nodeType: string;
|
||||
displayName: string;
|
||||
description: string;
|
||||
category: string;
|
||||
requiredProperties: any[];
|
||||
commonProperties: any[];
|
||||
operations?: any[];
|
||||
credentials?: any;
|
||||
examples?: any[];
|
||||
versionInfo: VersionSummary;
|
||||
}
|
||||
|
||||
interface NodeFullInfo {
|
||||
nodeType: string;
|
||||
displayName: string;
|
||||
description: string;
|
||||
category: string;
|
||||
properties: any[];
|
||||
operations?: any[];
|
||||
credentials?: any;
|
||||
documentation?: string;
|
||||
versionInfo: VersionSummary;
|
||||
}
|
||||
|
||||
interface VersionHistoryInfo {
|
||||
nodeType: string;
|
||||
versions: any[];
|
||||
latestVersion: string;
|
||||
hasBreakingChanges: boolean;
|
||||
}
|
||||
|
||||
interface VersionComparisonInfo {
|
||||
nodeType: string;
|
||||
fromVersion: string;
|
||||
toVersion: string;
|
||||
changes: any[];
|
||||
breakingChanges?: any[];
|
||||
migrations?: any[];
|
||||
}
|
||||
|
||||
type NodeInfoResponse = NodeMinimalInfo | NodeStandardInfo | NodeFullInfo | VersionHistoryInfo | VersionComparisonInfo;
|
||||
|
||||
export class N8NDocumentationMCPServer {
|
||||
private server: Server;
|
||||
private db: DatabaseAdapter | null = null;
|
||||
@@ -956,9 +1018,6 @@ export class N8NDocumentationMCPServer {
|
||||
case 'list_nodes':
|
||||
// No required parameters
|
||||
return this.listNodes(args);
|
||||
case 'get_node_info':
|
||||
this.validateToolParams(name, args, ['nodeType']);
|
||||
return this.getNodeInfo(args.nodeType);
|
||||
case 'search_nodes':
|
||||
this.validateToolParams(name, args, ['query']);
|
||||
// Convert limit to number if provided, otherwise use default
|
||||
@@ -973,9 +1032,17 @@ export class N8NDocumentationMCPServer {
|
||||
case 'get_database_statistics':
|
||||
// No required parameters
|
||||
return this.getDatabaseStatistics();
|
||||
case 'get_node_essentials':
|
||||
case 'get_node':
|
||||
this.validateToolParams(name, args, ['nodeType']);
|
||||
return this.getNodeEssentials(args.nodeType, args.includeExamples);
|
||||
return this.getNode(
|
||||
args.nodeType,
|
||||
args.detail,
|
||||
args.mode,
|
||||
args.includeTypeInfo,
|
||||
args.includeExamples,
|
||||
args.fromVersion,
|
||||
args.toVersion
|
||||
);
|
||||
case 'search_node_properties':
|
||||
this.validateToolParams(name, args, ['nodeType', 'query']);
|
||||
const maxResults = args.maxResults !== undefined ? Number(args.maxResults) || 20 : 20;
|
||||
@@ -2218,6 +2285,393 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Unified node information retrieval with multiple detail levels and modes.
|
||||
*
|
||||
* @param nodeType - Full node type identifier (e.g., "nodes-base.httpRequest" or "nodes-langchain.agent")
|
||||
* @param detail - Information detail level (minimal, standard, full). Only applies when mode='info'.
|
||||
* - minimal: ~200 tokens, basic metadata only (no version info)
|
||||
* - standard: ~1-2K tokens, essential properties and operations (includes version info, AI-friendly default)
|
||||
* - full: ~3-8K tokens, complete node information with all properties (includes version info)
|
||||
* @param mode - Operation mode determining the type of information returned:
|
||||
* - info: Node configuration details (respects detail level)
|
||||
* - versions: Complete version history with breaking changes summary
|
||||
* - compare: Property-level comparison between two versions (requires fromVersion)
|
||||
* - breaking: Breaking changes only between versions (requires fromVersion)
|
||||
* - migrations: Auto-migratable changes between versions (requires both fromVersion and toVersion)
|
||||
* @param includeTypeInfo - Include type structure metadata for properties (only applies to mode='info').
|
||||
* Adds ~80-120 tokens per property with type category, JS type, and validation rules.
|
||||
* @param includeExamples - Include real-world configuration examples from templates (only applies to mode='info' with detail='standard').
|
||||
* Adds ~200-400 tokens per example.
|
||||
* @param fromVersion - Source version for comparison modes (required for compare, breaking, migrations).
|
||||
* Format: "1.0" or "2.1"
|
||||
* @param toVersion - Target version for comparison modes (optional for compare/breaking, required for migrations).
|
||||
* Defaults to latest version if omitted.
|
||||
* @returns NodeInfoResponse - Union type containing different response structures based on mode and detail parameters
|
||||
*/
|
||||
private async getNode(
|
||||
nodeType: string,
|
||||
detail: string = 'standard',
|
||||
mode: string = 'info',
|
||||
includeTypeInfo?: boolean,
|
||||
includeExamples?: boolean,
|
||||
fromVersion?: string,
|
||||
toVersion?: string
|
||||
): Promise<NodeInfoResponse> {
|
||||
await this.ensureInitialized();
|
||||
if (!this.repository) throw new Error('Repository not initialized');
|
||||
|
||||
// Validate parameters
|
||||
const validDetailLevels = ['minimal', 'standard', 'full'];
|
||||
const validModes = ['info', 'versions', 'compare', 'breaking', 'migrations'];
|
||||
|
||||
if (!validDetailLevels.includes(detail)) {
|
||||
throw new Error(`get_node: Invalid detail level "${detail}". Valid options: ${validDetailLevels.join(', ')}`);
|
||||
}
|
||||
|
||||
if (!validModes.includes(mode)) {
|
||||
throw new Error(`get_node: Invalid mode "${mode}". Valid options: ${validModes.join(', ')}`);
|
||||
}
|
||||
|
||||
const normalizedType = NodeTypeNormalizer.normalizeToFullForm(nodeType);
|
||||
|
||||
// Version modes - detail level ignored
|
||||
if (mode !== 'info') {
|
||||
return this.handleVersionMode(
|
||||
normalizedType,
|
||||
mode,
|
||||
fromVersion,
|
||||
toVersion
|
||||
);
|
||||
}
|
||||
|
||||
// Info mode - respect detail level
|
||||
return this.handleInfoMode(
|
||||
normalizedType,
|
||||
detail,
|
||||
includeTypeInfo,
|
||||
includeExamples
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle info mode - returns node information at specified detail level
|
||||
*/
|
||||
private async handleInfoMode(
|
||||
nodeType: string,
|
||||
detail: string,
|
||||
includeTypeInfo?: boolean,
|
||||
includeExamples?: boolean
|
||||
): Promise<NodeMinimalInfo | NodeStandardInfo | NodeFullInfo> {
|
||||
switch (detail) {
|
||||
case 'minimal': {
|
||||
// Get basic node metadata only (no version info for minimal mode)
|
||||
let node = this.repository!.getNode(nodeType);
|
||||
|
||||
if (!node) {
|
||||
const alternatives = getNodeTypeAlternatives(nodeType);
|
||||
for (const alt of alternatives) {
|
||||
const found = this.repository!.getNode(alt);
|
||||
if (found) {
|
||||
node = found;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!node) {
|
||||
throw new Error(`Node ${nodeType} not found`);
|
||||
}
|
||||
|
||||
return {
|
||||
nodeType: node.nodeType,
|
||||
workflowNodeType: getWorkflowNodeType(node.package ?? 'n8n-nodes-base', node.nodeType),
|
||||
displayName: node.displayName,
|
||||
description: node.description,
|
||||
category: node.category,
|
||||
package: node.package,
|
||||
isAITool: node.isAITool,
|
||||
isTrigger: node.isTrigger,
|
||||
isWebhook: node.isWebhook
|
||||
};
|
||||
}
|
||||
|
||||
case 'standard': {
|
||||
// Use existing getNodeEssentials logic
|
||||
const essentials = await this.getNodeEssentials(nodeType, includeExamples);
|
||||
const versionSummary = this.getVersionSummary(nodeType);
|
||||
|
||||
// Apply type info enrichment if requested
|
||||
if (includeTypeInfo) {
|
||||
essentials.requiredProperties = this.enrichPropertiesWithTypeInfo(essentials.requiredProperties);
|
||||
essentials.commonProperties = this.enrichPropertiesWithTypeInfo(essentials.commonProperties);
|
||||
}
|
||||
|
||||
return {
|
||||
...essentials,
|
||||
versionInfo: versionSummary
|
||||
};
|
||||
}
|
||||
|
||||
case 'full': {
|
||||
// Use existing getNodeInfo logic
|
||||
const fullInfo = await this.getNodeInfo(nodeType);
|
||||
const versionSummary = this.getVersionSummary(nodeType);
|
||||
|
||||
// Apply type info enrichment if requested
|
||||
if (includeTypeInfo && fullInfo.properties) {
|
||||
fullInfo.properties = this.enrichPropertiesWithTypeInfo(fullInfo.properties);
|
||||
}
|
||||
|
||||
return {
|
||||
...fullInfo,
|
||||
versionInfo: versionSummary
|
||||
};
|
||||
}
|
||||
|
||||
default:
|
||||
throw new Error(`Unknown detail level: ${detail}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle version modes - returns version history and comparison data
|
||||
*/
|
||||
private async handleVersionMode(
|
||||
nodeType: string,
|
||||
mode: string,
|
||||
fromVersion?: string,
|
||||
toVersion?: string
|
||||
): Promise<VersionHistoryInfo | VersionComparisonInfo> {
|
||||
switch (mode) {
|
||||
case 'versions':
|
||||
return this.getVersionHistory(nodeType);
|
||||
|
||||
case 'compare':
|
||||
if (!fromVersion) {
|
||||
throw new Error(`get_node: fromVersion is required for compare mode (nodeType: ${nodeType})`);
|
||||
}
|
||||
return this.compareVersions(nodeType, fromVersion, toVersion);
|
||||
|
||||
case 'breaking':
|
||||
if (!fromVersion) {
|
||||
throw new Error(`get_node: fromVersion is required for breaking mode (nodeType: ${nodeType})`);
|
||||
}
|
||||
return this.getBreakingChanges(nodeType, fromVersion, toVersion);
|
||||
|
||||
case 'migrations':
|
||||
if (!fromVersion || !toVersion) {
|
||||
throw new Error(`get_node: Both fromVersion and toVersion are required for migrations mode (nodeType: ${nodeType})`);
|
||||
}
|
||||
return this.getMigrations(nodeType, fromVersion, toVersion);
|
||||
|
||||
default:
|
||||
throw new Error(`get_node: Unknown mode: ${mode} (nodeType: ${nodeType})`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get version summary (always included in info mode responses)
|
||||
* Cached for 24 hours to improve performance
|
||||
*/
|
||||
private getVersionSummary(nodeType: string): VersionSummary {
|
||||
const cacheKey = `version-summary:${nodeType}`;
|
||||
const cached = this.cache.get(cacheKey) as VersionSummary | null;
|
||||
|
||||
if (cached) {
|
||||
return cached;
|
||||
}
|
||||
|
||||
const versions = this.repository!.getNodeVersions(nodeType);
|
||||
const latest = this.repository!.getLatestNodeVersion(nodeType);
|
||||
|
||||
const summary: VersionSummary = {
|
||||
currentVersion: latest?.version || 'unknown',
|
||||
totalVersions: versions.length,
|
||||
hasVersionHistory: versions.length > 0
|
||||
};
|
||||
|
||||
// Cache for 24 hours (86400000 ms)
|
||||
this.cache.set(cacheKey, summary, 86400000);
|
||||
|
||||
return summary;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get complete version history for a node
|
||||
*/
|
||||
private getVersionHistory(nodeType: string): any {
|
||||
const versions = this.repository!.getNodeVersions(nodeType);
|
||||
|
||||
return {
|
||||
nodeType,
|
||||
totalVersions: versions.length,
|
||||
versions: versions.map(v => ({
|
||||
version: v.version,
|
||||
isCurrent: v.isCurrentMax,
|
||||
minimumN8nVersion: v.minimumN8nVersion,
|
||||
releasedAt: v.releasedAt,
|
||||
hasBreakingChanges: (v.breakingChanges || []).length > 0,
|
||||
breakingChangesCount: (v.breakingChanges || []).length,
|
||||
deprecatedProperties: v.deprecatedProperties || [],
|
||||
addedProperties: v.addedProperties || []
|
||||
})),
|
||||
available: versions.length > 0,
|
||||
message: versions.length === 0 ?
|
||||
'No version history available. Version tracking may not be enabled for this node.' :
|
||||
undefined
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Compare two versions of a node
|
||||
*/
|
||||
private compareVersions(
|
||||
nodeType: string,
|
||||
fromVersion: string,
|
||||
toVersion?: string
|
||||
): any {
|
||||
const latest = this.repository!.getLatestNodeVersion(nodeType);
|
||||
const targetVersion = toVersion || latest?.version;
|
||||
|
||||
if (!targetVersion) {
|
||||
throw new Error('No target version available');
|
||||
}
|
||||
|
||||
const changes = this.repository!.getPropertyChanges(
|
||||
nodeType,
|
||||
fromVersion,
|
||||
targetVersion
|
||||
);
|
||||
|
||||
return {
|
||||
nodeType,
|
||||
fromVersion,
|
||||
toVersion: targetVersion,
|
||||
totalChanges: changes.length,
|
||||
breakingChanges: changes.filter(c => c.isBreaking).length,
|
||||
changes: changes.map(c => ({
|
||||
property: c.propertyName,
|
||||
changeType: c.changeType,
|
||||
isBreaking: c.isBreaking,
|
||||
severity: c.severity,
|
||||
oldValue: c.oldValue,
|
||||
newValue: c.newValue,
|
||||
migrationHint: c.migrationHint,
|
||||
autoMigratable: c.autoMigratable
|
||||
}))
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get breaking changes between versions
|
||||
*/
|
||||
private getBreakingChanges(
|
||||
nodeType: string,
|
||||
fromVersion: string,
|
||||
toVersion?: string
|
||||
): any {
|
||||
const breakingChanges = this.repository!.getBreakingChanges(
|
||||
nodeType,
|
||||
fromVersion,
|
||||
toVersion
|
||||
);
|
||||
|
||||
return {
|
||||
nodeType,
|
||||
fromVersion,
|
||||
toVersion: toVersion || 'latest',
|
||||
totalBreakingChanges: breakingChanges.length,
|
||||
changes: breakingChanges.map(c => ({
|
||||
fromVersion: c.fromVersion,
|
||||
toVersion: c.toVersion,
|
||||
property: c.propertyName,
|
||||
changeType: c.changeType,
|
||||
severity: c.severity,
|
||||
migrationHint: c.migrationHint,
|
||||
oldValue: c.oldValue,
|
||||
newValue: c.newValue
|
||||
})),
|
||||
upgradeSafe: breakingChanges.length === 0
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get auto-migratable changes between versions
|
||||
*/
|
||||
private getMigrations(
|
||||
nodeType: string,
|
||||
fromVersion: string,
|
||||
toVersion: string
|
||||
): any {
|
||||
const migrations = this.repository!.getAutoMigratableChanges(
|
||||
nodeType,
|
||||
fromVersion,
|
||||
toVersion
|
||||
);
|
||||
|
||||
const allChanges = this.repository!.getPropertyChanges(
|
||||
nodeType,
|
||||
fromVersion,
|
||||
toVersion
|
||||
);
|
||||
|
||||
return {
|
||||
nodeType,
|
||||
fromVersion,
|
||||
toVersion,
|
||||
autoMigratableChanges: migrations.length,
|
||||
totalChanges: allChanges.length,
|
||||
migrations: migrations.map(m => ({
|
||||
property: m.propertyName,
|
||||
changeType: m.changeType,
|
||||
migrationStrategy: m.migrationStrategy,
|
||||
severity: m.severity
|
||||
})),
|
||||
requiresManualMigration: migrations.length < allChanges.length
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Enrich property with type structure metadata
|
||||
*/
|
||||
private enrichPropertyWithTypeInfo(property: any): any {
|
||||
if (!property || !property.type) return property;
|
||||
|
||||
const structure = TypeStructureService.getStructure(property.type);
|
||||
if (!structure) return property;
|
||||
|
||||
return {
|
||||
...property,
|
||||
typeInfo: {
|
||||
category: structure.type,
|
||||
jsType: structure.jsType,
|
||||
description: structure.description,
|
||||
isComplex: TypeStructureService.isComplexType(property.type),
|
||||
isPrimitive: TypeStructureService.isPrimitiveType(property.type),
|
||||
allowsExpressions: structure.validation?.allowExpressions ?? true,
|
||||
allowsEmpty: structure.validation?.allowEmpty ?? false,
|
||||
...(structure.structure && {
|
||||
structureHints: {
|
||||
hasProperties: !!structure.structure.properties,
|
||||
hasItems: !!structure.structure.items,
|
||||
isFlexible: structure.structure.flexible ?? false,
|
||||
requiredFields: structure.structure.required ?? []
|
||||
}
|
||||
}),
|
||||
...(structure.notes && { notes: structure.notes })
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Enrich an array of properties with type structure metadata
|
||||
*/
|
||||
private enrichPropertiesWithTypeInfo(properties: any[]): any[] {
|
||||
if (!properties || !Array.isArray(properties)) return properties;
|
||||
return properties.map((prop: any) => this.enrichPropertyWithTypeInfo(prop));
|
||||
}
|
||||
|
||||
private async searchNodeProperties(nodeType: string, query: string, maxResults: number = 20): Promise<any> {
|
||||
await this.ensureInitialized();
|
||||
if (!this.repository) throw new Error('Repository not initialized');
|
||||
|
||||
@@ -84,16 +84,17 @@ When working with Code nodes, always start by calling the relevant guide:
|
||||
|
||||
## Standard Workflow Pattern
|
||||
|
||||
⚠️ **CRITICAL**: Always call get_node_essentials() FIRST before configuring any node!
|
||||
⚠️ **CRITICAL**: Always call get_node() with detail='standard' FIRST before configuring any node!
|
||||
|
||||
1. **Find** the node you need:
|
||||
- search_nodes({query: "slack"}) - Search by keyword
|
||||
- list_nodes({category: "communication"}) - List by category
|
||||
- list_ai_tools() - List AI-capable nodes
|
||||
|
||||
2. **Configure** the node (ALWAYS START WITH ESSENTIALS):
|
||||
- ✅ get_node_essentials("nodes-base.slack") - Get essential properties FIRST (5KB, shows required fields)
|
||||
- get_node_info("nodes-base.slack") - Get complete schema only if essentials insufficient (100KB+)
|
||||
2. **Configure** the node (ALWAYS START WITH STANDARD DETAIL):
|
||||
- ✅ get_node("nodes-base.slack", {detail: 'standard'}) - Get essential properties FIRST (~1-2KB, shows required fields)
|
||||
- get_node("nodes-base.slack", {detail: 'full'}) - Get complete schema only if standard insufficient (~100KB+)
|
||||
- get_node("nodes-base.slack", {detail: 'minimal'}) - Get basic metadata only (~200 tokens)
|
||||
- search_node_properties("nodes-base.slack", "auth") - Find specific properties
|
||||
|
||||
3. **Validate** before deployment:
|
||||
@@ -109,8 +110,12 @@ When working with Code nodes, always start by calling the relevant guide:
|
||||
- list_ai_tools - List all AI-capable nodes with usage guidance
|
||||
|
||||
**Configuration Tools**
|
||||
- get_node_essentials - ✅ CALL THIS FIRST! Returns 10-20 key properties with examples and required fields
|
||||
- get_node_info - Returns complete node schema (only use if essentials is insufficient)
|
||||
- get_node - ✅ Unified node information tool with progressive detail levels:
|
||||
- detail='minimal': Basic metadata (~200 tokens)
|
||||
- detail='standard': Essential properties (default, ~1-2KB) - USE THIS FIRST!
|
||||
- detail='full': Complete schema (~100KB+, use only when standard insufficient)
|
||||
- mode='versions': View version history and breaking changes
|
||||
- includeTypeInfo=true: Add type structure metadata
|
||||
- search_node_properties - Search for specific properties within a node
|
||||
- get_property_dependencies - Analyze property visibility dependencies
|
||||
|
||||
@@ -132,9 +137,9 @@ When working with Code nodes, always start by calling the relevant guide:
|
||||
- n8n_trigger_webhook_workflow - Trigger workflow execution
|
||||
|
||||
## Performance Characteristics
|
||||
- Instant (<10ms): search_nodes, list_nodes, get_node_essentials
|
||||
- Instant (<10ms): search_nodes, list_nodes, get_node (minimal/standard)
|
||||
- Fast (<100ms): validate_node_minimal, get_node_for_task
|
||||
- Moderate (100-500ms): validate_workflow, get_node_info
|
||||
- Moderate (100-500ms): validate_workflow, get_node (full detail)
|
||||
- Network-dependent: All n8n_* tools
|
||||
|
||||
For comprehensive documentation on any tool:
|
||||
@@ -167,7 +172,7 @@ ${tools.map(toolName => {
|
||||
|
||||
## Usage Notes
|
||||
- All node types require the "nodes-base." or "nodes-langchain." prefix
|
||||
- Use get_node_essentials() first for most tasks (95% smaller than get_node_info)
|
||||
- Use get_node() with detail='standard' first for most tasks (~95% smaller than detail='full')
|
||||
- Validation profiles: minimal (editing), runtime (default), strict (deployment)
|
||||
- n8n API tools only available when N8N_API_URL and N8N_API_KEY are configured
|
||||
|
||||
|
||||
@@ -57,20 +57,6 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'get_node_info',
|
||||
description: `Get full node documentation. Pass nodeType as string with prefix. Example: nodeType="nodes-base.webhook"`,
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
nodeType: {
|
||||
type: 'string',
|
||||
description: 'Full type: "nodes-base.{name}" or "nodes-langchain.{name}". Examples: nodes-base.httpRequest, nodes-base.webhook, nodes-base.slack',
|
||||
},
|
||||
},
|
||||
required: ['nodeType'],
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'search_nodes',
|
||||
description: `Search n8n nodes by keyword with optional real-world examples. Pass query as string. Example: query="webhook" or query="database". Returns max 20 results. Use includeExamples=true to get top 2 template configs per node.`,
|
||||
@@ -132,19 +118,44 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'get_node_essentials',
|
||||
description: `Get node essential info with optional real-world examples from templates. Pass nodeType as string with prefix. Example: nodeType="nodes-base.slack". Use includeExamples=true to get top 3 template configs.`,
|
||||
name: 'get_node',
|
||||
description: `Get node info with progressive detail levels. Detail: minimal (~200 tokens), standard (~1-2K, default), full (~3-8K). Version modes: versions (history), compare (diff), breaking (changes), migrations (auto-migrate). Supports includeTypeInfo and includeExamples. Use standard for most tasks.`,
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
nodeType: {
|
||||
type: 'string',
|
||||
description: 'Full type: "nodes-base.httpRequest"',
|
||||
description: 'Full node type: "nodes-base.httpRequest" or "nodes-langchain.agent"',
|
||||
},
|
||||
detail: {
|
||||
type: 'string',
|
||||
enum: ['minimal', 'standard', 'full'],
|
||||
default: 'standard',
|
||||
description: 'Information detail level. standard=essential properties (recommended), full=everything',
|
||||
},
|
||||
mode: {
|
||||
type: 'string',
|
||||
enum: ['info', 'versions', 'compare', 'breaking', 'migrations'],
|
||||
default: 'info',
|
||||
description: 'Operation mode. info=node information, versions=version history, compare/breaking/migrations=version comparison',
|
||||
},
|
||||
includeTypeInfo: {
|
||||
type: 'boolean',
|
||||
default: false,
|
||||
description: 'Include type structure metadata (type category, JS type, validation rules). Only applies to mode=info. Adds ~80-120 tokens per property.',
|
||||
},
|
||||
includeExamples: {
|
||||
type: 'boolean',
|
||||
description: 'Include top 3 real-world configuration examples from popular templates (default: false)',
|
||||
default: false,
|
||||
description: 'Include real-world configuration examples from templates. Only applies to mode=info with detail=standard. Adds ~200-400 tokens per example.',
|
||||
},
|
||||
fromVersion: {
|
||||
type: 'string',
|
||||
description: 'Source version for compare/breaking/migrations modes (e.g., "1.0")',
|
||||
},
|
||||
toVersion: {
|
||||
type: 'string',
|
||||
description: 'Target version for compare mode (e.g., "2.0"). Defaults to latest if omitted.',
|
||||
},
|
||||
},
|
||||
required: ['nodeType'],
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
// Export n8n node type definitions and utilities
|
||||
export * from './node-types';
|
||||
export * from './type-structures';
|
||||
export * from './instance-context';
|
||||
export * from './session-state';
|
||||
|
||||
export interface MCPServerConfig {
|
||||
port: number;
|
||||
|
||||
92
src/types/session-state.ts
Normal file
92
src/types/session-state.ts
Normal file
@@ -0,0 +1,92 @@
|
||||
/**
|
||||
* Session persistence types for multi-tenant deployments
|
||||
*
|
||||
* These types support exporting and restoring MCP session state across
|
||||
* container restarts, enabling seamless session persistence in production.
|
||||
*/
|
||||
|
||||
import { InstanceContext } from './instance-context.js';
|
||||
|
||||
/**
|
||||
* Serializable session state for persistence across restarts
|
||||
*
|
||||
* This interface represents the minimal state needed to restore an MCP session
|
||||
* after a container restart. Only the session metadata and instance context are
|
||||
* persisted - transport and server objects are recreated on the first request.
|
||||
*
|
||||
* @example
|
||||
* // Export sessions before shutdown
|
||||
* const sessions = server.exportSessionState();
|
||||
* await saveToEncryptedStorage(sessions);
|
||||
*
|
||||
* @example
|
||||
* // Restore sessions on startup
|
||||
* const sessions = await loadFromEncryptedStorage();
|
||||
* const count = server.restoreSessionState(sessions);
|
||||
* console.log(`Restored ${count} sessions`);
|
||||
*/
|
||||
export interface SessionState {
|
||||
/**
|
||||
* Unique session identifier
|
||||
* Format: UUID v4 or custom format from MCP proxy
|
||||
*/
|
||||
sessionId: string;
|
||||
|
||||
/**
|
||||
* Session timing metadata for expiration tracking
|
||||
*/
|
||||
metadata: {
|
||||
/**
|
||||
* When the session was created (ISO 8601 timestamp)
|
||||
* Used to track total session age
|
||||
*/
|
||||
createdAt: string;
|
||||
|
||||
/**
|
||||
* When the session was last accessed (ISO 8601 timestamp)
|
||||
* Used to determine if session has expired based on timeout
|
||||
*/
|
||||
lastAccess: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* n8n instance context (credentials and configuration)
|
||||
*
|
||||
* Contains the n8n API credentials and instance-specific settings.
|
||||
* This is the critical data needed to reconnect to the correct n8n instance.
|
||||
*
|
||||
* Note: API keys are stored in plaintext. The downstream application
|
||||
* MUST encrypt this data before persisting to disk.
|
||||
*/
|
||||
context: {
|
||||
/**
|
||||
* n8n instance API URL
|
||||
* Example: "https://n8n.example.com"
|
||||
*/
|
||||
n8nApiUrl: string;
|
||||
|
||||
/**
|
||||
* n8n instance API key (plaintext - encrypt before storage!)
|
||||
* Example: "n8n_api_1234567890abcdef"
|
||||
*/
|
||||
n8nApiKey: string;
|
||||
|
||||
/**
|
||||
* Instance identifier (optional)
|
||||
* Custom identifier for tracking which n8n instance this session belongs to
|
||||
*/
|
||||
instanceId?: string;
|
||||
|
||||
/**
|
||||
* Session-specific ID (optional)
|
||||
* May differ from top-level sessionId in some proxy configurations
|
||||
*/
|
||||
sessionId?: string;
|
||||
|
||||
/**
|
||||
* Additional metadata (optional)
|
||||
* Extensible field for custom application data
|
||||
*/
|
||||
metadata?: Record<string, any>;
|
||||
};
|
||||
}
|
||||
@@ -59,7 +59,7 @@ describe('MCP Error Handling', () => {
|
||||
it('should handle invalid params', async () => {
|
||||
try {
|
||||
// Missing required parameter
|
||||
await client.callTool({ name: 'get_node_info', arguments: {} });
|
||||
await client.callTool({ name: 'get_node', arguments: {} });
|
||||
expect.fail('Should have thrown an error');
|
||||
} catch (error: any) {
|
||||
expect(error).toBeDefined();
|
||||
@@ -71,7 +71,7 @@ describe('MCP Error Handling', () => {
|
||||
it('should handle internal errors gracefully', async () => {
|
||||
try {
|
||||
// Invalid node type format should cause internal processing error
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'completely-invalid-format-$$$$'
|
||||
} });
|
||||
expect.fail('Should have thrown an error');
|
||||
@@ -123,7 +123,7 @@ describe('MCP Error Handling', () => {
|
||||
|
||||
it('should handle non-existent node types', async () => {
|
||||
try {
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.thisDoesNotExist'
|
||||
} });
|
||||
expect.fail('Should have thrown an error');
|
||||
@@ -228,15 +228,17 @@ describe('MCP Error Handling', () => {
|
||||
describe('Large Payload Handling', () => {
|
||||
it('should handle large node info requests', async () => {
|
||||
// HTTP Request node has extensive properties
|
||||
const response = await client.callTool({ name: 'get_node_info', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
const response = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest',
|
||||
detail: 'full'
|
||||
} });
|
||||
|
||||
expect((response as any).content[0].text.length).toBeGreaterThan(10000);
|
||||
|
||||
|
||||
// Should be valid JSON
|
||||
const nodeInfo = JSON.parse((response as any).content[0].text);
|
||||
expect(nodeInfo).toHaveProperty('properties');
|
||||
expect(nodeInfo).toHaveProperty('nodeType');
|
||||
expect(nodeInfo).toHaveProperty('displayName');
|
||||
});
|
||||
|
||||
it('should handle large workflow validation', async () => {
|
||||
@@ -355,7 +357,7 @@ describe('MCP Error Handling', () => {
|
||||
|
||||
for (const nodeType of largeNodes) {
|
||||
promises.push(
|
||||
client.callTool({ name: 'get_node_info', arguments: { nodeType } })
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType } })
|
||||
.catch(() => null) // Some might not exist
|
||||
);
|
||||
}
|
||||
@@ -400,7 +402,7 @@ describe('MCP Error Handling', () => {
|
||||
it('should continue working after errors', async () => {
|
||||
// Cause an error
|
||||
try {
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'invalid'
|
||||
} });
|
||||
} catch (error) {
|
||||
@@ -415,7 +417,7 @@ describe('MCP Error Handling', () => {
|
||||
it('should handle mixed success and failure', async () => {
|
||||
const promises = [
|
||||
client.callTool({ name: 'list_nodes', arguments: { limit: 5 } }),
|
||||
client.callTool({ name: 'get_node_info', arguments: { nodeType: 'invalid' } }).catch(e => ({ error: e })),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType: 'invalid' } }).catch(e => ({ error: e })),
|
||||
client.callTool({ name: 'get_database_statistics', arguments: {} }),
|
||||
client.callTool({ name: 'search_nodes', arguments: { query: '' } }).catch(e => ({ error: e })),
|
||||
client.callTool({ name: 'list_ai_tools', arguments: {} })
|
||||
@@ -482,7 +484,7 @@ describe('MCP Error Handling', () => {
|
||||
it('should provide helpful error messages', async () => {
|
||||
try {
|
||||
// Use a truly invalid node type
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'invalid-node-type-that-does-not-exist'
|
||||
} });
|
||||
expect.fail('Should have thrown an error');
|
||||
|
||||
@@ -114,13 +114,13 @@ describe('MCP Performance Tests', () => {
|
||||
const start = performance.now();
|
||||
|
||||
for (const nodeType of nodeTypes) {
|
||||
await client.callTool({ name: 'get_node_info', arguments: { nodeType } });
|
||||
await client.callTool({ name: 'get_node', arguments: { nodeType } });
|
||||
}
|
||||
|
||||
const duration = performance.now() - start;
|
||||
const avgTime = duration / nodeTypes.length;
|
||||
|
||||
console.log(`Average response time for get_node_info: ${avgTime.toFixed(2)}ms`);
|
||||
console.log(`Average response time for get_node: ${avgTime.toFixed(2)}ms`);
|
||||
console.log(`Environment: ${process.env.CI ? 'CI' : 'Local'}`);
|
||||
|
||||
// Environment-aware threshold (these are large responses)
|
||||
@@ -331,7 +331,7 @@ describe('MCP Performance Tests', () => {
|
||||
// Perform large operations
|
||||
for (let i = 0; i < 10; i++) {
|
||||
await client.callTool({ name: 'list_nodes', arguments: { limit: 200 } });
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
} });
|
||||
}
|
||||
@@ -503,7 +503,7 @@ describe('MCP Performance Tests', () => {
|
||||
|
||||
// First call (cold)
|
||||
const coldStart = performance.now();
|
||||
await client.callTool({ name: 'get_node_info', arguments: { nodeType } });
|
||||
await client.callTool({ name: 'get_node', arguments: { nodeType } });
|
||||
const coldTime = performance.now() - coldStart;
|
||||
|
||||
// Give cache time to settle
|
||||
@@ -513,7 +513,7 @@ describe('MCP Performance Tests', () => {
|
||||
const warmTimes: number[] = [];
|
||||
for (let i = 0; i < 10; i++) {
|
||||
const start = performance.now();
|
||||
await client.callTool({ name: 'get_node_info', arguments: { nodeType } });
|
||||
await client.callTool({ name: 'get_node', arguments: { nodeType } });
|
||||
warmTimes.push(performance.now() - start);
|
||||
}
|
||||
|
||||
|
||||
@@ -132,7 +132,7 @@ describe('MCP Protocol Compliance', () => {
|
||||
it('should validate params schema', async () => {
|
||||
try {
|
||||
// Invalid nodeType format (missing prefix)
|
||||
const response = await client.callTool({ name: 'get_node_info', arguments: {
|
||||
const response = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'httpRequest' // Should be 'nodes-base.httpRequest'
|
||||
} });
|
||||
// Check if the response indicates an error
|
||||
@@ -157,7 +157,7 @@ describe('MCP Protocol Compliance', () => {
|
||||
|
||||
it('should handle large text responses', async () => {
|
||||
// Get a large node info response
|
||||
const response = await client.callTool({ name: 'get_node_info', arguments: {
|
||||
const response = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
} });
|
||||
|
||||
@@ -181,9 +181,9 @@ describe('MCP Protocol Compliance', () => {
|
||||
describe('Request/Response Correlation', () => {
|
||||
it('should correlate concurrent requests correctly', async () => {
|
||||
const requests = [
|
||||
client.callTool({ name: 'get_node_essentials', arguments: { nodeType: 'nodes-base.httpRequest' } }),
|
||||
client.callTool({ name: 'get_node_essentials', arguments: { nodeType: 'nodes-base.webhook' } }),
|
||||
client.callTool({ name: 'get_node_essentials', arguments: { nodeType: 'nodes-base.slack' } })
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType: 'nodes-base.httpRequest' } }),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType: 'nodes-base.webhook' } }),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType: 'nodes-base.slack' } })
|
||||
];
|
||||
|
||||
const responses = await Promise.all(requests);
|
||||
|
||||
@@ -451,7 +451,7 @@ describe('MCP Session Management', { timeout: 15000 }, () => {
|
||||
|
||||
// Make an error-inducing request
|
||||
try {
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'invalid-node-type'
|
||||
} });
|
||||
expect.fail('Should have thrown an error');
|
||||
@@ -485,8 +485,8 @@ describe('MCP Session Management', { timeout: 15000 }, () => {
|
||||
// Multiple error-inducing requests
|
||||
// Note: get_node_for_task was removed in v2.15.0
|
||||
const errorPromises = [
|
||||
client.callTool({ name: 'get_node_info', arguments: { nodeType: 'invalid1' } }).catch(e => e),
|
||||
client.callTool({ name: 'get_node_info', arguments: { nodeType: 'invalid2' } }).catch(e => e),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType: 'invalid1' } }).catch(e => e),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType: 'invalid2' } }).catch(e => e),
|
||||
client.callTool({ name: 'search_nodes', arguments: { query: '' } }).catch(e => e) // Empty query should error
|
||||
];
|
||||
|
||||
|
||||
@@ -146,24 +146,25 @@ describe('MCP Tool Invocation', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('get_node_info', () => {
|
||||
describe('get_node', () => {
|
||||
it('should get complete node information', async () => {
|
||||
const response = await client.callTool({ name: 'get_node_info', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
const response = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest',
|
||||
detail: 'full'
|
||||
}});
|
||||
|
||||
expect(((response as any).content[0]).type).toBe('text');
|
||||
const nodeInfo = JSON.parse(((response as any).content[0]).text);
|
||||
|
||||
|
||||
expect(nodeInfo).toHaveProperty('nodeType', 'nodes-base.httpRequest');
|
||||
expect(nodeInfo).toHaveProperty('displayName');
|
||||
expect(nodeInfo).toHaveProperty('properties');
|
||||
expect(Array.isArray(nodeInfo.properties)).toBe(true);
|
||||
expect(nodeInfo).toHaveProperty('description');
|
||||
expect(nodeInfo).toHaveProperty('version');
|
||||
});
|
||||
|
||||
it('should handle non-existent nodes', async () => {
|
||||
try {
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.nonExistent'
|
||||
}});
|
||||
expect.fail('Should have thrown an error');
|
||||
@@ -174,7 +175,7 @@ describe('MCP Tool Invocation', () => {
|
||||
|
||||
it('should handle invalid node type format', async () => {
|
||||
try {
|
||||
await client.callTool({ name: 'get_node_info', arguments: {
|
||||
await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'invalidFormat'
|
||||
}});
|
||||
expect.fail('Should have thrown an error');
|
||||
@@ -184,24 +185,26 @@ describe('MCP Tool Invocation', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('get_node_essentials', () => {
|
||||
it('should return condensed node information', async () => {
|
||||
const response = await client.callTool({ name: 'get_node_essentials', arguments: {
|
||||
describe('get_node with different detail levels', () => {
|
||||
it('should return standard detail by default', async () => {
|
||||
const response = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
}});
|
||||
|
||||
const essentials = JSON.parse(((response as any).content[0]).text);
|
||||
|
||||
expect(essentials).toHaveProperty('nodeType');
|
||||
expect(essentials).toHaveProperty('displayName');
|
||||
expect(essentials).toHaveProperty('commonProperties');
|
||||
expect(essentials).toHaveProperty('requiredProperties');
|
||||
|
||||
// Should be smaller than full info
|
||||
const fullResponse = await client.callTool({ name: 'get_node_info', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
const nodeInfo = JSON.parse(((response as any).content[0]).text);
|
||||
|
||||
expect(nodeInfo).toHaveProperty('nodeType');
|
||||
expect(nodeInfo).toHaveProperty('displayName');
|
||||
expect(nodeInfo).toHaveProperty('description');
|
||||
expect(nodeInfo).toHaveProperty('requiredProperties');
|
||||
expect(nodeInfo).toHaveProperty('commonProperties');
|
||||
|
||||
// Should be smaller than full detail
|
||||
const fullResponse = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: 'nodes-base.httpRequest',
|
||||
detail: 'full'
|
||||
}});
|
||||
|
||||
|
||||
expect(((response as any).content[0]).text.length).toBeLessThan(((fullResponse as any).content[0]).text.length);
|
||||
});
|
||||
});
|
||||
@@ -515,7 +518,7 @@ describe('MCP Tool Invocation', () => {
|
||||
|
||||
// Get info for first result
|
||||
const firstNode = nodes[0];
|
||||
const infoResponse = await client.callTool({ name: 'get_node_info', arguments: {
|
||||
const infoResponse = await client.callTool({ name: 'get_node', arguments: {
|
||||
nodeType: firstNode.nodeType
|
||||
}});
|
||||
|
||||
@@ -548,8 +551,8 @@ describe('MCP Tool Invocation', () => {
|
||||
const nodeType = 'nodes-base.httpRequest';
|
||||
|
||||
const [fullInfo, essentials, searchResult] = await Promise.all([
|
||||
client.callTool({ name: 'get_node_info', arguments: { nodeType } }),
|
||||
client.callTool({ name: 'get_node_essentials', arguments: { nodeType } }),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType } }),
|
||||
client.callTool({ name: 'get_node', arguments: { nodeType } }),
|
||||
client.callTool({ name: 'search_nodes', arguments: { query: 'httpRequest' } })
|
||||
]);
|
||||
|
||||
|
||||
@@ -227,7 +227,7 @@ describe.skip('MCP Telemetry Integration', () => {
|
||||
const callToolRequest: CallToolRequest = {
|
||||
method: 'tools/call',
|
||||
params: {
|
||||
name: 'get_node_info',
|
||||
name: 'get_node',
|
||||
arguments: { nodeType: 'invalid-node' }
|
||||
}
|
||||
};
|
||||
@@ -247,11 +247,11 @@ describe.skip('MCP Telemetry Integration', () => {
|
||||
}
|
||||
}
|
||||
|
||||
expect(telemetry.trackToolUsage).toHaveBeenCalledWith('get_node_info', false);
|
||||
expect(telemetry.trackToolUsage).toHaveBeenCalledWith('get_node', false);
|
||||
expect(telemetry.trackError).toHaveBeenCalledWith(
|
||||
'Error',
|
||||
'Node not found',
|
||||
'get_node_info'
|
||||
'get_node'
|
||||
);
|
||||
});
|
||||
|
||||
@@ -263,7 +263,7 @@ describe.skip('MCP Telemetry Integration', () => {
|
||||
const callToolRequest: CallToolRequest = {
|
||||
method: 'tools/call',
|
||||
params: {
|
||||
name: 'get_node_info',
|
||||
name: 'get_node',
|
||||
arguments: { nodeType: 'nodes-base.webhook' }
|
||||
}
|
||||
};
|
||||
@@ -282,7 +282,7 @@ describe.skip('MCP Telemetry Integration', () => {
|
||||
|
||||
expect(telemetry.trackToolSequence).toHaveBeenCalledWith(
|
||||
'search_nodes',
|
||||
'get_node_info',
|
||||
'get_node',
|
||||
expect.any(Number)
|
||||
);
|
||||
});
|
||||
|
||||
546
tests/unit/http-server/session-persistence.test.ts
Normal file
546
tests/unit/http-server/session-persistence.test.ts
Normal file
@@ -0,0 +1,546 @@
|
||||
/**
|
||||
* Unit tests for session persistence API
|
||||
* Tests export and restore functionality for multi-tenant session management
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach, vi } from 'vitest';
|
||||
import { SingleSessionHTTPServer } from '../../../src/http-server-single-session';
|
||||
import { SessionState } from '../../../src/types/session-state';
|
||||
|
||||
describe('SingleSessionHTTPServer - Session Persistence', () => {
|
||||
let server: SingleSessionHTTPServer;
|
||||
|
||||
beforeEach(() => {
|
||||
server = new SingleSessionHTTPServer();
|
||||
});
|
||||
|
||||
describe('exportSessionState()', () => {
|
||||
it('should return empty array when no sessions exist', () => {
|
||||
const exported = server.exportSessionState();
|
||||
expect(exported).toEqual([]);
|
||||
});
|
||||
|
||||
it('should export active sessions with all required fields', () => {
|
||||
// Create mock sessions by directly manipulating internal state
|
||||
const sessionId1 = 'test-session-1';
|
||||
const sessionId2 = 'test-session-2';
|
||||
|
||||
// Use current timestamps to avoid expiration
|
||||
const now = new Date();
|
||||
const createdAt1 = new Date(now.getTime() - 10 * 60 * 1000); // 10 minutes ago
|
||||
const lastAccess1 = new Date(now.getTime() - 5 * 60 * 1000); // 5 minutes ago
|
||||
const createdAt2 = new Date(now.getTime() - 15 * 60 * 1000); // 15 minutes ago
|
||||
const lastAccess2 = new Date(now.getTime() - 3 * 60 * 1000); // 3 minutes ago
|
||||
|
||||
// Access private properties for testing
|
||||
const serverAny = server as any;
|
||||
|
||||
serverAny.sessionMetadata[sessionId1] = {
|
||||
createdAt: createdAt1,
|
||||
lastAccess: lastAccess1
|
||||
};
|
||||
|
||||
serverAny.sessionContexts[sessionId1] = {
|
||||
n8nApiUrl: 'https://n8n1.example.com',
|
||||
n8nApiKey: 'key1',
|
||||
instanceId: 'instance1',
|
||||
sessionId: sessionId1,
|
||||
metadata: { userId: 'user1' }
|
||||
};
|
||||
|
||||
serverAny.sessionMetadata[sessionId2] = {
|
||||
createdAt: createdAt2,
|
||||
lastAccess: lastAccess2
|
||||
};
|
||||
|
||||
serverAny.sessionContexts[sessionId2] = {
|
||||
n8nApiUrl: 'https://n8n2.example.com',
|
||||
n8nApiKey: 'key2',
|
||||
instanceId: 'instance2'
|
||||
};
|
||||
|
||||
const exported = server.exportSessionState();
|
||||
|
||||
expect(exported).toHaveLength(2);
|
||||
|
||||
// Verify first session
|
||||
expect(exported[0]).toMatchObject({
|
||||
sessionId: sessionId1,
|
||||
metadata: {
|
||||
createdAt: createdAt1.toISOString(),
|
||||
lastAccess: lastAccess1.toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://n8n1.example.com',
|
||||
n8nApiKey: 'key1',
|
||||
instanceId: 'instance1',
|
||||
sessionId: sessionId1,
|
||||
metadata: { userId: 'user1' }
|
||||
}
|
||||
});
|
||||
|
||||
// Verify second session
|
||||
expect(exported[1]).toMatchObject({
|
||||
sessionId: sessionId2,
|
||||
metadata: {
|
||||
createdAt: createdAt2.toISOString(),
|
||||
lastAccess: lastAccess2.toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://n8n2.example.com',
|
||||
n8nApiKey: 'key2',
|
||||
instanceId: 'instance2'
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
it('should skip expired sessions during export', () => {
|
||||
const serverAny = server as any;
|
||||
const now = Date.now();
|
||||
const sessionTimeout = 30 * 60 * 1000; // 30 minutes (default)
|
||||
|
||||
// Create an active session (accessed recently)
|
||||
serverAny.sessionMetadata['active-session'] = {
|
||||
createdAt: new Date(now - 10 * 60 * 1000), // 10 minutes ago
|
||||
lastAccess: new Date(now - 5 * 60 * 1000) // 5 minutes ago
|
||||
};
|
||||
serverAny.sessionContexts['active-session'] = {
|
||||
n8nApiUrl: 'https://active.example.com',
|
||||
n8nApiKey: 'active-key',
|
||||
instanceId: 'active-instance'
|
||||
};
|
||||
|
||||
// Create an expired session (last accessed > 30 minutes ago)
|
||||
serverAny.sessionMetadata['expired-session'] = {
|
||||
createdAt: new Date(now - 60 * 60 * 1000), // 60 minutes ago
|
||||
lastAccess: new Date(now - 45 * 60 * 1000) // 45 minutes ago (expired)
|
||||
};
|
||||
serverAny.sessionContexts['expired-session'] = {
|
||||
n8nApiUrl: 'https://expired.example.com',
|
||||
n8nApiKey: 'expired-key',
|
||||
instanceId: 'expired-instance'
|
||||
};
|
||||
|
||||
const exported = server.exportSessionState();
|
||||
|
||||
expect(exported).toHaveLength(1);
|
||||
expect(exported[0].sessionId).toBe('active-session');
|
||||
});
|
||||
|
||||
it('should skip sessions without required context fields', () => {
|
||||
const serverAny = server as any;
|
||||
|
||||
// Session with complete context
|
||||
serverAny.sessionMetadata['complete-session'] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
serverAny.sessionContexts['complete-session'] = {
|
||||
n8nApiUrl: 'https://complete.example.com',
|
||||
n8nApiKey: 'complete-key',
|
||||
instanceId: 'complete-instance'
|
||||
};
|
||||
|
||||
// Session with missing n8nApiUrl
|
||||
serverAny.sessionMetadata['missing-url'] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
serverAny.sessionContexts['missing-url'] = {
|
||||
n8nApiKey: 'key',
|
||||
instanceId: 'instance'
|
||||
};
|
||||
|
||||
// Session with missing n8nApiKey
|
||||
serverAny.sessionMetadata['missing-key'] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
serverAny.sessionContexts['missing-key'] = {
|
||||
n8nApiUrl: 'https://example.com',
|
||||
instanceId: 'instance'
|
||||
};
|
||||
|
||||
// Session with no context at all
|
||||
serverAny.sessionMetadata['no-context'] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
|
||||
const exported = server.exportSessionState();
|
||||
|
||||
expect(exported).toHaveLength(1);
|
||||
expect(exported[0].sessionId).toBe('complete-session');
|
||||
});
|
||||
|
||||
it('should use sessionId as fallback for instanceId', () => {
|
||||
const serverAny = server as any;
|
||||
const sessionId = 'test-session';
|
||||
|
||||
serverAny.sessionMetadata[sessionId] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
serverAny.sessionContexts[sessionId] = {
|
||||
n8nApiUrl: 'https://example.com',
|
||||
n8nApiKey: 'key'
|
||||
// No instanceId provided
|
||||
};
|
||||
|
||||
const exported = server.exportSessionState();
|
||||
|
||||
expect(exported).toHaveLength(1);
|
||||
expect(exported[0].context.instanceId).toBe(sessionId);
|
||||
});
|
||||
});
|
||||
|
||||
describe('restoreSessionState()', () => {
|
||||
it('should restore valid sessions correctly', () => {
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'restored-session-1',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://restored1.example.com',
|
||||
n8nApiKey: 'restored-key-1',
|
||||
instanceId: 'restored-instance-1'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'restored-session-2',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://restored2.example.com',
|
||||
n8nApiKey: 'restored-key-2',
|
||||
instanceId: 'restored-instance-2',
|
||||
sessionId: 'custom-session-id',
|
||||
metadata: { custom: 'data' }
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = server.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(2);
|
||||
|
||||
// Verify sessions were restored by checking internal state
|
||||
const serverAny = server as any;
|
||||
|
||||
expect(serverAny.sessionMetadata['restored-session-1']).toBeDefined();
|
||||
expect(serverAny.sessionContexts['restored-session-1']).toMatchObject({
|
||||
n8nApiUrl: 'https://restored1.example.com',
|
||||
n8nApiKey: 'restored-key-1',
|
||||
instanceId: 'restored-instance-1'
|
||||
});
|
||||
|
||||
expect(serverAny.sessionMetadata['restored-session-2']).toBeDefined();
|
||||
expect(serverAny.sessionContexts['restored-session-2']).toMatchObject({
|
||||
n8nApiUrl: 'https://restored2.example.com',
|
||||
n8nApiKey: 'restored-key-2',
|
||||
instanceId: 'restored-instance-2',
|
||||
sessionId: 'custom-session-id',
|
||||
metadata: { custom: 'data' }
|
||||
});
|
||||
});
|
||||
|
||||
it('should skip expired sessions during restore', () => {
|
||||
const now = Date.now();
|
||||
const sessionTimeout = 30 * 60 * 1000; // 30 minutes
|
||||
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'active-session',
|
||||
metadata: {
|
||||
createdAt: new Date(now - 10 * 60 * 1000).toISOString(),
|
||||
lastAccess: new Date(now - 5 * 60 * 1000).toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://active.example.com',
|
||||
n8nApiKey: 'active-key',
|
||||
instanceId: 'active-instance'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'expired-session',
|
||||
metadata: {
|
||||
createdAt: new Date(now - 60 * 60 * 1000).toISOString(),
|
||||
lastAccess: new Date(now - 45 * 60 * 1000).toISOString() // Expired
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://expired.example.com',
|
||||
n8nApiKey: 'expired-key',
|
||||
instanceId: 'expired-instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = server.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(1);
|
||||
|
||||
const serverAny = server as any;
|
||||
expect(serverAny.sessionMetadata['active-session']).toBeDefined();
|
||||
expect(serverAny.sessionMetadata['expired-session']).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should skip sessions with missing required context fields', () => {
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'valid-session',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://valid.example.com',
|
||||
n8nApiKey: 'valid-key',
|
||||
instanceId: 'valid-instance'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'missing-url',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: '', // Empty URL
|
||||
n8nApiKey: 'key',
|
||||
instanceId: 'instance'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'missing-key',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://example.com',
|
||||
n8nApiKey: '', // Empty key
|
||||
instanceId: 'instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = server.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(1);
|
||||
|
||||
const serverAny = server as any;
|
||||
expect(serverAny.sessionMetadata['valid-session']).toBeDefined();
|
||||
expect(serverAny.sessionMetadata['missing-url']).toBeUndefined();
|
||||
expect(serverAny.sessionMetadata['missing-key']).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should skip duplicate sessionIds', () => {
|
||||
const serverAny = server as any;
|
||||
|
||||
// Create an existing session
|
||||
serverAny.sessionMetadata['existing-session'] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'new-session',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://new.example.com',
|
||||
n8nApiKey: 'new-key',
|
||||
instanceId: 'new-instance'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'existing-session', // Duplicate
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://duplicate.example.com',
|
||||
n8nApiKey: 'duplicate-key',
|
||||
instanceId: 'duplicate-instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = server.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(1);
|
||||
expect(serverAny.sessionMetadata['new-session']).toBeDefined();
|
||||
});
|
||||
|
||||
it('should handle restore failures gracefully', () => {
|
||||
const sessions: any[] = [
|
||||
{
|
||||
sessionId: 'valid-session',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://valid.example.com',
|
||||
n8nApiKey: 'valid-key',
|
||||
instanceId: 'valid-instance'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'bad-session',
|
||||
metadata: {}, // Missing required fields
|
||||
context: null // Invalid context
|
||||
},
|
||||
null, // Invalid session
|
||||
{
|
||||
// Missing sessionId
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://example.com',
|
||||
n8nApiKey: 'key',
|
||||
instanceId: 'instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
// Should not throw and should restore only the valid session
|
||||
expect(() => {
|
||||
const count = server.restoreSessionState(sessions);
|
||||
expect(count).toBe(1); // Only valid-session should be restored
|
||||
}).not.toThrow();
|
||||
|
||||
// Verify the valid session was restored
|
||||
const serverAny = server as any;
|
||||
expect(serverAny.sessionMetadata['valid-session']).toBeDefined();
|
||||
});
|
||||
|
||||
it('should respect MAX_SESSIONS limit during restore', () => {
|
||||
// Create 99 existing sessions (MAX_SESSIONS is 100)
|
||||
const serverAny = server as any;
|
||||
const now = new Date();
|
||||
for (let i = 0; i < 99; i++) {
|
||||
serverAny.sessionMetadata[`existing-${i}`] = {
|
||||
createdAt: now,
|
||||
lastAccess: now
|
||||
};
|
||||
}
|
||||
|
||||
// Try to restore 3 sessions (should only restore 1 due to limit)
|
||||
const sessions: SessionState[] = [];
|
||||
for (let i = 0; i < 3; i++) {
|
||||
sessions.push({
|
||||
sessionId: `new-session-${i}`,
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: `https://new${i}.example.com`,
|
||||
n8nApiKey: `new-key-${i}`,
|
||||
instanceId: `new-instance-${i}`
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
const count = server.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(1);
|
||||
expect(serverAny.sessionMetadata['new-session-0']).toBeDefined();
|
||||
expect(serverAny.sessionMetadata['new-session-1']).toBeUndefined();
|
||||
expect(serverAny.sessionMetadata['new-session-2']).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should parse ISO 8601 timestamps correctly', () => {
|
||||
// Use current timestamps to avoid expiration
|
||||
const now = new Date();
|
||||
const createdAtDate = new Date(now.getTime() - 10 * 60 * 1000); // 10 minutes ago
|
||||
const lastAccessDate = new Date(now.getTime() - 5 * 60 * 1000); // 5 minutes ago
|
||||
const createdAt = createdAtDate.toISOString();
|
||||
const lastAccess = lastAccessDate.toISOString();
|
||||
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'timestamp-session',
|
||||
metadata: { createdAt, lastAccess },
|
||||
context: {
|
||||
n8nApiUrl: 'https://example.com',
|
||||
n8nApiKey: 'key',
|
||||
instanceId: 'instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = server.restoreSessionState(sessions);
|
||||
expect(count).toBe(1);
|
||||
|
||||
const serverAny = server as any;
|
||||
const metadata = serverAny.sessionMetadata['timestamp-session'];
|
||||
|
||||
expect(metadata.createdAt).toBeInstanceOf(Date);
|
||||
expect(metadata.lastAccess).toBeInstanceOf(Date);
|
||||
expect(metadata.createdAt.toISOString()).toBe(createdAt);
|
||||
expect(metadata.lastAccess.toISOString()).toBe(lastAccess);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Round-trip export and restore', () => {
|
||||
it('should preserve data through export → restore cycle', () => {
|
||||
// Create sessions with current timestamps
|
||||
const serverAny = server as any;
|
||||
const now = new Date();
|
||||
const createdAt = new Date(now.getTime() - 10 * 60 * 1000); // 10 minutes ago
|
||||
const lastAccess = new Date(now.getTime() - 5 * 60 * 1000); // 5 minutes ago
|
||||
|
||||
serverAny.sessionMetadata['session-1'] = {
|
||||
createdAt,
|
||||
lastAccess
|
||||
};
|
||||
serverAny.sessionContexts['session-1'] = {
|
||||
n8nApiUrl: 'https://n8n1.example.com',
|
||||
n8nApiKey: 'key1',
|
||||
instanceId: 'instance1',
|
||||
sessionId: 'custom-id-1',
|
||||
metadata: { userId: 'user1', role: 'admin' }
|
||||
};
|
||||
|
||||
// Export sessions
|
||||
const exported = server.exportSessionState();
|
||||
expect(exported).toHaveLength(1);
|
||||
|
||||
// Clear sessions
|
||||
delete serverAny.sessionMetadata['session-1'];
|
||||
delete serverAny.sessionContexts['session-1'];
|
||||
|
||||
// Restore sessions
|
||||
const count = server.restoreSessionState(exported);
|
||||
expect(count).toBe(1);
|
||||
|
||||
// Verify data integrity
|
||||
const metadata = serverAny.sessionMetadata['session-1'];
|
||||
const context = serverAny.sessionContexts['session-1'];
|
||||
|
||||
expect(metadata.createdAt.toISOString()).toBe(createdAt.toISOString());
|
||||
expect(metadata.lastAccess.toISOString()).toBe(lastAccess.toISOString());
|
||||
|
||||
expect(context).toMatchObject({
|
||||
n8nApiUrl: 'https://n8n1.example.com',
|
||||
n8nApiKey: 'key1',
|
||||
instanceId: 'instance1',
|
||||
sessionId: 'custom-id-1',
|
||||
metadata: { userId: 'user1', role: 'admin' }
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
255
tests/unit/mcp-engine/session-persistence.test.ts
Normal file
255
tests/unit/mcp-engine/session-persistence.test.ts
Normal file
@@ -0,0 +1,255 @@
|
||||
/**
|
||||
* Unit tests for N8NMCPEngine session persistence wrapper methods
|
||||
*/
|
||||
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { N8NMCPEngine } from '../../../src/mcp-engine';
|
||||
import { SessionState } from '../../../src/types/session-state';
|
||||
|
||||
describe('N8NMCPEngine - Session Persistence', () => {
|
||||
let engine: N8NMCPEngine;
|
||||
|
||||
beforeEach(() => {
|
||||
engine = new N8NMCPEngine({
|
||||
sessionTimeout: 30 * 60 * 1000,
|
||||
logLevel: 'error' // Quiet during tests
|
||||
});
|
||||
});
|
||||
|
||||
describe('exportSessionState()', () => {
|
||||
it('should return empty array when no sessions exist', () => {
|
||||
const exported = engine.exportSessionState();
|
||||
expect(exported).toEqual([]);
|
||||
});
|
||||
|
||||
it('should delegate to underlying server', () => {
|
||||
// Access private server to create test sessions
|
||||
const engineAny = engine as any;
|
||||
const server = engineAny.server;
|
||||
const serverAny = server as any;
|
||||
|
||||
// Create a mock session
|
||||
serverAny.sessionMetadata['test-session'] = {
|
||||
createdAt: new Date(),
|
||||
lastAccess: new Date()
|
||||
};
|
||||
serverAny.sessionContexts['test-session'] = {
|
||||
n8nApiUrl: 'https://test.example.com',
|
||||
n8nApiKey: 'test-key',
|
||||
instanceId: 'test-instance'
|
||||
};
|
||||
|
||||
const exported = engine.exportSessionState();
|
||||
|
||||
expect(exported).toHaveLength(1);
|
||||
expect(exported[0].sessionId).toBe('test-session');
|
||||
expect(exported[0].context.n8nApiUrl).toBe('https://test.example.com');
|
||||
});
|
||||
|
||||
it('should handle server not initialized', () => {
|
||||
// Create engine without server
|
||||
const engineAny = {} as N8NMCPEngine;
|
||||
const exportMethod = N8NMCPEngine.prototype.exportSessionState.bind(engineAny);
|
||||
|
||||
// Should not throw, should return empty array
|
||||
expect(() => exportMethod()).not.toThrow();
|
||||
const result = exportMethod();
|
||||
expect(result).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('restoreSessionState()', () => {
|
||||
it('should restore sessions via underlying server', () => {
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'restored-session',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://restored.example.com',
|
||||
n8nApiKey: 'restored-key',
|
||||
instanceId: 'restored-instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = engine.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(1);
|
||||
|
||||
// Verify session was restored
|
||||
const engineAny = engine as any;
|
||||
const server = engineAny.server;
|
||||
const serverAny = server as any;
|
||||
|
||||
expect(serverAny.sessionMetadata['restored-session']).toBeDefined();
|
||||
expect(serverAny.sessionContexts['restored-session']).toMatchObject({
|
||||
n8nApiUrl: 'https://restored.example.com',
|
||||
n8nApiKey: 'restored-key',
|
||||
instanceId: 'restored-instance'
|
||||
});
|
||||
});
|
||||
|
||||
it('should return 0 when restoring empty array', () => {
|
||||
const count = engine.restoreSessionState([]);
|
||||
expect(count).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle server not initialized', () => {
|
||||
const engineAny = {} as N8NMCPEngine;
|
||||
const restoreMethod = N8NMCPEngine.prototype.restoreSessionState.bind(engineAny);
|
||||
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'test',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://test.example.com',
|
||||
n8nApiKey: 'test-key',
|
||||
instanceId: 'test-instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
// Should not throw, should return 0
|
||||
expect(() => restoreMethod(sessions)).not.toThrow();
|
||||
const result = restoreMethod(sessions);
|
||||
expect(result).toBe(0);
|
||||
});
|
||||
|
||||
it('should return count of successfully restored sessions', () => {
|
||||
const now = Date.now();
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'valid-1',
|
||||
metadata: {
|
||||
createdAt: new Date(now - 10 * 60 * 1000).toISOString(),
|
||||
lastAccess: new Date(now - 5 * 60 * 1000).toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://valid1.example.com',
|
||||
n8nApiKey: 'key1',
|
||||
instanceId: 'instance1'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'valid-2',
|
||||
metadata: {
|
||||
createdAt: new Date(now - 10 * 60 * 1000).toISOString(),
|
||||
lastAccess: new Date(now - 5 * 60 * 1000).toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://valid2.example.com',
|
||||
n8nApiKey: 'key2',
|
||||
instanceId: 'instance2'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'expired',
|
||||
metadata: {
|
||||
createdAt: new Date(now - 60 * 60 * 1000).toISOString(),
|
||||
lastAccess: new Date(now - 45 * 60 * 1000).toISOString() // Expired
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://expired.example.com',
|
||||
n8nApiKey: 'expired-key',
|
||||
instanceId: 'expired-instance'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
const count = engine.restoreSessionState(sessions);
|
||||
|
||||
expect(count).toBe(2); // Only 2 valid sessions
|
||||
});
|
||||
});
|
||||
|
||||
describe('Round-trip through engine', () => {
|
||||
it('should preserve sessions through export → restore cycle', () => {
|
||||
// Create mock sessions with current timestamps
|
||||
const engineAny = engine as any;
|
||||
const server = engineAny.server;
|
||||
const serverAny = server as any;
|
||||
|
||||
const now = new Date();
|
||||
const createdAt = new Date(now.getTime() - 10 * 60 * 1000); // 10 minutes ago
|
||||
const lastAccess = new Date(now.getTime() - 5 * 60 * 1000); // 5 minutes ago
|
||||
|
||||
serverAny.sessionMetadata['engine-session'] = {
|
||||
createdAt,
|
||||
lastAccess
|
||||
};
|
||||
serverAny.sessionContexts['engine-session'] = {
|
||||
n8nApiUrl: 'https://engine-test.example.com',
|
||||
n8nApiKey: 'engine-key',
|
||||
instanceId: 'engine-instance',
|
||||
metadata: { env: 'production' }
|
||||
};
|
||||
|
||||
// Export via engine
|
||||
const exported = engine.exportSessionState();
|
||||
expect(exported).toHaveLength(1);
|
||||
|
||||
// Clear sessions
|
||||
delete serverAny.sessionMetadata['engine-session'];
|
||||
delete serverAny.sessionContexts['engine-session'];
|
||||
|
||||
// Restore via engine
|
||||
const count = engine.restoreSessionState(exported);
|
||||
expect(count).toBe(1);
|
||||
|
||||
// Verify data
|
||||
expect(serverAny.sessionMetadata['engine-session']).toBeDefined();
|
||||
expect(serverAny.sessionContexts['engine-session']).toMatchObject({
|
||||
n8nApiUrl: 'https://engine-test.example.com',
|
||||
n8nApiKey: 'engine-key',
|
||||
instanceId: 'engine-instance',
|
||||
metadata: { env: 'production' }
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('Integration with getSessionInfo()', () => {
|
||||
it('should reflect restored sessions in session info', () => {
|
||||
const sessions: SessionState[] = [
|
||||
{
|
||||
sessionId: 'info-session-1',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://info1.example.com',
|
||||
n8nApiKey: 'info-key-1',
|
||||
instanceId: 'info-instance-1'
|
||||
}
|
||||
},
|
||||
{
|
||||
sessionId: 'info-session-2',
|
||||
metadata: {
|
||||
createdAt: new Date().toISOString(),
|
||||
lastAccess: new Date().toISOString()
|
||||
},
|
||||
context: {
|
||||
n8nApiUrl: 'https://info2.example.com',
|
||||
n8nApiKey: 'info-key-2',
|
||||
instanceId: 'info-instance-2'
|
||||
}
|
||||
}
|
||||
];
|
||||
|
||||
engine.restoreSessionState(sessions);
|
||||
|
||||
const info = engine.getSessionInfo();
|
||||
|
||||
// Note: getSessionInfo() reflects metadata, not transports
|
||||
// Restored sessions won't have transports until first request
|
||||
expect(info).toBeDefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
1163
tests/unit/mcp/get-node-unified.test.ts
Normal file
1163
tests/unit/mcp/get-node-unified.test.ts
Normal file
File diff suppressed because it is too large
Load Diff
@@ -140,10 +140,9 @@ describe('Parameter Validation', () => {
|
||||
// Mock the actual tool methods to avoid database calls
|
||||
beforeEach(() => {
|
||||
// Mock all the tool methods that would be called
|
||||
vi.spyOn(server as any, 'getNodeInfo').mockResolvedValue({ mockResult: true });
|
||||
vi.spyOn(server as any, 'getNode').mockResolvedValue({ mockResult: true });
|
||||
vi.spyOn(server as any, 'searchNodes').mockResolvedValue({ results: [] });
|
||||
vi.spyOn(server as any, 'getNodeDocumentation').mockResolvedValue({ docs: 'test' });
|
||||
vi.spyOn(server as any, 'getNodeEssentials').mockResolvedValue({ essentials: true });
|
||||
vi.spyOn(server as any, 'searchNodeProperties').mockResolvedValue({ properties: [] });
|
||||
// Note: getNodeForTask removed in v2.15.0
|
||||
vi.spyOn(server as any, 'validateNodeConfig').mockResolvedValue({ valid: true });
|
||||
@@ -159,15 +158,15 @@ describe('Parameter Validation', () => {
|
||||
vi.spyOn(server as any, 'validateWorkflowExpressions').mockResolvedValue({ valid: true });
|
||||
});
|
||||
|
||||
describe('get_node_info', () => {
|
||||
describe('get_node', () => {
|
||||
it('should require nodeType parameter', async () => {
|
||||
await expect(server.testExecuteTool('get_node_info', {}))
|
||||
.rejects.toThrow('Missing required parameters for get_node_info: nodeType');
|
||||
await expect(server.testExecuteTool('get_node', {}))
|
||||
.rejects.toThrow('Missing required parameters for get_node: nodeType');
|
||||
});
|
||||
|
||||
it('should succeed with valid nodeType', async () => {
|
||||
const result = await server.testExecuteTool('get_node_info', {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
const result = await server.testExecuteTool('get_node', {
|
||||
nodeType: 'nodes-base.httpRequest'
|
||||
});
|
||||
expect(result).toEqual({ mockResult: true });
|
||||
});
|
||||
@@ -424,8 +423,8 @@ describe('Parameter Validation', () => {
|
||||
describe('Error Message Quality', () => {
|
||||
it('should provide clear error messages with tool name', () => {
|
||||
expect(() => {
|
||||
server.testValidateToolParams('get_node_info', {}, ['nodeType']);
|
||||
}).toThrow('Missing required parameters for get_node_info: nodeType. Please provide the required parameters to use this tool.');
|
||||
server.testValidateToolParams('get_node', {}, ['nodeType']);
|
||||
}).toThrow('Missing required parameters for get_node: nodeType. Please provide the required parameters to use this tool.');
|
||||
});
|
||||
|
||||
it('should list all missing parameters', () => {
|
||||
@@ -447,11 +446,11 @@ describe('Parameter Validation', () => {
|
||||
it('should convert validation errors to MCP error responses rather than throwing exceptions', async () => {
|
||||
// This test simulates what happens at the MCP level when a tool validation fails
|
||||
// The server should catch the validation error and return it as an MCP error response
|
||||
|
||||
|
||||
// Directly test the executeTool method to ensure it throws appropriately
|
||||
// The MCP server's request handler should catch these and convert to error responses
|
||||
await expect(server.testExecuteTool('get_node_info', {}))
|
||||
.rejects.toThrow('Missing required parameters for get_node_info: nodeType');
|
||||
await expect(server.testExecuteTool('get_node', {}))
|
||||
.rejects.toThrow('Missing required parameters for get_node: nodeType');
|
||||
|
||||
await expect(server.testExecuteTool('search_nodes', {}))
|
||||
.rejects.toThrow('search_nodes: Validation failed:\n • query: query is required');
|
||||
@@ -462,20 +461,19 @@ describe('Parameter Validation', () => {
|
||||
|
||||
it('should handle edge cases in parameter validation gracefully', async () => {
|
||||
// Test with null args (should be handled by args = args || {})
|
||||
await expect(server.testExecuteTool('get_node_info', null))
|
||||
await expect(server.testExecuteTool('get_node', null))
|
||||
.rejects.toThrow('Missing required parameters');
|
||||
|
||||
|
||||
// Test with undefined args
|
||||
await expect(server.testExecuteTool('get_node_info', undefined))
|
||||
await expect(server.testExecuteTool('get_node', undefined))
|
||||
.rejects.toThrow('Missing required parameters');
|
||||
});
|
||||
|
||||
it('should provide consistent error format across all tools', async () => {
|
||||
// Tools using legacy validation
|
||||
const legacyValidationTools = [
|
||||
{ name: 'get_node_info', args: {}, expected: 'Missing required parameters for get_node_info: nodeType' },
|
||||
{ name: 'get_node', args: {}, expected: 'Missing required parameters for get_node: nodeType' },
|
||||
{ name: 'get_node_documentation', args: {}, expected: 'Missing required parameters for get_node_documentation: nodeType' },
|
||||
{ name: 'get_node_essentials', args: {}, expected: 'Missing required parameters for get_node_essentials: nodeType' },
|
||||
{ name: 'search_node_properties', args: {}, expected: 'Missing required parameters for search_node_properties: nodeType, query' },
|
||||
// Note: get_node_for_task removed in v2.15.0
|
||||
{ name: 'get_property_dependencies', args: {}, expected: 'Missing required parameters for get_property_dependencies: nodeType' },
|
||||
|
||||
@@ -103,8 +103,8 @@ describe('n8nDocumentationToolsFinal', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('get_node_info', () => {
|
||||
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'get_node_info');
|
||||
describe('get_node', () => {
|
||||
const tool = n8nDocumentationToolsFinal.find(t => t.name === 'get_node');
|
||||
|
||||
it('should exist', () => {
|
||||
expect(tool).toBeDefined();
|
||||
@@ -114,8 +114,8 @@ describe('n8nDocumentationToolsFinal', () => {
|
||||
expect(tool?.inputSchema.required).toContain('nodeType');
|
||||
});
|
||||
|
||||
it('should mention performance implications in description', () => {
|
||||
expect(tool?.description).toMatch(/100KB\+|large|full/i);
|
||||
it('should mention detail levels in description', () => {
|
||||
expect(tool?.description).toMatch(/minimal|standard|full/i);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -206,9 +206,8 @@ describe('n8nDocumentationToolsFinal', () => {
|
||||
it('should include examples or key information in descriptions', () => {
|
||||
const toolsWithExamples = [
|
||||
'list_nodes',
|
||||
'get_node_info',
|
||||
'get_node',
|
||||
'search_nodes',
|
||||
'get_node_essentials',
|
||||
'get_node_documentation'
|
||||
];
|
||||
|
||||
@@ -252,7 +251,7 @@ describe('n8nDocumentationToolsFinal', () => {
|
||||
it('should have tools for all major categories', () => {
|
||||
const categories = {
|
||||
discovery: ['list_nodes', 'search_nodes', 'list_ai_tools'],
|
||||
configuration: ['get_node_info', 'get_node_essentials', 'get_node_documentation'],
|
||||
configuration: ['get_node', 'get_node_documentation'],
|
||||
validation: ['validate_node_operation', 'validate_workflow', 'validate_node_minimal'],
|
||||
templates: ['list_tasks', 'search_templates', 'list_templates', 'get_template', 'list_node_templates'], // get_node_for_task removed in v2.15.0
|
||||
documentation: ['tools_documentation']
|
||||
|
||||
Reference in New Issue
Block a user