@mcp-shark/mcp-shark 1.5.8 → 1.5.10

package/README.md

@@ -54,6 +54,7 @@ MCP Shark is a monitoring and aggregation solution for Model Context Protocol (M
 - **Security analysis**: AI-powered scanning for security risks and vulnerabilities
 - **IDE integration**: Automatic configuration detection for Cursor, Windsurf, Codex, and other IDEs
 - **API documentation**: Comprehensive Swagger/OpenAPI documentation for all endpoints with interactive testing
+- **Action menu**: Expandable menu providing quick access to API docs, help tour, and server shutdown
 
 ## Documentation
 
@@ -72,7 +73,7 @@ MCP Shark is a monitoring and aggregation solution for Model Context Protocol (M
 - **[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)
+- **API Documentation** - Interactive Swagger/OpenAPI documentation available at `/api-docs` when server is running (or click the menu button ☰ in the bottom-right corner, then select the API docs button 📡)
 
 ### Architecture & Coding Rules
 - **[Architecture Rules](rules/ARCHITECTURE_RULES.md)** - Architecture principles and guidelines
@@ -111,4 +112,4 @@ See the [LICENSE](LICENSE) file for full terms and conditions.
 
 ---
 
-**Version**: 1.5.4 | **Homepage**: [https://mcpshark.sh](https://mcpshark.sh)
+**Version**: 1.5.9 | **Homepage**: [https://mcpshark.sh](https://mcpshark.sh)

package/core/configs/environment.js

@@ -7,14 +7,9 @@ import { Server } from '#core/constants/Server.js';
  * 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');
+  getEnv() {
+    return process.env;
   },
-
   /**
    * Get UI server port
    * @returns {number} UI server port (default: 9853)
@@ -48,4 +43,12 @@ export const Environment = {
   getMcpSharkHome() {
     return process.env.MCP_SHARK_HOME || join(homedir(), '.mcp-shark');
   },
+
+  getUserProfile() {
+    return process.env.USERPROFILE || homedir();
+  },
+
+  getCodexHome() {
+    return process.env.CODEX_HOME || join(homedir(), '.codex');
+  },
 };

package/core/configs/index.js

@@ -2,7 +2,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
-export * from './codex.js';
 export { Environment } from './environment.js';
 
 const WORKING_DIRECTORY_NAME = '.mcp-shark';

package/core/constants/Defaults.js

@@ -12,4 +12,6 @@ export const Defaults = {
 
   // Statistics defaults
   STATISTICS_LIMIT: 1000000,
+
+  DEFAULT_MCP_SERVER_PORT: 9851,
 };

package/core/libraries/TransportLibrary.js

@@ -2,6 +2,8 @@ import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
 
+import { Environment } from '#core/configs/environment.js';
+
 /**
  * Library for MCP transport creation utilities
  * Pure utility - no dependencies on services or repositories
@@ -31,7 +33,7 @@ export function createTransport(serverConfig, serverName = null) {
   } = serverConfig;
 
   const env = {
-    ...process.env,
+    ...Environment.getEnv(),
     ...configEnv,
   };
 

package/core/mcp-server/auditor/audit.js

@@ -226,14 +226,13 @@ export async function withAuditRequestResponseHandler(
 
   // Extract response body as string
   const resBodyStr = resBuf.toString('utf8');
-  const resBodyJson = parseJsonSafely(resBodyStr);
 
   const jsonrpcId = reqJsonRpc?.payload?.id !== undefined ? String(reqJsonRpc.payload.id) : null;
 
   auditLogger.logResponsePacket({
     statusCode: wrappedRes.statusCode || 200,
     headers: resHeaders,
-    body: resBodyJson || resBodyStr,
+    body: resBodyStr,
     requestFrameNumber: requestResult?.frameNumber || null,
     requestTimestampNs: requestResult?.timestampNs || null,
     jsonrpcId,

package/core/mcp-server/index.js

@@ -11,6 +11,7 @@ import {
   getMcpConfigPath,
   prepareAppDataSpaces,
 } from '#core/configs/index.js';
+import { Defaults } from '#core/constants/Defaults.js';
 import { initDb } from '#core/db/init.js';
 import { withAuditRequestResponseHandler } from './auditor/audit.js';
 import { getInternalServer } from './server/internal/run.js';
@@ -114,25 +115,27 @@ function createServerPromise(httpServer, port, serverLogger, onError, onReady) {
  * @param {number} [options.port=9851] - Port to listen on
  * @param {Function} [options.onError] - Error callback
  * @param {Function} [options.onReady] - Ready callback
+ * @param {Function} [options.onLog] - Log callback: (type: string, message: string) => void
  * @param {Object} options.auditLogger - Required audit logger instance (use initAuditLogger() to create)
  * @returns {Promise<{app: Express, server: http.Server, stop: Function}>} Server instance
  */
 export async function startMcpSharkServer(options = {}) {
   const {
     configPath = getMcpConfigPath(),
-    port = 9851,
+    port = Defaults.DEFAULT_MCP_SERVER_PORT,
     onError,
     onReady,
+    onLog,
     auditLogger: providedAuditLogger,
   } = options;
 
   prepareAppDataSpaces();
 
-  serverLogger.info('[MCP-Shark] Starting MCP server...');
-  serverLogger.info(`[MCP-Shark] Config path: ${configPath}`);
-  serverLogger.info(`[MCP-Shark] Database path: ${getDatabaseFile()}`);
-  serverLogger.info(`[MCP-Shark] Working directory: ${process.cwd()}`);
-  serverLogger.info({ path: Environment.getPath() }, '[MCP-Shark] PATH');
+  logServerInfo(serverLogger, onLog, 'Starting MCP server...', { port });
+  logServerInfo(serverLogger, onLog, 'Config path', { path: configPath });
+  logServerInfo(serverLogger, onLog, 'Database path', { path: getDatabaseFile() });
+  logServerInfo(serverLogger, onLog, 'Working directory', { path: process.cwd() });
+  logServerInfo(serverLogger, onLog, 'PATH', { path: Environment.getPath() });
 
   try {
     if (!providedAuditLogger) {
@@ -190,3 +193,16 @@ export async function startMcpSharkServer(options = {}) {
     throw error;
   }
 }
+
+function logServerInfo(serverLogger, onLog, message, metadata) {
+  const finalMessage = `[MCP Server] ${message}`;
+  serverLogger.info({ ...metadata, message: finalMessage }, finalMessage);
+  if (onLog) {
+    onLog(
+      'stdout',
+      `${finalMessage} ${Object.entries(metadata)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(' ')}`
+    );
+  }
+}

package/core/mcp-server/server/external/single/transport.js

@@ -2,8 +2,8 @@ import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
 
+import { Environment } from '#core/configs/environment.js';
 import { CompositeError } from '#core/libraries/ErrorLibrary.js';
-
 export class TransportError extends CompositeError {
   constructor(message, error) {
     super('TransportError', message, error);
@@ -20,7 +20,7 @@ export function makeTransport({
 }) {
   // Start with enhanced PATH
   const env = {
-    ...process.env,
+    ...Environment.getEnv(),
     ...configEnv,
   };
 

package/core/repositories/AuditRepository.js

@@ -69,17 +69,68 @@ export class AuditRepository {
     return `${statusCode}${rpcInfo}`;
   }
 
+  _isCharacterCodeObject(obj) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+      return false;
+    }
+
+    const keys = Object.keys(obj);
+    if (keys.length === 0) {
+      return false;
+    }
+
+    // Check if all keys are numeric strings starting from "0"
+    for (let i = 0; i < keys.length; i++) {
+      if (keys[i] !== String(i)) {
+        return false;
+      }
+      // Check if values are numbers (character codes)
+      if (typeof obj[keys[i]] !== 'number') {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  _convertCharacterCodeObjectToString(obj) {
+    const chars = [];
+    const keys = Object.keys(obj).sort((a, b) => Number(a) - Number(b));
+    for (const key of keys) {
+      chars.push(String.fromCharCode(obj[key]));
+    }
+    return chars.join('');
+  }
+
   _normalizeBody(body) {
     if (!body) {
       return { bodyRaw: '', bodyJson: null };
     }
+
+    // Handle String objects (created with new String())
+    if (Object.prototype.toString.call(body) === '[object String]') {
+      const str = String(body);
+      return { bodyRaw: str, bodyJson: str };
+    }
+
+    // Handle primitive strings
     if (typeof body === 'string') {
       return { bodyRaw: body, bodyJson: body };
     }
+
+    // Handle objects
     if (typeof body === 'object') {
+      // Check if it's a character code object and convert it back to string
+      if (this._isCharacterCodeObject(body)) {
+        const str = this._convertCharacterCodeObjectToString(body);
+        return { bodyRaw: str, bodyJson: str };
+      }
+
+      // Otherwise, stringify normally
       const raw = JSON.stringify(body);
       return { bodyRaw: raw, bodyJson: raw };
     }
+
     return { bodyRaw: '', bodyJson: null };
   }
 

package/core/repositories/StatisticsRepository.js

@@ -38,7 +38,7 @@ export class StatisticsRepository {
         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(CASE WHEN status_code >= ${StatusCodeRanges.CLIENT_ERROR_MIN} THEN 1 END) as total_errors,
         COUNT(DISTINCT session_id) as unique_sessions,
         AVG(length) as avg_packet_size,
         SUM(length) as total_bytes,

package/core/services/ConfigDetectionService.js

@@ -1,7 +1,11 @@
 import * as fs from 'node:fs';
 import { homedir } from 'node:os';
 import * as path from 'node:path';
-import { getCodexConfigPath } from '#core/configs/index.js';
+import { Environment } from '#core/configs/environment.js';
+
+const cursorDefaultPath = path.join(homedir(), '.cursor', 'mcp.json');
+const windsurfDefaultPath = path.join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+const codexDefaultPath = path.join(homedir(), '.codex', 'config.toml');
 
 /**
  * Service for detecting configuration files on the system
@@ -16,16 +20,24 @@ export class ConfigDetectionService {
     const platform = process.platform;
 
     const cursorPaths = [
-      path.join(homeDir, '.cursor', 'mcp.json'),
+      cursorDefaultPath,
       ...(platform === 'win32'
-        ? [path.join(process.env.USERPROFILE || '', '.cursor', 'mcp.json')]
+        ? [path.join(Environment.getUserProfile(), '.cursor', 'mcp.json')]
         : []),
     ];
 
     const windsurfPaths = [
-      path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json'),
+      windsurfDefaultPath,
+      ...(platform === 'win32'
+        ? [path.join(Environment.getUserProfile(), '.codeium', 'windsurf', 'mcp_config.json')]
+        : []),
+    ];
+
+    const codexPaths = [
+      codexDefaultPath,
+      path.join(Environment.getCodexHome(), 'config.toml'),
       ...(platform === 'win32'
-        ? [path.join(process.env.USERPROFILE || '', '.codeium', 'windsurf', 'mcp_config.json')]
+        ? [path.join(Environment.getUserProfile(), '.codex', 'config.toml')]
         : []),
     ];
 
@@ -53,34 +65,35 @@ export class ConfigDetectionService {
       }
     }
 
-    const codexPath = getCodexConfigPath();
-    if (fs.existsSync(codexPath)) {
-      detected.push({
-        editor: 'Codex',
-        path: codexPath,
-        displayPath: codexPath.replace(homeDir, '~'),
-        exists: true,
-      });
+    for (const codexPath of codexPaths) {
+      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')),
+        path: cursorDefaultPath.replace(homeDir, '~'),
+        displayPath: cursorDefaultPath.replace(homeDir, '~'),
+        exists: fs.existsSync(cursorDefaultPath),
       },
       {
         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')),
+        path: windsurfDefaultPath.replace(homeDir, '~'),
+        displayPath: windsurfDefaultPath.replace(homeDir, '~'),
+        exists: fs.existsSync(windsurfDefaultPath),
       },
       {
         editor: 'Codex',
-        path: codexPath,
-        displayPath: codexPath.replace(homeDir, '~'),
-        exists: fs.existsSync(codexPath),
+        path: codexDefaultPath.replace(homeDir, '~'),
+        displayPath: codexDefaultPath.replace(homeDir, '~'),
+        exists: fs.existsSync(codexDefaultPath),
       },
     ];
 

package/core/services/ServerManagementService.js

@@ -1,3 +1,4 @@
+import { Defaults } from '#core/constants/Defaults.js';
 import { initAuditLogger, startMcpSharkServer } from '#core/mcp-server/index.js';
 
 /**
@@ -19,13 +20,21 @@ export class ServerManagementService {
    * @param {string} [options.filePath] - Path to config file
    * @param {string} [options.fileContent] - Config file content
    * @param {Array} [options.selectedServices] - Selected services to include
-   * @param {number} [options.port=9851] - Server port
+   * @param {number} [options.port=Defaults.DEFAULT_MCP_SERVER_PORT] - Server port
    * @param {Function} [options.onError] - Error callback
    * @param {Function} [options.onReady] - Ready callback
    * @returns {Promise<Object>} Setup result with convertedConfig, updatedConfig, filePath
    */
   async setup(options = {}) {
-    const { filePath, fileContent, selectedServices, port = 9851, onError, onReady } = options;
+    const {
+      filePath,
+      fileContent,
+      selectedServices,
+      port = Defaults.DEFAULT_MCP_SERVER_PORT,
+      onError,
+      onReady,
+      onLog,
+    } = options;
 
     if (!filePath && !fileContent) {
       return {
@@ -63,6 +72,7 @@ export class ServerManagementService {
     await this.startServer({
       configPath: mcpsJsonPath,
       port,
+      onLog,
       onError: (err) => {
         if (onError) {
           onError(err);
@@ -98,7 +108,13 @@ export class ServerManagementService {
    * Start MCP Shark server
    */
   async startServer(options = {}) {
-    const { configPath, port = 9851, onError, onReady } = options;
+    const {
+      configPath,
+      port = Defaults.DEFAULT_MCP_SERVER_PORT,
+      onError,
+      onReady,
+      onLog,
+    } = options;
 
     const mcpsJsonPath = configPath || this.configService.getMcpConfigPath();
 
@@ -114,8 +130,13 @@ export class ServerManagementService {
       configPath: mcpsJsonPath,
       port,
       auditLogger,
+      logger: this.logger,
+      onLog,
       onError: (err) => {
-        this.logger?.error({ error: err.message }, 'Failed to start mcp-shark server');
+        this.logger?.error(
+          { message: err.message, stack: err.stack, error: err },
+          'Failed to start mcp-shark server'
+        );
         this.serverInstance = null;
         if (onError) {
           onError(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-shark/mcp-shark",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "description": "Aggregate multiple Model Context Protocol (MCP) servers into a single unified interface with a powerful monitoring UI. Prov deep visibility into every request and response.",
   "type": "module",
   "main": "./bin/mcp-shark.js",
@@ -25,13 +25,26 @@
   "bugs": {
     "url": "https://github.com/mcp-shark/mcp-shark/issues"
   },
-  "files": ["bin", "ui", "core", "README.md", "LICENSE", "package.json"],
+  "files": [
+    "bin",
+    "ui",
+    "core",
+    "!**/__tests__",
+    "!**/*.test.js",
+    "!**/*.spec.js",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
   "scripts": {
     "start": "node scripts/start-ui.js",
     "predev": "npm run build:ui",
     "dev": "node scripts/start-ui.js",
     "build": "bash -c 'cd ui && vite build'",
     "build:ui": "bash -c 'cd ui && vite build'",
+    "test": "c8 node --test --test-name-pattern='.*' --test-reporter spec $(find core ui/server -path '*/__tests__/*.test.js' -type f)",
+    "test:ui": "vitest run --coverage",
+    "test:all": "npm run test:coverage && npm run test:ui",
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
     "format": "biome format --write .",
@@ -46,7 +59,7 @@
     "publish:dry-run": "npm publish --dry-run"
   },
   "lint-staged": {
-    "*": ["biome check --write"]
+    "*.{js,jsx,ts,tsx,json}": ["biome check --write"]
   },
   "keywords": [
     "mcp",
@@ -93,9 +106,21 @@
     "@biomejs/biome": "^1.9.4",
     "@commitlint/cli": "^19.5.0",
     "@commitlint/config-conventional": "^19.5.0",
+    "@testing-library/jest-dom": "^6.4.0",
+    "@testing-library/react": "^16.0.0",
     "@vitejs/plugin-react": "^4.2.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "c8": "^10.1.2",
     "husky": "^9.1.6",
+    "jsdom": "^25.0.0",
     "lint-staged": "^15.2.10",
-    "vite": "^7.3.0"
+    "vite": "^7.3.0",
+    "vitest": "^4.0.18"
+  },
+  "c8": {
+    "include": ["core/**/*.js", "ui/server/**/*.js"],
+    "exclude": ["**/__tests__/**", "**/*.test.js", "**/index.js"],
+    "reporter": ["text", "html"],
+    "check-coverage": false
   }
 }