@mcp-shark/mcp-shark 1.5.2 → 1.5.3

package/bin/mcp-shark.js

@@ -6,7 +6,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import open from 'open';
-import logger from '../shared/logger.js';
+import logger from '#common/logger';
 
 const SERVER_URL = 'http://localhost:9853';
 const BROWSER_OPEN_DELAY = 1000;
@@ -40,46 +40,6 @@ function displayWelcomeBanner() {
 
 const uiDir = join(rootDir, 'ui');
 const distDir = join(uiDir, 'dist');
-const rootNodeModules = join(rootDir, 'node_modules');
-
-/**
- * Run a command and return a promise that resolves when it completes
- */
-function runCommand(command, args, options) {
-  return new Promise((resolve, reject) => {
-    const process = spawn(command, args, {
-      ...options,
-      stdio: 'inherit',
-      shell: true,
-    });
-
-    process.on('close', (code) => {
-      if (code !== 0) {
-        reject(new Error(`Command failed with exit code ${code}`));
-      } else {
-        resolve();
-      }
-    });
-
-    process.on('error', (error) => {
-      reject(error);
-    });
-  });
-}
-
-/**
- * Install dependencies in the root directory
- */
-async function installDependencies() {
-  logger.info('Installing dependencies...');
-  try {
-    await runCommand('npm', ['install'], { cwd: rootDir });
-    logger.info('Dependencies installed successfully!\n');
-  } catch (error) {
-    logger.error({ error: error.message }, 'Failed to install dependencies');
-    process.exit(1);
-  }
-}
 
 /**
  * Validate that UI dist directory exists
@@ -172,15 +132,6 @@ function validateDirectories() {
   }
 }
 
-/**
- * Ensure dependencies are installed
- */
-async function ensureDependencies() {
-  if (!existsSync(rootNodeModules)) {
-    await installDependencies();
-  }
-}
-
 /**
  * Main execution function
  */
@@ -197,9 +148,6 @@ async function main() {
   // Validate environment
   validateDirectories();
 
-  // Ensure dependencies are installed
-  await ensureDependencies();
-
   // Validate UI is built (pre-built files should be included in package)
   validateUIBuilt();
 

package/lib/common/configs/index.js

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const WORKING_DIRECTORY_NAME = '.mcp-shark';
+const MCP_CONFIG_NAME = 'mcps.json';
+const APP_DB_DIR_NAME = 'db';
+const APP_DB_FILE_NAME = 'mcp-shark.sqlite';
+const HELP_STATE_NAME = 'help-state.json';
+
+export function getWorkingDirectory() {
+  return join(homedir(), WORKING_DIRECTORY_NAME);
+}
+
+export function getDatabasePath() {
+  return join(getWorkingDirectory(), APP_DB_DIR_NAME);
+}
+
+export function getDatabaseFile() {
+  return join(getDatabasePath(), APP_DB_FILE_NAME);
+}
+
+export function createWorkingDirectorySpaces() {
+  const workingDirectory = getWorkingDirectory();
+  if (!existsSync(workingDirectory)) {
+    mkdirSync(workingDirectory, { recursive: true });
+  }
+}
+
+export function createDatabaseSpaces() {
+  createWorkingDirectorySpaces();
+  const databasePath = getDatabasePath();
+  if (!existsSync(databasePath)) {
+    mkdirSync(databasePath, { recursive: true });
+    const databaseFile = getDatabaseFile();
+    if (!existsSync(databaseFile)) {
+      writeFileSync(databaseFile, '');
+    }
+  }
+}
+
+export function getMcpConfigPath() {
+  return join(getWorkingDirectory(), MCP_CONFIG_NAME);
+}
+
+export function prepareAppDataSpaces() {
+  createWorkingDirectorySpaces();
+  createDatabaseSpaces();
+}
+
+export function getHelpStatePath() {
+  return join(getWorkingDirectory(), HELP_STATE_NAME);
+}
+
+export function readHelpState() {
+  try {
+    const helpStatePath = getHelpStatePath();
+    if (existsSync(helpStatePath)) {
+      const content = readFileSync(helpStatePath, 'utf8');
+      const state = JSON.parse(content);
+      // Ensure we have the expected structure
+      return {
+        dismissed: state.dismissed || false,
+        tourCompleted: state.tourCompleted || false,
+        dismissedAt: state.dismissedAt || null,
+        version: state.version || '1.0.0',
+      };
+    }
+    return {
+      dismissed: false,
+      tourCompleted: false,
+      dismissedAt: null,
+      version: '1.0.0',
+    };
+  } catch (_error) {
+    // Error reading help state - return defaults
+    return {
+      dismissed: false,
+      tourCompleted: false,
+      dismissedAt: null,
+      version: '1.0.0',
+    };
+  }
+}
+
+export function writeHelpState(state) {
+  try {
+    const helpStatePath = getHelpStatePath();
+    prepareAppDataSpaces(); // Ensure directory exists
+
+    // Merge with existing state to preserve other fields
+    const existingState = readHelpState();
+    const newState = {
+      ...existingState,
+      ...state,
+      dismissedAt:
+        state.dismissed || state.tourCompleted
+          ? new Date().toISOString()
+          : existingState.dismissedAt,
+      version: '1.0.0',
+    };
+
+    writeFileSync(helpStatePath, JSON.stringify(newState, null, 2));
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}

package/lib/common/db/init.js

@@ -0,0 +1,132 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import Database from 'better-sqlite3';
+
+function createTables(db) {
+  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);
+  `);
+
+  return db;
+}
+
+export function initDb(dbConnectionString) {
+  const db = new Database(dbConnectionString);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+
+  return createTables(db);
+}
+
+/**
+ * Open or create a database file, ensuring the directory exists
+ * Creates tables if the database is new or ensures they exist
+ */
+export function openDb(dbPath) {
+  // Ensure the directory exists
+  const dbDir = path.dirname(dbPath);
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+  }
+
+  // Check if database file exists
+  const _dbExists = fs.existsSync(dbPath);
+
+  // Open or create the database
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+
+  // Create tables if database is new or tables don't exist
+  // Even if database exists, ensure tables exist (in case schema changed)
+  createTables(db);
+
+  return db;
+}

package/lib/common/db/logger.js

@@ -0,0 +1,349 @@
+/**
+ * Helper functions for logging HTTP packets to the database for forensic analysis
+ */
+
+function getTimestampNs() {
+  return Number(process.hrtime.bigint());
+}
+
+function getTimestampISO() {
+  return new Date().toISOString();
+}
+
+function calculateDurationMs(startNs, endNs) {
+  return (endNs - startNs) / 1_000_000;
+}
+
+/**
+ * Normalize session ID from various header formats
+ * Supports: mcp-session-id, Mcp-Session-Id, X-MCP-Session-Id
+ */
+function normalizeSessionId(headers) {
+  if (!headers || typeof headers !== 'object') {
+    return null;
+  }
+
+  // Check all possible header formats (case-insensitive)
+  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;
+}
+
+/**
+ * Extract JSON-RPC metadata from body
+ */
+function extractJsonRpcMetadata(bodyJson) {
+  if (!bodyJson) {
+    return { id: null, method: null, result: null, error: null };
+  }
+
+  try {
+    const parsed = typeof bodyJson === 'string' ? JSON.parse(bodyJson) : bodyJson;
+    return {
+      id: parsed.id !== undefined ? String(parsed.id) : null,
+      method: parsed.method || null,
+      result: parsed.result ? JSON.stringify(parsed.result) : null,
+      error: parsed.error ? JSON.stringify(parsed.error) : null,
+    };
+  } catch {
+    return { id: null, method: null, result: null, error: null };
+  }
+}
+
+/**
+ * Generate info summary for quick packet identification
+ */
+function generateInfo(direction, method, url, statusCode, jsonrpcMethod) {
+  if (direction === 'request') {
+    const rpcInfo = jsonrpcMethod ? ` ${jsonrpcMethod}` : '';
+    return `${method} ${url}${rpcInfo}`;
+  }
+
+  const rpcInfo = jsonrpcMethod ? ` ${jsonrpcMethod}` : '';
+  return `${statusCode}${rpcInfo}`;
+}
+
+/**
+ * Log an HTTP request packet
+ */
+function logRequestPacket(db, options) {
+  const { method, url, headers = {}, body, userAgent = null, remoteAddress = null } = options;
+
+  const timestampNs = getTimestampNs();
+  const timestampISO = getTimestampISO();
+  const sessionId = normalizeSessionId(headers);
+  const host = headers.host || headers.Host || null;
+
+  // Prepare body data
+  const { bodyRaw, bodyJson } = (() => {
+    if (!body) {
+      return { bodyRaw: '', bodyJson: null };
+    }
+    if (typeof body === 'string') {
+      return { bodyRaw: body, bodyJson: body };
+    }
+    if (typeof body === 'object') {
+      const raw = JSON.stringify(body);
+      return { bodyRaw: raw, bodyJson: raw };
+    }
+    return { bodyRaw: '', bodyJson: null };
+  })();
+  const headersJson = JSON.stringify(headers);
+
+  // Extract JSON-RPC metadata
+  const jsonrpc = extractJsonRpcMetadata(bodyJson || bodyRaw);
+  const jsonrpcId = jsonrpc.id;
+  const jsonrpcMethod = jsonrpc.method;
+
+  // Calculate packet length
+  const length = Buffer.byteLength(headersJson, 'utf8') + Buffer.byteLength(bodyRaw, 'utf8');
+
+  // Generate info summary
+  const info = generateInfo('request', method, url, null, jsonrpcMethod);
+
+  const stmt = db.prepare(`
+    INSERT INTO packets (
+      timestamp_ns,
+      timestamp_iso,
+      direction,
+      protocol,
+      session_id,
+      method,
+      url,
+      headers_json,
+      body_raw,
+      body_json,
+      jsonrpc_id,
+      jsonrpc_method,
+      length,
+      info,
+      user_agent,
+      remote_address,
+      host
+    ) VALUES (?, ?, 'request', 'HTTP', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const result = stmt.run(
+    timestampNs,
+    timestampISO,
+    sessionId,
+    method,
+    url,
+    headersJson,
+    bodyRaw,
+    bodyJson,
+    jsonrpcId,
+    jsonrpcMethod,
+    length,
+    info,
+    userAgent,
+    remoteAddress,
+    host
+  );
+
+  const frameNumber = result.lastInsertRowid;
+
+  // Update or create session record
+  if (sessionId) {
+    const sessionStmt = 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)
+    `);
+    sessionStmt.run(sessionId, timestampNs, timestampNs, userAgent, remoteAddress, host);
+  }
+
+  // Create conversation entry for request
+  if (jsonrpcId) {
+    const convStmt = db.prepare(`
+      INSERT INTO conversations (
+        request_frame_number,
+        session_id,
+        jsonrpc_id,
+        method,
+        request_timestamp_ns,
+        status
+      ) VALUES (?, ?, ?, ?, ?, 'pending')
+    `);
+    convStmt.run(frameNumber, sessionId, jsonrpcId, jsonrpcMethod || method, timestampNs);
+  }
+
+  return { frameNumber, timestampNs };
+}
+
+/**
+ * Log an HTTP response packet
+ */
+function logResponsePacket(db, options) {
+  const {
+    statusCode,
+    headers = {},
+    body,
+    requestFrameNumber = null,
+    requestTimestampNs = null,
+    jsonrpcId = null,
+    userAgent = null,
+    remoteAddress = null,
+  } = options;
+
+  const timestampNs = getTimestampNs();
+  const timestampISO = getTimestampISO();
+  const sessionId = normalizeSessionId(headers);
+  const host = headers.host || headers.Host || null;
+
+  // Prepare body data
+  const { bodyRaw, bodyJson } = (() => {
+    if (!body) {
+      return { bodyRaw: '', bodyJson: null };
+    }
+    if (typeof body === 'string') {
+      return { bodyRaw: body, bodyJson: body };
+    }
+    if (typeof body === 'object') {
+      const raw = JSON.stringify(body);
+      return { bodyRaw: raw, bodyJson: raw };
+    }
+    return { bodyRaw: '', bodyJson: null };
+  })();
+  const headersJson = JSON.stringify(headers);
+
+  // Extract JSON-RPC metadata
+  const jsonrpc = extractJsonRpcMetadata(bodyJson || bodyRaw);
+  const jsonrpcIdFromBody = jsonrpc.id || jsonrpcId;
+  const jsonrpcMethod = jsonrpc.method;
+  const jsonrpcResult = jsonrpc.result;
+  const jsonrpcError = jsonrpc.error;
+
+  // Calculate packet length
+  const length = Buffer.byteLength(headersJson, 'utf8') + Buffer.byteLength(bodyRaw, 'utf8');
+
+  // Generate info summary
+  const info = generateInfo('response', null, null, statusCode, jsonrpcMethod);
+
+  const stmt = db.prepare(`
+    INSERT INTO packets (
+      timestamp_ns,
+      timestamp_iso,
+      direction,
+      protocol,
+      session_id,
+      status_code,
+      headers_json,
+      body_raw,
+      body_json,
+      jsonrpc_id,
+      jsonrpc_method,
+      jsonrpc_result,
+      jsonrpc_error,
+      length,
+      info,
+      user_agent,
+      remote_address,
+      host
+    ) VALUES (?, ?, 'response', 'HTTP', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const result = stmt.run(
+    timestampNs,
+    timestampISO,
+    sessionId,
+    statusCode,
+    headersJson,
+    bodyRaw,
+    bodyJson,
+    jsonrpcIdFromBody,
+    jsonrpcMethod,
+    jsonrpcResult,
+    jsonrpcError,
+    length,
+    info,
+    userAgent,
+    remoteAddress,
+    host
+  );
+
+  const frameNumber = result.lastInsertRowid;
+
+  // Update session record
+  if (sessionId) {
+    const sessionStmt = 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)
+    `);
+    sessionStmt.run(sessionId, timestampNs, timestampNs, userAgent, remoteAddress, host);
+  }
+
+  // Update conversation entry with response
+  if (jsonrpcIdFromBody || requestFrameNumber) {
+    const durationMs = requestTimestampNs
+      ? calculateDurationMs(requestTimestampNs, timestampNs)
+      : null;
+
+    const status = statusCode >= 200 && statusCode < 300 ? 'completed' : 'error';
+
+    if (requestFrameNumber) {
+      // Update existing conversation
+      const updateConvStmt = db.prepare(`
+        UPDATE conversations
+        SET response_frame_number = ?,
+            response_timestamp_ns = ?,
+            duration_ms = ?,
+            status = ?
+        WHERE request_frame_number = ?
+      `);
+      updateConvStmt.run(frameNumber, timestampNs, durationMs, status, requestFrameNumber);
+    } else if (jsonrpcIdFromBody) {
+      // Try to find conversation by JSON-RPC ID
+      const findConvStmt = db.prepare(`
+        SELECT request_frame_number FROM conversations
+        WHERE jsonrpc_id = ? AND response_frame_number IS NULL
+        ORDER BY request_timestamp_ns DESC
+        LIMIT 1
+      `);
+      const conv = findConvStmt.get(jsonrpcIdFromBody);
+      if (conv) {
+        const updateConvStmt = db.prepare(`
+          UPDATE conversations
+          SET response_frame_number = ?,
+              response_timestamp_ns = ?,
+              duration_ms = ?,
+              status = ?
+          WHERE request_frame_number = ?
+        `);
+        updateConvStmt.run(frameNumber, timestampNs, durationMs, status, conv.request_frame_number);
+      }
+    }
+  }
+
+  return frameNumber;
+}
+
+export function getLogger(db) {
+  return {
+    logRequestPacket: logRequestPacket.bind(null, db),
+    logResponsePacket: logResponsePacket.bind(null, db),
+  };
+}