@mcp-shark/mcp-shark 1.5.4 → 1.5.5

package/core/repositories/SchemaRepository.js

@@ -0,0 +1,107 @@
+/**
+ * Repository for database schema operations
+ * Handles table and index creation
+ * All SQL schema statements are encapsulated here
+ */
+export class SchemaRepository {
+  constructor(db) {
+    this.db = db;
+  }
+
+  /**
+   * Create all database tables and indexes
+   * This is called during database initialization
+   */
+  createSchema() {
+    this.db.exec(`
+      -- Packet capture table
+      -- Each HTTP request/response is stored as a packet for forensic analysis
+      CREATE TABLE IF NOT EXISTS packets (
+        frame_number INTEGER PRIMARY KEY AUTOINCREMENT,
+        
+        -- Timestamps (nanosecond precision)
+        timestamp_ns INTEGER NOT NULL,  -- Unix timestamp in nanoseconds
+        timestamp_iso TEXT NOT NULL,    -- ISO 8601 formatted timestamp for readability
+        
+        -- Packet direction and protocol
+        direction TEXT NOT NULL CHECK(direction IN ('request', 'response')),
+        protocol TEXT NOT NULL DEFAULT 'HTTP',
+        
+        -- Session identification (normalized from various header formats)
+        session_id TEXT,                -- Normalized session ID (from mcp-session-id, Mcp-Session-Id, or X-MCP-Session-Id)
+        
+        -- HTTP metadata
+        method TEXT,                    -- HTTP method (GET, POST, etc.)
+        url TEXT,                       -- Request URL/path
+        status_code INTEGER,            -- HTTP status code (for responses)
+        
+        -- Headers and body
+        headers_json TEXT NOT NULL,     -- Full HTTP headers as JSON
+        body_raw TEXT,                  -- Raw body content
+        body_json TEXT,                 -- Parsed JSON body (if applicable)
+        
+        -- JSON-RPC metadata (for correlation)
+        jsonrpc_id TEXT,                -- JSON-RPC request ID
+        jsonrpc_method TEXT,           -- JSON-RPC method (e.g., 'tools/list', 'tools/call')
+        jsonrpc_result TEXT,           -- JSON-RPC result (for responses, as JSON string)
+        jsonrpc_error TEXT,            -- JSON-RPC error (for error responses, as JSON string)
+        
+        -- Packet metadata
+        length INTEGER NOT NULL,        -- Total packet size in bytes
+        info TEXT,                      -- Summary info for quick viewing
+        
+        -- Network metadata
+        user_agent TEXT,                -- User agent string
+        remote_address TEXT,            -- Remote IP address
+        host TEXT                       -- Host header value
+      );
+
+      -- Conversations table - correlates request/response pairs
+      CREATE TABLE IF NOT EXISTS conversations (
+        conversation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        request_frame_number INTEGER NOT NULL,
+        response_frame_number INTEGER,
+        session_id TEXT,
+        jsonrpc_id TEXT,
+        method TEXT,
+        request_timestamp_ns INTEGER NOT NULL,
+        response_timestamp_ns INTEGER,
+        duration_ms REAL,               -- Round-trip time in milliseconds
+        status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'completed', 'timeout', 'error')),
+        
+        FOREIGN KEY (request_frame_number) REFERENCES packets(frame_number),
+        FOREIGN KEY (response_frame_number) REFERENCES packets(frame_number)
+      );
+
+      -- Sessions table - tracks session metadata
+      CREATE TABLE IF NOT EXISTS sessions (
+        session_id TEXT PRIMARY KEY,
+        first_seen_ns INTEGER NOT NULL,
+        last_seen_ns INTEGER NOT NULL,
+        packet_count INTEGER DEFAULT 0,
+        user_agent TEXT,
+        remote_address TEXT,
+        host TEXT
+      );
+
+      -- Create indexes for forensic analysis
+      CREATE INDEX IF NOT EXISTS idx_packets_timestamp ON packets(timestamp_ns);
+      CREATE INDEX IF NOT EXISTS idx_packets_session ON packets(session_id);
+      CREATE INDEX IF NOT EXISTS idx_packets_direction ON packets(direction);
+      CREATE INDEX IF NOT EXISTS idx_packets_jsonrpc_id ON packets(jsonrpc_id);
+      CREATE INDEX IF NOT EXISTS idx_packets_jsonrpc_method ON packets(jsonrpc_method);
+      CREATE INDEX IF NOT EXISTS idx_packets_method ON packets(method);
+      CREATE INDEX IF NOT EXISTS idx_packets_status_code ON packets(status_code);
+      CREATE INDEX IF NOT EXISTS idx_packets_session_timestamp ON packets(session_id, timestamp_ns);
+      
+      CREATE INDEX IF NOT EXISTS idx_conversations_session ON conversations(session_id);
+      CREATE INDEX IF NOT EXISTS idx_conversations_jsonrpc_id ON conversations(jsonrpc_id);
+      CREATE INDEX IF NOT EXISTS idx_conversations_request_frame ON conversations(request_frame_number);
+      CREATE INDEX IF NOT EXISTS idx_conversations_response_frame ON conversations(response_frame_number);
+      CREATE INDEX IF NOT EXISTS idx_conversations_timestamp ON conversations(request_timestamp_ns);
+      
+      CREATE INDEX IF NOT EXISTS idx_sessions_first_seen ON sessions(first_seen_ns);
+      CREATE INDEX IF NOT EXISTS idx_sessions_last_seen ON sessions(last_seen_ns);
+    `);
+  }
+}

