@mcp-shark/mcp-shark 1.5.3 → 1.5.5

package/ui/server/swagger/paths/smartScan/scans.js

@@ -0,0 +1,151 @@
+/**
+ * Smart Scan - Scan endpoints
+ * Create, list, and retrieve scan results
+ */
+
+export const scansPaths = {
+  '/api/smartscan/scans': {
+    get: {
+      tags: ['Smart Scan'],
+      summary: 'List scans',
+      description: 'Get a list of all cached Smart Scan results',
+      responses: {
+        200: {
+          description: 'List of scans',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: { $ref: '#/components/schemas/Scan' },
+              },
+            },
+          },
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+    post: {
+      tags: ['Smart Scan'],
+      summary: 'Create scan',
+      description: 'Create a new Smart Scan for an MCP server',
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              required: ['apiToken', 'scanData'],
+              properties: {
+                apiToken: { type: 'string', description: 'Smart Scan API token' },
+                scanData: {
+                  type: 'object',
+                  description: 'Scan configuration data',
+                },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        200: {
+          description: 'Scan created',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/Scan' },
+            },
+          },
+        },
+        400: {
+          description: 'Bad request',
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+  },
+  '/api/smartscan/scans/{scanId}': {
+    get: {
+      tags: ['Smart Scan'],
+      summary: 'Get scan',
+      description: 'Get details of a specific scan',
+      parameters: [
+        {
+          name: 'scanId',
+          in: 'path',
+          required: true,
+          description: 'Scan ID',
+          schema: { type: 'string' },
+        },
+      ],
+      responses: {
+        200: {
+          description: 'Scan details',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/Scan' },
+            },
+          },
+        },
+        404: {
+          description: 'Scan not found',
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+  },
+  '/api/smartscan/scans/batch': {
+    post: {
+      tags: ['Smart Scan'],
+      summary: 'Create batch scans',
+      description: 'Create multiple scans for multiple servers',
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              required: ['apiToken', 'servers'],
+              properties: {
+                apiToken: { type: 'string', description: 'Smart Scan API token' },
+                servers: {
+                  type: 'array',
+                  items: { type: 'object' },
+                  description: 'List of server configurations to scan',
+                },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        200: {
+          description: 'Batch scans created',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  scans: {
+                    type: 'array',
+                    items: { $ref: '#/components/schemas/Scan' },
+                  },
+                },
+              },
+            },
+          },
+        },
+        400: {
+          description: 'Bad request',
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+  },
+};

package/ui/server/swagger/paths/smartScan/token.js

@@ -0,0 +1,71 @@
+/**
+ * Smart Scan - Token management endpoints
+ */
+
+export const tokenPaths = {
+  '/api/smartscan/token': {
+    get: {
+      tags: ['Smart Scan'],
+      summary: 'Get API token',
+      description: 'Get the stored Smart Scan API token',
+      responses: {
+        200: {
+          description: 'API token',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  token: { type: 'string', nullable: true },
+                },
+              },
+            },
+          },
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+    post: {
+      tags: ['Smart Scan'],
+      summary: 'Save API token',
+      description: 'Save the Smart Scan API token',
+      requestBody: {
+        required: true,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              required: ['token'],
+              properties: {
+                token: { type: 'string', description: 'Smart Scan API token' },
+              },
+            },
+          },
+        },
+      },
+      responses: {
+        200: {
+          description: 'Token saved',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  success: { type: 'boolean' },
+                },
+              },
+            },
+          },
+        },
+        400: {
+          description: 'Bad request',
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+  },
+};

package/ui/server/swagger/paths/statistics.js

@@ -0,0 +1,40 @@
+/**
+ * Statistics endpoints - Traffic statistics and analytics
+ */
+
+export const statisticsPaths = {
+  '/api/statistics': {
+    get: {
+      tags: ['Statistics'],
+      summary: 'Get traffic statistics',
+      description: 'Retrieve aggregated statistics about captured traffic',
+      parameters: [
+        {
+          name: 'sessionId',
+          in: 'query',
+          description: 'Filter by session ID',
+          schema: { type: 'string' },
+        },
+        {
+          name: 'serverName',
+          in: 'query',
+          description: 'Filter by server name',
+          schema: { type: 'string' },
+        },
+      ],
+      responses: {
+        200: {
+          description: 'Traffic statistics',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/Statistics' },
+            },
+          },
+        },
+        500: {
+          description: 'Internal server error',
+        },
+      },
+    },
+  },
+};

package/ui/server/swagger/paths.js

