n8n-mcp 2.18.5 → 2.18.7

package/dist/mcp/handlers-n8n-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers-n8n-manager.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers-n8n-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAML,eAAe,EAGhB,MAAM,kBAAkB,CAAC;AAiB1B,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAA2B,MAAM,2BAA2B,CAAC;AAuDrF,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAMD,wBAAgB,uBAAuB,gDAEtC;AAKD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAgF9E;AAgGD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA8E7G;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC1G;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAoDjH;AAED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAmDnH;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyCjH;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyD7G;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAkC7G;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiE5G;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CA0F1B;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CAkK1B;AAID,wBAAsB,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAsErH;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA4F3G;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAgD7G;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC9G;AAID,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyC3F;AAED,wBAAsB,wBAAwB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAwDlG;AAGD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAsGxG"}
+{"version":3,"file":"handlers-n8n-manager.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers-n8n-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAML,eAAe,EAGhB,MAAM,kBAAkB,CAAC;AAiB1B,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAA2B,MAAM,2BAA2B,CAAC;AAiMrF,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAMD,wBAAgB,uBAAuB,gDAEtC;AAKD,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAgF9E;AAgGD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA8E7G;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC1G;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAoDjH;AAED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAmDnH;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyCjH;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAyD7G;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAkC7G;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiE5G;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CA0F1B;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,cAAc,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,CAAC,CAkK1B;AAID,wBAAsB,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAsErH;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA4F3G;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAgD7G;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC9G;AAID,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAwG3F;AAED,wBAAsB,wBAAwB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAwDlG;AAkLD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAkQxG"}

package/dist/mcp/handlers-n8n-manager.js

@@ -37,6 +37,7 @@ const handlers_workflow_diff_1 = require("./handlers-workflow-diff");
 const telemetry_1 = require("../telemetry");
 const cache_utils_1 = require("../utils/cache-utils");
 const execution_processor_1 = require("../services/execution-processor");
+const npm_version_checker_1 = require("../utils/npm-version-checker");
 let defaultApiClient = null;
 let lastDefaultConfigUrl = null;
 const cacheMutex = new cache_utils_1.CacheMutex();
