@mcp-shark/mcp-shark 1.4.0

package/ui/src/utils/groupingUtils.js

@@ -0,0 +1,93 @@
+import { extractServerName } from './requestUtils.js';
+
+export function groupByServerAndSession(requests) {
+  const serverGroups = new Map();
+
+  requests.forEach((request) => {
+    const sessionId = request.session_id || '__NO_SESSION__';
+    const serverName = extractServerName(request);
+
+    if (!serverGroups.has(serverName)) {
+      serverGroups.set(serverName, new Map());
+    }
+
+    const sessionGroups = serverGroups.get(serverName);
+    if (!sessionGroups.has(sessionId)) {
+      sessionGroups.set(sessionId, []);
+    }
+
+    sessionGroups.get(sessionId).push(request);
+  });
+
+  return Array.from(serverGroups.entries())
+    .map(([serverName, sessionGroups]) => {
+      const sessions = Array.from(sessionGroups.entries())
+        .map(([sessionId, groupRequests]) => ({
+          sessionId: sessionId === '__NO_SESSION__' ? null : sessionId,
+          requests: groupRequests.sort(
+            (a, b) => new Date(a.timestamp_iso) - new Date(b.timestamp_iso)
+          ),
+        }))
+        .sort((a, b) => {
+          const aTime = a.requests[0]?.timestamp_iso || '';
+          const bTime = b.requests[0]?.timestamp_iso || '';
+          return new Date(aTime) - new Date(bTime);
+        });
+
+      return {
+        serverName: serverName === '__UNKNOWN_SERVER__' ? null : serverName,
+        sessions,
+      };
+    })
+    .sort((a, b) => {
+      const aTime = a.sessions[0]?.requests[0]?.timestamp_iso || '';
+      const bTime = b.sessions[0]?.requests[0]?.timestamp_iso || '';
+      return new Date(bTime) - new Date(aTime);
+    });
+}
+
+export function groupBySessionAndServer(requests) {
+  const sessionGroups = new Map();
+
+  requests.forEach((request) => {
+    const sessionId = request.session_id || '__NO_SESSION__';
+    const serverName = extractServerName(request);
+
+    if (!sessionGroups.has(sessionId)) {
+      sessionGroups.set(sessionId, new Map());
+    }
+
+    const serverGroups = sessionGroups.get(sessionId);
+    if (!serverGroups.has(serverName)) {
+      serverGroups.set(serverName, []);
+    }
+
+    serverGroups.get(serverName).push(request);
+  });
+
+  return Array.from(sessionGroups.entries())
+    .map(([sessionId, serverGroups]) => {
+      const servers = Array.from(serverGroups.entries())
+        .map(([serverName, groupRequests]) => ({
+          serverName: serverName === '__UNKNOWN_SERVER__' ? null : serverName,
+          requests: groupRequests.sort(
+            (a, b) => new Date(a.timestamp_iso) - new Date(b.timestamp_iso)
+          ),
+        }))
+        .sort((a, b) => {
+          const aTime = a.requests[0]?.timestamp_iso || '';
+          const bTime = b.requests[0]?.timestamp_iso || '';
+          return new Date(aTime) - new Date(bTime);
+        });
+
+      return {
+        sessionId: sessionId === '__NO_SESSION__' ? null : sessionId,
+        servers,
+      };
+    })
+    .sort((a, b) => {
+      const aTime = a.servers[0]?.requests[0]?.timestamp_iso || '';
+      const bTime = b.servers[0]?.requests[0]?.timestamp_iso || '';
+      return new Date(bTime) - new Date(aTime);
+    });
+}

package/ui/src/utils/hexUtils.js