@@ -0,0 +1,38 @@
+/**
+ * Swagger/OpenAPI path definitions for MCP Shark API
+ * Aggregates all endpoint documentation from individual files
+ */
+
+import { backupsPaths } from './paths/backups.js';
+import { components } from './paths/components.js';
+import { configPaths } from './paths/config.js';
+import { conversationsPaths } from './paths/conversations.js';
+import { helpPaths } from './paths/help.js';
+import { logsPaths } from './paths/logs.js';
+import { playgroundPaths } from './paths/playground.js';
+import { requestsPaths } from './paths/requests.js';
+import { serverManagementPaths } from './paths/serverManagement.js';
+import { sessionsPaths } from './paths/sessions.js';
+import { settingsPaths } from './paths/settings.js';
+import { smartScanPaths } from './paths/smartScan/index.js';
+import { statisticsPaths } from './paths/statistics.js';
+
+/**
+ * Combine all path definitions into a single object
+ */
+export const paths = {
+  ...requestsPaths,
+  ...sessionsPaths,
+  ...conversationsPaths,
+  ...statisticsPaths,
+  ...logsPaths,
+  ...configPaths,
+  ...backupsPaths,
+  ...serverManagementPaths,
+  ...helpPaths,
+  ...playgroundPaths,
+  ...smartScanPaths,
+  ...settingsPaths,
+};
+
+export { components };

package/ui/server/swagger/swagger.js

@@ -0,0 +1,37 @@
+import { components, paths } from './paths.js';
+
+export const swaggerSpec = {
+  openapi: '3.0.0',
+  info: {
+    title: 'MCP Shark API',
+    version: '1.5.4',
+    description:
+      'API documentation for MCP Shark - A powerful monitoring and debugging tool for Model Context Protocol (MCP) servers. Provides deep visibility into every request and response.',
+    contact: {
+      name: 'MCP Shark',
+      url: 'https://mcpshark.sh',
+    },
+  },
+  servers: [
+    {
+      url: 'http://localhost:9853',
+      description: 'Development server',
+    },
+  ],
+  tags: [
+    { name: 'Requests', description: 'Traffic capture and request/response analysis' },
+    { name: 'Sessions', description: 'Session management and tracking' },
+    { name: 'Conversations', description: 'Conversation tracking and analysis' },
+    { name: 'Statistics', description: 'Traffic statistics and analytics' },
+    { name: 'Logs', description: 'MCP Shark server logs' },
+    { name: 'Config', description: 'Configuration file management' },
+    { name: 'Backups', description: 'Configuration backup management' },
+    { name: 'Server Management', description: 'MCP Shark server lifecycle management' },
+    { name: 'Help', description: 'Help and tour management' },
+    { name: 'Playground', description: 'MCP playground for testing tools and resources' },
+    { name: 'Smart Scan', description: 'AI-powered security analysis for MCP servers' },
+    { name: 'Settings', description: 'Application settings' },
+  ],
+  paths,
+  components,
+};

package/ui/server/utils/cleanup.js

@@ -0,0 +1,99 @@
+/**
+ * Perform cleanup operations on shutdown
+ * @param {number} intervalId - Interval ID to clear
+ * @param {object} processState - Process state object
+ * @param {Set} clients - Set of WebSocket clients
+ * @param {WebSocketServer} wss - WebSocket server instance
+ * @param {object} server - HTTP server instance
+ * @param {object} container - Dependency container
+ * @param {object} logger - Logger instance
+ * @returns {Promise} Promise that resolves when cleanup is complete
+ */
+export async function performCleanup(
+  intervalId,
+  processState,
+  clients,
+  wss,
+  server,
+  container,
+  logger
+) {
+  logger?.info('Shutting down UI server...');
+
+  // Clear interval
+  clearInterval(intervalId);
+
+  // Stop MCP Shark server if running and restore config
+  // Use ServerManagementService to ensure proper cleanup and config restoration
+  try {
+    const serverManagementService = container.getService('serverManagement');
+    const serverStatus = serverManagementService.getServerStatus();
+
+    if (serverStatus.running) {
+      logger?.info('Stopping MCP Shark server...');
+      try {
+        await serverManagementService.stopServer();
+        logger?.info('MCP Shark server stopped');
+      } catch (stopErr) {
+        logger?.warn(
+          { error: stopErr.message },
+          'Error stopping MCP Shark server, continuing with cleanup'
+        );
+      }
+    }
+  } catch (err) {
+    logger?.warn(
+      { error: err.message },
+      'Error accessing server management service during shutdown'
+    );
+    // Continue with cleanup even if server stop fails
+  }
+
+  // Restore config (always attempt, even if server stop failed)
+  // This ensures patched configs are restored on exit
+  try {
+    const configService = container.getService('config');
+    const restored = configService.restoreOriginalConfig();
+    if (restored) {
+      logger?.info('Config restored successfully');
+    }
+  } catch (configErr) {
+    logger?.warn({ error: configErr.message }, 'Failed to restore config during shutdown');
+    // Continue anyway - config restoration failure shouldn't prevent exit
+  }
+
+  // Clear process state
+  processState.mcpSharkServer = null;
+
+  // Close WebSocket connections
+  try {
+    for (const client of clients) {
+      if (client.readyState === 1) {
+        client.close();
+      }
+    }
+    clients.clear();
+  } catch (err) {
+    logger?.warn({ error: err.message }, 'Error closing WebSocket connections');
+  }
+
+  // Close WebSocket server
+  try {
+    wss.close();
+  } catch (err) {
+    logger?.warn({ error: err.message }, 'Error closing WebSocket server');
+  }
+
+  // Close HTTP server
+  return new Promise((resolve) => {
+    try {
+      server.close(() => {
+        logger?.info('UI server stopped');
+        resolve();
+      });
+    } catch (err) {
+      logger?.warn({ error: err.message }, 'Error closing HTTP server');
+      resolve(); // Resolve anyway to allow exit
+    }
+  });
+}

