feat(gateway): add 'clients' command to display connected MCP clients with detailed information

Author: Lasim

services/gateway/README.md

@@ -368,6 +368,62 @@ deploystack status --verbose
 deploystack status --json
 ```
 
+### `deploystack clients`
+
+Show all connected MCP clients with detailed connection information.
+
+**Examples:**
+
+```bash
+# Show connected clients
+deploystack clients
+```
+
+**Features:**
+
+- **Real-time Status**: Shows currently connected MCP clients from cache
+- **Connection Types**: Displays both SSE and Streamable HTTP connections
+- **Activity Tracking**: Shows last activity time and request counts
+- **Client Information**: Displays client name, version, and user agent when available
+- **Connection Endpoints**: Lists all available gateway endpoints
+- **Cache Integration**: Uses client state cache for accurate connection tracking
+
+**Sample Output:**
+
+```text
+Connected MCP Clients
+══════════════════════════════════════════════════
+
+Summary: 2 active connections
+   • SSE connections: 1
+   • Streamable HTTP connections: 1
+   • Initialized clients: 2
+   • Active (last 5min): 2
+
+Client Details:
+
+VS Code v1.95.0
+   ID: sse_abc123
+   Type: SSE Initialized
+   Activity: 30s ago (15 requests)
+   Uptime: 2h 15m
+   User Agent: VSCode/1.95.0
+
+Cursor v0.42.0
+   ID: http_def456
+   Type: Streamable HTTP Initialized
+   Activity: 1m ago (8 requests)
+   Uptime: 45m 30s
+
+Connection Endpoints:
+   • SSE: http://localhost:9095/sse
+   • Messages: http://localhost:9095/message
+   • MCP: http://localhost:9095/mcp
+   • Health: http://localhost:9095/health
+
+Cache last updated: 1/4/2025, 9:30:15 AM
+```
+
 ## 🛠️ Troubleshooting
 
 ### Common Issues

services/gateway/src/commands/clients.ts

@@ -6,36 +6,12 @@ export function registerClientsCommand(program: Command) {
   program
     .command('clients')
     .description('Show all connected MCP clients')
-    .option('--port <port>', 'Gateway port (default: 9095)', '9095')
-    .option('--host <host>', 'Gateway host (default: localhost)', 'localhost')
-    .action(async (options) => {
-      await showConnectedClients(options);
+    .action(async () => {
+      await showConnectedClients();
     });
 }
 
-interface ClientConnection {
-  id: string;
-  type: 'SSE' | 'Streamable HTTP';
-  clientInfo?: {
-    name: string;
-    version: string;
-  };
-  createdAt: number;
-  lastActivity: number;
-  uptime: number;
-  requestCount: number;
-  errorCount: number;
-  mcpInitialized: boolean;
-}
-
-interface ClientStatus {
-  totalConnections: number;
-  sseConnections: number;
-  streamableHttpConnections: number;
-  clients: ClientConnection[];
-}
-
-async function showConnectedClients(options: { port: string; host: string }): Promise<void> {
+async function showConnectedClients(): Promise<void> {
   try {
     const clientCache = new ClientStateCacheService();
 
@@ -148,104 +124,3 @@ function formatUptime(milliseconds: number): string {
     return `${seconds}s`;
   }
 }
-
-/**
- * Fetch gateway status via HTTP
- */
-async function fetchGatewayStatus(gatewayUrl: string): Promise<any> {
-  const fetch = (await import('node-fetch')).default;
-  
-  // Create AbortController for timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 5000);
-  
-  try {
-    const response = await fetch(`${gatewayUrl}/status`, {
-      signal: controller.signal
-    });
-    
-    clearTimeout(timeoutId);
-    
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status}`);
-    }
-    
-    return await response.json();
-  } catch (error) {
-    clearTimeout(timeoutId);
-    throw error;
-  }
-}
-
-/**
- * Extract client status from gateway status response
- */
-function extractClientStatus(gatewayStatus: any): ClientStatus {
-  const clients: ClientConnection[] = [];
-  const now = Date.now();
-
-  // Extract SSE sessions
-  if (gatewayStatus.clients?.sse?.sessions) {
-    for (const session of gatewayStatus.clients.sse.sessions) {
-      clients.push({
-        id: session.id,
-        type: 'SSE',
-        clientInfo: session.clientInfo,
-        createdAt: session.createdAt,
-        lastActivity: session.lastActivity,
-        uptime: session.uptime,
-        requestCount: session.requestCount,
-        errorCount: session.errorCount,
-        mcpInitialized: session.mcpInitialized
-      });
-    }
-  }
-
-  // Extract Streamable HTTP sessions
-  if (gatewayStatus.clients?.streamableHttp?.sessions) {
-    for (const session of gatewayStatus.clients.streamableHttp.sessions) {
-      clients.push({
-        id: session.id,
-        type: 'Streamable HTTP',
-        clientInfo: session.clientInfo,
-        createdAt: session.createdAt,
-        lastActivity: session.lastActivity,
-        uptime: session.uptime,
-        requestCount: session.requestCount,
-        errorCount: session.errorCount,
-        mcpInitialized: session.mcpInitialized
-      });
-    }
-  }
-
-  // Sort by creation time (newest first)
-  clients.sort((a, b) => b.createdAt - a.createdAt);
-  
-  return {
-    totalConnections: clients.length,
-    sseConnections: gatewayStatus.clients?.sse?.activeCount || 0,
-    streamableHttpConnections: gatewayStatus.clients?.streamableHttp?.activeSessionCount || 0,
-    clients
-  };
-}
-
-/**
- * Calculate summary statistics
- */
-function calculateSummary(status: ClientStatus): {
-  total: number;
-  sse: number;
-  streamableHttp: number;
-  initialized: number;
-  active: number;
-} {
-  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
-
-  return {
-    total: status.totalConnections,
-    sse: status.sseConnections,
-    streamableHttp: status.streamableHttpConnections,
-    initialized: status.clients.filter(c => c.mcpInitialized).length,
-    active: status.clients.filter(c => c.lastActivity > fiveMinutesAgo).length
-  };
-}