@@ -0,0 +1,24 @@
+export function generateHexDump(text) {
+  if (!text) return [];
+  const bytes = new TextEncoder().encode(text);
+  const lines = [];
+  for (let i = 0; i < bytes.length; i += 16) {
+    const chunk = bytes.slice(i, i + 16);
+    const hex = Array.from(chunk)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join(' ');
+    const ascii = Array.from(chunk)
+      .map((b) => (b >= 32 && b < 127 ? String.fromCharCode(b) : '.'))
+      .join('');
+    const offset = i.toString(16).padStart(8, '0');
+    lines.push({ offset, hex, ascii });
+  }
+  return lines;
+}
+
+export function createFullRequestText(headers, bodyRaw) {
+  const headersText = Object.entries(headers)
+    .map(([key, value]) => `${key}: ${value}`)
+    .join('\r\n');
+  return headersText + (bodyRaw ? '\r\n\r\n' + bodyRaw : '');
+}

package/ui/src/utils/mcpGroupingUtils.js

@@ -0,0 +1,262 @@
+import { pairRequestsWithResponses } from './requestUtils.js';
+import {
+  IconRefresh,
+  IconTool,
+  IconDatabase,
+  IconMessage,
+  IconBell,
+  IconUser,
+  IconPackage,
+} from '@tabler/icons-react';
+
+/**
+ * MCP Method Categories based on the protocol specification
+ * Reference: https://modelcontextprotocol.io/docs/learn/architecture
+ */
+export const MCP_METHOD_CATEGORIES = {
+  LIFECYCLE: 'lifecycle',
+  TOOLS: 'tools',
+  RESOURCES: 'resources',
+  PROMPTS: 'prompts',
+  NOTIFICATIONS: 'notifications',
+  CLIENT_FEATURES: 'client-features',
+  OTHER: 'other',
+};
+
+/**
+ * Categorize an MCP method into its protocol category
+ */
+export function categorizeMcpMethod(method) {
+  if (!method) return MCP_METHOD_CATEGORIES.OTHER;
+
+  // Lifecycle methods
+  if (method === 'initialize' || method === 'notifications/initialized') {
+    return MCP_METHOD_CATEGORIES.LIFECYCLE;
+  }
+
+  // Tools methods
+  if (method.startsWith('tools/')) {
+    return MCP_METHOD_CATEGORIES.TOOLS;
+  }
+
+  // Resources methods
+  if (method.startsWith('resources/')) {
+    return MCP_METHOD_CATEGORIES.RESOURCES;
+  }
+
+  // Prompts methods
+  if (method.startsWith('prompts/')) {
+    return MCP_METHOD_CATEGORIES.PROMPTS;
+  }
+
+  // Notifications (no response expected)
+  if (method.startsWith('notifications/')) {
+    return MCP_METHOD_CATEGORIES.NOTIFICATIONS;
+  }
+
+  // Client features
+  if (
+    method.startsWith('elicitation/') ||
+    method.startsWith('sampling/') ||
+    method.startsWith('logging/')
+  ) {
+    return MCP_METHOD_CATEGORIES.CLIENT_FEATURES;
+  }
+
+  return MCP_METHOD_CATEGORIES.OTHER;
+}
+
+/**
+ * Get a human-readable label for an MCP method category
+ */
+export function getCategoryLabel(category) {
+  const labels = {
+    [MCP_METHOD_CATEGORIES.LIFECYCLE]: 'Lifecycle',
+    [MCP_METHOD_CATEGORIES.TOOLS]: 'Tools',
+    [MCP_METHOD_CATEGORIES.RESOURCES]: 'Resources',
+    [MCP_METHOD_CATEGORIES.PROMPTS]: 'Prompts',
+    [MCP_METHOD_CATEGORIES.NOTIFICATIONS]: 'Notifications',
+    [MCP_METHOD_CATEGORIES.CLIENT_FEATURES]: 'Client Features',
+    [MCP_METHOD_CATEGORIES.OTHER]: 'Other',
+  };
+  return labels[category] || 'Unknown';
+}
+
+/**
+ * Get Tabler icon component for category (for visual grouping)
+ */
+export function getCategoryIconComponent(category) {
+  const iconMap = {
+    [MCP_METHOD_CATEGORIES.LIFECYCLE]: IconRefresh,
+    [MCP_METHOD_CATEGORIES.TOOLS]: IconTool,
+    [MCP_METHOD_CATEGORIES.RESOURCES]: IconDatabase,
+    [MCP_METHOD_CATEGORIES.PROMPTS]: IconMessage,
+    [MCP_METHOD_CATEGORIES.NOTIFICATIONS]: IconBell,
+    [MCP_METHOD_CATEGORIES.CLIENT_FEATURES]: IconUser,
+    [MCP_METHOD_CATEGORIES.OTHER]: IconPackage,
+  };
+
+  return iconMap[category] || IconPackage;
+}
+
+// Import getJsonRpcMethod from requestUtils instead of duplicating
+import { getJsonRpcMethod } from './requestUtils.js';
+
+/**
+ * Group requests by MCP session and method category
+ * This provides a view that shows the flow of MCP operations organized by protocol category
+ */
+export function groupByMcpSessionAndCategory(requests) {
+  const pairs = pairRequestsWithResponses(requests);
+  const sessionGroups = new Map();
+
+  pairs.forEach((pair) => {
+    const request = pair.request || pair.response;
+    if (!request) return;
+
+    const sessionId = request.session_id || '__NO_SESSION__';
+    const method = getJsonRpcMethod(request);
+    const category = categorizeMcpMethod(method || '');
+
+    if (!sessionGroups.has(sessionId)) {
+      sessionGroups.set(sessionId, {
+        sessionId: sessionId === '__NO_SESSION__' ? null : sessionId,
+        categories: new Map(),
+        firstTimestamp: request.timestamp_iso,
+      });
+    }
+
+    const session = sessionGroups.get(sessionId);
+    if (!session.categories.has(category)) {
+      session.categories.set(category, []);
+    }
+
+    session.categories.get(category).push(pair);
+
+    // Update first timestamp if earlier
+    if (new Date(request.timestamp_iso) < new Date(session.firstTimestamp)) {
+      session.firstTimestamp = request.timestamp_iso;
+    }
+  });
+
+  return Array.from(sessionGroups.entries())
+    .map(([sessionId, session]) => ({
+      sessionId: session.sessionId,
+      firstTimestamp: session.firstTimestamp,
+      categories: Array.from(session.categories.entries())
+        .map(([category, pairs]) => ({
+          category,
+          label: getCategoryLabel(category),
+          pairs: pairs.sort((a, b) => {
+            const aTime = (a.request || a.response)?.timestamp_iso || '';
+            const bTime = (b.request || b.response)?.timestamp_iso || '';
+            return new Date(aTime) - new Date(bTime);
+          }),
+        }))
+        .sort((a, b) => {
+          // Order: lifecycle first, then tools, resources, prompts, notifications, client features, other
+          const order = [
+            MCP_METHOD_CATEGORIES.LIFECYCLE,
+            MCP_METHOD_CATEGORIES.TOOLS,
+            MCP_METHOD_CATEGORIES.RESOURCES,
+            MCP_METHOD_CATEGORIES.PROMPTS,
+            MCP_METHOD_CATEGORIES.NOTIFICATIONS,
+            MCP_METHOD_CATEGORIES.CLIENT_FEATURES,
+            MCP_METHOD_CATEGORIES.OTHER,
+          ];
+          const aIndex = order.indexOf(a.category);
+          const bIndex = order.indexOf(b.category);
+          return aIndex - bIndex;
+        }),
+    }))
+    .sort((a, b) => new Date(b.firstTimestamp) - new Date(a.firstTimestamp));
+}
+
+/**
+ * Group requests by MCP method category (across all sessions)
+ * Useful for seeing all tool calls, all resource reads, etc.
+ */
+export function groupByMcpCategory(requests) {
+  const pairs = pairRequestsWithResponses(requests);
+  const categoryGroups = new Map();
+
+  pairs.forEach((pair) => {
+    const request = pair.request || pair.response;
+    if (!request) return;
+
+    const method = getJsonRpcMethod(request);
+    const category = categorizeMcpMethod(method || '');
+
+    if (!categoryGroups.has(category)) {
+      categoryGroups.set(category, []);
+    }
+
+    categoryGroups.get(category).push(pair);
+  });
+
+  return Array.from(categoryGroups.entries())
+    .map(([category, pairs]) => ({
+      category,
+      label: getCategoryLabel(category),
+      pairs: pairs.sort((a, b) => {
+        const aTime = (a.request || a.response)?.timestamp_iso || '';
+        const bTime = (b.request || b.response)?.timestamp_iso || '';
+        return new Date(bTime) - new Date(aTime);
+      }),
+    }))
+    .sort((a, b) => {
+      // Order: lifecycle first, then tools, resources, prompts, notifications, client features, other
+      const order = [
+        MCP_METHOD_CATEGORIES.LIFECYCLE,
+        MCP_METHOD_CATEGORIES.TOOLS,
+        MCP_METHOD_CATEGORIES.RESOURCES,
+        MCP_METHOD_CATEGORIES.PROMPTS,
+        MCP_METHOD_CATEGORIES.NOTIFICATIONS,
+        MCP_METHOD_CATEGORIES.CLIENT_FEATURES,
+        MCP_METHOD_CATEGORIES.OTHER,
+      ];
+      const aIndex = order.indexOf(a.category);
+      const bIndex = order.indexOf(b.category);
+      return aIndex - bIndex;
+    });
+}
+
+/**
+ * Get a short description of what an MCP method does
+ * Based on the protocol specification
+ */
+export function getMethodDescription(method) {
+  if (!method) return 'Unknown operation';
+
+  const descriptions = {
+    // Lifecycle
+    initialize: 'Initialize MCP connection and negotiate capabilities',
+    'notifications/initialized': 'Client ready notification after initialization',
+
+    // Tools
+    'tools/list': 'Discover available tools from server',
+    'tools/call': 'Execute a tool with arguments',
+
+    // Resources
+    'resources/list': 'List available direct resources',
+    'resources/templates/list': 'Discover resource templates',
+    'resources/read': 'Retrieve resource contents',
+    'resources/subscribe': 'Monitor resource changes',
+
+    // Prompts
+    'prompts/list': 'Discover available prompts',
+    'prompts/get': 'Retrieve prompt details',
+
+    // Notifications
+    'notifications/tools/list_changed': 'Server notifies client that tool list changed',
+    'notifications/resources/list_changed': 'Server notifies client that resource list changed',
+    'notifications/prompts/list_changed': 'Server notifies client that prompt list changed',
+
+    // Client features
+    'elicitation/request': 'Server requests information from user',
+    'sampling/complete': 'Server requests LLM completion from client',
+    'logging/message': 'Server sends log message to client',
+  };
+
+  return descriptions[method] || `${method} operation`;
+}