package/ui/server/utils/config.js

@@ -1,98 +1,20 @@
-import * as fs from 'node:fs';
-import logger from './logger.js';
-
-const state = { originalConfigData: null };
-
-export function storeOriginalConfig(filePath, originalContent, backupPath) {
-  state.originalConfigData = { filePath, originalContent, backupPath };
-}
-
-export function restoreOriginalConfig(mcpSharkLogs, broadcastLogUpdate) {
-  if (state.originalConfigData?.filePath) {
-    try {
-      if (fs.existsSync(state.originalConfigData.filePath)) {
-        fs.writeFileSync(
-          state.originalConfigData.filePath,
-          state.originalConfigData.originalContent
-        );
-        logger.info({ path: state.originalConfigData.filePath }, 'Restored original config');
-        state.originalConfigData = null;
-        return true;
-      }
-      state.originalConfigData = null;
-      return false;
-    } catch (error) {
-      logger.error({ error: error.message }, 'Failed to restore original config');
-      const timestamp = new Date().toISOString();
-      const errorLog = {
-        timestamp,
-        type: 'error',
-        line: `[RESTORE ERROR] Failed to restore: ${error.message}`,
-      };
-      mcpSharkLogs.push(errorLog);
-      if (mcpSharkLogs.length > 10000) {
-        mcpSharkLogs.shift();
-      }
-      broadcastLogUpdate(errorLog);
-      return false;
-    }
-  }
-  return false;
-}
-
-export function clearOriginalConfig() {
-  state.originalConfigData = null;
-}
-
-export function convertMcpServersToServers(config) {
-  const { mcpServers, servers } = config;
-  const converted = { servers: {} };
-
-  if (servers) {
-    converted.servers = servers;
-  }
-
-  if (mcpServers) {
-    Object.entries(mcpServers).forEach(([name, cfg]) => {
-      const type = cfg.type || (cfg.url ? 'http' : cfg.command ? 'stdio' : 'stdio');
-      converted.servers[name] = { type, ...cfg };
-    });
-  }
-
-  return converted;
-}
-
-export function extractServices(config) {
-  const { mcpServers, servers } = config;
-  const servicesMap = new Map();
-
-  if (servers) {
-    Object.entries(servers).forEach(([name, cfg]) => {
-      const type = cfg.type || (cfg.url ? 'http' : cfg.command ? 'stdio' : 'stdio');
-      servicesMap.set(name, {
-        name,
-        type,
-        url: cfg.url || null,
-        command: cfg.command || null,
-        args: cfg.args || null,
-      });
-    });
-  }
-
-  if (mcpServers) {
-    Object.entries(mcpServers).forEach(([name, cfg]) => {
-      if (!servicesMap.has(name)) {
-        const type = cfg.type || (cfg.url ? 'http' : cfg.command ? 'stdio' : 'stdio');
-        servicesMap.set(name, {
-          name,
-          type,
-          url: cfg.url || null,
-          command: cfg.command || null,
-          args: cfg.args || null,
-        });
-      }
-    });
+/**
+ * Restore original config from backup
+ * @param {object} container - Dependency container
+ * @returns {boolean} True if config was restored
+ */
+export function restoreConfig(container) {
+  const configService = container.getService('config');
+  const logService = container.getService('log');
+  const restored = configService.restoreOriginalConfig();
+  if (restored) {
+    const timestamp = new Date().toISOString();
+    const restoreLog = {
+      timestamp,
+      type: 'stdout',
+      line: '[RESTORE] Restored original config',
+    };
+    logService.addLog(restoreLog);
   }
-
-  return Array.from(servicesMap.values());
+  return restored;
 }

package/ui/server/utils/errorHandler.js

@@ -0,0 +1,43 @@
+import { StatusCodes } from '#core/constants/index.js';
+import { toApplicationError } from '#core/libraries/errors/ApplicationError.js';
+
+/**
+ * Standardized error handler for controllers
+ * Converts errors to consistent HTTP responses
+ *
+ * @param {Error|ApplicationError} error - The error to handle
+ * @param {Object} res - Express response object
+ * @param {Object} logger - Logger instance
+ * @param {string} context - Context for logging (e.g., 'Error in endpoint name')
+ */
+export function handleError(error, res, logger, context) {
+  const appError = toApplicationError(error, 'An unexpected error occurred');
+
+  // Log error with full context
+  logger?.error(
+    {
+      error: appError.message,
+      statusCode: appError.statusCode,
+      stack: appError.stack,
+      originalError: appError.error?.message,
+    },
+    context || 'Error handling request'
+  );
+
+  // Send standardized error response
+  res.status(appError.statusCode || StatusCodes.INTERNAL_SERVER_ERROR).json(appError.toResponse());
+}
+
+/**
+ * Handle validation errors specifically
+ * @param {string} message - Validation error message
+ * @param {Object} res - Express response object
+ * @param {Object} logger - Logger instance
+ */
+export function handleValidationError(message, res, logger) {
+  logger?.warn({ message }, 'Validation error');
+  res.status(StatusCodes.BAD_REQUEST).json({
+    error: 'ValidationError',
+    message,
+  });
+}

package/ui/server/utils/logger.js

@@ -1,2 +1,2 @@
-// Re-export common logger
-export { default } from '#common/logger';
+// Re-export bootstrap logger for UI server utilities
+export { bootstrapLogger as default } from '#core/libraries/index.js';

package/ui/server/utils/paths.js

@@ -23,10 +23,10 @@ function getNvmNodeBinPaths(homeDir) {
 
 export function findMcpServerPath() {
   const pathsToCheck = [
-    path.join(process.cwd(), '../mcp-server'),
-    path.join(__dirname, '../../mcp-server'),
-    path.join(process.cwd(), 'mcp-server'),
-    path.join(__dirname, '../../mcp-server'),
+    path.join(process.cwd(), 'core/mcp-server'),
+    path.join(__dirname, '../../../core/mcp-server'),
+    path.join(process.cwd(), '../core/mcp-server'),
+    path.join(__dirname, '../../../../core/mcp-server'),
   ];
 
   for (const possiblePath of pathsToCheck) {
@@ -35,7 +35,29 @@ export function findMcpServerPath() {
     }
   }
 
-  return path.join(process.cwd(), '../mcp-server');
+  return path.join(process.cwd(), 'core/mcp-server');
+}
+
+function getPathOutput(shell, shellName) {
+  const execOptions = {
+    encoding: 'utf8',
+    timeout: 2000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 1024 * 1024,
+    env: {
+      ...Object.fromEntries(Object.entries(process.env).filter(([key]) => key !== 'PATH')),
+    },
+  };
+
+  if (shellName === 'zsh') {
+    try {
+      return execSync(`${shell} -i -c 'echo $PATH'`, execOptions);
+    } catch (_e) {
+      return execSync(`${shell} -l -c 'echo $PATH'`, execOptions);
+    }
+  }
+
+  return execSync(`${shell} -l -c 'echo $PATH'`, execOptions);
 }
 
 /**
@@ -60,31 +82,6 @@ function getSystemPath() {
       if (fs.existsSync(shell)) {
         try {
           const shellName = path.basename(shell);
-
-          const getPathOutput = (shell, shellName) => {
-            const execOptions = {
-              encoding: 'utf8',
-              timeout: 2000,
-              stdio: ['ignore', 'pipe', 'ignore'],
-              maxBuffer: 1024 * 1024,
-              env: {
-                ...Object.fromEntries(
-                  Object.entries(process.env).filter(([key]) => key !== 'PATH')
-                ),
-              },
-            };
-
-            if (shellName === 'zsh') {
-              try {
-                return execSync(`${shell} -i -c 'echo $PATH'`, execOptions);
-              } catch (_e) {
-                return execSync(`${shell} -l -c 'echo $PATH'`, execOptions);
-              }
-            }
-
-            return execSync(`${shell} -l -c 'echo $PATH'`, execOptions);
-          };
-
           const pathOutput = getPathOutput(shell, shellName);
           const systemPath = pathOutput.trim();
           if (systemPath) {