package/core/repositories/SessionRepository.js

@@ -0,0 +1,59 @@
+import { Defaults } from '#core/constants/Defaults.js';
+
+/**
+ * Repository for session-related database operations
+ */
+export class SessionRepository {
+  constructor(db) {
+    this.db = db;
+  }
+
+  /**
+   * Get session metadata
+   */
+  getSessions(filters = {}) {
+    const {
+      startTime = null,
+      endTime = null,
+      limit = Defaults.DEFAULT_LIMIT,
+      offset = Defaults.DEFAULT_OFFSET,
+    } = filters;
+
+    const queryParts = ['SELECT * FROM sessions WHERE 1=1'];
+    const params = [];
+
+    if (startTime) {
+      queryParts.push('AND first_seen_ns >= ?');
+      params.push(startTime);
+    }
+
+    if (endTime) {
+      queryParts.push('AND last_seen_ns <= ?');
+      params.push(endTime);
+    }
+
+    queryParts.push('ORDER BY first_seen_ns DESC LIMIT ? OFFSET ?');
+    params.push(limit, offset);
+
+    const query = queryParts.join(' ');
+    const stmt = this.db.prepare(query);
+    return stmt.all(...params);
+  }
+
+  /**
+   * Update or create session record
+   */
+  upsertSession(sessionId, timestampNs, userAgent, remoteAddress, host) {
+    const stmt = this.db.prepare(`
+      INSERT INTO sessions (session_id, first_seen_ns, last_seen_ns, packet_count, user_agent, remote_address, host)
+      VALUES (?, ?, ?, 1, ?, ?, ?)
+      ON CONFLICT(session_id) DO UPDATE SET
+        last_seen_ns = excluded.last_seen_ns,
+        packet_count = packet_count + 1,
+        user_agent = COALESCE(excluded.user_agent, user_agent),
+        remote_address = COALESCE(excluded.remote_address, remote_address),
+        host = COALESCE(excluded.host, host)
+    `);
+    stmt.run(sessionId, timestampNs, timestampNs, userAgent, remoteAddress, host);
+  }
+}

package/core/repositories/StatisticsRepository.js