package/ui/src/utils/requestUtils.js

@@ -0,0 +1,297 @@
+export function extractServerName(request) {
+  if (request.body_json) {
+    try {
+      const body =
+        typeof request.body_json === 'string' ? JSON.parse(request.body_json) : request.body_json;
+      if (body.params && body.params.name) {
+        const fullName = body.params.name;
+        return fullName.includes('.') ? fullName.split('.')[0] : fullName;
+      }
+    } catch (e) {
+      // Failed to parse JSON, try body_raw
+    }
+  }
+
+  if (request.body_raw) {
+    try {
+      const body =
+        typeof request.body_raw === 'string' ? JSON.parse(request.body_raw) : request.body_raw;
+      if (body.params && body.params.name) {
+        const fullName = body.params.name;
+        return fullName.includes('.') ? fullName.split('.')[0] : fullName;
+      }
+    } catch (e) {
+      // Failed to parse
+    }
+  }
+
+  if (request.host) {
+    return request.host;
+  }
+
+  return '__UNKNOWN_SERVER__';
+}
+
+export function formatRelativeTime(timestampISO, firstTime) {
+  if (!firstTime) return '0.000000';
+  const diff = new Date(timestampISO) - new Date(firstTime);
+  return (diff / 1000).toFixed(6);
+}
+
+export function formatDateTime(timestampISO) {
+  if (!timestampISO) return '-';
+  try {
+    const date = new Date(timestampISO);
+    return date.toLocaleString('en-US', {
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+    });
+  } catch (e) {
+    return timestampISO;
+  }
+}
+
+export function getSourceDest(request) {
+  if (request.direction === 'request') {
+    return {
+      source: request.remote_address || 'Client',
+      dest: request.host || 'Server',
+    };
+  }
+  return {
+    source: request.host || 'Server',
+    dest: request.remote_address || 'Client',
+  };
+}
+
+export function getEndpoint(request) {
+  if (request.direction === 'request') {
+    if (request.body_json) {
+      try {
+        const body =
+          typeof request.body_json === 'string' ? JSON.parse(request.body_json) : request.body_json;
+        if (body && typeof body === 'object' && body.method) {
+          return body.method;
+        }
+      } catch (e) {
+        // Failed to parse JSON, try body_raw
+      }
+    }
+    if (request.body_raw) {
+      try {
+        const body =
+          typeof request.body_raw === 'string' ? JSON.parse(request.body_raw) : request.body_raw;
+        if (body && typeof body === 'object' && body.method) {
+          return body.method;
+        }
+      } catch (e) {
+        // Failed to parse
+      }
+    }
+    if (request.jsonrpc_method) {
+      return request.jsonrpc_method;
+    }
+    if (request.url) {
+      try {
+        const url = new URL(request.url);
+        return url.pathname + (url.search || '');
+      } catch (e) {
+        const url = request.url;
+        const match = url.match(/^https?:\/\/[^\/]+(\/.*)$/);
+        return match ? match[1] : url;
+      }
+    }
+  }
+  return '-';
+}
+
+export function getInfo(request) {
+  if (request.direction === 'request') {
+    // Use getEndpoint to get the method/endpoint (it already handles extraction from body)
+    const endpoint = getEndpoint(request);
+
+    // Get HTTP method if available
+    const httpMethod = request.method || '';
+
+    // Get URL if available
+    const url = request.url || '';
+
+    // Build info string - prioritize endpoint (JSON-RPC method), then HTTP method + URL, then just method
+    if (endpoint && endpoint !== '-') {
+      // If we have both HTTP method and endpoint, show both
+      if (httpMethod && url) {
+        return `${httpMethod} ${endpoint}`;
+      } else if (httpMethod) {
+        return `${httpMethod} ${endpoint}`;
+      }
+      return endpoint;
+    } else if (httpMethod && url) {
+      return `${httpMethod} ${url}`;
+    } else if (httpMethod) {
+      return httpMethod;
+    } else if (url) {
+      return url;
+    }
+    return 'Request';
+  }
+
+  // For responses
+  const status = request.status_code || '';
+
+  // Try to get JSON-RPC method if available
+  const rpcMethod = request.jsonrpc_method || getJsonRpcMethod(request);
+
+  if (status && rpcMethod) {
+    return `${status} ${rpcMethod}`;
+  } else if (status) {
+    return `Status: ${status}`;
+  } else if (rpcMethod) {
+    return rpcMethod;
+  }
+  return 'Response';
+}
+
+export function getRequestColor(request) {
+  if (request.direction === 'request') {
+    return '#faf9f7';
+  }
+  if (request.status_code >= 400) {
+    return '#fef0f0';
+  }
+  if (request.status_code >= 300) {
+    return '#fff8e8';
+  }
+  return '#f0f8f0';
+}
+
+// Helper function to extract JSON-RPC method from a request or response
+export function getJsonRpcMethod(req) {
+  // First check the jsonrpc_method field (most reliable)
+  if (req.jsonrpc_method) {
+    return req.jsonrpc_method;
+  }
+
+  // For requests, try to extract from body
+  if (req.direction === 'request') {
+    if (req.body_json) {
+      try {
+        const body = typeof req.body_json === 'string' ? JSON.parse(req.body_json) : req.body_json;
+        if (body && typeof body === 'object' && body.method) {
+          return body.method;
+        }
+      } catch (e) {
+        // Failed to parse
+      }
+    }
+    if (req.body_raw) {
+      try {
+        const body = typeof req.body_raw === 'string' ? JSON.parse(req.body_raw) : req.body_raw;
+        if (body && typeof body === 'object' && body.method) {
+          return body.method;
+        }
+      } catch (e) {
+        // Failed to parse
+      }
+    }
+  }
+
+  // For responses, try to extract from body if available
+  if (req.direction === 'response' && req.body_json) {
+    try {
+      const body = typeof req.body_json === 'string' ? JSON.parse(req.body_json) : req.body_json;
+      // Responses don't have a method field, but we can check if it's an error response
+      // For now, we'll rely on jsonrpc_method field
+    } catch (e) {
+      // Failed to parse
+    }
+  }
+
+  return null;
+}
+
+export function pairRequestsWithResponses(requests) {
+  const pairs = [];
+  const processed = new Set();
+
+  // Helper function to check if two requests match (same session, JSON-RPC method, and optionally jsonrpc_id)
+  const matches = (req, resp) => {
+    // Session ID must match (or both null for initiation)
+    const sessionMatch = req.session_id === resp.session_id;
+    if (!sessionMatch) return false;
+
+    // JSON-RPC Method must match
+    const reqMethod = getJsonRpcMethod(req);
+    const respMethod = getJsonRpcMethod(resp);
+
+    // Both must have a method, and they must match
+    if (!reqMethod || !respMethod) {
+      // If either doesn't have a method, we can't match by method
+      // Fall back to JSON-RPC ID matching only
+      if (req.jsonrpc_id && resp.jsonrpc_id) {
+        return req.jsonrpc_id === resp.jsonrpc_id;
+      }
+      // If no method and no ID, we can't match reliably
+      return false;
+    }
+
+    const methodMatch = reqMethod === respMethod;
+    if (!methodMatch) return false;
+
+    // If JSON-RPC ID exists, it must match (for more precise pairing)
+    if (req.jsonrpc_id && resp.jsonrpc_id) {
+      return req.jsonrpc_id === resp.jsonrpc_id;
+    }
+
+    // If no JSON-RPC ID, match by session and method only
+    return true;
+  };
+
+  requests.forEach((request) => {
+    if (processed.has(request.frame_number)) return;
+
+    if (request.direction === 'request') {
+      // Find matching response - must match session, endpoint, and optionally jsonrpc_id
+      const response = requests.find(
+        (r) =>
+          r.direction === 'response' &&
+          !processed.has(r.frame_number) &&
+          matches(request, r) &&
+          r.frame_number > request.frame_number
+      );
+
+      if (response) {
+        pairs.push({ request, response, frame_number: request.frame_number });
+        processed.add(request.frame_number);
+        processed.add(response.frame_number);
+      } else {
+        // Request without response
+        pairs.push({ request, response: null, frame_number: request.frame_number });
+        processed.add(request.frame_number);
+      }
+    } else if (request.direction === 'response') {
+      // Find matching request - must match session, endpoint, and optionally jsonrpc_id
+      const matchingRequest = requests.find(
+        (r) =>
+          r.direction === 'request' &&
+          !processed.has(r.frame_number) &&
+          matches(r, request) &&
+          r.frame_number < request.frame_number
+      );
+
+      if (!matchingRequest) {
+        // Response without request (orphaned)
+        pairs.push({ request: null, response: request, frame_number: request.frame_number });
+        processed.add(request.frame_number);
+      }
+      // If matching request exists, it will be handled when we iterate over it
+    }
+  });
+
+  // Sort by frame number (descending - latest first)
+  return pairs.sort((a, b) => b.frame_number - a.frame_number);
+}

package/ui/vite.config.js

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:9853',
+        changeOrigin: true,
+      },
+      '/ws': {
+        target: 'ws://localhost:9853',
+        ws: true,
+      },
+    },
+  },
+});