fix: Improve server status detection with health check instead of process monitoring

- Replace unreliable process exit detection with functional health check
- Test /health endpoint after startup delay to confirm server is actually ready
- Prevent client launch and browser auto-open when server fails to start
- Provides clear error messages for different failure scenarios

This fixes the issue where port conflicts and server crashes during startup
would still result in browser auto-opening to a non-functional page.

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

Co-Authored-By: Claude <[email protected]>

Author: felixweinberger

client/bin/start.js

@@ -12,6 +12,14 @@ function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms, true));
 }
 
+const ServerStatus = {
+  UNKNOWN: "unknown",
+  STARTING: "starting",
+  RUNNING: "running",
+  FAILED: "failed",
+  STOPPED: "stopped",
+};
+
 async function startDevServer(serverOptions) {
   const { SERVER_PORT, CLIENT_PORT, sessionToken, envVars, abort } =
     serverOptions;
@@ -39,19 +47,48 @@ async function startDevServer(serverOptions) {
 
   const server = spawn(serverCommand, serverArgs, spawnOptions);
 
-  // Give server time to start
-  const serverOk = await Promise.race([
-    new Promise((resolve) => {
-      server.subscribe({
-        complete: () => resolve(false),
-        error: () => resolve(false),
-        next: () => {}, // We're using echoOutput
+  // Track server status
+  let serverStatus = ServerStatus.STARTING;
+
+  server.subscribe({
+    complete: () => {
+      // Server process ended - could be normal or abnormal
+      if (serverStatus === ServerStatus.STARTING) {
+        serverStatus = ServerStatus.FAILED; // Failed during startup
+        console.log("Server failed during startup (process completed)");
+      } else {
+        serverStatus = ServerStatus.STOPPED; // Stopped after running
+      }
+    },
+    error: () => {
+      serverStatus = ServerStatus.FAILED;
+      console.log("Server failed with error");
+    },
+    next: () => {}, // We're using echoOutput
+  });
+
+  // Wait for server to start and actually test the connection
+  await delay(3000);
+  if (serverStatus === ServerStatus.STARTING) {
+    // Check if server is actually listening by attempting a connection
+    try {
+      const response = await fetch(`http://127.0.0.1:${SERVER_PORT}/health`, {
+        signal: AbortSignal.timeout(2000),
       });
-    }),
-    delay(3000).then(() => true),
-  ]);
+      if (response.ok) {
+        serverStatus = ServerStatus.RUNNING;
+        console.log("Server confirmed healthy via /health endpoint");
+      } else {
+        serverStatus = ServerStatus.FAILED;
+        console.log(`Server health check failed: ${response.status}`);
+      }
+    } catch (err) {
+      serverStatus = ServerStatus.FAILED;
+      console.log(`Server health check failed: ${err.message}`);
+    }
+  }
 
-  return { server, serverOk };
+  return { server, getServerStatus: () => serverStatus };
 }
 
 async function startProdServer(serverOptions) {
@@ -72,6 +109,9 @@ async function startProdServer(serverOptions) {
     "index.js",
   );
 
+  // Track server status
+  let serverStatus = ServerStatus.STARTING;
+
   const server = spawnPromise(
     "node",
     [
@@ -92,15 +132,56 @@ async function startProdServer(serverOptions) {
     },
   );
 
-  // Make sure server started before starting client
-  const serverOk = await Promise.race([server, delay(2 * 1000)]);
+  // Monitor for server completion
+  server
+    .then(() => {
+      // Server completed normally
+      if (serverStatus === ServerStatus.STARTING) {
+        serverStatus = ServerStatus.FAILED; // Never started properly
+        console.log("Server failed during startup (process completed)");
+      } else {
+        serverStatus = ServerStatus.STOPPED;
+      }
+    })
+    .catch(() => {
+      serverStatus = ServerStatus.FAILED;
+      console.log("Server failed with error");
+    });
+
+  // Wait for server to start - but actually test the connection
+  await delay(2000); // Initial delay for server to attempt startup
+
+  if (serverStatus === ServerStatus.STARTING) {
+    // Check if server is actually listening by attempting a connection
+    try {
+      const response = await fetch(`http://127.0.0.1:${SERVER_PORT}/health`, {
+        signal: AbortSignal.timeout(2000),
+      });
+      if (response.ok) {
+        serverStatus = ServerStatus.RUNNING;
+        console.log("Server confirmed healthy via /health endpoint");
+      } else {
+        serverStatus = ServerStatus.FAILED;
+        console.log(`Server health check failed: ${response.status}`);
+      }
+    } catch (err) {
+      serverStatus = ServerStatus.FAILED;
+      console.log(`Server health check failed: ${err.message}`);
+    }
+  }
 
-  return { server, serverOk };
+  return { server, getServerStatus: () => serverStatus };
 }
 
 async function startDevClient(clientOptions) {
-  const { CLIENT_PORT, authDisabled, sessionToken, abort, cancelled } =
-    clientOptions;
+  const {
+    CLIENT_PORT,
+    authDisabled,
+    sessionToken,
+    abort,
+    cancelled,
+    getServerStatus,
+  } = clientOptions;
   const clientCommand = "npx";
   const clientArgs = ["vite", "--port", CLIENT_PORT];
 
@@ -111,23 +192,45 @@ async function startDevClient(clientOptions) {
     echoOutput: true,
   });
 
+  let autoOpenTimeout = null;
+  let hasOpened = false;
+
   // Auto-open browser after vite starts
   if (process.env.MCP_AUTO_OPEN_ENABLED !== "false") {
     const url = authDisabled
       ? `http://127.0.0.1:${CLIENT_PORT}`
       : `http://127.0.0.1:${CLIENT_PORT}/?MCP_PROXY_AUTH_TOKEN=${sessionToken}`;
 
     // Give vite time to start before opening browser
-    setTimeout(() => {
-      open(url);
-      console.log(`\n🔗 Opening browser at: ${url}\n`);
+    autoOpenTimeout = setTimeout(() => {
+      // Check if server is still running before opening
+      if (
+        !cancelled &&
+        !hasOpened &&
+        getServerStatus &&
+        getServerStatus() === ServerStatus.RUNNING
+      ) {
+        hasOpened = true;
+        open(url);
+        console.log(`\n🔗 Opening browser at: ${url}\n`);
+      }
     }, 3000);
   }
 
   await new Promise((resolve) => {
     client.subscribe({
-      complete: resolve,
+      complete: () => {
+        // Clear timeout if process completes
+        if (autoOpenTimeout) {
+          clearTimeout(autoOpenTimeout);
+        }
+        resolve(null);
+      },
       error: (err) => {
+        // Clear timeout on error
+        if (autoOpenTimeout) {
+          clearTimeout(autoOpenTimeout);
+        }
         if (!cancelled || process.env.DEBUG) {
           console.error("Client error:", err);
         }
@@ -139,7 +242,8 @@ async function startDevClient(clientOptions) {
 }
 
 async function startProdClient(clientOptions) {
-  const { CLIENT_PORT, authDisabled, sessionToken, abort } = clientOptions;
+  const { CLIENT_PORT, authDisabled, sessionToken, abort, cancelled } =
+    clientOptions;
   const inspectorClientPath = resolve(
     __dirname,
     "../..",
@@ -148,12 +252,13 @@ async function startProdClient(clientOptions) {
     "client.js",
   );
 
-  // Auto-open browser with token
-  if (process.env.MCP_AUTO_OPEN_ENABLED !== "false") {
+  // Only auto-open browser if not cancelled
+  if (process.env.MCP_AUTO_OPEN_ENABLED !== "false" && !cancelled) {
     const url = authDisabled
       ? `http://127.0.0.1:${CLIENT_PORT}`
       : `http://127.0.0.1:${CLIENT_PORT}/?MCP_PROXY_AUTH_TOKEN=${sessionToken}`;
     open(url);
+    console.log(`\n🔗 Opening browser at: ${url}\n`);
   }
 
   await spawnPromise("node", [inspectorClientPath], {
@@ -224,7 +329,8 @@ async function main() {
     abort.abort();
   });
 
-  let server, serverOk;
+  let server;
+  let getServerStatus = () => ServerStatus.UNKNOWN;
 
   try {
     const serverOptions = {
@@ -242,17 +348,19 @@ async function main() {
       : await startProdServer(serverOptions);
 
     server = result.server;
-    serverOk = result.serverOk;
+    getServerStatus = result.getServerStatus;
   } catch (error) {}
 
-  if (serverOk) {
+  if (getServerStatus() === ServerStatus.RUNNING) {
+    console.log("Server is confirmed running, starting client...");
     try {
       const clientOptions = {
         CLIENT_PORT,
         authDisabled,
         sessionToken,
         abort,
         cancelled,
+        getServerStatus,
       };
 
       await (isDev
@@ -261,6 +369,10 @@ async function main() {
     } catch (e) {
       if (!cancelled || process.env.DEBUG) throw e;
     }
+  } else {
+    console.log(
+      `Server failed to start (status: ${getServerStatus()}), not starting client`,
+    );
   }
 
   return 0;