fix: limits on retries

Author: Jordan Munch O'Hare

.env.example

@@ -26,3 +26,11 @@ SSH_PRIVATE_KEY_PATH=/home/mcp/.ssh/id_rsa
 # For Unraid: /root/.ssh/id_rsa_mcp or /boot/config/ssh/id_rsa_mcp
 # For other systems: /home/user/.ssh/id_rsa_mcp
 SSH_KEY_HOST_PATH=/root/.ssh/id_rsa_mcp
+
+# Command execution timeout in milliseconds (default: 15000 = 15 seconds)
+# Increase for long-running commands like database dumps
+COMMAND_TIMEOUT_MS=15000
+
+# Maximum consecutive command failures before circuit breaker opens (default: 3)
+# When circuit breaker is open, commands will fail immediately to prevent retry loops
+MAX_CONSECUTIVE_FAILURES=3

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-ssh-unraid",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for SSH access to Unraid",
   "main": "dist/index.js",
   "type": "module",

src/__tests__/http-server.test.ts

@@ -65,7 +65,7 @@ describe('HTTP Server', () => {
     const data = await response.json() as Record<string, any>;
     expect(data).toHaveProperty('status');
     expect(data).toHaveProperty('server', 'mcp-ssh-unraid');
-    expect(data).toHaveProperty('version', '1.0.0');
+    expect(data).toHaveProperty('version', '1.1.0');
     expect(data).toHaveProperty('transport', 'http');
     expect(data).toHaveProperty('ssh_connected');
 

src/http-server.ts

@@ -121,7 +121,7 @@ async function main() {
   log.info("Initializing MCP server...");
   const server = new McpServer({
     name: "ssh-unraid-server-http",
-    version: "1.0.0",
+    version: "1.1.0",
   });
 
   // Create SSH executor adapter for tool modules
@@ -311,7 +311,7 @@ async function main() {
       status,
       ssh_connected: isSSHConnected,
       server: "mcp-ssh-unraid",
-      version: "1.0.0",
+      version: "1.1.0",
       transport: "http",
       oauth: "enabled",
     });

src/ssh-manager.ts

@@ -18,6 +18,10 @@ export class SSHConnectionManager {
   private reconnectAttempts: number = 0;
   private maxReconnectAttempts: number = 5;
   private baseBackoffMs: number = 1000;
+  private commandTimeoutMs: number;
+  private maxConsecutiveFailures: number;
+  private consecutiveFailures: number = 0;
+  private circuitBreakerOpen: boolean = false;
 
   constructor() {
     this.ssh = new NodeSSH();
@@ -46,6 +50,14 @@ export class SSHConnectionManager {
       privateKeyPath,
       password,
     };
+
+    // Load timeout and circuit breaker configuration
+    this.commandTimeoutMs = process.env.COMMAND_TIMEOUT_MS
+      ? parseInt(process.env.COMMAND_TIMEOUT_MS)
+      : 15000; // Default: 15 seconds
+    this.maxConsecutiveFailures = process.env.MAX_CONSECUTIVE_FAILURES
+      ? parseInt(process.env.MAX_CONSECUTIVE_FAILURES)
+      : 3; // Default: 3 consecutive failures
   }
 
   /**
@@ -93,36 +105,89 @@ export class SSHConnectionManager {
   }
 
   /**
-   * Execute command via SSH
+   * Execute command via SSH with timeout and circuit breaker protection
    */
   async executeCommand(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    // Check circuit breaker
+    if (this.circuitBreakerOpen) {
+      throw new Error(
+        `Circuit breaker is open after ${this.consecutiveFailures} consecutive failures. ` +
+        `Please check server health or restart the MCP server to reset.`
+      );
+    }
+
+    // Timeout ID for cleanup
+    let timeoutId: NodeJS.Timeout | null = null;
+
     try {
       if (!this.connected) {
         await this.connect();
       }
 
-      const result = await this.ssh.execCommand(command);
+      // Create a timeout promise
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`TIMEOUT: Command timed out after ${this.commandTimeoutMs}ms`));
+        }, this.commandTimeoutMs);
+      });
+
+      // Race between command execution and timeout
+      const result = await Promise.race([
+        this.ssh.execCommand(command),
+        timeoutPromise,
+      ]);
+
+      // Clear timeout on success
+      if (timeoutId) clearTimeout(timeoutId);
+
+      // Reset circuit breaker on successful command
+      this.consecutiveFailures = 0;
+      this.circuitBreakerOpen = false;
 
       return {
         stdout: result.stdout,
         stderr: result.stderr,
         exitCode: result.code ?? 0,
       };
     } catch (error) {
-      // Attempt to reconnect on connection errors
-      if (error instanceof Error && error.message.includes("connection")) {
+      // Clear timeout on error
+      if (timeoutId) clearTimeout(timeoutId);
+
+      // Increment failure counter
+      this.consecutiveFailures++;
+
+      // Open circuit breaker if threshold reached
+      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+        this.circuitBreakerOpen = true;
+        console.error(
+          `Circuit breaker opened after ${this.consecutiveFailures} consecutive failures. ` +
+          `Future commands will fail immediately until the MCP server is restarted.`
+        );
+      }
+
+      // Determine error type for better error messages
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const isTimeout = errorMessage.includes("TIMEOUT:");
+      const isConnection = errorMessage.toLowerCase().includes("connection");
+
+      if (isTimeout) {
+        throw new Error(
+          `Command timed out after ${this.commandTimeoutMs}ms. ` +
+          `The command may be hung or taking too long. ` +
+          `Consider increasing COMMAND_TIMEOUT_MS if this is a long-running operation.`
+        );
+      }
+
+      if (isConnection) {
         this.connected = false;
-        await this.reconnect();
-        // Retry the command after reconnection
-        const result = await this.ssh.execCommand(command);
-        return {
-          stdout: result.stdout,
-          stderr: result.stderr,
-          exitCode: result.code ?? 0,
-        };
+        throw new Error(
+          `SSH connection lost: ${errorMessage}. ` +
+          `The MCP server will attempt to reconnect on the next command. ` +
+          `If this persists, check your network connection and SSH credentials.`
+        );
       }
 
-      throw new Error(`Failed to execute command: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Failed to execute command: ${errorMessage}`);
     }
   }