ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement n8n integration improvements and protocol version negotiation

Browse Source 
- Add intelligent protocol version negotiation (2024-11-05 for n8n, 2025-03-26 for standard clients)
- Fix memory leak potential with async cleanup and connection close handling
- Enhance error sanitization for production environments
- Add schema validation for n8n nested output workaround
- Improve Docker security with unpredictable UIDs/GIDs
- Create n8n-friendly tool descriptions to reduce schema validation errors
- Add comprehensive protocol negotiation test suite

Addresses code review feedback:
- Protocol version inconsistency resolved
- Memory management improved
- Error information leakage fixed
- Docker security enhanced

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-08-01 14:23:48 +02:00
parent 6cdb52f56f
commit 3fec6813f3
21 changed files with 2517 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -16,11 +16,16 @@ import { getStartupBaseUrl, formatEndpointUrls, detectBaseUrl } from './utils/ur
import { PROJECT_VERSION } from './utils/version';
import { v4 as uuidv4 } from 'uuid';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
import {
negotiateProtocolVersion,
logProtocolNegotiation,
STANDARD_PROTOCOL_VERSION
} from './utils/protocol-version';
dotenv.config();
// Protocol version constant
const PROTOCOL_VERSION = '2024-11-05';
// Protocol version constant - will be negotiated per client
const DEFAULT_PROTOCOL_VERSION = STANDARD_PROTOCOL_VERSION;
// Session management constants
const MAX_SESSIONS = 100;
@@ -67,8 +72,12 @@ export class SingleSessionHTTPServer {
* Start periodic session cleanup
*/
private startSessionCleanup(): void {
this.cleanupTimer = setInterval(() => {
this.cleanupExpiredSessions();
this.cleanupTimer = setInterval(async () => {
try {
await this.cleanupExpiredSessions();
} catch (error) {
logger.error('Error during session cleanup', error);
}
}, SESSION_CLEANUP_INTERVAL);
logger.info('Session cleanup started', {
@@ -150,6 +159,40 @@ export class SingleSessionHTTPServer {
return uuidv4Regex.test(sessionId);
}
/**
* Sanitize error information for client responses
*/
private sanitizeErrorForClient(error: unknown): { message: string; code: string } {
const isProduction = process.env.NODE_ENV === 'production';
if (error instanceof Error) {
// In production, only return generic messages
if (isProduction) {
// Map known error types to safe messages
if (error.message.includes('Unauthorized') || error.message.includes('authentication')) {
return { message: 'Authentication failed', code: 'AUTH_ERROR' };
}
if (error.message.includes('Session') || error.message.includes('session')) {
return { message: 'Session error', code: 'SESSION_ERROR' };
}
if (error.message.includes('Invalid') || error.message.includes('validation')) {
return { message: 'Validation error', code: 'VALIDATION_ERROR' };
}
// Default generic error
return { message: 'Internal server error', code: 'INTERNAL_ERROR' };
}
// In development, return more details but no stack traces
return {
message: error.message.substring(0, 200), // Limit message length
code: error.name || 'ERROR'
};
}
// For non-Error objects
return { message: 'An error occurred', code: 'UNKNOWN_ERROR' };
}
/**
* Update session last access time
*/
@@ -304,11 +347,12 @@ export class SingleSessionHTTPServer {
// For initialize requests: always create new transport and server
logger.info('handleRequest: Creating new transport for initialize request');
const newSessionId = uuidv4();
// Use client-provided session ID or generate one if not provided
const sessionIdToUse = sessionId || uuidv4();
const server = new N8NDocumentationMCPServer();
transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => newSessionId,
sessionIdGenerator: () => sessionIdToUse,
onsessioninitialized: (initializedSessionId: string) => {
// Store both transport and server by session ID when session is initialized
logger.info('handleRequest: Session initialized, storing transport and server', {
@@ -415,11 +459,16 @@ export class SingleSessionHTTPServer {
});
if (!res.headersSent) {
// Send sanitized error to client
const sanitizedError = this.sanitizeErrorForClient(error);
res.status(500).json({
jsonrpc: '2.0',
error: {
code: -32603,
message: error instanceof Error ? error.message : 'Internal server error'
message: sanitizedError.message,
data: {
code: sanitizedError.code
}
},
id: req.body?.id || null
});
@@ -618,12 +667,22 @@ export class SingleSessionHTTPServer {
bodyContent: req.body ? JSON.stringify(req.body, null, 2) : 'undefined'
});
// Negotiate protocol version for test endpoint
const negotiationResult = negotiateProtocolVersion(
undefined, // no client version in test
undefined, // no client info
req.get('user-agent'),
req.headers
);
logProtocolNegotiation(negotiationResult, logger, 'TEST_ENDPOINT');
// Test what a basic MCP initialize request should look like
const testResponse = {
jsonrpc: '2.0',
id: req.body?.id || 1,
result: {
protocolVersion: PROTOCOL_VERSION,
protocolVersion: negotiationResult.version,
capabilities: {
tools: {}
},
@@ -681,8 +740,18 @@ export class SingleSessionHTTPServer {
// In n8n mode, return protocol version and server info
if (process.env.N8N_MODE === 'true') {
// Negotiate protocol version for n8n mode
const negotiationResult = negotiateProtocolVersion(
undefined, // no client version in GET request
undefined, // no client info
req.get('user-agent'),
req.headers
);
logProtocolNegotiation(negotiationResult, logger, 'N8N_MODE_GET');
res.json({
protocolVersion: PROTOCOL_VERSION,
protocolVersion: negotiationResult.version,
serverInfo: {
name: 'n8n-mcp',
version: PROJECT_VERSION,
@@ -800,6 +869,28 @@ export class SingleSessionHTTPServer {
originalUrl: req.originalUrl
});
// Handle connection close to immediately clean up sessions
const sessionId = req.headers['mcp-session-id'] as string | undefined;
// Only add event listener if the request object supports it (not in test mocks)
if (typeof req.on === 'function') {
req.on('close', () => {
if (!res.headersSent && sessionId) {
logger.info('Connection closed before response sent', { sessionId });
// Schedule immediate cleanup if connection closes unexpectedly
setImmediate(() => {
if (this.sessionMetadata[sessionId]) {
const metadata = this.sessionMetadata[sessionId];
const timeSinceAccess = Date.now() - metadata.lastAccess.getTime();
// Only remove if it's been inactive for a bit to avoid race conditions
if (timeSinceAccess > 60000) { // 1 minute
this.removeSession(sessionId, 'connection_closed');
}
}
});
}
});
}
// Enhanced authentication check with specific logging
const authHeader = req.headers.authorization;

17
src/http-server.ts
View File

@@ -14,6 +14,11 @@ import { isN8nApiConfigured } from './config/n8n-api';
import dotenv from 'dotenv';
import { readFileSync } from 'fs';
import { getStartupBaseUrl, formatEndpointUrls, detectBaseUrl } from './utils/url-detector';
import {
negotiateProtocolVersion,
logProtocolNegotiation,
N8N_PROTOCOL_VERSION
} from './utils/protocol-version';
dotenv.config();
@@ -342,10 +347,20 @@ export async function startFixedHTTPServer() {
switch (jsonRpcRequest.method) {
case 'initialize':
// Negotiate protocol version for this client/request
const negotiationResult = negotiateProtocolVersion(
jsonRpcRequest.params?.protocolVersion,
jsonRpcRequest.params?.clientInfo,
req.get('user-agent'),
req.headers
);
logProtocolNegotiation(negotiationResult, logger, 'HTTP_SERVER_INITIALIZE');
response = {
jsonrpc: '2.0',
result: {
protocolVersion: '2024-11-05',
protocolVersion: negotiationResult.version,
capabilities: {
tools: {},
resources: {}

439
src/mcp/server.ts
View File

@@ -9,6 +9,8 @@ import { existsSync, promises as fs } from 'fs';
import path from 'path';
import { n8nDocumentationToolsFinal } from './tools';
import { n8nManagementTools } from './tools-n8n-manager';
import { makeToolsN8nFriendly } from './tools-n8n-friendly';
import { getWorkflowExampleString } from './workflow-examples';
import { logger } from '../utils/logger';
import { NodeRepository } from '../database/node-repository';
import { DatabaseAdapter, createDatabaseAdapter } from '../database/database-adapter';
@@ -26,6 +28,11 @@ import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
import { getToolDocumentation, getToolsOverview } from './tools-documentation';
import { PROJECT_VERSION } from '../utils/version';
import { normalizeNodeType, getNodeTypeAlternatives, getWorkflowNodeType } from '../utils/node-utils';
import {
negotiateProtocolVersion,
logProtocolNegotiation,
STANDARD_PROTOCOL_VERSION
} from '../utils/protocol-version';
interface NodeRow {
node_type: string;
@@ -52,6 +59,7 @@ export class N8NDocumentationMCPServer {
private templateService: TemplateService | null = null;
private initialized: Promise<void>;
private cache = new SimpleCache();
private clientInfo: any = null;
constructor() {
// Check for test environment first
@@ -154,9 +162,39 @@ export class N8NDocumentationMCPServer {
private setupHandlers(): void {
// Handle initialization
this.server.setRequestHandler(InitializeRequestSchema, async () => {
this.server.setRequestHandler(InitializeRequestSchema, async (request) => {
const clientVersion = request.params.protocolVersion;
const clientCapabilities = request.params.capabilities;
const clientInfo = request.params.clientInfo;
logger.info('MCP Initialize request received', {
clientVersion,
clientCapabilities,
clientInfo
});
// Store client info for later use
this.clientInfo = clientInfo;
// Negotiate protocol version based on client information
const negotiationResult = negotiateProtocolVersion(
clientVersion,
clientInfo,
undefined, // no user agent in MCP protocol
undefined // no headers in MCP protocol
);
logProtocolNegotiation(negotiationResult, logger, 'MCP_INITIALIZE');
// Warn if there's a version mismatch (for debugging)
if (clientVersion && clientVersion !== negotiationResult.version) {
logger.warn(`Protocol version negotiated: client requested ${clientVersion}, server will use ${negotiationResult.version}`, {
reasoning: negotiationResult.reasoning
});
}
const response = {
protocolVersion: '2024-11-05',
protocolVersion: negotiationResult.version,
capabilities: {
tools: {},
},
@@ -166,18 +204,14 @@ export class N8NDocumentationMCPServer {
},
};
// Debug logging
if (process.env.DEBUG_MCP === 'true') {
logger.debug('Initialize handler called', { response });
}
logger.info('MCP Initialize response', { response });
return response;
});
// Handle tool listing
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
this.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
// Combine documentation tools with management tools if API is configured
const tools = [...n8nDocumentationToolsFinal];
let tools = [...n8nDocumentationToolsFinal];
const isConfigured = isN8nApiConfigured();
if (isConfigured) {
@@ -187,6 +221,27 @@ export class N8NDocumentationMCPServer {
logger.debug(`Tool listing: ${tools.length} tools available (documentation only)`);
}
// Check if client is n8n (from initialization)
const clientInfo = this.clientInfo;
const isN8nClient = clientInfo?.name?.includes('n8n') ||
clientInfo?.name?.includes('langchain');
if (isN8nClient) {
logger.info('Detected n8n client, using n8n-friendly tool descriptions');
tools = makeToolsN8nFriendly(tools);
}
// Log validation tools' input schemas for debugging
const validationTools = tools.filter(t => t.name.startsWith('validate_'));
validationTools.forEach(tool => {
logger.info('Validation tool schema', {
toolName: tool.name,
inputSchema: JSON.stringify(tool.inputSchema, null, 2),
hasOutputSchema: !!tool.outputSchema,
description: tool.description
});
});
return { tools };
});
@@ -194,25 +249,124 @@ export class N8NDocumentationMCPServer {
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
// Enhanced logging for debugging tool calls
logger.info('Tool call received - DETAILED DEBUG', {
toolName: name,
arguments: JSON.stringify(args, null, 2),
argumentsType: typeof args,
argumentsKeys: args ? Object.keys(args) : [],
hasNodeType: args && 'nodeType' in args,
hasConfig: args && 'config' in args,
configType: args && args.config ? typeof args.config : 'N/A',
rawRequest: JSON.stringify(request.params)
});
// Workaround for n8n's nested output bug
// Check if args contains nested 'output' structure from n8n's memory corruption
let processedArgs = args;
if (args && typeof args === 'object' && 'output' in args) {
try {
const possibleNestedData = args.output;
// If output is a string that looks like JSON, try to parse it
if (typeof possibleNestedData === 'string' && possibleNestedData.trim().startsWith('{')) {
const parsed = JSON.parse(possibleNestedData);
if (parsed && typeof parsed === 'object') {
logger.warn('Detected n8n nested output bug, attempting to extract actual arguments', {
originalArgs: args,
extractedArgs: parsed
});
// Validate the extracted arguments match expected tool schema
if (this.validateExtractedArgs(name, parsed)) {
// Use the extracted data as args
processedArgs = parsed;
} else {
logger.warn('Extracted arguments failed validation, using original args', {
toolName: name,
extractedArgs: parsed
});
}
}
}
} catch (parseError) {
logger.debug('Failed to parse nested output, continuing with original args', {
error: parseError instanceof Error ? parseError.message : String(parseError)
});
}
}
try {
logger.debug(`Executing tool: ${name}`, { args });
const result = await this.executeTool(name, args);
logger.debug(`Executing tool: ${name}`, { args: processedArgs });
const result = await this.executeTool(name, processedArgs);
logger.debug(`Tool ${name} executed successfully`);
return {
// Ensure the result is properly formatted for MCP
let responseText: string;
let structuredContent: any = null;
try {
// For validation tools, check if we should use structured content
if (name.startsWith('validate_') && typeof result === 'object' && result !== null) {
// Clean up the result to ensure it matches the outputSchema
const cleanResult = this.sanitizeValidationResult(result, name);
structuredContent = cleanResult;
responseText = JSON.stringify(cleanResult, null, 2);
} else {
responseText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
}
} catch (jsonError) {
logger.warn(`Failed to stringify tool result for ${name}:`, jsonError);
responseText = String(result);
}
// Validate response size (n8n might have limits)
if (responseText.length > 1000000) { // 1MB limit
logger.warn(`Tool ${name} response is very large (${responseText.length} chars), truncating`);
responseText = responseText.substring(0, 999000) + '\n\n[Response truncated due to size limits]';
structuredContent = null; // Don't use structured content for truncated responses
}
// Build MCP response with strict schema compliance
const mcpResponse: any = {
content: [
{
type: 'text',
text: JSON.stringify(result, null, 2),
type: 'text' as const,
text: responseText,
},
],
};
// For tools with outputSchema, structuredContent is REQUIRED by MCP spec
if (name.startsWith('validate_') && structuredContent !== null) {
mcpResponse.structuredContent = structuredContent;
}
return mcpResponse;
} catch (error) {
logger.error(`Error executing tool ${name}`, error);
const errorMessage = error instanceof Error ? error.message : 'Unknown error';
// Provide more helpful error messages for common n8n issues
let helpfulMessage = `Error executing tool ${name}: ${errorMessage}`;
if (errorMessage.includes('required') || errorMessage.includes('missing')) {
helpfulMessage += '\n\nNote: This error often occurs when the AI agent sends incomplete or incorrectly formatted parameters. Please ensure all required fields are provided with the correct types.';
} else if (errorMessage.includes('type') || errorMessage.includes('expected')) {
helpfulMessage += '\n\nNote: This error indicates a type mismatch. The AI agent may be sending data in the wrong format (e.g., string instead of object).';
} else if (errorMessage.includes('Unknown category') || errorMessage.includes('not found')) {
helpfulMessage += '\n\nNote: The requested resource or category was not found. Please check the available options.';
}
// For n8n schema errors, add specific guidance
if (name.startsWith('validate_') && (errorMessage.includes('config') || errorMessage.includes('nodeType'))) {
helpfulMessage += '\n\nFor validation tools:\n- nodeType should be a string (e.g., "nodes-base.webhook")\n- config should be an object (e.g., {})';
}
return {
content: [
{
type: 'text',
text: `Error executing tool ${name}: ${error instanceof Error ? error.message : 'Unknown error'}`,
text: helpfulMessage,
},
],
isError: true,
@@ -221,6 +375,90 @@ export class N8NDocumentationMCPServer {
});
}
/**
* Sanitize validation result to match outputSchema
*/
private sanitizeValidationResult(result: any, toolName: string): any {
if (!result || typeof result !== 'object') {
return result;
}
const sanitized = { ...result };
// Ensure required fields exist with proper types and filter to schema-defined fields only
if (toolName === 'validate_node_minimal') {
// Filter to only schema-defined fields
const filtered = {
nodeType: String(sanitized.nodeType || ''),
displayName: String(sanitized.displayName || ''),
valid: Boolean(sanitized.valid),
missingRequiredFields: Array.isArray(sanitized.missingRequiredFields)
? sanitized.missingRequiredFields.map(String)
: []
};
return filtered;
} else if (toolName === 'validate_node_operation') {
// Ensure summary exists
let summary = sanitized.summary;
if (!summary || typeof summary !== 'object') {
summary = {
hasErrors: Array.isArray(sanitized.errors) ? sanitized.errors.length > 0 : false,
errorCount: Array.isArray(sanitized.errors) ? sanitized.errors.length : 0,
warningCount: Array.isArray(sanitized.warnings) ? sanitized.warnings.length : 0,
suggestionCount: Array.isArray(sanitized.suggestions) ? sanitized.suggestions.length : 0
};
}
// Filter to only schema-defined fields
const filtered = {
nodeType: String(sanitized.nodeType || ''),
workflowNodeType: String(sanitized.workflowNodeType || sanitized.nodeType || ''),
displayName: String(sanitized.displayName || ''),
valid: Boolean(sanitized.valid),
errors: Array.isArray(sanitized.errors) ? sanitized.errors : [],
warnings: Array.isArray(sanitized.warnings) ? sanitized.warnings : [],
suggestions: Array.isArray(sanitized.suggestions) ? sanitized.suggestions : [],
summary: summary
};
return filtered;
} else if (toolName.startsWith('validate_workflow')) {
sanitized.valid = Boolean(sanitized.valid);
// Ensure arrays exist
sanitized.errors = Array.isArray(sanitized.errors) ? sanitized.errors : [];
sanitized.warnings = Array.isArray(sanitized.warnings) ? sanitized.warnings : [];
// Ensure statistics/summary exists
if (toolName === 'validate_workflow') {
if (!sanitized.summary || typeof sanitized.summary !== 'object') {
sanitized.summary = {
totalNodes: 0,
enabledNodes: 0,
triggerNodes: 0,
validConnections: 0,
invalidConnections: 0,
expressionsValidated: 0,
errorCount: sanitized.errors.length,
warningCount: sanitized.warnings.length
};
}
} else {
if (!sanitized.statistics || typeof sanitized.statistics !== 'object') {
sanitized.statistics = {
totalNodes: 0,
triggerNodes: 0,
validConnections: 0,
invalidConnections: 0,
expressionsValidated: 0
};
}
}
}
// Remove undefined values to ensure clean JSON
return JSON.parse(JSON.stringify(sanitized));
}
/**
* Validate required parameters for tool execution
*/
@@ -238,10 +476,95 @@ export class N8NDocumentationMCPServer {
}
}
/**
* Validate extracted arguments match expected tool schema
*/
private validateExtractedArgs(toolName: string, args: any): boolean {
if (!args || typeof args !== 'object') {
return false;
}
// Get all available tools
const allTools = [...n8nDocumentationToolsFinal, ...n8nManagementTools];
const tool = allTools.find(t => t.name === toolName);
if (!tool || !tool.inputSchema) {
return true; // If no schema, assume valid
}
const schema = tool.inputSchema;
const required = schema.required || [];
const properties = schema.properties || {};
// Check all required fields are present
for (const requiredField of required) {
if (!(requiredField in args)) {
logger.debug(`Extracted args missing required field: ${requiredField}`, {
toolName,
extractedArgs: args,
required
});
return false;
}
}
// Check field types match schema
for (const [fieldName, fieldValue] of Object.entries(args)) {
if (properties[fieldName]) {
const expectedType = properties[fieldName].type;
const actualType = Array.isArray(fieldValue) ? 'array' : typeof fieldValue;
// Basic type validation
if (expectedType && expectedType !== actualType) {
// Special case: number can be coerced from string
if (expectedType === 'number' && actualType === 'string' && !isNaN(Number(fieldValue))) {
continue;
}
logger.debug(`Extracted args field type mismatch: ${fieldName}`, {
toolName,
expectedType,
actualType,
fieldValue
});
return false;
}
}
}
// Check for extraneous fields if additionalProperties is false
if (schema.additionalProperties === false) {
const allowedFields = Object.keys(properties);
const extraFields = Object.keys(args).filter(field => !allowedFields.includes(field));
if (extraFields.length > 0) {
logger.debug(`Extracted args have extra fields`, {
toolName,
extraFields,
allowedFields
});
// For n8n compatibility, we'll still consider this valid but log it
}
}
return true;
}
async executeTool(name: string, args: any): Promise<any> {
// Ensure args is an object
// Ensure args is an object and validate it
args = args || {};
// Log the tool call for debugging n8n issues
logger.info(`Tool execution: ${name}`, {
args: typeof args === 'object' ? JSON.stringify(args) : args,
argsType: typeof args,
argsKeys: typeof args === 'object' ? Object.keys(args) : 'not-object'
});
// Validate that args is actually an object
if (typeof args !== 'object' || args === null) {
throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
}
switch (name) {
case 'tools_documentation':
// No required parameters
@@ -281,9 +604,43 @@ export class N8NDocumentationMCPServer {
return this.listTasks(args.category);
case 'validate_node_operation':
this.validateToolParams(name, args, ['nodeType', 'config']);
// Ensure config is an object
if (typeof args.config !== 'object' || args.config === null) {
logger.warn(`validate_node_operation called with invalid config type: ${typeof args.config}`);
return {
nodeType: args.nodeType || 'unknown',
workflowNodeType: args.nodeType || 'unknown',
displayName: 'Unknown Node',
valid: false,
errors: [{
type: 'config',
property: 'config',
message: 'Invalid config format - expected object',
fix: 'Provide config as an object with node properties'
}],
warnings: [],
suggestions: [],
summary: {
hasErrors: true,
errorCount: 1,
warningCount: 0,
suggestionCount: 0
}
};
}
return this.validateNodeConfig(args.nodeType, args.config, 'operation', args.profile);
case 'validate_node_minimal':
this.validateToolParams(name, args, ['nodeType', 'config']);
// Ensure config is an object
if (typeof args.config !== 'object' || args.config === null) {
logger.warn(`validate_node_minimal called with invalid config type: ${typeof args.config}`);
return {
nodeType: args.nodeType || 'unknown',
displayName: 'Unknown Node',
valid: false,
missingRequiredFields: ['Invalid config format - expected object']
};
}
return this.validateNodeMinimal(args.nodeType, args.config);
case 'get_property_dependencies':
this.validateToolParams(name, args, ['nodeType']);
@@ -1909,6 +2266,56 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
await this.ensureInitialized();
if (!this.repository) throw new Error('Repository not initialized');
// Enhanced logging for workflow validation
logger.info('Workflow validation requested', {
hasWorkflow: !!workflow,
workflowType: typeof workflow,
hasNodes: workflow?.nodes !== undefined,
nodesType: workflow?.nodes ? typeof workflow.nodes : 'undefined',
nodesIsArray: Array.isArray(workflow?.nodes),
nodesCount: Array.isArray(workflow?.nodes) ? workflow.nodes.length : 0,
hasConnections: workflow?.connections !== undefined,
connectionsType: workflow?.connections ? typeof workflow.connections : 'undefined',
options: options
});
// Help n8n AI agents with common mistakes
if (!workflow || typeof workflow !== 'object') {
return {
valid: false,
errors: [{
node: 'workflow',
message: 'Workflow must be an object with nodes and connections',
details: 'Expected format: ' + getWorkflowExampleString()
}],
summary: { errorCount: 1 }
};
}
if (!workflow.nodes || !Array.isArray(workflow.nodes)) {
return {
valid: false,
errors: [{
node: 'workflow',
message: 'Workflow must have a nodes array',
details: 'Expected: workflow.nodes = [array of node objects]. ' + getWorkflowExampleString()
}],
summary: { errorCount: 1 }
};
}
if (!workflow.connections || typeof workflow.connections !== 'object') {
return {
valid: false,
errors: [{
node: 'workflow',
message: 'Workflow must have a connections object',
details: 'Expected: workflow.connections = {} (can be empty object). ' + getWorkflowExampleString()
}],
summary: { errorCount: 1 }
};
}
// Create workflow validator instance
const validator = new WorkflowValidator(
this.repository,

175
src/mcp/tools-n8n-friendly.ts Normal file
View File

@@ -0,0 +1,175 @@
/**
* n8n-friendly tool descriptions
* These descriptions are optimized to reduce schema validation errors in n8n's AI Agent
*
* Key principles:
* 1. Use exact JSON examples in descriptions
* 2. Be explicit about data types
* 3. Keep descriptions short and directive
* 4. Avoid ambiguity
*/
export const n8nFriendlyDescriptions: Record<string, {
description: string;
params: Record<string, string>;
}> = {
// Validation tools - most prone to errors
validate_node_operation: {
description: 'Validate n8n node. ALWAYS pass two parameters: nodeType (string) and config (object). Example call: {"nodeType": "nodes-base.slack", "config": {"resource": "channel", "operation": "create"}}',
params: {
nodeType: 'String value like "nodes-base.slack"',
config: 'Object value like {"resource": "channel", "operation": "create"} or empty object {}',
profile: 'Optional string: "minimal" or "runtime" or "ai-friendly" or "strict"'
}
},
validate_node_minimal: {
description: 'Check required fields. MUST pass: nodeType (string) and config (object). Example: {"nodeType": "nodes-base.webhook", "config": {}}',
params: {
nodeType: 'String like "nodes-base.webhook"',
config: 'Object, use {} for empty'
}
},
// Search and info tools
search_nodes: {
description: 'Search nodes. Pass query (string). Example: {"query": "webhook"}',
params: {
query: 'String keyword like "webhook" or "database"',
limit: 'Optional number, default 20'
}
},
get_node_info: {
description: 'Get node details. Pass nodeType (string). Example: {"nodeType": "nodes-base.httpRequest"}',
params: {
nodeType: 'String with prefix like "nodes-base.httpRequest"'
}
},
get_node_essentials: {
description: 'Get node basics. Pass nodeType (string). Example: {"nodeType": "nodes-base.slack"}',
params: {
nodeType: 'String with prefix like "nodes-base.slack"'
}
},
// Task tools
get_node_for_task: {
description: 'Find node for task. Pass task (string). Example: {"task": "send_http_request"}',
params: {
task: 'String task name like "send_http_request"'
}
},
list_tasks: {
description: 'List tasks by category. Pass category (string). Example: {"category": "HTTP/API"}',
params: {
category: 'String: "HTTP/API" or "Webhooks" or "Database" or "AI/LangChain" or "Data Processing" or "Communication"'
}
},
// Workflow validation
validate_workflow: {
description: 'Validate workflow. Pass workflow object. MUST have: {"workflow": {"nodes": [array of node objects], "connections": {object with node connections}}}. Each node needs: name, type, typeVersion, position.',
params: {
workflow: 'Object with two required fields: nodes (array) and connections (object). Example: {"nodes": [{"name": "Webhook", "type": "n8n-nodes-base.webhook", "typeVersion": 2, "position": [250, 300], "parameters": {}}], "connections": {}}',
options: 'Optional object. Example: {"validateNodes": true, "profile": "runtime"}'
}
},
validate_workflow_connections: {
description: 'Validate workflow connections only. Pass workflow object. Example: {"workflow": {"nodes": [...], "connections": {}}}',
params: {
workflow: 'Object with nodes array and connections object. Minimal example: {"nodes": [{"name": "Webhook"}], "connections": {}}'
}
},
validate_workflow_expressions: {
description: 'Validate n8n expressions in workflow. Pass workflow object. Example: {"workflow": {"nodes": [...], "connections": {}}}',
params: {
workflow: 'Object with nodes array and connections object containing n8n expressions like {{ $json.data }}'
}
},
// Property tools
get_property_dependencies: {
description: 'Get field dependencies. Pass nodeType (string) and optional config (object). Example: {"nodeType": "nodes-base.httpRequest", "config": {}}',
params: {
nodeType: 'String like "nodes-base.httpRequest"',
config: 'Optional object, use {} for empty'
}
},
// AI tool info
get_node_as_tool_info: {
description: 'Get AI tool usage. Pass nodeType (string). Example: {"nodeType": "nodes-base.slack"}',
params: {
nodeType: 'String with prefix like "nodes-base.slack"'
}
},
// Template tools
search_templates: {
description: 'Search workflow templates. Pass query (string). Example: {"query": "chatbot"}',
params: {
query: 'String keyword like "chatbot" or "webhook"',
limit: 'Optional number, default 20'
}
},
get_template: {
description: 'Get template by ID. Pass templateId (number). Example: {"templateId": 1234}',
params: {
templateId: 'Number ID like 1234'
}
},
// Documentation tool
tools_documentation: {
description: 'Get tool docs. Pass optional depth (string). Example: {"depth": "essentials"} or {}',
params: {
depth: 'Optional string: "essentials" or "overview" or "detailed"',
topic: 'Optional string topic name'
}
}
};
/**
* Apply n8n-friendly descriptions to tools
* This function modifies tool descriptions to be more explicit for n8n's AI agent
*/
export function makeToolsN8nFriendly(tools: any[]): any[] {
return tools.map(tool => {
const toolName = tool.name as string;
const friendlyDesc = n8nFriendlyDescriptions[toolName];
if (friendlyDesc) {
// Clone the tool to avoid mutating the original
const updatedTool = { ...tool };
// Update the main description
updatedTool.description = friendlyDesc.description;
// Clone inputSchema if it exists
if (tool.inputSchema?.properties) {
updatedTool.inputSchema = {
...tool.inputSchema,
properties: { ...tool.inputSchema.properties }
};
// Update parameter descriptions
Object.keys(updatedTool.inputSchema.properties).forEach(param => {
if (friendlyDesc.params[param]) {
updatedTool.inputSchema.properties[param] = {
...updatedTool.inputSchema.properties[param],
description: friendlyDesc.params[param]
};
}
});
}
return updatedTool;
}
return tool;
});
}

198
src/mcp/tools.ts
View File

@@ -59,7 +59,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
{
name: 'get_node_info',
description: `Get FULL node schema (100KB+). TIP: Use get_node_essentials first! Returns all properties/operations/credentials. Prefix required: "nodes-base.httpRequest" not "httpRequest".`,
description: `Get full node documentation. Pass nodeType as string with prefix. Example: nodeType="nodes-base.webhook"`,
inputSchema: {
type: 'object',
properties: {
@@ -73,7 +73,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
{
name: 'search_nodes',
description: `Search nodes by keywords. Modes: OR (any word), AND (all words), FUZZY (typos OK). Primary nodes ranked first. Examples: "webhook"→Webhook, "http call"→HTTP Request.`,
description: `Search n8n nodes by keyword. Pass query as string. Example: query="webhook" or query="database". Returns max 20 results.`,
inputSchema: {
type: 'object',
properties: {
@@ -128,7 +128,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
{
name: 'get_node_essentials',
description: `Get 10-20 key properties only (<5KB vs 100KB+). USE THIS FIRST! Includes examples. Format: "nodes-base.httpRequest"`,
description: `Get node essential info. Pass nodeType as string with prefix. Example: nodeType="nodes-base.slack"`,
inputSchema: {
type: 'object',
properties: {
@@ -192,44 +192,103 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
{
name: 'validate_node_operation',
description: `Validate node config. Checks required fields, types, operation rules. Returns errors with fixes. Essential for Slack/Sheets/DB nodes.`,
description: `Validate n8n node configuration. Pass nodeType as string and config as object. Example: nodeType="nodes-base.slack", config={resource:"channel",operation:"create"}`,
inputSchema: {
type: 'object',
properties: {
nodeType: {
type: 'string',
description: 'The node type to validate (e.g., "nodes-base.slack")',
description: 'Node type as string. Example: "nodes-base.slack"',
},
config: {
type: 'object',
description: 'Your node configuration. Must include operation fields (resource/operation/action) if the node has multiple operations.',
description: 'Configuration as object. For simple nodes use {}. For complex nodes include fields like {resource:"channel",operation:"create"}',
},
profile: {
type: 'string',
enum: ['strict', 'runtime', 'ai-friendly', 'minimal'],
description: 'Validation profile: minimal (only required fields), runtime (critical errors only), ai-friendly (balanced - default), strict (all checks including best practices)',
description: 'Profile string: "minimal", "runtime", "ai-friendly", or "strict". Default is "ai-friendly"',
default: 'ai-friendly',
},
},
required: ['nodeType', 'config'],
additionalProperties: false,
},
outputSchema: {
type: 'object',
properties: {
nodeType: { type: 'string' },
workflowNodeType: { type: 'string' },
displayName: { type: 'string' },
valid: { type: 'boolean' },
errors: {
type: 'array',
items: {
type: 'object',
properties: {
type: { type: 'string' },
property: { type: 'string' },
message: { type: 'string' },
fix: { type: 'string' }
}
}
},
warnings: {
type: 'array',
items: {
type: 'object',
properties: {
type: { type: 'string' },
property: { type: 'string' },
message: { type: 'string' },
suggestion: { type: 'string' }
}
}
},
suggestions: { type: 'array', items: { type: 'string' } },
summary: {
type: 'object',
properties: {
hasErrors: { type: 'boolean' },
errorCount: { type: 'number' },
warningCount: { type: 'number' },
suggestionCount: { type: 'number' }
}
}
},
required: ['nodeType', 'displayName', 'valid', 'errors', 'warnings', 'suggestions', 'summary']
},
},
{
name: 'validate_node_minimal',
description: `Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.`,
description: `Check n8n node required fields. Pass nodeType as string and config as empty object {}. Example: nodeType="nodes-base.webhook", config={}`,
inputSchema: {
type: 'object',
properties: {
nodeType: {
type: 'string',
description: 'The node type to validate (e.g., "nodes-base.slack")',
description: 'Node type as string. Example: "nodes-base.slack"',
},
config: {
type: 'object',
description: 'The node configuration to check',
description: 'Configuration object. Always pass {} for empty config',
},
},
required: ['nodeType', 'config'],
additionalProperties: false,
},
outputSchema: {
type: 'object',
properties: {
nodeType: { type: 'string' },
displayName: { type: 'string' },
valid: { type: 'boolean' },
missingRequiredFields: {
type: 'array',
items: { type: 'string' }
}
},
required: ['nodeType', 'displayName', 'valid', 'missingRequiredFields']
},
},
{
@@ -306,7 +365,7 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
properties: {
query: {
type: 'string',
description: 'Search query for template names/descriptions. NOT for node types! Examples: "chatbot", "automation", "social media", "webhook". For node-based search use list_node_templates instead.',
description: 'Search keyword as string. Example: "chatbot"',
},
limit: {
type: 'number',
@@ -382,6 +441,50 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
},
required: ['workflow'],
additionalProperties: false,
},
outputSchema: {
type: 'object',
properties: {
valid: { type: 'boolean' },
summary: {
type: 'object',
properties: {
totalNodes: { type: 'number' },
enabledNodes: { type: 'number' },
triggerNodes: { type: 'number' },
validConnections: { type: 'number' },
invalidConnections: { type: 'number' },
expressionsValidated: { type: 'number' },
errorCount: { type: 'number' },
warningCount: { type: 'number' }
}
},
errors: {
type: 'array',
items: {
type: 'object',
properties: {
node: { type: 'string' },
message: { type: 'string' },
details: { type: 'string' }
}
}
},
warnings: {
type: 'array',
items: {
type: 'object',
properties: {
node: { type: 'string' },
message: { type: 'string' },
details: { type: 'string' }
}
}
},
suggestions: { type: 'array', items: { type: 'string' } }
},
required: ['valid', 'summary']
},
},
{
@@ -396,6 +499,43 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
},
required: ['workflow'],
additionalProperties: false,
},
outputSchema: {
type: 'object',
properties: {
valid: { type: 'boolean' },
statistics: {
type: 'object',
properties: {
totalNodes: { type: 'number' },
triggerNodes: { type: 'number' },
validConnections: { type: 'number' },
invalidConnections: { type: 'number' }
}
},
errors: {
type: 'array',
items: {
type: 'object',
properties: {
node: { type: 'string' },
message: { type: 'string' }
}
}
},
warnings: {
type: 'array',
items: {
type: 'object',
properties: {
node: { type: 'string' },
message: { type: 'string' }
}
}
}
},
required: ['valid', 'statistics']
},
},
{
@@ -410,6 +550,42 @@ export const n8nDocumentationToolsFinal: ToolDefinition[] = [
},
},
required: ['workflow'],
additionalProperties: false,
},
outputSchema: {
type: 'object',
properties: {
valid: { type: 'boolean' },
statistics: {
type: 'object',
properties: {
totalNodes: { type: 'number' },
expressionsValidated: { type: 'number' }
}
},
errors: {
type: 'array',
items: {
type: 'object',
properties: {
node: { type: 'string' },
message: { type: 'string' }
}
}
},
warnings: {
type: 'array',
items: {
type: 'object',
properties: {
node: { type: 'string' },
message: { type: 'string' }
}
}
},
tips: { type: 'array', items: { type: 'string' } }
},
required: ['valid', 'statistics']
},
},
];

112
src/mcp/workflow-examples.ts Normal file
View File

@@ -0,0 +1,112 @@
/**
* Example workflows for n8n AI agents to understand the structure
*/
export const MINIMAL_WORKFLOW_EXAMPLE = {
nodes: [
{
name: "Webhook",
type: "n8n-nodes-base.webhook",
typeVersion: 2,
position: [250, 300],
parameters: {
httpMethod: "POST",
path: "webhook"
}
}
],
connections: {}
};
export const SIMPLE_WORKFLOW_EXAMPLE = {
nodes: [
{
name: "Webhook",
type: "n8n-nodes-base.webhook",
typeVersion: 2,
position: [250, 300],
parameters: {
httpMethod: "POST",
path: "webhook"
}
},
{
name: "Set",
type: "n8n-nodes-base.set",
typeVersion: 2,
position: [450, 300],
parameters: {
mode: "manual",
assignments: {
assignments: [
{
name: "message",
type: "string",
value: "Hello"
}
]
}
}
},
{
name: "Respond to Webhook",
type: "n8n-nodes-base.respondToWebhook",
typeVersion: 1,
position: [650, 300],
parameters: {
respondWith: "firstIncomingItem"
}
}
],
connections: {
"Webhook": {
"main": [
[
{
"node": "Set",
"type": "main",
"index": 0
}
]
]
},
"Set": {
"main": [
[
{
"node": "Respond to Webhook",
"type": "main",
"index": 0
}
]
]
}
}
};
export function getWorkflowExampleString(): string {
return `Example workflow structure:
${JSON.stringify(MINIMAL_WORKFLOW_EXAMPLE, null, 2)}
Each node MUST have:
- name: unique string identifier
- type: full node type with prefix (e.g., "n8n-nodes-base.webhook")
- typeVersion: number (usually 1 or 2)
- position: [x, y] coordinates array
- parameters: object with node-specific settings
Connections format:
{
"SourceNodeName": {
"main": [
[
{
"node": "TargetNodeName",
"type": "main",
"index": 0
}
]
]
}
}`;
}

206
src/scripts/test-protocol-negotiation.ts Normal file
View File

@@ -0,0 +1,206 @@
#!/usr/bin/env node
/**
* Test Protocol Version Negotiation
*
* This script tests the protocol version negotiation logic with different client scenarios.
*/
import {
negotiateProtocolVersion,
isN8nClient,
STANDARD_PROTOCOL_VERSION,
N8N_PROTOCOL_VERSION
} from '../utils/protocol-version';
interface TestCase {
name: string;
clientVersion?: string;
clientInfo?: any;
userAgent?: string;
headers?: Record<string, string>;
expectedVersion: string;
expectedIsN8nClient: boolean;
}
const testCases: TestCase[] = [
{
name: 'Standard MCP client (Claude Desktop)',
clientVersion: '2025-03-26',
clientInfo: { name: 'Claude Desktop', version: '1.0.0' },
expectedVersion: '2025-03-26',
expectedIsN8nClient: false
},
{
name: 'n8n client with specific client info',
clientVersion: '2025-03-26',
clientInfo: { name: 'n8n', version: '1.0.0' },
expectedVersion: N8N_PROTOCOL_VERSION,
expectedIsN8nClient: true
},
{
name: 'LangChain client',
clientVersion: '2025-03-26',
clientInfo: { name: 'langchain-js', version: '0.1.0' },
expectedVersion: N8N_PROTOCOL_VERSION,
expectedIsN8nClient: true
},
{
name: 'n8n client via user agent',
clientVersion: '2025-03-26',
userAgent: 'n8n/1.0.0',
expectedVersion: N8N_PROTOCOL_VERSION,
expectedIsN8nClient: true
},
{
name: 'n8n mode environment variable',
clientVersion: '2025-03-26',
expectedVersion: N8N_PROTOCOL_VERSION,
expectedIsN8nClient: true
},
{
name: 'Client requesting older version',
clientVersion: '2024-06-25',
clientInfo: { name: 'Some Client', version: '1.0.0' },
expectedVersion: '2024-06-25',
expectedIsN8nClient: false
},
{
name: 'Client requesting unsupported version',
clientVersion: '2020-01-01',
clientInfo: { name: 'Old Client', version: '1.0.0' },
expectedVersion: STANDARD_PROTOCOL_VERSION,
expectedIsN8nClient: false
},
{
name: 'No client info provided',
expectedVersion: STANDARD_PROTOCOL_VERSION,
expectedIsN8nClient: false
},
{
name: 'n8n headers detection',
clientVersion: '2025-03-26',
headers: { 'x-n8n-version': '1.0.0' },
expectedVersion: N8N_PROTOCOL_VERSION,
expectedIsN8nClient: true
}
];
async function runTests(): Promise<void> {
console.log('🧪 Testing Protocol Version Negotiation\n');
let passed = 0;
let failed = 0;
// Set N8N_MODE for the environment variable test
const originalN8nMode = process.env.N8N_MODE;
for (const testCase of testCases) {
try {
// Set N8N_MODE for specific test
if (testCase.name.includes('environment variable')) {
process.env.N8N_MODE = 'true';
} else {
delete process.env.N8N_MODE;
}
// Test isN8nClient function
const detectedAsN8n = isN8nClient(testCase.clientInfo, testCase.userAgent, testCase.headers);
// Test negotiateProtocolVersion function
const result = negotiateProtocolVersion(
testCase.clientVersion,
testCase.clientInfo,
testCase.userAgent,
testCase.headers
);
// Check results
const versionCorrect = result.version === testCase.expectedVersion;
const n8nDetectionCorrect = result.isN8nClient === testCase.expectedIsN8nClient;
const isN8nFunctionCorrect = detectedAsN8n === testCase.expectedIsN8nClient;
if (versionCorrect && n8nDetectionCorrect && isN8nFunctionCorrect) {
console.log(`✅ ${testCase.name}`);
console.log(` Version: ${result.version}, n8n client: ${result.isN8nClient}`);
console.log(` Reasoning: ${result.reasoning}\n`);
passed++;
} else {
console.log(`❌ ${testCase.name}`);
console.log(` Expected: version=${testCase.expectedVersion}, isN8n=${testCase.expectedIsN8nClient}`);
console.log(` Got: version=${result.version}, isN8n=${result.isN8nClient}`);
console.log(` isN8nClient function: ${detectedAsN8n} (expected: ${testCase.expectedIsN8nClient})`);
console.log(` Reasoning: ${result.reasoning}\n`);
failed++;
}
} catch (error) {
console.log(`💥 ${testCase.name} - ERROR`);
console.log(` ${error instanceof Error ? error.message : String(error)}\n`);
failed++;
}
}
// Restore original N8N_MODE
if (originalN8nMode) {
process.env.N8N_MODE = originalN8nMode;
} else {
delete process.env.N8N_MODE;
}
// Summary
console.log(`\n📊 Test Results:`);
console.log(` ✅ Passed: ${passed}`);
console.log(` ❌ Failed: ${failed}`);
console.log(` Total: ${passed + failed}`);
if (failed > 0) {
console.log(`\n❌ Some tests failed!`);
process.exit(1);
} else {
console.log(`\n🎉 All tests passed!`);
}
}
// Additional integration test
async function testIntegration(): Promise<void> {
console.log('\n🔧 Integration Test - MCP Server Protocol Negotiation\n');
// This would normally test the actual MCP server, but we'll just verify
// the negotiation logic works in typical scenarios
const scenarios = [
{
name: 'Claude Desktop connecting',
clientInfo: { name: 'Claude Desktop', version: '1.0.0' },
clientVersion: '2025-03-26'
},
{
name: 'n8n connecting via HTTP',
headers: { 'user-agent': 'n8n/1.52.0' },
clientVersion: '2025-03-26'
}
];
for (const scenario of scenarios) {
const result = negotiateProtocolVersion(
scenario.clientVersion,
scenario.clientInfo,
scenario.headers?.['user-agent'],
scenario.headers
);
console.log(`🔍 ${scenario.name}:`);
console.log(` Negotiated version: ${result.version}`);
console.log(` Is n8n client: ${result.isN8nClient}`);
console.log(` Reasoning: ${result.reasoning}\n`);
}
}
if (require.main === module) {
runTests()
.then(() => testIntegration())
.catch(error => {
console.error('Test execution failed:', error);
process.exit(1);
});
}

6
src/types/index.ts
View File

@@ -13,6 +13,12 @@ export interface ToolDefinition {
required?: string[];
additionalProperties?: boolean | Record<string, any>;
};
outputSchema?: {
type: string;
properties: Record<string, any>;
required?: string[];
additionalProperties?: boolean | Record<string, any>;
};
}
export interface ResourceDefinition {

175
src/utils/protocol-version.ts Normal file
View File

@@ -0,0 +1,175 @@
/**
* Protocol Version Negotiation Utility
*
* Handles MCP protocol version negotiation between server and clients,
* with special handling for n8n clients that require specific versions.
*/
export interface ClientInfo {
name?: string;
version?: string;
[key: string]: any;
}
export interface ProtocolNegotiationResult {
version: string;
isN8nClient: boolean;
reasoning: string;
}
/**
* Standard MCP protocol version (latest)
*/
export const STANDARD_PROTOCOL_VERSION = '2025-03-26';
/**
* n8n specific protocol version (what n8n expects)
*/
export const N8N_PROTOCOL_VERSION = '2024-11-05';
/**
* Supported protocol versions in order of preference
*/
export const SUPPORTED_VERSIONS = [
STANDARD_PROTOCOL_VERSION,
N8N_PROTOCOL_VERSION,
'2024-06-25', // Older fallback
];
/**
* Detect if the client is n8n based on various indicators
*/
export function isN8nClient(
clientInfo?: ClientInfo,
userAgent?: string,
headers?: Record<string, string | string[] | undefined>
): boolean {
// Check client info
if (clientInfo?.name) {
const clientName = clientInfo.name.toLowerCase();
if (clientName.includes('n8n') || clientName.includes('langchain')) {
return true;
}
}
// Check user agent
if (userAgent) {
const ua = userAgent.toLowerCase();
if (ua.includes('n8n') || ua.includes('langchain')) {
return true;
}
}
// Check headers for n8n-specific indicators
if (headers) {
// Check for n8n-specific headers or values
const headerValues = Object.values(headers).join(' ').toLowerCase();
if (headerValues.includes('n8n') || headerValues.includes('langchain')) {
return true;
}
// Check specific header patterns that n8n might use
if (headers['x-n8n-version'] || headers['x-langchain-version']) {
return true;
}
}
// Check environment variable that might indicate n8n mode
if (process.env.N8N_MODE === 'true') {
return true;
}
return false;
}
/**
* Negotiate protocol version based on client information
*/
export function negotiateProtocolVersion(
clientRequestedVersion?: string,
clientInfo?: ClientInfo,
userAgent?: string,
headers?: Record<string, string | string[] | undefined>
): ProtocolNegotiationResult {
const isN8n = isN8nClient(clientInfo, userAgent, headers);
// For n8n clients, always use the n8n-specific version
if (isN8n) {
return {
version: N8N_PROTOCOL_VERSION,
isN8nClient: true,
reasoning: 'n8n client detected, using n8n-compatible protocol version'
};
}
// If client requested a specific version, try to honor it if supported
if (clientRequestedVersion && SUPPORTED_VERSIONS.includes(clientRequestedVersion)) {
return {
version: clientRequestedVersion,
isN8nClient: false,
reasoning: `Using client-requested version: ${clientRequestedVersion}`
};
}
// If client requested an unsupported version, use the closest supported one
if (clientRequestedVersion) {
// For now, default to standard version for unknown requests
return {
version: STANDARD_PROTOCOL_VERSION,
isN8nClient: false,
reasoning: `Client requested unsupported version ${clientRequestedVersion}, using standard version`
};
}
// Default to standard protocol version for unknown clients
return {
version: STANDARD_PROTOCOL_VERSION,
isN8nClient: false,
reasoning: 'No specific client detected, using standard protocol version'
};
}
/**
* Check if a protocol version is supported
*/
export function isVersionSupported(version: string): boolean {
return SUPPORTED_VERSIONS.includes(version);
}
/**
* Get the most appropriate protocol version for backwards compatibility
* This is used when we need to maintain compatibility with older clients
*/
export function getCompatibleVersion(targetVersion?: string): string {
if (!targetVersion) {
return STANDARD_PROTOCOL_VERSION;
}
if (SUPPORTED_VERSIONS.includes(targetVersion)) {
return targetVersion;
}
// If not supported, return the most recent supported version
return STANDARD_PROTOCOL_VERSION;
}
/**
* Log protocol version negotiation for debugging
*/
export function logProtocolNegotiation(
result: ProtocolNegotiationResult,
logger: any,
context?: string
): void {
const logContext = context ? `[${context}] ` : '';
logger.info(`${logContext}Protocol version negotiated`, {
version: result.version,
isN8nClient: result.isN8nClient,
reasoning: result.reasoning
});
if (result.isN8nClient) {
logger.info(`${logContext}Using n8n-compatible protocol version for better integration`);
}
}