@@ -952,27 +953,66 @@ async function handleDeleteExecution(args, context) {
     }
 }
 async function handleHealthCheck(context) {
+    const startTime = Date.now();
     try {
         const client = ensureApiConfigured(context);
         const health = await client.healthCheck();
         const packageJson = require('../../package.json');
         const mcpVersion = packageJson.version;
         const supportedN8nVersion = packageJson.dependencies?.n8n?.replace(/[^0-9.]/g, '');
+        const versionCheck = await (0, npm_version_checker_1.checkNpmVersion)();
+        const cacheMetricsData = getInstanceCacheMetrics();
+        const responseTime = Date.now() - startTime;
+        const responseData = {
+            status: health.status,
+            instanceId: health.instanceId,
+            n8nVersion: health.n8nVersion,
+            features: health.features,
+            apiUrl: (0, n8n_api_1.getN8nApiConfig)()?.baseUrl,
+            mcpVersion,
+            supportedN8nVersion,
+            versionCheck: {
+                current: versionCheck.currentVersion,
+                latest: versionCheck.latestVersion,
+                upToDate: !versionCheck.isOutdated,
+                message: (0, npm_version_checker_1.formatVersionMessage)(versionCheck),
+                ...(versionCheck.updateCommand ? { updateCommand: versionCheck.updateCommand } : {})
+            },
+            performance: {
+                responseTimeMs: responseTime,
+                cacheHitRate: (cacheMetricsData.hits + cacheMetricsData.misses) > 0
+                    ? ((cacheMetricsData.hits / (cacheMetricsData.hits + cacheMetricsData.misses)) * 100).toFixed(2) + '%'
+                    : 'N/A',
+                cachedInstances: cacheMetricsData.size
+            }
+        };
+        responseData.nextSteps = [
+            '• Create workflow: n8n_create_workflow',
+            '• List workflows: n8n_list_workflows',
+            '• Search nodes: search_nodes',
+            '• Browse templates: search_templates'
+        ];
+        if (versionCheck.isOutdated && versionCheck.latestVersion) {
+            responseData.updateWarning = `⚠️  n8n-mcp v${versionCheck.latestVersion} is available (you have v${versionCheck.currentVersion}). Update recommended.`;
+        }
+        telemetry_1.telemetry.trackEvent('health_check_completed', {
+            success: true,
+            responseTimeMs: responseTime,
+            upToDate: !versionCheck.isOutdated,
+            apiConnected: true
+        });
         return {
             success: true,
-            data: {
-                status: health.status,
-                instanceId: health.instanceId,
-                n8nVersion: health.n8nVersion,
-                features: health.features,
-                apiUrl: (0, n8n_api_1.getN8nApiConfig)()?.baseUrl,
-                mcpVersion,
-                supportedN8nVersion,
-                versionNote: 'AI Agent: Please inform the user to verify their n8n instance version matches or is compatible with the supported version listed above. The n8n API currently does not expose version information, so manual verification is required.'
-            }
+            data: responseData
         };
     }
     catch (error) {
+        const responseTime = Date.now() - startTime;
+        telemetry_1.telemetry.trackEvent('health_check_failed', {
+            success: false,
+            responseTimeMs: responseTime,
+            errorType: error instanceof n8n_errors_1.N8nApiError ? error.code : 'unknown'
+        });
         if (error instanceof n8n_errors_1.N8nApiError) {
             return {
                 success: false,
@@ -980,7 +1020,13 @@ async function handleHealthCheck(context) {
                 code: error.code,
                 details: {
                     apiUrl: (0, n8n_api_1.getN8nApiConfig)()?.baseUrl,
-                    hint: 'Check if n8n is running and API is enabled'
+                    hint: 'Check if n8n is running and API is enabled',
+                    troubleshooting: [
+                        '1. Verify n8n instance is running',
+                        '2. Check N8N_API_URL is correct',
+                        '3. Verify N8N_API_KEY has proper permissions',
+                        '4. Run n8n_diagnostic for detailed analysis'
+                    ]
                 }
             };
         }
@@ -1045,13 +1091,183 @@ async function handleListAvailableTools(context) {
         }
     };
 }
+function detectCloudPlatform() {
+    if (process.env.RAILWAY_ENVIRONMENT)
+        return 'railway';
+    if (process.env.RENDER)
+        return 'render';
+    if (process.env.FLY_APP_NAME)
+        return 'fly';
+    if (process.env.HEROKU_APP_NAME)
+        return 'heroku';
+    if (process.env.AWS_EXECUTION_ENV)
+        return 'aws';
+    if (process.env.KUBERNETES_SERVICE_HOST)
+        return 'kubernetes';
+    if (process.env.GOOGLE_CLOUD_PROJECT)
+        return 'gcp';
+    if (process.env.AZURE_FUNCTIONS_ENVIRONMENT)
+        return 'azure';
+    return null;
+}
+function getModeSpecificDebug(mcpMode) {
+    if (mcpMode === 'http') {
+        const port = process.env.MCP_PORT || process.env.PORT || 3000;
+        return {
+            mode: 'HTTP Server',
+            port,
+            authTokenConfigured: !!(process.env.MCP_AUTH_TOKEN || process.env.AUTH_TOKEN),
+            corsEnabled: true,
+            serverUrl: `http://localhost:${port}`,
+            healthCheckUrl: `http://localhost:${port}/health`,
+            troubleshooting: [
+                `1. Test server health: curl http://localhost:${port}/health`,
+                '2. Check browser console for CORS errors',
+                '3. Verify MCP_AUTH_TOKEN or AUTH_TOKEN if authentication enabled',
+                `4. Ensure port ${port} is not in use: lsof -i :${port} (macOS/Linux) or netstat -ano | findstr :${port} (Windows)`,
+                '5. Check firewall settings for port access',
+                '6. Review server logs for connection errors'
+            ],
+            commonIssues: [
+                'CORS policy blocking browser requests',
+                'Port already in use by another application',
+                'Authentication token mismatch',
+                'Network firewall blocking connections'
+            ]
+        };
+    }
+    else {
+        const configLocation = process.platform === 'darwin'
+            ? '~/Library/Application Support/Claude/claude_desktop_config.json'
+            : process.platform === 'win32'
+                ? '%APPDATA%\\Claude\\claude_desktop_config.json'
+                : '~/.config/Claude/claude_desktop_config.json';
+        return {
+            mode: 'Standard I/O (Claude Desktop)',
+            configLocation,
+            troubleshooting: [
+                '1. Verify Claude Desktop config file exists and is valid JSON',
+                '2. Check MCP server entry: {"mcpServers": {"n8n": {"command": "npx", "args": ["-y", "n8n-mcp"]}}}',
+                '3. Restart Claude Desktop after config changes',
+                '4. Check Claude Desktop logs for startup errors',
+                '5. Test npx can run: npx -y n8n-mcp --version',
+                '6. Verify executable permissions if using local installation'
+            ],
+            commonIssues: [
+                'Invalid JSON in claude_desktop_config.json',
+                'Incorrect command or args in MCP server config',
+                'Claude Desktop not restarted after config changes',
+                'npx unable to download or run package',
+                'Missing execute permissions on local binary'
+            ]
+        };
+    }
+}
+function getDockerDebug(isDocker) {
+    if (!isDocker)
+        return null;
+    return {
+        containerDetected: true,
+        troubleshooting: [
+            '1. Verify volume mounts for data/nodes.db',
+            '2. Check network connectivity to n8n instance',
+            '3. Ensure ports are correctly mapped',
+            '4. Review container logs: docker logs <container-name>',
+            '5. Verify environment variables passed to container',
+            '6. Check IS_DOCKER=true is set correctly'
+        ],
+        commonIssues: [
+            'Volume mount not persisting database',
+            'Network isolation preventing n8n API access',
+            'Port mapping conflicts',
+            'Missing environment variables in container'
+        ]
+    };
+}
+function getCloudPlatformDebug(cloudPlatform) {
+    if (!cloudPlatform)
+        return null;
+    const platformGuides = {
+        railway: {
+            name: 'Railway',
+            troubleshooting: [
+                '1. Check Railway environment variables are set',
+                '2. Verify deployment logs in Railway dashboard',
+                '3. Ensure PORT matches Railway assigned port (automatic)',
+                '4. Check networking configuration for external access'
+            ]
+        },
+        render: {
+            name: 'Render',
+            troubleshooting: [
+                '1. Verify Render environment variables',
+                '2. Check Render logs for startup errors',
+                '3. Ensure health check endpoint is responding',
+                '4. Verify instance type has sufficient resources'
+            ]
+        },
+        fly: {
+            name: 'Fly.io',
+            troubleshooting: [
+                '1. Check Fly.io logs: flyctl logs',
+                '2. Verify fly.toml configuration',
+                '3. Ensure volumes are properly mounted',
+                '4. Check app status: flyctl status'
+            ]
+        },
+        heroku: {
+            name: 'Heroku',
+            troubleshooting: [
+                '1. Check Heroku logs: heroku logs --tail',
+                '2. Verify Procfile configuration',
+                '3. Ensure dynos are running: heroku ps',
+                '4. Check environment variables: heroku config'
+            ]
+        },
+        kubernetes: {
+            name: 'Kubernetes',
+            troubleshooting: [
+                '1. Check pod logs: kubectl logs <pod-name>',
+                '2. Verify service and ingress configuration',
+                '3. Check persistent volume claims',
+                '4. Verify resource limits and requests'
+            ]
+        },
+        aws: {
+            name: 'AWS',
+            troubleshooting: [
+                '1. Check CloudWatch logs',
+                '2. Verify IAM roles and permissions',
+                '3. Check security groups and networking',
+                '4. Verify environment variables in service config'
+            ]
+        }
+    };
+    return platformGuides[cloudPlatform] || {
+        name: cloudPlatform.toUpperCase(),
+        troubleshooting: [
+            '1. Check cloud platform logs',
+            '2. Verify environment variables are set',
+            '3. Check networking and port configuration',
+            '4. Review platform-specific documentation'
+        ]
+    };
+}
 async function handleDiagnostic(request, context) {
+    const startTime = Date.now();
     const verbose = request.params?.arguments?.verbose || false;
+    const mcpMode = process.env.MCP_MODE || 'stdio';
+    const isDocker = process.env.IS_DOCKER === 'true';
+    const cloudPlatform = detectCloudPlatform();
     const envVars = {
         N8N_API_URL: process.env.N8N_API_URL || null,
         N8N_API_KEY: process.env.N8N_API_KEY ? '***configured***' : null,
         NODE_ENV: process.env.NODE_ENV || 'production',
-        MCP_MODE: process.env.MCP_MODE || 'stdio'
+        MCP_MODE: mcpMode,
+        isDocker,
+        cloudPlatform,
+        nodeVersion: process.version,
+        platform: process.platform
     };
     const apiConfig = (0, n8n_api_1.getN8nApiConfig)();
     const apiConfigured = apiConfig !== null;
@@ -1075,6 +1291,9 @@ async function handleDiagnostic(request, context) {
     const documentationTools = 22;
     const managementTools = apiConfigured ? 16 : 0;
     const totalTools = documentationTools + managementTools;
+    const versionCheck = await (0, npm_version_checker_1.checkNpmVersion)();
+    const cacheMetricsData = getInstanceCacheMetrics();
+    const responseTime = Date.now() - startTime;
     const diagnostic = {
         timestamp: new Date().toISOString(),
         environment: envVars,
@@ -1087,6 +1306,13 @@ async function handleDiagnostic(request, context) {
                 maxRetries: apiConfig.maxRetries
             } : null
         },
+        versionInfo: {
+            current: versionCheck.currentVersion,
+            latest: versionCheck.latestVersion,
+            upToDate: !versionCheck.isOutdated,
+            message: (0, npm_version_checker_1.formatVersionMessage)(versionCheck),
+            ...(versionCheck.updateCommand ? { updateCommand: versionCheck.updateCommand } : {})
+        },
         toolsAvailability: {
             documentationTools: {
                 count: documentationTools,
@@ -1102,32 +1328,153 @@ async function handleDiagnostic(request, context) {
             },
             totalAvailable: totalTools
         },
-        troubleshooting: {
-            steps: apiConfigured ? [
-                'API is configured and should work',
-                'If tools are not showing in Claude Desktop:',
-                '1. Restart Claude Desktop completely',
-                '2. Check if using latest Docker image',
-                '3. Verify environment variables are passed correctly',
-                '4. Try running n8n_health_check to test connectivity'
-            ] : [
-                'To enable management tools:',
-                '1. Set N8N_API_URL environment variable (e.g., https://your-n8n-instance.com)',
-                '2. Set N8N_API_KEY environment variable (get from n8n API settings)',
-                '3. Restart the MCP server',
-                '4. Management tools will automatically appear'
-            ],
-            documentation: 'For detailed setup instructions, see: https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
-        }
+        performance: {
+            diagnosticResponseTimeMs: responseTime,
+            cacheHitRate: (cacheMetricsData.hits + cacheMetricsData.misses) > 0
+                ? ((cacheMetricsData.hits / (cacheMetricsData.hits + cacheMetricsData.misses)) * 100).toFixed(2) + '%'
+                : 'N/A',
+            cachedInstances: cacheMetricsData.size
+        },
+        modeSpecificDebug: getModeSpecificDebug(mcpMode)
     };
+    if (apiConfigured && apiStatus.connected) {
+        diagnostic.nextSteps = {
+            message: '✓ API connected! Here\'s what you can do:',
+            recommended: [
+                {
+                    action: 'n8n_list_workflows',
+                    description: 'See your existing workflows',
+                    timing: 'Fast (6 seconds median)'
+                },
+                {
+                    action: 'n8n_create_workflow',
+                    description: 'Create a new workflow',
+                    timing: 'Typically 6-14 minutes to build'
+                },
+                {
+                    action: 'search_nodes',
+                    description: 'Discover available nodes',
+                    timing: 'Fast - explore 500+ nodes'
+                },
+                {
+                    action: 'search_templates',
+                    description: 'Browse pre-built workflows',
+                    timing: 'Find examples quickly'
+                }
+            ],
+            tips: [
+                '82% of users start creating workflows after diagnostics - you\'re ready to go!',
+                'Most common first action: n8n_update_partial_workflow (managing existing workflows)',
+                'Use n8n_validate_workflow before deploying to catch issues early'
+            ]
+        };
+    }
+    else if (apiConfigured && !apiStatus.connected) {
+        diagnostic.troubleshooting = {
+            issue: '⚠️ API configured but connection failed',
+            error: apiStatus.error,
+            steps: [
+                '1. Verify n8n instance is running and accessible',
+                '2. Check N8N_API_URL is correct (currently: ' + apiConfig?.baseUrl + ')',
+                '3. Test URL in browser: ' + apiConfig?.baseUrl + '/healthz',
+                '4. Verify N8N_API_KEY has proper permissions',
+                '5. Check firewall/network settings if using remote n8n',
+                '6. Try running n8n_health_check again after fixes'
+            ],
+            commonIssues: [
+                'Wrong port number in N8N_API_URL',
+                'API key doesn\'t have sufficient permissions',
+                'n8n instance not running or crashed',
+                'Network firewall blocking connection'
+            ],
+            documentation: 'https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
+        };
+    }
+    else {
+        diagnostic.setupGuide = {
+            message: 'n8n API not configured. You can still use documentation tools!',
+            whatYouCanDoNow: {
+                documentation: [
+                    {
+                        tool: 'search_nodes',
+                        description: 'Search 500+ n8n nodes',
+                        example: 'search_nodes({query: "slack"})'
+                    },
+                    {
+                        tool: 'get_node_essentials',
+                        description: 'Get node configuration details',
+                        example: 'get_node_essentials({nodeType: "nodes-base.httpRequest"})'
+                    },
+                    {
+                        tool: 'search_templates',
+                        description: 'Browse workflow templates',
+                        example: 'search_templates({query: "chatbot"})'
+                    },
+                    {
+                        tool: 'validate_workflow',
+                        description: 'Validate workflow JSON',
+                        example: 'validate_workflow({workflow: {...}})'
+                    }
+                ],
+                note: '22 documentation tools available without API configuration'
+            },
+            whatYouCannotDo: [
+                '✗ Create/update workflows in n8n instance',
+                '✗ List your workflows',
+                '✗ Execute workflows',
+                '✗ View execution results'
+            ],
+            howToEnable: {
+                steps: [
+                    '1. Get your n8n API key: [Your n8n instance]/settings/api',
+                    '2. Set environment variables:',
+                    '   N8N_API_URL=https://your-n8n-instance.com',
+                    '   N8N_API_KEY=your_api_key_here',
+                    '3. Restart the MCP server',
+                    '4. Run n8n_diagnostic again to verify',
+                    '5. All 38 tools will be available!'
+                ],
+                documentation: 'https://github.com/czlonkowski/n8n-mcp?tab=readme-ov-file#n8n-management-tools-optional---requires-api-configuration'
+            }
+        };
+    }
+    if (versionCheck.isOutdated && versionCheck.latestVersion) {
+        diagnostic.updateWarning = {
+            message: `⚠️ Update available: v${versionCheck.currentVersion} → v${versionCheck.latestVersion}`,
+            command: versionCheck.updateCommand,
+            benefits: [
+                'Latest bug fixes and improvements',
+                'New features and tools',
+                'Better performance and reliability'
+            ]
+        };
+    }
+    const dockerDebug = getDockerDebug(isDocker);
+    if (dockerDebug) {
+        diagnostic.dockerDebug = dockerDebug;
+    }
+    const cloudDebug = getCloudPlatformDebug(cloudPlatform);
+    if (cloudDebug) {
+        diagnostic.cloudPlatformDebug = cloudDebug;
+    }
     if (verbose) {
-        diagnostic['debug'] = {
+        diagnostic.debug = {
             processEnv: Object.keys(process.env).filter(key => key.startsWith('N8N_') || key.startsWith('MCP_')),
             nodeVersion: process.version,
             platform: process.platform,
-            workingDirectory: process.cwd()
+            workingDirectory: process.cwd(),
+            cacheMetrics: cacheMetricsData
         };
     }
+    telemetry_1.telemetry.trackEvent('diagnostic_completed', {
+        success: true,
+        apiConfigured,
+        apiConnected: apiStatus.connected,
+        toolsAvailable: totalTools,
+        responseTimeMs: responseTime,
+        upToDate: !versionCheck.isOutdated,
+        verbose
+    });
     return {
         success: true,
         data: diagnostic