@mcp-shark/mcp-shark 1.5.3 → 1.5.5

package/README.md

@@ -11,7 +11,9 @@
 [![npm version](https://img.shields.io/npm/v/@mcp-shark/mcp-shark.svg)](https://www.npmjs.com/package/@mcp-shark/mcp-shark)
 [![License: Non-Commercial](https://img.shields.io/badge/License-Non--Commercial-red.svg)](LICENSE)
 
-## Desktop Application
+## Quick Start
+
+### Desktop Application
 
 Download the native desktop application for macOS, Windows, or Linux:
 
@@ -23,130 +25,64 @@ Download the native desktop application for macOS, Windows, or Linux:
 
 The desktop application provides a native experience with automatic updates and system integration. No Node.js installation required.
 
-## npm Package
-
-### Installation
-
-**Global installation (recommended):**
+### npm Package
 
+**Install globally:**
 ```bash
 npm install -g @mcp-shark/mcp-shark
 ```
 
-**Local installation:**
-
+**Run:**
 ```bash
-npm install @mcp-shark/mcp-shark
+mcp-shark --open
 ```
 
-**Using npx (no installation required):**
-
+**Or use npx (no installation):**
 ```bash
 npx @mcp-shark/mcp-shark --open
-# or
-npx @mcp-shark/mcp-shark -o
-# or
-npx @mcp-shark/mcp-shark
 ```
 
-### Usage
-
-After global installation, run:
-
-```bash
-mcp-shark
-```
-
-**Options:**
-- `--open` or `-o`: Automatically open the browser after starting
-
-The executable will:
-- Install dependencies if needed
-- Build the frontend if needed
-- Start the server on `http://localhost:9853`
-- Optionally open your browser automatically
-
-**Package Information:**
-- **Package Name**: `@mcp-shark/mcp-shark`
-- **npm Registry**: [https://www.npmjs.com/package/@mcp-shark/mcp-shark](https://www.npmjs.com/package/@mcp-shark/mcp-shark)
-- **Version**: 1.4.2
-- **License**: Source-Available Non-Commercial (see [LICENSE](LICENSE) for details)
-- **Node.js**: Requires Node.js 18+
-
-## Quick Start
-
-1. **Install:**
-   ```bash
-   npm install -g @mcp-shark/mcp-shark
-   ```
-
-2. **Run:**
-   ```bash
-   mcp-shark --open
-   ```
+The server will start on `http://localhost:9853` and optionally open your browser automatically.
 
-3. **Access the UI:**
-   Navigate to `http://localhost:9853` (or it will open automatically with `--open`)
+## What is MCP Shark?
 
-4. **Configure servers:**
-   Go to the "MCP Server Setup" tab and select your IDE configuration or upload a custom config file.
-
-5. **Start monitoring:**
-   Click "Start MCP Shark" to begin capturing traffic.
-
-For detailed instructions, see [Getting Started Guide](docs/getting-started.md).
-
-## Table of Contents
-
-- [Desktop Application](#desktop-application)
-- [npm Package](#npm-package)
-- [Quick Start](#quick-start)
-- [About](#about)
-- [Features](#features)
-- [Documentation](#documentation)
-- [Requirements](#requirements)
-- [License](#license)
-
-## About
-
-MCP Shark is a monitoring and aggregation solution for Model Context Protocol (MCP) servers. It provides a unified interface for multiple MCP servers (both HTTP and stdio-based) with real-time traffic inspection, security analysis, and interactive testing capabilities.
-
-Key capabilities:
+MCP Shark is a monitoring and aggregation solution for Model Context Protocol (MCP) servers. It provides:
 
 - **Multi-server aggregation**: Connect to multiple MCP servers simultaneously
 - **Real-time monitoring**: Wireshark-like interface for inspecting all MCP communications
 - **Interactive playground**: Test tools, prompts, and resources directly in the UI
 - **Security analysis**: AI-powered scanning for security risks and vulnerabilities
-- **IDE integration**: Automatic configuration for Cursor, Windsurf, and other IDEs
-
-## Features
-
-- **Traffic Capture**: Real-time monitoring with advanced filtering and search
-- **MCP Playground**: Interactive testing environment for tools, prompts, and resources
-- **Smart Scan**: AI-powered security analysis for MCP servers
-- **Session Management**: Track and analyze conversation sessions
-- **Export & Backup**: Export data in multiple formats and manage configuration backups
-- **Statistics & Analytics**: Performance metrics and traffic analysis
-
-For detailed feature documentation, see [Features Guide](docs/features.md).
+- **IDE integration**: Automatic configuration detection for Cursor, Windsurf, Codex, and other IDEs
+- **API documentation**: Comprehensive Swagger/OpenAPI documentation for all endpoints with interactive testing
 
 ## Documentation
 
-Comprehensive documentation is available in the [`docs/`](docs/) directory:
+### Getting Started
+- **[Installation & Setup](docs/getting-started.md)** - Complete installation guide for desktop app and npm package
+- **[Quick Start Guide](docs/getting-started.md#quick-start)** - Get up and running in minutes
 
-- **[Getting Started](docs/getting-started.md)** - Installation, setup, and first steps
+### User Guides
 - **[Features](docs/features.md)** - Detailed feature documentation
 - **[User Guide](docs/user-guide.md)** - Complete guide to using MCP Shark
-- **[Architecture](docs/architecture.md)** - System architecture and design
-- **[API Reference](docs/api-reference.md)** - API endpoints and WebSocket protocol
 - **[Configuration](docs/configuration.md)** - Configuration options and file formats
 - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
-- **[Development](docs/development.md)** - Developer guide and contribution guidelines
+
+### Developer Guides
+- **[Development Guide](docs/development.md)** - Developer guide and contribution guidelines
+- **[Architecture](docs/architecture.md)** - System architecture and design
+- **[Database Architecture](docs/database-architecture.md)** - Database architecture and repository pattern
+- **[API Reference](docs/api-reference.md)** - API endpoints and WebSocket protocol
+- **API Documentation** - Interactive Swagger/OpenAPI documentation available at `/api-docs` when server is running (or click the 📡 button in the UI)
+
+### Architecture & Coding Rules
+- **[Architecture Rules](rules/ARCHITECTURE_RULES.md)** - Architecture principles and guidelines
+- **[Database Architecture Rules](rules/DB_ARCHITECTURE.md)** - Database architecture rules
+- **[Coding Rules](rules/CODING_RULES.md)** - Coding standards and best practices
+- **[Linting Rules](rules/LINTING_RULES.md)** - Linting configuration and rules
 
 ## Requirements
 
-- **Node.js**: 18.0.0 or higher
-- **npm**: Comes with Node.js
+- **Node.js**: 20.0.0 or higher (for npm package)
 - **Operating System**: macOS, Windows, or Linux
 
 ## License
@@ -175,4 +111,4 @@ See the [LICENSE](LICENSE) file for full terms and conditions.
 
 ---
 
-**Version**: 1.5.0 | **Homepage**: [https://mcpshark.sh](https://mcpshark.sh)
+**Version**: 1.5.4 | **Homepage**: [https://mcpshark.sh](https://mcpshark.sh)

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 '#common/logger';
+import { bootstrapLogger as logger } from '#core/libraries/index.js';
 
 const SERVER_URL = 'http://localhost:9853';
 const BROWSER_OPEN_DELAY = 1000;

package/core/configs/codex.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ConfigParserFactory } from '#core/services/parsers/ConfigParserFactory.js';
+import { Environment } from './environment.js';
+
+const parserFactory = new ConfigParserFactory();
+
+/**
+ * Get Codex config.toml path
+ * Codex uses $CODEX_HOME/config.toml, defaulting to ~/.codex/config.toml
+ * @returns {string} Path to Codex config file
+ */
+export function getCodexConfigPath() {
+  const codexHome = Environment.getCodexHome();
+  return join(codexHome, 'config.toml');
+}
+
+/**
+ * Check if Codex config.toml exists
+ */
+export function codexConfigExists() {
+  return existsSync(getCodexConfigPath());
+}
+
+/**
+ * Read and parse Codex config.toml
+ * Uses TomlConfigParser for parsing
+ */
+export function readCodexConfig() {
+  const configPath = getCodexConfigPath();
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    return parserFactory.parse(content, configPath);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Convert Codex mcp_servers TOML format to MCP Shark JSON format
+ * Uses TomlConfigParser for conversion
+ * @deprecated Use ConfigParserFactory.normalizeToInternalFormat() instead
+ */
+export function convertCodexConfigToMcpShark(codexConfig) {
+  return parserFactory.normalizeToInternalFormat(codexConfig);
+}
+
+/**
+ * Read Codex config and convert to MCP Shark format
+ * Uses ConfigParserFactory for unified parsing and conversion
+ */
+export function readCodexConfigAsMcpShark() {
+  const configPath = getCodexConfigPath();
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    return parserFactory.parseAndNormalize(content, configPath);
+  } catch (_error) {
+    return null;
+  }
+}

package/core/configs/environment.js

@@ -0,0 +1,51 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Server } from '#core/constants/Server.js';
+
+/**
+ * Environment variable management
+ * Provides validated access to environment variables with defaults
+ */
+export const Environment = {
+  /**
+   * Get Codex home directory
+   * @returns {string} Codex home path
+   */
+  getCodexHome() {
+    return process.env.CODEX_HOME || join(homedir(), '.codex');
+  },
+
+  /**
+   * Get UI server port
+   * @returns {number} UI server port (default: 9853)
+   */
+  getUiPort() {
+    const port = Number.parseInt(process.env.UI_PORT, 10);
+    return Number.isNaN(port) ? Server.DEFAULT_UI_PORT : port;
+  },
+
+  /**
+   * Get MCP server port
+   * @returns {number} MCP server port (default: 9851)
+   */
+  getMcpServerPort() {
+    const port = Number.parseInt(process.env.MCP_SHARK_SERVER_PORT, 10);
+    return Number.isNaN(port) ? Server.DEFAULT_MCP_SERVER_PORT : port;
+  },
+
+  /**
+   * Get system PATH
+   * @returns {string} System PATH environment variable
+   */
+  getPath() {
+    return process.env.PATH || '';
+  },
+
+  /**
+   * Get MCP Shark home directory
+   * @returns {string} MCP Shark home path
+   */
+  getMcpSharkHome() {
+    return process.env.MCP_SHARK_HOME || join(homedir(), '.mcp-shark');
+  },
+};

package/{lib/common → core}/configs/index.js

@@ -1,6 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+
+export * from './codex.js';
+export { Environment } from './environment.js';
 
 const WORKING_DIRECTORY_NAME = '.mcp-shark';
 const MCP_CONFIG_NAME = 'mcps.json';
@@ -48,6 +51,18 @@ export function prepareAppDataSpaces() {
   createDatabaseSpaces();
 }
 
+/**
+ * Ensure directory exists for a given file path
+ * Creates parent directory if it doesn't exist
+ * @param {string} filePath - Full path to a file
+ */
+export function ensureDirectoryExists(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
 export function getHelpStatePath() {
   return join(getWorkingDirectory(), HELP_STATE_NAME);
 }

package/core/constants/Defaults.js

@@ -0,0 +1,15 @@
+/**
+ * Default values used across the application
+ */
+export const Defaults = {
+  // Pagination defaults
+  DEFAULT_LIMIT: 1000,
+  DEFAULT_OFFSET: 0,
+  DEFAULT_SESSION_LIMIT: 10000,
+
+  // Export defaults
+  EXPORT_LIMIT: 100000,
+
+  // Statistics defaults
+  STATISTICS_LIMIT: 1000000,
+};

package/core/constants/HttpStatus.js

@@ -0,0 +1,14 @@
+/**
+ * HTTP status codes
+ * @deprecated Use StatusCodes from './StatusCodes.js' instead
+ */
+export const HttpStatus = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  INTERNAL_SERVER_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+};

package/core/constants/Server.js

@@ -0,0 +1,20 @@
+/**
+ * Server configuration constants
+ */
+export const Server = {
+  // Default ports
+  DEFAULT_UI_PORT: 9853,
+  DEFAULT_MCP_SERVER_PORT: 9851,
+
+  // Connection settings
+  WEBSOCKET_HEARTBEAT_INTERVAL_MS: 30000, // 30 seconds
+  WEBSOCKET_TIMEOUT_MS: 1800000, // 30 minutes
+  MCP_CLIENT_SESSION_TIMEOUT_MS: 1800000, // 30 minutes
+
+  // Polling intervals
+  PACKET_CHECK_INTERVAL_MS: 500,
+
+  // Limits
+  MAX_LOG_LINES: 10000,
+  MAX_WEBSOCKET_CONNECTIONS: 1000,
+};

package/core/constants/StatusCodes.js

@@ -0,0 +1,25 @@
+/**
+ * HTTP status code constants
+ */
+export const StatusCodes = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  INTERNAL_SERVER_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+};
+
+/**
+ * Status code ranges for validation
+ */
+export const StatusCodeRanges = {
+  SUCCESS_MIN: 200,
+  SUCCESS_MAX: 299,
+  CLIENT_ERROR_MIN: 400,
+  CLIENT_ERROR_MAX: 499,
+  SERVER_ERROR_MIN: 500,
+  SERVER_ERROR_MAX: 599,
+};

package/core/constants/index.js

@@ -0,0 +1,7 @@
+/**
+ * Constants exports
+ */
+export { Defaults } from './Defaults.js';
+export { HttpStatus } from './HttpStatus.js';
+export { StatusCodes, StatusCodeRanges } from './StatusCodes.js';
+export { Server } from './Server.js';

package/core/container/DependencyContainer.js

@@ -0,0 +1,179 @@
+import { LoggerLibrary, SerializationLibrary } from '#core/libraries/index.js';
+import {
+  AuditRepository,
+  ConversationRepository,
+  PacketRepository,
+  SessionRepository,
+  StatisticsRepository,
+} from '#core/repositories/index.js';
+import {
+  AuditService,
+  BackupService,
+  ConfigDetectionService,
+  ConfigFileService,
+  ConfigPatchingService,
+  ConfigService,
+  ConfigTransformService,
+  ConversationService,
+  ExportService,
+  LogService,
+  McpClientService,
+  McpDiscoveryService,
+  RequestService,
+  ScanCacheService,
+  ScanService,
+  ServerManagementService,
+  SessionService,
+  SettingsService,
+  StatisticsService,
+  TokenService,
+} from '#core/services/index.js';
+import { ConfigParserFactory } from '#core/services/parsers/ConfigParserFactory.js';
+
+/**
+ * Dependency Injection Container
+ * Manages all dependencies and provides instances of services, repositories, and libraries
+ * Follows SOLID principles with dependency inversion
+ */
+export class DependencyContainer {
+  constructor(db) {
+    this.db = db;
+    this._repositories = {};
+    this._services = {};
+    this._libraries = {};
+  }
+
+  /**
+   * Get or create repository instances
+   */
+  _getRepositories() {
+    if (!this._repositories.packet) {
+      this._repositories.packet = new PacketRepository(this.db);
+    }
+    if (!this._repositories.session) {
+      this._repositories.session = new SessionRepository(this.db);
+    }
+    if (!this._repositories.conversation) {
+      this._repositories.conversation = new ConversationRepository(this.db);
+    }
+    if (!this._repositories.audit) {
+      this._repositories.audit = new AuditRepository(this.db);
+    }
+    if (!this._repositories.statistics) {
+      this._repositories.statistics = new StatisticsRepository(this.db);
+    }
+
+    return this._repositories;
+  }
+
+  /**
+   * Get or create library instances
+   */
+  _getLibraries() {
+    if (!this._libraries.serialization) {
+      this._libraries.serialization = new SerializationLibrary();
+    }
+    if (!this._libraries.logger) {
+      this._libraries.logger = new LoggerLibrary();
+    }
+
+    return this._libraries;
+  }
+
+  /**
+   * Get or create service instances
+   */
+  _getServices() {
+    if (Object.keys(this._services).length === 0) {
+      const repos = this._getRepositories();
+      const libs = this._getLibraries();
+
+      this._services.request = new RequestService(repos.packet);
+      this._services.session = new SessionService(repos.session, repos.packet);
+      this._services.conversation = new ConversationService(repos.conversation);
+      this._services.statistics = new StatisticsService(
+        repos.statistics,
+        repos.packet,
+        repos.conversation
+      );
+      this._services.audit = new AuditService(repos.audit, repos.session, repos.conversation);
+
+      // Config services (with proper DI)
+      const configParserFactory = new ConfigParserFactory();
+      const configDetectionService = new ConfigDetectionService();
+      const configFileService = new ConfigFileService(
+        libs.logger,
+        configDetectionService,
+        configParserFactory
+      );
+      const configTransformService = new ConfigTransformService(configParserFactory);
+      this._services.config = new ConfigService(
+        libs.logger,
+        configFileService,
+        configTransformService,
+        configDetectionService
+      );
+
+      this._services.backup = new BackupService(this._services.config, libs.logger);
+      this._services.configPatching = new ConfigPatchingService(
+        this._services.config,
+        this._services.backup,
+        libs.logger
+      );
+      this._services.serverManagement = new ServerManagementService(
+        this._services.config,
+        this._services.configPatching,
+        libs.logger
+      );
+      this._services.log = new LogService(libs.logger);
+      this._services.scanCache = new ScanCacheService(libs.logger);
+      this._services.scan = new ScanService(this._services.scanCache, libs.logger);
+      this._services.mcpDiscovery = new McpDiscoveryService(this._services.config, libs.logger);
+      this._services.mcpClient = new McpClientService(libs.logger);
+      this._services.token = new TokenService(libs.logger);
+      this._services.settings = new SettingsService(
+        this._services.token,
+        this._services.backup,
+        libs.logger
+      );
+      this._services.export = new ExportService();
+    }
+
+    return this._services;
+  }
+
+  /**
+   * Get a service by name
+   */
+  getService(serviceName) {
+    const services = this._getServices();
+    return services[serviceName];
+  }
+
+  /**
+   * Get a repository by name
+   */
+  getRepository(repositoryName) {
+    const repos = this._getRepositories();
+    return repos[repositoryName];
+  }
+
+  /**
+   * Get a library by name
+   */
+  getLibrary(libraryName) {
+    const libs = this._getLibraries();
+    return libs[libraryName];
+  }
+
+  /**
+   * Get audit logger (wrapper around AuditService for backward compatibility)
+   */
+  getAuditLogger() {
+    const auditService = this.getService('audit');
+    return {
+      logRequestPacket: (options) => auditService.logRequestPacket(options),
+      logResponsePacket: (options) => auditService.logResponsePacket(options),
+    };
+  }
+}

package/core/db/init.js

@@ -0,0 +1,33 @@
+import Database from 'better-sqlite3';
+import { ensureDirectoryExists } from '#core/configs/index.js';
+import { SchemaRepository } from '#core/repositories/SchemaRepository.js';
+
+function configureDatabase(db) {
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  return db;
+}
+
+function initializeSchema(db) {
+  const schemaRepository = new SchemaRepository(db);
+  schemaRepository.createSchema();
+  return db;
+}
+
+export function initDb(dbConnectionString) {
+  const db = new Database(dbConnectionString);
+  configureDatabase(db);
+  return initializeSchema(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) {
+  ensureDirectoryExists(dbPath);
+
+  const db = new Database(dbPath);
+  configureDatabase(db);
+  return initializeSchema(db);
+}

package/core/index.js

@@ -0,0 +1,10 @@
+/**
+ * Core module exports
+ * Main entry point for the core architecture
+ */
+export { DependencyContainer } from './container/DependencyContainer.js';
+export * from './repositories/index.js';
+export * from './services/index.js';
+export * from './libraries/index.js';
+export * from './models/index.js';
+export * from './constants/index.js';

package/{mcp-server/lib/common/error.js → core/libraries/ErrorLibrary.js}

@@ -1,3 +1,7 @@
+/**
+ * Library for error handling utilities
+ * Pure utility - no dependencies on services or repositories
+ */
 export class CompositeError extends Error {
   constructor(name, message, error) {
     super(name, message);