services/gateway/src/commands/stop.ts

@@ -13,13 +13,13 @@ export function registerStopCommand(program: Command) {
 
       try {
         const timeoutSeconds = parseInt(options.timeout, 10) || 30;
-        console.log(chalk.blue('🛑 Stopping DeployStack Gateway...'));
+        console.log(chalk.blue('Stopping DeployStack Gateway...'));
 
         // Get current PID for progress messages
         const pid = stopService.getRunningPid();
 
         if (options.force && pid) {
-          console.log(chalk.yellow('⚠️  Force stopping gateway (MCP servers may not shutdown gracefully)'));
+          console.log(chalk.yellow('Force stopping gateway (MCP servers may not shutdown gracefully)'));
           console.log(chalk.gray(`   Sending SIGKILL to process ${pid}...`));
         } else if (pid) {
           console.log(chalk.gray(`   Sending SIGTERM to process ${pid}...`));
@@ -35,21 +35,19 @@ export function registerStopCommand(program: Command) {
 
         if (result.success) {
           if (result.wasRunning) {
-            console.log(chalk.green(`✅ ${result.message}`));
-            console.log(chalk.gray('💡 All MCP servers have been stopped along with the gateway'));
+            console.log(chalk.green(`${result.message}`));
+            console.log(chalk.gray('All MCP servers have been stopped along with the gateway'));
           } else {
-            console.log(chalk.yellow(`⚠️  ${result.message}`));
+            console.log(chalk.yellow(`${result.message}`));
           }
         } else {
-          console.log(chalk.red(`❌ ${result.message}`));
+          console.log(chalk.red(`${result.message}`));
           process.exit(1);
         }
 
       } catch (error) {
-        console.error(chalk.red('❌ Failed to stop gateway:'), error instanceof Error ? error.message : String(error));
+        console.error(chalk.red('Failed to stop gateway:'), error instanceof Error ? error.message : String(error));
         process.exit(1);
       }
     });
 }
-
-

services/gateway/src/core/client/client-state-cache.ts

@@ -368,10 +368,10 @@ export class ClientStateCacheService {
     try {
       if (await fs.pathExists(this.cacheFile)) {
         await fs.remove(this.cacheFile);
-        console.log(chalk.gray(`🗑️  Client state cache cleared`));
+        console.log(chalk.gray(`Client state cache cleared`));
       }
     } catch (error) {
-      console.warn(chalk.yellow(`⚠️  Failed to clear client cache:`, error));
+      console.warn(chalk.yellow(`Failed to clear client cache:`, error));
     }
   }
 }

services/gateway/src/services/server-stop-service.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { ClientStateCacheService } from '../core/client/client-state-cache';
 
 // PID file location
 const PID_FILE = path.join(os.tmpdir(), 'deploystack-gateway.pid');
@@ -17,6 +18,12 @@ export interface ServerStopResult {
 }
 
 export class ServerStopService {
+  private clientCacheService: ClientStateCacheService;
+
+  constructor() {
+    this.clientCacheService = new ClientStateCacheService();
+  }
+
   /**
    * Stop the DeployStack Gateway server gracefully or forcefully
    */
@@ -68,13 +75,15 @@ export class ServerStopService {
         try {
           process.kill(pid, 'SIGKILL');
           this.removePidFile();
+          await this.cleanupClientCache();
           return {
             success: true,
             message: 'Gateway server force stopped (MCP servers may not have shutdown gracefully)',
             wasRunning: true
           };
         } catch {
           this.removePidFile();
+          await this.cleanupClientCache();
           return {
             success: true,
             message: 'Process was already stopped - cleaned up PID file',
@@ -108,6 +117,7 @@ export class ServerStopService {
               };
             } else {
               this.removePidFile();
+              await this.cleanupClientCache();
               return {
                 success: true,
                 message: `Gateway force stopped after ${timeoutSeconds}s timeout`,
@@ -116,6 +126,7 @@ export class ServerStopService {
             }
           } else {
             this.removePidFile();
+            await this.cleanupClientCache();
             return {
               success: true,
               message: 'Gateway server stopped gracefully',
@@ -125,6 +136,7 @@ export class ServerStopService {
         } catch (error) {
           if ((error as NodeJS.ErrnoException).code === 'ESRCH') {
             this.removePidFile();
+            await this.cleanupClientCache();
             return {
               success: true,
               message: 'Process was already stopped - cleaned up PID file',
@@ -203,4 +215,16 @@ export class ServerStopService {
       // Ignore file removal errors
     }
   }
+
+  /**
+   * Clean up client state cache when gateway stops
+   */
+  private async cleanupClientCache(): Promise<void> {
+    try {
+      await this.clientCacheService.clearCache();
+    } catch (error) {
+      // Don't fail the stop operation if cache cleanup fails
+      console.warn('Failed to clear client cache:', error instanceof Error ? error.message : String(error));
+    }
+  }
 }