ros/n8n-mcp
1
0
Fork 0
mirror of https://github.com/czlonkowski/n8n-mcp.git synced 2026-03-21 09:53:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revert to v2.18.10 - Remove session persistence (v2.19.0-v2.19.5) (#322)

Browse Source 
After 5 consecutive hotfix attempts, session persistence has proven
architecturally incompatible with the MCP SDK. Rolling back to last
known stable version.

## Removed
- 16 new files (session types, docs, tests, planning docs)
- 1,100+ lines of session persistence code
- Session restoration hooks and lifecycle events
- Retry policy and warm-start implementations

## Restored
- Stable v2.18.10 codebase
- Library export fields (from PR #310)
- All core MCP functionality

## Breaking Changes
- Session persistence APIs removed
- onSessionNotFound hook removed
- Session lifecycle events removed

This reverts commits fe13091 through 1d34ad8.
Restores commit 4566253 (v2.18.10, PR #310).

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

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Romuald Członkowski
2025-10-14 10:13:43 +02:00
committed by GitHub
parent fe1309151a
commit 8d20c64f5c
25 changed files with 97 additions and 13086 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1079
src/http-server-single-session.ts
View File

File diff suppressed because it is too large Load Diff

7
src/index.ts
View File

@@ -19,13 +19,6 @@ export {
isInstanceContext
} from './types/instance-context';
// Session restoration types (v2.19.0)
export type {
SessionRestoreHook,
SessionRestorationOptions,
SessionState
} from './types/session-restoration';
// Re-export MCP SDK types for convenience
export type {
Tool,

186
src/mcp-engine.ts
View File

@@ -9,7 +9,6 @@ import { Request, Response } from 'express';
import { SingleSessionHTTPServer } from './http-server-single-session';
import { logger } from './utils/logger';
import { InstanceContext } from './types/instance-context';
import { SessionRestoreHook, SessionState } from './types/session-restoration';
export interface EngineHealth {
status: 'healthy' | 'unhealthy';
@@ -26,71 +25,6 @@ export interface EngineHealth {
export interface EngineOptions {
sessionTimeout?: number;
logLevel?: 'error' | 'warn' | 'info' | 'debug';
/**
* Session restoration hook for multi-tenant persistence
* Called when a client tries to use an unknown session ID
* Return instance context to restore the session, or null to reject
*
* @security IMPORTANT: Implement rate limiting in this hook to prevent abuse.
* Malicious clients could trigger excessive database lookups by sending random
* session IDs. Consider using express-rate-limit or similar middleware.
*
* @since 2.19.0
*/
onSessionNotFound?: SessionRestoreHook;
/**
* Maximum time to wait for session restoration (milliseconds)
* @default 5000 (5 seconds)
* @since 2.19.0
*/
sessionRestorationTimeout?: number;
/**
* Session lifecycle event handlers (Phase 3 - REQ-4)
*
* Optional callbacks for session lifecycle events:
* - onSessionCreated: Called when a new session is created
* - onSessionRestored: Called when a session is restored from storage
* - onSessionAccessed: Called on EVERY request (consider throttling!)
* - onSessionExpired: Called when a session expires
* - onSessionDeleted: Called when a session is manually deleted
*
* All handlers are fire-and-forget (non-blocking).
* Errors are logged but don't affect session operations.
*
* @since 2.19.0
*/
sessionEvents?: {
onSessionCreated?: (sessionId: string, instanceContext: InstanceContext) => void | Promise<void>;
onSessionRestored?: (sessionId: string, instanceContext: InstanceContext) => void | Promise<void>;
onSessionAccessed?: (sessionId: string) => void | Promise<void>;
onSessionExpired?: (sessionId: string) => void | Promise<void>;
onSessionDeleted?: (sessionId: string) => void | Promise<void>;
};
/**
* Number of retry attempts for failed session restoration (Phase 4 - REQ-7)
*
* When the restoration hook throws an error, the system will retry
* up to this many times with a delay between attempts.
*
* Timeout errors are NOT retried (already took too long).
* The overall timeout applies to ALL retry attempts combined.
*
* @default 0 (no retries, opt-in)
* @since 2.19.0
*/
sessionRestorationRetries?: number;
/**
* Delay between retry attempts in milliseconds (Phase 4 - REQ-7)
*
* @default 100 (100 milliseconds)
* @since 2.19.0
*/
sessionRestorationRetryDelay?: number;
}
export class N8NMCPEngine {
@@ -98,9 +32,9 @@ export class N8NMCPEngine {
private startTime: Date;
constructor(options: EngineOptions = {}) {
this.server = new SingleSessionHTTPServer(options);
this.server = new SingleSessionHTTPServer();
this.startTime = new Date();
if (options.logLevel) {
process.env.LOG_LEVEL = options.logLevel;
}
@@ -163,7 +97,7 @@ export class N8NMCPEngine {
total: Math.round(memoryUsage.heapTotal / 1024 / 1024),
unit: 'MB'
},
version: '2.19.4'
version: '2.3.2'
};
} catch (error) {
logger.error('Health check failed:', error);
@@ -172,7 +106,7 @@ export class N8NMCPEngine {
uptime: 0,
sessionActive: false,
memoryUsage: { used: 0, total: 0, unit: 'MB' },
version: '2.19.4'
version: '2.3.2'
};
}
}
@@ -184,118 +118,10 @@ export class N8NMCPEngine {
getSessionInfo(): { active: boolean; sessionId?: string; age?: number } {
return this.server.getSessionInfo();
}
/**
* Get all active session IDs (Phase 2 - REQ-5)
* Returns array of currently active session IDs
*
* @returns Array of session IDs
* @since 2.19.0
*
* @example
* ```typescript
* const engine = new N8NMCPEngine();
* const sessionIds = engine.getActiveSessions();
* console.log(`Active sessions: ${sessionIds.length}`);
* ```
*/
getActiveSessions(): string[] {
return this.server.getActiveSessions();
}
/**
* Get session state for a specific session (Phase 2 - REQ-5)
* Returns session state or null if session doesn't exist
*
* @param sessionId - The session ID to get state for
* @returns SessionState object or null
* @since 2.19.0
*
* @example
* ```typescript
* const state = engine.getSessionState('session-123');
* if (state) {
* // Save to database
* await db.saveSession(state);
* }
* ```
*/
getSessionState(sessionId: string): SessionState | null {
return this.server.getSessionState(sessionId);
}
/**
* Get all session states (Phase 2 - REQ-5)
* Returns array of all active session states for bulk backup
*
* @returns Array of SessionState objects
* @since 2.19.0
*
* @example
* ```typescript
* // Periodic backup every 5 minutes
* setInterval(async () => {
* const states = engine.getAllSessionStates();
* for (const state of states) {
* await database.upsertSession(state);
* }
* }, 300000);
* ```
*/
getAllSessionStates(): SessionState[] {
return this.server.getAllSessionStates();
}
/**
* Manually restore a session (Phase 2 - REQ-5)
* Creates a session with the given ID and instance context
*
* @param sessionId - The session ID to restore
* @param instanceContext - Instance configuration
* @returns true if session was restored successfully, false otherwise
* @since 2.19.0
*
* @example
* ```typescript
* // Restore session from database
* const session = await db.loadSession('session-123');
* if (session) {
* const restored = engine.restoreSession(
* session.sessionId,
* session.instanceContext
* );
* console.log(`Restored: ${restored}`);
* }
* ```
*/
restoreSession(sessionId: string, instanceContext: InstanceContext): boolean {
return this.server.manuallyRestoreSession(sessionId, instanceContext);
}
/**
* Manually delete a session (Phase 2 - REQ-5)
* Removes the session and cleans up resources
*
* @param sessionId - The session ID to delete
* @returns true if session was deleted, false if not found
* @since 2.19.0
*
* @example
* ```typescript
* // Delete expired session
* const deleted = engine.deleteSession('session-123');
* if (deleted) {
* await db.deleteSession('session-123');
* }
* ```
*/
deleteSession(sessionId: string): boolean {
return this.server.manuallyDeleteSession(sessionId);
}
/**
* Graceful shutdown for service lifecycle
*
*
* @example
* process.on('SIGTERM', async () => {
* await engine.shutdown();

35
src/mcp/server.ts
View File

@@ -267,13 +267,6 @@ export class N8NDocumentationMCPServer {
private dbHealthChecked: boolean = false;
private async validateDatabaseHealth(): Promise<void> {
// CRITICAL: Skip all database validation in test mode
// This allows session lifecycle tests to use empty :memory: databases
if (process.env.NODE_ENV === 'test') {
logger.debug('Skipping database validation in test mode');
return;
}
if (!this.db) return;
try {
@@ -285,26 +278,18 @@ export class N8NDocumentationMCPServer {
throw new Error('Database is empty. Run "npm run rebuild" to populate node data.');
}
// Check FTS5 support before attempting FTS5 queries
// sql.js doesn't support FTS5, so we need to skip FTS5 validation for sql.js databases
const hasFTS5 = this.db.checkFTS5Support();
// Check if FTS5 table exists
const ftsExists = this.db.prepare(`
SELECT name FROM sqlite_master
WHERE type='table' AND name='nodes_fts'
`).get();
if (!hasFTS5) {
logger.warn('FTS5 not supported (likely using sql.js) - search will use basic queries');
if (!ftsExists) {
logger.warn('FTS5 table missing - search performance will be degraded. Please run: npm run rebuild');
} else {
// Only check FTS5 table if FTS5 is supported
const ftsExists = this.db.prepare(`
SELECT name FROM sqlite_master
WHERE type='table' AND name='nodes_fts'
`).get();
if (!ftsExists) {
logger.warn('FTS5 table missing - search performance will be degraded. Please run: npm run rebuild');
} else {
const ftsCount = this.db.prepare('SELECT COUNT(*) as count FROM nodes_fts').get() as { count: number };
if (ftsCount.count === 0) {
logger.warn('FTS5 index is empty - search will not work properly. Please run: npm run rebuild');
}
const ftsCount = this.db.prepare('SELECT COUNT(*) as count FROM nodes_fts').get() as { count: number };
if (ftsCount.count === 0) {
logger.warn('FTS5 index is empty - search will not work properly. Please run: npm run rebuild');
}
}

242
src/types/session-restoration.ts
View File

@@ -1,242 +0,0 @@
/**
* Session Restoration Types
*
* Defines types for session persistence and restoration functionality.
* Enables multi-tenant backends to restore sessions after container restarts.
*
* @since 2.19.0
*/
import { InstanceContext } from './instance-context';
/**
* Session restoration hook callback
*
* Called when a client tries to use an unknown session ID.
* The backend can load session state from external storage (database, Redis, etc.)
* and return the instance context to recreate the session.
*
* @param sessionId - The session ID that was not found in memory
* @returns Instance context to restore the session, or null if session should not be restored
*
* @example
* ```typescript
* const engine = new N8NMCPEngine({
* onSessionNotFound: async (sessionId) => {
* // Load from database
* const session = await db.loadSession(sessionId);
* if (!session || session.expired) return null;
* return session.instanceContext;
* }
* });
* ```
*/
export type SessionRestoreHook = (sessionId: string) => Promise<InstanceContext | null>;
/**
* Session restoration configuration options
*
* @since 2.19.0
*/
export interface SessionRestorationOptions {
/**
* Session timeout in milliseconds
* After this period of inactivity, sessions are expired and cleaned up
* @default 1800000 (30 minutes)
*/
sessionTimeout?: number;
/**
* Maximum time to wait for session restoration hook to complete
* If the hook takes longer than this, the request will fail with 408 Request Timeout
* @default 5000 (5 seconds)
*/
sessionRestorationTimeout?: number;
/**
* Hook called when a client tries to use an unknown session ID
* Return instance context to restore the session, or null to reject
*
* @param sessionId - The session ID that was not found
* @returns Instance context for restoration, or null
*
* Error handling:
* - Hook throws exception → 500 Internal Server Error
* - Hook times out → 408 Request Timeout
* - Hook returns null → 400 Bad Request (session not found)
* - Hook returns invalid context → 400 Bad Request (invalid context)
*/
onSessionNotFound?: SessionRestoreHook;
/**
* Number of retry attempts for failed session restoration
*
* When the restoration hook throws an error, the system will retry
* up to this many times with a delay between attempts.
*
* Timeout errors are NOT retried (already took too long).
*
* Note: The overall timeout (sessionRestorationTimeout) applies to
* ALL retry attempts combined, not per attempt.
*
* @default 0 (no retries)
* @example
* ```typescript
* const engine = new N8NMCPEngine({
* onSessionNotFound: async (id) => db.loadSession(id),
* sessionRestorationRetries: 2, // Retry up to 2 times
* sessionRestorationRetryDelay: 100 // 100ms between retries
* });
* ```
* @since 2.19.0
*/
sessionRestorationRetries?: number;
/**
* Delay between retry attempts in milliseconds
*
* @default 100 (100 milliseconds)
* @since 2.19.0
*/
sessionRestorationRetryDelay?: number;
}
/**
* Session state for persistence
* Contains all information needed to restore a session after restart
*
* @since 2.19.0
*/
export interface SessionState {
/**
* Unique session identifier
*/
sessionId: string;
/**
* Instance-specific configuration
* Contains n8n API credentials and instance ID
*/
instanceContext: InstanceContext;
/**
* When the session was created
*/
createdAt: Date;
/**
* Last time the session was accessed
* Used for TTL-based expiration
*/
lastAccess: Date;
/**
* When the session will expire
* Calculated from lastAccess + sessionTimeout
*/
expiresAt: Date;
/**
* Optional metadata for application-specific use
*/
metadata?: Record<string, any>;
}
/**
* Session lifecycle event handlers
*
* These callbacks are called at various points in the session lifecycle.
* All callbacks are optional and should not throw errors.
*
* ⚠️ Performance Note: onSessionAccessed is called on EVERY request.
* Consider implementing throttling if you need database updates.
*
* @example
* ```typescript
* import throttle from 'lodash.throttle';
*
* const engine = new N8NMCPEngine({
* sessionEvents: {
* onSessionCreated: async (sessionId, context) => {
* await db.saveSession(sessionId, context);
* },
* onSessionAccessed: throttle(async (sessionId) => {
* await db.updateLastAccess(sessionId);
* }, 60000) // Max once per minute per session
* }
* });
* ```
*
* @since 2.19.0
*/
export interface SessionLifecycleEvents {
/**
* Called when a new session is created (not restored)
*
* Use cases:
* - Save session to database for persistence
* - Track session creation metrics
* - Initialize session-specific resources
*
* @param sessionId - The newly created session ID
* @param instanceContext - The instance context for this session
*/
onSessionCreated?: (sessionId: string, instanceContext: InstanceContext) => void | Promise<void>;
/**
* Called when a session is restored from external storage
*
* Use cases:
* - Track session restoration metrics
* - Log successful recovery after restart
* - Update database restoration timestamp
*
* @param sessionId - The restored session ID
* @param instanceContext - The restored instance context
*/
onSessionRestored?: (sessionId: string, instanceContext: InstanceContext) => void | Promise<void>;
/**
* Called on EVERY request that uses an existing session
*
* ⚠️ HIGH FREQUENCY: This event fires for every MCP tool call.
* For a busy session, this could be 100+ calls per minute.
*
* Recommended: Implement throttling if you need database updates
*
* Use cases:
* - Update session last_access timestamp (throttled)
* - Track session activity metrics
* - Extend session TTL in database
*
* @param sessionId - The session ID that was accessed
*/
onSessionAccessed?: (sessionId: string) => void | Promise<void>;
/**
* Called when a session expires due to inactivity
*
* Called during cleanup cycle (every 5 minutes) BEFORE session removal.
* This allows you to perform cleanup operations before the session is gone.
*
* Use cases:
* - Delete session from database
* - Log session expiration metrics
* - Cleanup session-specific resources
*
* @param sessionId - The session ID that expired
*/
onSessionExpired?: (sessionId: string) => void | Promise<void>;
/**
* Called when a session is manually deleted
*
* Use cases:
* - Delete session from database
* - Cascade delete related data
* - Log manual session termination
*
* @param sessionId - The session ID that was deleted
*/
onSessionDeleted?: (sessionId: string) => void | Promise<void>;
}