@mcp-shark/mcp-shark 1.6.0 → 1.7.2

package/core/mcp-server/server/external/config.js

@@ -4,6 +4,36 @@ import { ConfigParserFactory } from '#core/services/parsers/ConfigParserFactory.
 
 const DEFAULT_TYPE = 'stdio';
 
+// An upstream entry is considered a self-reference (and pruned) when:
+//   - its name is in this reserved set, OR
+//   - it is an HTTP entry whose host:port resolves to mcp-shark's own
+//     listening port. Including such an entry would loop the proxy back
+//     onto itself at startup and crash with RunAllExternalServersError.
+const RESERVED_UPSTREAM_NAMES = new Set(['mcp-shark']);
+
+function isSelfReferencingEntry(name, cfg, selfPort) {
+  if (RESERVED_UPSTREAM_NAMES.has(name)) {
+    return { selfRef: true, reason: `reserved name '${name}'` };
+  }
+  if (!selfPort || !cfg || typeof cfg.url !== 'string') {
+    return { selfRef: false };
+  }
+  let parsed;
+  try {
+    parsed = new URL(cfg.url);
+  } catch {
+    return { selfRef: false };
+  }
+  const port = Number.parseInt(parsed.port || (parsed.protocol === 'https:' ? '443' : '80'), 10);
+  if (port !== selfPort) return { selfRef: false };
+  const localHosts = new Set(['127.0.0.1', 'localhost', '0.0.0.0', '::1']);
+  if (!localHosts.has(parsed.hostname)) return { selfRef: false };
+  return {
+    selfRef: true,
+    reason: `URL ${parsed.hostname}:${port} points back at mcp-shark's own proxy`,
+  };
+}
+
 export class ConfigError extends CompositeError {
   constructor(message, error) {
     super('ConfigError', message, error);
@@ -37,7 +67,8 @@ function parseConfig(configPath) {
   }
 }
 
-export function normalizeConfig(configPath) {
+export function normalizeConfig(configPath, options = {}) {
+  const { selfPort, logger, allowEmpty = false } = options;
   const parsedConfigResult = parseConfig(configPath);
   if (isError(parsedConfigResult)) {
     return parsedConfigResult;
@@ -45,29 +76,55 @@ export function normalizeConfig(configPath) {
 
   const normalized = parserFactory.normalizeToInternalFormat(parsedConfigResult, configPath);
   if (!normalized) {
+    if (allowEmpty) return {};
     return new ConfigError('No servers found in config');
   }
 
   // Convert to flat map format expected by MCP server
   const out = new Map();
+  const pruned = [];
+
+  function addEntry(name, cfg) {
+    const { selfRef, reason } = isSelfReferencingEntry(name, cfg, selfPort);
+    if (selfRef) {
+      pruned.push({ name, reason });
+      return;
+    }
+    const type = cfg.type ?? DEFAULT_TYPE;
+    out.set(name, { type, ...cfg });
+  }
 
   // Handle normalized mcpServers format
   if (normalized.mcpServers) {
     for (const [name, cfg] of Object.entries(normalized.mcpServers)) {
-      const type = cfg.type ?? DEFAULT_TYPE;
-      out.set(name, { type, ...cfg });
+      addEntry(name, cfg);
     }
   }
 
   // Handle normalized servers format (legacy)
   if (normalized.servers) {
     for (const [name, cfg] of Object.entries(normalized.servers)) {
-      const type = cfg.type ?? DEFAULT_TYPE;
-      out.set(name, { type, ...cfg });
+      addEntry(name, cfg);
+    }
+  }
+
+  if (pruned.length > 0 && logger?.warn) {
+    for (const { name, reason } of pruned) {
+      logger.warn(
+        { upstream: name, reason },
+        `[MCP-Shark] Skipping self-referencing upstream '${name}': ${reason}`
+      );
     }
   }
 
   if (out.size === 0) {
+    if (allowEmpty) {
+      logger?.warn?.(
+        { configPath },
+        '[MCP-Shark] No upstream MCP servers configured — running in monitoring-only mode'
+      );
+      return {};
+    }
     return new ConfigError('No servers found in config');
   }
 

package/core/models/RequestFilters.js

@@ -19,6 +19,9 @@ export class RequestFilters {
     this.limit = data.limit !== undefined ? Number.parseInt(data.limit) : Defaults.DEFAULT_LIMIT;
     this.offset =
       data.offset !== undefined ? Number.parseInt(data.offset) : Defaults.DEFAULT_OFFSET;
+    this.aauthPosture = data.aauthPosture || null;
+    this.aauthAgent = data.aauthAgent || null;
+    this.aauthMission = data.aauthMission || null;
   }
 
   /**

package/core/services/ConfigService.js

@@ -201,7 +201,15 @@ export class ConfigService {
         ? this.transformService.filterServers(baseConvertedConfig, selectedServices)
         : baseConvertedConfig;
 
-    if (Object.keys(convertedConfig.servers || {}).length === 0) {
+    // A zero-upstream config is a legitimate state (monitoring-only mode):
+    // mcp-shark still runs the audit/UI/AAuth surfaces, just without any
+    // upstreams to forward to. We only fail here if the *original* config
+    // file declared no servers at all (different from "all servers were
+    // self-references and got filtered out").
+    const originalHadAnyServer =
+      Object.keys(originalConfig.mcpServers || {}).length > 0 ||
+      Object.keys(originalConfig.servers || {}).length > 0;
+    if (!originalHadAnyServer) {
       return {
         success: false,
         error: 'No servers found in config',

package/core/services/ConfigTransformService.js

@@ -1,3 +1,29 @@
+// mcp-shark must never appear as an upstream of itself. The UI reads the
+// user's editor MCP config (e.g. ~/.cursor/mcp.json) — which legitimately
+// contains an `mcp-shark` entry pointing at the proxy port so the editor
+// routes calls through us — and copies it into ~/.mcp-shark/mcps.json as
+// the proxy's upstream list. Without this filter the proxy ends up with a
+// recursive self-reference that crashes startup.
+const RESERVED_PROXY_NAMES = new Set(['mcp-shark']);
+function isProxySelfReference(name, cfg) {
+  if (RESERVED_PROXY_NAMES.has(name)) return true;
+  if (!cfg || typeof cfg.url !== 'string') return false;
+  let parsed;
+  try {
+    parsed = new URL(cfg.url);
+  } catch {
+    return false;
+  }
+  const localHosts = new Set(['127.0.0.1', 'localhost', '0.0.0.0', '::1']);
+  if (!localHosts.has(parsed.hostname)) return false;
+  const port = Number.parseInt(parsed.port || (parsed.protocol === 'https:' ? '443' : '80'), 10);
+  // We don't have access to the runtime port here; the proxy default is
+  // 9851 and the UI always starts it on that port unless overridden via
+  // env. If the user runs on a different port they can still safely include
+  // a custom-named entry; the runtime config.js layer will catch true loops.
+  return port === 9851;
+}
+
 /**
  * Service for configuration transformations
  * Handles converting, filtering, and updating config structures
@@ -9,7 +35,9 @@ export class ConfigTransformService {
 
   /**
    * Convert MCP servers format to servers format
-   * Normalizes config first, then converts mcpServers to servers
+   * Normalizes config first, then converts mcpServers to servers.
+   * Self-referencing entries (mcp-shark itself) are dropped — they would
+   * create an infinite proxy loop if written to ~/.mcp-shark/mcps.json.
    */
   convertMcpServersToServers(config) {
     // Normalize config to ensure consistent format
@@ -22,12 +50,16 @@ export class ConfigTransformService {
 
     // Handle normalized servers (legacy format)
     if (normalized.servers) {
-      converted.servers = { ...normalized.servers };
+      for (const [name, cfg] of Object.entries(normalized.servers)) {
+        if (isProxySelfReference(name, cfg)) continue;
+        converted.servers[name] = cfg;
+      }
     }
 
     // Convert mcpServers to servers format
     if (normalized.mcpServers) {
       for (const [name, cfg] of Object.entries(normalized.mcpServers)) {
+        if (isProxySelfReference(name, cfg)) continue;
         const type = cfg.type || (cfg.url ? 'http' : cfg.command ? 'stdio' : 'stdio');
         converted.servers[name] = { type, ...cfg };
       }

package/core/services/RequestService.js

@@ -5,6 +5,53 @@ import { Defaults } from '../constants/Defaults.js';
  * HTTP-agnostic: accepts models, returns models
  */
 import { RequestFilters } from '../models/RequestFilters.js';
+import { parseAauthForPacket } from './security/aauthParser.js';
+
+/**
+ * Attach an `aauth` field to a packet record by parsing its headers_json.
+ * Pure function; no DB writes. Always returns a new object.
+ */
+function enrichWithAauth(packet) {
+  if (!packet) {
+    return packet;
+  }
+  try {
+    return { ...packet, aauth: parseAauthForPacket(packet) };
+  } catch {
+    return packet;
+  }
+}
+
+/**
+ * Filter a list of packets according to AAuth-derived filters that are not
+ * supported by the repository (which only knows about DB columns).
+ */
+function applyAauthFilters(packets, filters) {
+  if (!filters) {
+    return packets;
+  }
+  const { aauthPosture = null, aauthAgent = null, aauthMission = null } = filters;
+  if (!aauthPosture && !aauthAgent && !aauthMission) {
+    return packets;
+  }
+
+  return packets.filter((p) => {
+    const aauth = p?.aauth;
+    if (!aauth) {
+      return false;
+    }
+    if (aauthPosture && aauth.posture !== aauthPosture) {
+      return false;
+    }
+    if (aauthAgent && aauth.agent !== aauthAgent) {
+      return false;
+    }
+    if (aauthMission && aauth.mission !== aauthMission) {
+      return false;
+    }
+    return true;
+  });
+}
 
 export class RequestService {
   constructor(packetRepository) {
@@ -14,21 +61,27 @@ export class RequestService {
   /**
    * Get requests with filters
    * @param {RequestFilters} filters - Typed filter model
-   * @returns {Array} Array of packet objects (raw from repository)
+   * @returns {Array} Array of packet objects, each enriched with an `aauth` block.
    */
   getRequests(filters) {
     const repoFilters = filters.toRepositoryFilters();
-    return this.packetRepository.queryRequests(repoFilters);
+    const rows = this.packetRepository.queryRequests(repoFilters);
+    const enriched = rows.map(enrichWithAauth);
+    return applyAauthFilters(enriched, {
+      aauthPosture: filters.aauthPosture,
+      aauthAgent: filters.aauthAgent,
+      aauthMission: filters.aauthMission,
+    });
   }
 
   /**
    * Get request by frame number
    * @param {number} frameNumber - Frame number
-   * @returns {Object|null} Packet object or null if not found
+   * @returns {Object|null} Packet object enriched with an `aauth` block, or null.
    */
   getRequest(frameNumber) {
     const parsedFrameNumber = Number.parseInt(frameNumber);
-    return this.packetRepository.getByFrameNumber(parsedFrameNumber);
+    return enrichWithAauth(this.packetRepository.getByFrameNumber(parsedFrameNumber));
   }
 
   /**
@@ -51,6 +104,6 @@ export class RequestService {
       offset: Defaults.DEFAULT_OFFSET,
     });
     const repoFilters = exportFilters.toRepositoryFilters();
-    return this.packetRepository.queryRequests(repoFilters);
+    return this.packetRepository.queryRequests(repoFilters).map(enrichWithAauth);
   }
 }

package/core/services/ServerManagementService.js

@@ -1,6 +1,17 @@
+import path from 'node:path';
+
 import { Defaults } from '#core/constants/Defaults.js';
 import { initAuditLogger, startMcpSharkServer } from '#core/mcp-server/index.js';
 
+function isSamePath(a, b) {
+  if (!a || !b) return false;
+  try {
+    return path.resolve(a) === path.resolve(b);
+  } catch {
+    return a === b;
+  }
+}
+
 /**
  * Service for managing MCP Shark server lifecycle
  * Handles server startup, shutdown, and status
@@ -60,8 +71,34 @@ export class ServerManagementService {
     const { fileData, convertedConfig, updatedConfig } = setupResult;
     const mcpsJsonPath = this.configService.getMcpConfigPath();
 
-    // Write converted config to MCP Shark config path
-    this.configService.writeConfigAsJson(mcpsJsonPath, convertedConfig);
+    // The user can legitimately point the Setup panel at the proxy's own
+    // config file (~/.mcp-shark/mcps.json) when they just want to (re)start
+    // the proxy with whatever is already there — for example after
+    // `npm run testbed:up` has written upstreams directly. In that case the
+    // input *is* the output and the "patch the editor config" step at the
+    // end would rewrite every upstream URL into the proxy-local form
+    // (http://localhost:9851/mcp/<name>), turning mcps.json into a
+    // self-referential file that the next startup has to strip.
+    const sourceIsProxyConfig = isSamePath(fileData.resolvedFilePath, mcpsJsonPath);
+
+    // If the conversion produced zero upstreams (e.g. the user picked an
+    // already-patched ~/.cursor/mcp.json that only contains the mcp-shark
+    // self-reference, and no backup was available to restore), don't blow
+    // away whatever the proxy already has. A healthy existing mcps.json is
+    // strictly more useful than an empty new one.
+    const convertedUpstreamCount = Object.keys(convertedConfig?.servers || {}).length;
+    const existingHasUpstreams = this._existingMcpsHasUpstreams(mcpsJsonPath);
+    const skipWriteToPreserveExisting =
+      convertedUpstreamCount === 0 && existingHasUpstreams && !sourceIsProxyConfig;
+
+    if (skipWriteToPreserveExisting) {
+      this.logger?.warn(
+        { path: mcpsJsonPath, source: fileData.resolvedFilePath },
+        'Conversion yielded zero upstreams; preserving existing mcps.json instead of overwriting'
+      );
+    } else {
+      this.configService.writeConfigAsJson(mcpsJsonPath, convertedConfig);
+    }
 
     // Stop existing server if running
     if (this.serverInstance?.stop) {
@@ -86,9 +123,13 @@ export class ServerManagementService {
       },
     });
 
-    // Patch the original config file if it exists
+    // Patch the original config file if it exists. Skip this when the
+    // source IS our own proxy config — patching it would corrupt the
+    // upstream list we just wrote.
     const patchWarning =
-      fileData.resolvedFilePath && this.configService.fileExists(fileData.resolvedFilePath)
+      fileData.resolvedFilePath &&
+      this.configService.fileExists(fileData.resolvedFilePath) &&
+      !sourceIsProxyConfig
         ? this.configPatchingService.patchConfigFile(fileData.resolvedFilePath, updatedConfig)
             .warning || null
         : null;
@@ -104,6 +145,20 @@ export class ServerManagementService {
     };
   }
 
+  _existingMcpsHasUpstreams(mcpsJsonPath) {
+    try {
+      if (!this.configService.fileExists(mcpsJsonPath)) return false;
+      const content = this.configService.readConfigFile(mcpsJsonPath);
+      const parsed = this.configService.tryParseJson(content, mcpsJsonPath);
+      if (!parsed) return false;
+      const count =
+        Object.keys(parsed.servers || {}).length + Object.keys(parsed.mcpServers || {}).length;
+      return count > 0;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Start MCP Shark server
    */

package/core/services/security/aauthGraph.js

@@ -0,0 +1,199 @@
+/**
+ * AAuth knowledge-graph builder.
+ *
+ * Walks the captured packets, extracts AAuth signals via aauthParser, and
+ * shapes a node/edge graph that mirrors the categories on
+ * https://mcp-shark.github.io/aauth-explorer/ — but every node here is
+ * grounded in observed traffic, not a static spec illustration.
+ *
+ * Categories (kept stable so the UI can color-code them):
+ *   - agent     — observed AAuth-Agent values
+ *   - mission   — observed AAuth-Mission values
+ *   - resource  — destination host/server names
+ *   - signing   — algorithms parsed from Signature-Input (`alg=...`)
+ *   - access    — access modes parsed from AAuth-Requirement (`mode=...`)
+ *
+ * Edges are weighted by observed packet count so the force layout settles
+ * naturally around the busiest nodes.
+ */
+
+import { parseAauthForPacket } from './aauthParser.js';
+
+const ACCESS_MODE_REGEX = /mode\s*=\s*"?([A-Za-z0-9_-]+)"?/i;
+
+function nodeKey(category, id) {
+  return `${category}::${id}`;
+}
+
+function ensureNode(map, category, id, extra = {}) {
+  const key = nodeKey(category, id);
+  if (!map.has(key)) {
+    map.set(key, {
+      id: key,
+      name: id,
+      category,
+      packet_count: 0,
+      sample_frame_numbers: [],
+      ...extra,
+    });
+  }
+  return map.get(key);
+}
+
+function bumpNode(node, frameNumber) {
+  node.packet_count += 1;
+  if (frameNumber != null && node.sample_frame_numbers.length < 5) {
+    node.sample_frame_numbers.push(frameNumber);
+  }
+}
+
+function ensureEdge(map, sourceKey, targetKey, kind) {
+  const key = `${sourceKey}->${targetKey}::${kind}`;
+  if (!map.has(key)) {
+    map.set(key, { id: key, source: sourceKey, target: targetKey, kind, weight: 0 });
+  }
+  return map.get(key);
+}
+
+function bumpEdge(edge) {
+  edge.weight += 1;
+}
+
+function extractAccessMode(requirement) {
+  if (!requirement || typeof requirement !== 'string') {
+    return null;
+  }
+  const m = requirement.match(ACCESS_MODE_REGEX);
+  return m ? m[1] : null;
+}
+
+function extractResource(packet) {
+  const host = packet?.host || packet?.remote_address || null;
+  if (host) {
+    return host;
+  }
+  const url = packet?.url;
+  if (typeof url === 'string') {
+    try {
+      return new URL(url).host;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Build an AAuth knowledge graph from a list of packets.
+ *
+ * @param {Array} packets - packets as returned by RequestService.getRequests
+ * @returns {{
+ *   categories: Array<{id:string,label:string}>,
+ *   nodes: Array,
+ *   edges: Array,
+ *   stats: object,
+ * }}
+ */
+export function buildAauthGraph(packets) {
+  const nodes = new Map();
+  const edges = new Map();
+
+  let observedSignals = 0;
+
+  for (const packet of packets || []) {
+    const aauth = parseAauthForPacket(packet);
+    const hasAnySignal =
+      aauth.posture !== 'none' ||
+      aauth.agent ||
+      aauth.mission ||
+      aauth.requirement ||
+      aauth.sig_alg;
+    if (!hasAnySignal) {
+      continue;
+    }
+    observedSignals += 1;
+
+    const resourceId = extractResource(packet);
+    const frame = packet?.frame_number ?? null;
+
+    const resourceNode = resourceId
+      ? ensureNode(nodes, 'resource', resourceId, { url: packet?.url || null })
+      : null;
+    if (resourceNode) {
+      bumpNode(resourceNode, frame);
+    }
+
+    let agentNode = null;
+    if (aauth.agent) {
+      agentNode = ensureNode(nodes, 'agent', aauth.agent, {
+        last_keyid: aauth.sig_keyid,
+        posture: aauth.posture,
+      });
+      bumpNode(agentNode, frame);
+    }
+
+    let missionNode = null;
+    if (aauth.mission) {
+      missionNode = ensureNode(nodes, 'mission', aauth.mission);
+      bumpNode(missionNode, frame);
+    }
+
+    let signingNode = null;
+    if (aauth.sig_alg) {
+      signingNode = ensureNode(nodes, 'signing', aauth.sig_alg, {
+        keyid: aauth.sig_keyid,
+      });
+      bumpNode(signingNode, frame);
+    }
+
+    const accessMode = extractAccessMode(aauth.requirement);
+    let accessNode = null;
+    if (accessMode) {
+      accessNode = ensureNode(nodes, 'access', accessMode);
+      bumpNode(accessNode, frame);
+    }
+
+    if (agentNode && resourceNode) {
+      bumpEdge(ensureEdge(edges, agentNode.id, resourceNode.id, 'calls'));
+    }
+    if (agentNode && missionNode) {
+      bumpEdge(ensureEdge(edges, agentNode.id, missionNode.id, 'pursues'));
+    }
+    if (missionNode && resourceNode) {
+      bumpEdge(ensureEdge(edges, missionNode.id, resourceNode.id, 'targets'));
+    }
+    if (agentNode && signingNode) {
+      bumpEdge(ensureEdge(edges, agentNode.id, signingNode.id, 'signs-with'));
+    }
+    if (resourceNode && accessNode) {
+      bumpEdge(ensureEdge(edges, resourceNode.id, accessNode.id, 'requires'));
+    }
+  }
+
+  const categories = [
+    { id: 'agent', label: 'Agent' },
+    { id: 'mission', label: 'Mission' },
+    { id: 'resource', label: 'Resource' },
+    { id: 'signing', label: 'Signing' },
+    { id: 'access', label: 'Access' },
+  ];
+
+  return {
+    categories,
+    nodes: [...nodes.values()],
+    edges: [...edges.values()],
+    stats: {
+      observed_packets: observedSignals,
+      node_counts: countByCategory([...nodes.values()]),
+      edge_count: edges.size,
+    },
+  };
+}
+
+function countByCategory(nodes) {
+  const out = {};
+  for (const n of nodes) {
+    out[n.category] = (out[n.category] || 0) + 1;
+  }
+  return out;
+}