@@ -0,0 +1,54 @@
+import { StatusCodeRanges } from '#core/constants/StatusCodes.js';
+
+/**
+ * Repository for statistics-related database operations
+ */
+export class StatisticsRepository {
+  constructor(db) {
+    this.db = db;
+  }
+
+  /**
+   * Get statistics for forensic analysis
+   */
+  getStatistics(filters = {}) {
+    const { sessionId = null, startTime = null, endTime = null } = filters;
+
+    const whereParts = ['WHERE 1=1'];
+    const params = [];
+
+    if (sessionId) {
+      whereParts.push('AND session_id = ?');
+      params.push(sessionId);
+    }
+
+    if (startTime) {
+      whereParts.push('AND timestamp_ns >= ?');
+      params.push(startTime);
+    }
+
+    if (endTime) {
+      whereParts.push('AND timestamp_ns <= ?');
+      params.push(endTime);
+    }
+
+    const whereClause = whereParts.join(' ');
+    const statsQuery = `
+      SELECT 
+        COUNT(*) as total_packets,
+        COUNT(CASE WHEN direction = 'request' THEN 1 END) as total_requests,
+        COUNT(CASE WHEN direction = 'response' THEN 1 END) as total_responses,
+        COUNT(CASE WHEN status_code >= ${StatusCodeRanges.CLIENT_ERROR_START} THEN 1 END) as total_errors,
+        COUNT(DISTINCT session_id) as unique_sessions,
+        AVG(length) as avg_packet_size,
+        SUM(length) as total_bytes,
+        MIN(timestamp_ns) as first_packet_ns,
+        MAX(timestamp_ns) as last_packet_ns
+      FROM packets
+      ${whereClause}
+    `;
+
+    const stmt = this.db.prepare(statsQuery);
+    return stmt.get(...params);
+  }
+}

package/core/repositories/index.js

@@ -0,0 +1,10 @@
+/**
+ * Repository layer exports
+ * All database access should go through repositories
+ */
+export { AuditRepository } from './AuditRepository.js';
+export { ConversationRepository } from './ConversationRepository.js';
+export { PacketRepository } from './PacketRepository.js';
+export { SchemaRepository } from './SchemaRepository.js';
+export { SessionRepository } from './SessionRepository.js';
+export { StatisticsRepository } from './StatisticsRepository.js';

package/core/services/AuditService.js

@@ -0,0 +1,144 @@
+/**
+ * Service for audit logging business logic
+ * Coordinates between audit repository and session repository
+ * HTTP-agnostic: accepts models, returns models
+ */
+import { StatusCodeRanges } from '../constants/StatusCodes.js';
+
+export class AuditService {
+  constructor(auditRepository, sessionRepository, conversationRepository) {
+    this.auditRepository = auditRepository;
+    this.sessionRepository = sessionRepository;
+    this.conversationRepository = conversationRepository;
+  }
+
+  /**
+   * Normalize session ID from various header formats
+   */
+  _normalizeSessionId(headers) {
+    if (!headers || typeof headers !== 'object') {
+      return null;
+    }
+
+    const sessionHeaderKeys = [
+      'mcp-session-id',
+      'Mcp-Session-Id',
+      'X-MCP-Session-Id',
+      'x-mcp-session-id',
+      'MCP-Session-Id',
+    ];
+
+    for (const key of sessionHeaderKeys) {
+      if (headers[key]) {
+        return headers[key];
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Calculate duration in milliseconds
+   */
+  _calculateDurationMs(startNs, endNs) {
+    return (endNs - startNs) / 1_000_000;
+  }
+
+  /**
+   * Log request packet and create conversation entry
+   */
+  logRequestPacket(options) {
+    // Normalize session ID before passing to repository
+    const sessionId = this._normalizeSessionId(options.headers) || options.sessionId || null;
+    const result = this.auditRepository.logRequestPacket({
+      ...options,
+      sessionId,
+    });
+
+    // Update or create session record
+    if (result.sessionId) {
+      this.sessionRepository.upsertSession(
+        result.sessionId,
+        result.timestampNs,
+        options.userAgent || null,
+        options.remoteAddress || null,
+        options.headers?.host || options.headers?.Host || null
+      );
+    }
+
+    // Create conversation entry for request
+    if (result.jsonrpcId) {
+      const method = options.body?.method || options.method || null;
+      this.conversationRepository.createConversation(
+        result.frameNumber,
+        result.sessionId,
+        result.jsonrpcId,
+        method,
+        result.timestampNs
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Log response packet and update conversation entry
+   */
+  logResponsePacket(options) {
+    // Normalize session ID before passing to repository
+    const sessionId = this._normalizeSessionId(options.headers) || options.sessionId || null;
+    const result = this.auditRepository.logResponsePacket({
+      ...options,
+      sessionId,
+    });
+
+    // Update session record
+    if (result.sessionId) {
+      this.sessionRepository.upsertSession(
+        result.sessionId,
+        result.timestampNs,
+        options.userAgent || null,
+        options.remoteAddress || null,
+        options.headers?.host || options.headers?.Host || null
+      );
+    }
+
+    // Update conversation entry with response
+    if (result.jsonrpcId || options.requestFrameNumber) {
+      const durationMs = options.requestTimestampNs
+        ? this._calculateDurationMs(options.requestTimestampNs, result.timestampNs)
+        : null;
+
+      const statusCode = options.statusCode || StatusCodeRanges.SUCCESS_MIN;
+      const status =
+        statusCode >= StatusCodeRanges.SUCCESS_MIN && statusCode <= StatusCodeRanges.SUCCESS_MAX
+          ? 'completed'
+          : 'error';
+
+      if (options.requestFrameNumber) {
+        // Update existing conversation
+        this.conversationRepository.updateConversationWithResponse(
+          options.requestFrameNumber,
+          result.frameNumber,
+          result.timestampNs,
+          durationMs,
+          status
+        );
+      } else if (result.jsonrpcId) {
+        // Try to find conversation by JSON-RPC ID
+        const conv = this.conversationRepository.findConversationByJsonRpcId(result.jsonrpcId);
+        if (conv) {
+          this.conversationRepository.updateConversationWithResponse(
+            conv.request_frame_number,
+            result.frameNumber,
+            result.timestampNs,
+            durationMs,
+            status
+          );
+        }
+      }
+    }
+
+    return result;
+  }
+}

package/core/services/BackupService.js

@@ -0,0 +1,222 @@
+import * as fs from 'node:fs';
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+
+/**
+ * Service for backup operations
+ * Handles creating, restoring, listing, and deleting backups
+ */
+export class BackupService {
+  constructor(configService, logger) {
+    this.configService = configService;
+    this.logger = logger;
+  }
+
+  /**
+   * List all backups
+   */
+  listBackups() {
+    const backups = [];
+    const homeDir = homedir();
+
+    const commonPaths = [
+      path.join(homeDir, '.cursor', 'mcp.json'),
+      path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json'),
+    ];
+
+    const backupDirs = [path.join(homeDir, '.cursor'), path.join(homeDir, '.codeium', 'windsurf')];
+
+    // Find backups with new format: .mcp.json-mcpshark.<datetime>.json
+    for (const dir of backupDirs) {
+      if (fs.existsSync(dir)) {
+        const files = fs.readdirSync(dir);
+        const matchingFiles = files.filter((file) => {
+          return /^\.(.+)-mcpshark\.\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}\.json$/.test(file);
+        });
+        for (const file of matchingFiles) {
+          const match = file.match(/^\.(.+)-mcpshark\./);
+          if (match) {
+            const originalBasename = match[1];
+            const originalPath = path.join(dir, originalBasename);
+            const backupPath = path.join(dir, file);
+            const stats = fs.statSync(backupPath);
+            backups.push({
+              originalPath: originalPath,
+              backupPath: backupPath,
+              createdAt: stats.birthtime.toISOString(),
+              modifiedAt: stats.mtime.toISOString(),
+              size: stats.size,
+              displayPath: originalPath.replace(homeDir, '~'),
+              backupFileName: file,
+            });
+          }
+        }
+      }
+    }
+
+    // Also check for old .backup format for backward compatibility
+    for (const configPath of commonPaths) {
+      const backupPath = `${configPath}.backup`;
+      if (fs.existsSync(backupPath)) {
+        const stats = fs.statSync(backupPath);
+        backups.push({
+          originalPath: configPath,
+          backupPath: backupPath,
+          createdAt: stats.birthtime.toISOString(),
+          modifiedAt: stats.mtime.toISOString(),
+          size: stats.size,
+          displayPath: configPath.replace(homeDir, '~'),
+          backupFileName: path.basename(backupPath),
+        });
+      }
+    }
+
+    // Sort by modifiedAt (latest first)
+    return backups.sort(
+      (a, b) => new Date(b.modifiedAt || b.createdAt) - new Date(a.modifiedAt || a.createdAt)
+    );
+  }
+
+  /**
+   * View backup content
+   */
+  viewBackup(backupPath) {
+    const resolvedBackupPath = this.configService.resolveFilePath(backupPath);
+
+    if (!fs.existsSync(resolvedBackupPath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(resolvedBackupPath, 'utf-8');
+    const parsed = this.configService.tryParseJson(content);
+    const stats = fs.statSync(resolvedBackupPath);
+    const homeDir = homedir();
+
+    return {
+      backupPath: resolvedBackupPath,
+      displayPath: resolvedBackupPath.replace(homeDir, '~'),
+      content: content,
+      parsed: parsed,
+      createdAt: stats.birthtime.toISOString(),
+      modifiedAt: stats.mtime.toISOString(),
+      size: stats.size,
+    };
+  }
+
+  /**
+   * Repatch config if it was patched and server is running
+   * @private
+   */
+  _repatchIfNeeded(wasPatched, serverIsRunning, config, targetPath) {
+    if (wasPatched && serverIsRunning && config) {
+      try {
+        // Repatch the restored config
+        const repatchedConfig = this.configService.updateConfigForMcpShark(config);
+        this.configService.writeConfigAsJson(targetPath, repatchedConfig);
+        this.logger?.info(
+          { path: targetPath },
+          'Repatched config after restore (server is running)'
+        );
+        return true;
+      } catch (error) {
+        this.logger?.error(
+          { error: error.message, path: targetPath },
+          'Failed to repatch config after restore'
+        );
+        // Continue anyway - at least the restore succeeded
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Determine target path for restore
+   */
+  _determineTargetPath(originalPath, backupPath) {
+    if (originalPath) {
+      return this.configService.resolveFilePath(originalPath);
+    }
+
+    // Try to extract from backup filename
+    if (backupPath.endsWith('.backup')) {
+      return backupPath.replace('.backup', '');
+    }
+
+    // New format: .mcp.json-mcpshark.<datetime>.json
+    const match = path.basename(backupPath).match(/^\.(.+)-mcpshark\./);
+    if (match) {
+      const originalBasename = match[1];
+      return path.join(path.dirname(backupPath), originalBasename);
+    }
+
+    return null;
+  }
+
+  /**
+   * Restore backup
+   * @param {string} backupPath - Path to backup file
+   * @param {string} originalPath - Path to original file (optional, will be determined from backup)
+   * @param {boolean} serverIsRunning - Whether MCP Shark server is currently running
+   * @returns {{success: boolean, error?: string, originalPath?: string, wasPatched?: boolean, repatched?: boolean}}
+   */
+  restoreBackup(backupPath, originalPath, serverIsRunning = false) {
+    const resolvedBackupPath = this.configService.resolveFilePath(backupPath);
+
+    if (!fs.existsSync(resolvedBackupPath)) {
+      return { success: false, error: 'Backup file not found' };
+    }
+
+    const targetPath = this._determineTargetPath(originalPath, resolvedBackupPath);
+    if (!targetPath) {
+      return { success: false, error: 'Could not determine original file path' };
+    }
+
+    // Read backup content and check if it was patched
+    const backupContent = fs.readFileSync(resolvedBackupPath, 'utf8');
+    const parseResult = this.configService.parseJsonConfig(backupContent, resolvedBackupPath);
+    const wasPatched = parseResult.config && this.configService.isConfigPatched(parseResult.config);
+
+    // Restore the backup
+    fs.writeFileSync(targetPath, backupContent);
+
+    this.logger?.info({ path: targetPath, wasPatched }, 'Restored config from backup');
+
+    // If the backup was patched and server is running, repatch it
+    const repatched = this._repatchIfNeeded(
+      wasPatched,
+      serverIsRunning,
+      parseResult.config,
+      targetPath
+    );
+
+    const homeDir = homedir();
+    return {
+      success: true,
+      originalPath: targetPath.replace(homeDir, '~'),
+      wasPatched,
+      repatched,
+    };
+  }
+
+  /**
+   * Delete backup
+   */
+  deleteBackup(backupPath) {
+    const resolvedBackupPath = this.configService.resolveFilePath(backupPath);
+
+    if (!fs.existsSync(resolvedBackupPath)) {
+      return { success: false, error: 'Backup file not found' };
+    }
+
+    fs.unlinkSync(resolvedBackupPath);
+
+    this.logger?.info({ path: resolvedBackupPath }, 'Deleted backup');
+
+    const homeDir = homedir();
+    return {
+      success: true,
+      backupPath: resolvedBackupPath.replace(homeDir, '~'),
+    };
+  }
+}

package/core/services/ConfigDetectionService.js

@@ -0,0 +1,89 @@
+import * as fs from 'node:fs';
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+import { getCodexConfigPath } from '#core/configs/index.js';
+
+/**
+ * Service for detecting configuration files on the system
+ */
+export class ConfigDetectionService {
+  /**
+   * Detect config files on the system
+   */
+  detectConfigFiles() {
+    const detected = [];
+    const homeDir = homedir();
+    const platform = process.platform;
+
+    const cursorPaths = [
+      path.join(homeDir, '.cursor', 'mcp.json'),
+      ...(platform === 'win32'
+        ? [path.join(process.env.USERPROFILE || '', '.cursor', 'mcp.json')]
+        : []),
+    ];
+
+    const windsurfPaths = [
+      path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json'),
+      ...(platform === 'win32'
+        ? [path.join(process.env.USERPROFILE || '', '.codeium', 'windsurf', 'mcp_config.json')]
+        : []),
+    ];
+
+    for (const cursorPath of cursorPaths) {
+      if (fs.existsSync(cursorPath)) {
+        detected.push({
+          editor: 'Cursor',
+          path: cursorPath,
+          displayPath: cursorPath.replace(homeDir, '~'),
+          exists: true,
+        });
+        break;
+      }
+    }
+
+    for (const windsurfPath of windsurfPaths) {
+      if (fs.existsSync(windsurfPath)) {
+        detected.push({
+          editor: 'Windsurf',
+          path: windsurfPath,
+          displayPath: windsurfPath.replace(homeDir, '~'),
+          exists: true,
+        });
+        break;
+      }
+    }
+
+    const codexPath = getCodexConfigPath();
+    if (fs.existsSync(codexPath)) {
+      detected.push({
+        editor: 'Codex',
+        path: codexPath,
+        displayPath: codexPath.replace(homeDir, '~'),
+        exists: true,
+      });
+    }
+
+    const defaultPaths = [
+      {
+        editor: 'Cursor',
+        path: path.join(homeDir, '.cursor', 'mcp.json'),
+        displayPath: '~/.cursor/mcp.json',
+        exists: fs.existsSync(path.join(homeDir, '.cursor', 'mcp.json')),
+      },
+      {
+        editor: 'Windsurf',
+        path: path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json'),
+        displayPath: '~/.codeium/windsurf/mcp_config.json',
+        exists: fs.existsSync(path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json')),
+      },
+      {
+        editor: 'Codex',
+        path: codexPath,
+        displayPath: codexPath.replace(homeDir, '~'),
+        exists: fs.existsSync(codexPath),
+      },
+    ];
+
+    return detected.length > 0 ? detected : defaultPaths;
+  }
+}