@frontmcp/testing 1.7.2 → 1.8.1

package/fixtures/index.js

@@ -215,236 +215,281 @@ var TestTokenFactory = class {
   }
 };
 
-// libs/testing/src/platform/platform-client-info.ts
-var MCP_APPS_EXTENSION_KEY = "io.modelcontextprotocol/ui";
-function getPlatformClientInfo(platform) {
-  switch (platform) {
-    case "openai":
-      return {
-        name: "ChatGPT",
-        version: "1.0"
-      };
-    case "ext-apps":
-      return {
-        name: "mcp-ext-apps",
-        version: "1.0"
-      };
-    case "claude":
-      return {
-        name: "claude-desktop",
-        version: "1.0"
-      };
-    case "cursor":
-      return {
-        name: "cursor",
-        version: "1.0"
-      };
-    case "continue":
-      return {
-        name: "continue",
-        version: "1.0"
-      };
-    case "cody":
-      return {
-        name: "cody",
-        version: "1.0"
-      };
-    case "gemini":
-      return {
-        name: "gemini",
-        version: "1.0"
-      };
-    case "generic-mcp":
-      return {
-        name: "generic-mcp-client",
-        version: "1.0"
-      };
-    case "unknown":
-    default:
-      return {
-        name: "mcp-test-client",
-        version: "1.0"
-      };
-  }
-}
-function getPlatformCapabilities(platform) {
-  const baseCapabilities = {
-    sampling: {},
-    // Include elicitation.form by default for testing elicitation workflows
-    // Note: MCP SDK expects form to be an object, not boolean
-    elicitation: {
-      form: {}
-    }
-  };
-  if (platform === "ext-apps") {
+// libs/testing/src/interceptor/mock-registry.ts
+var DefaultMockRegistry = class {
+  mocks = [];
+  add(mock) {
+    const entry = {
+      definition: mock,
+      callCount: 0,
+      calls: [],
+      remainingUses: mock.times ?? Infinity
+    };
+    this.mocks.push(entry);
     return {
-      ...baseCapabilities,
-      experimental: {
-        [MCP_APPS_EXTENSION_KEY]: {
-          mimeTypes: ["text/html;profile=mcp-app"]
+      remove: () => {
+        const index = this.mocks.indexOf(entry);
+        if (index !== -1) {
+          this.mocks.splice(index, 1);
         }
-      }
+      },
+      callCount: () => entry.callCount,
+      calls: () => [...entry.calls]
     };
   }
-  return baseCapabilities;
-}
-
-// libs/testing/src/client/mcp-test-client.builder.ts
-var McpTestClientBuilder = class {
-  config;
-  constructor(config) {
-    this.config = { ...config };
+  clear() {
+    this.mocks = [];
   }
-  /**
-   * Set the authentication configuration
-   */
-  withAuth(auth) {
-    this.config.auth = { ...this.config.auth, ...auth };
-    return this;
+  getAll() {
+    return this.mocks.map((e) => e.definition);
+  }
+  match(request) {
+    for (const entry of this.mocks) {
+      if (entry.remainingUses <= 0) continue;
+      const { definition } = entry;
+      if (definition.method !== request.method) continue;
+      if (definition.params !== void 0) {
+        const params = request.params ?? {};
+        if (typeof definition.params === "function") {
+          if (!definition.params(params)) continue;
+        } else {
+          if (!this.paramsMatch(definition.params, params)) continue;
+        }
+      }
+      entry.callCount++;
+      entry.calls.push(request);
+      entry.remainingUses--;
+      return definition;
+    }
+    return void 0;
   }
   /**
-   * Set the bearer token for authentication
+   * Check if request params match the mock params definition
    */
-  withToken(token) {
-    this.config.auth = { ...this.config.auth, token };
-    return this;
+  paramsMatch(expected, actual) {
+    for (const [key, value] of Object.entries(expected)) {
+      if (!(key in actual)) return false;
+      const actualValue = actual[key];
+      if (Array.isArray(value)) {
+        if (!Array.isArray(actualValue)) return false;
+        if (value.length !== actualValue.length) return false;
+        for (let i = 0; i < value.length; i++) {
+          const expectedItem = value[i];
+          const actualItem = actualValue[i];
+          if (typeof expectedItem === "object" && expectedItem !== null) {
+            if (typeof actualItem !== "object" || actualItem === null) return false;
+            if (!this.paramsMatch(expectedItem, actualItem)) {
+              return false;
+            }
+          } else if (actualItem !== expectedItem) {
+            return false;
+          }
+        }
+      } else if (typeof value === "object" && value !== null) {
+        if (typeof actualValue !== "object" || actualValue === null) return false;
+        if (!this.paramsMatch(value, actualValue)) {
+          return false;
+        }
+      } else if (actualValue !== value) {
+        return false;
+      }
+    }
+    return true;
   }
+};
+var mockResponse = {
   /**
-   * Add custom headers to all requests
+   * Create a successful JSON-RPC response
    */
-  withHeaders(headers) {
-    this.config.auth = {
-      ...this.config.auth,
-      headers: { ...this.config.auth?.headers, ...headers }
+  success(result, id = 1) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result
     };
-    return this;
-  }
+  },
   /**
-   * Set the transport type
+   * Create an error JSON-RPC response
    */
-  withTransport(transport) {
-    this.config.transport = transport;
-    return this;
-  }
+  error(code, message, data, id = 1) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      error: { code, message, data }
+    };
+  },
   /**
-   * Set the request timeout in milliseconds
+   * Create a tool result response
    */
-  withTimeout(timeoutMs) {
-    this.config.timeout = timeoutMs;
-    return this;
-  }
+  toolResult(content, id = 1) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { content }
+    };
+  },
   /**
-   * Enable debug logging
+   * Create a tools/list response
    */
-  withDebug(enabled = true) {
-    this.config.debug = enabled;
-    return this;
-  }
+  toolsList(tools, id = 1) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { tools }
+    };
+  },
   /**
-   * Enable public mode - skip authentication entirely.
-   * When true, no Authorization header is sent and anonymous token is not requested.
-   * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.
+   * Create a resources/list response
    */
-  withPublicMode(enabled = true) {
-    this.config.publicMode = enabled;
-    return this;
-  }
+  resourcesList(resources, id = 1) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { resources }
+    };
+  },
   /**
-   * Set the MCP protocol version to request
+   * Create a resources/read response
    */
-  withProtocolVersion(version) {
-    this.config.protocolVersion = version;
-    return this;
-  }
+  resourceRead(contents, id = 1) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { contents }
+    };
+  },
   /**
-   * Set the client info sent during initialization
+   * Common MCP errors
    */
-  withClientInfo(info) {
-    this.config.clientInfo = info;
-    return this;
+  errors: {
+    methodNotFound: (method, id = 1) => mockResponse.error(-32601, `Method not found: ${method}`, void 0, id),
+    invalidParams: (message, id = 1) => mockResponse.error(-32602, message, void 0, id),
+    internalError: (message, id = 1) => mockResponse.error(-32603, message, void 0, id),
+    resourceNotFound: (uri, id = 1) => mockResponse.error(-32002, `Resource not found: ${uri}`, { uri }, id),
+    toolNotFound: (name, id = 1) => mockResponse.error(-32601, `Tool not found: ${name}`, { name }, id),
+    unauthorized: (id = 1) => mockResponse.error(-32001, "Unauthorized", void 0, id),
+    forbidden: (id = 1) => mockResponse.error(-32003, "Forbidden", void 0, id)
+  }
+};
+
+// libs/testing/src/interceptor/interceptor-chain.ts
+var DefaultInterceptorChain = class {
+  request = [];
+  response = [];
+  mocks;
+  constructor() {
+    this.mocks = new DefaultMockRegistry();
   }
   /**
-   * Set the platform type for testing platform-specific meta keys.
-   * Automatically configures clientInfo and capabilities for platform detection.
-   *
-   * Platform-specific behavior:
-   * - `openai`: Uses openai/* meta keys, sets User-Agent to "ChatGPT/1.0"
-   * - `ext-apps`: Uses ui/* meta keys per SEP-1865, sets io.modelcontextprotocol/ui capability
-   * - `claude`: Uses frontmcp/* + ui/* keys, sets User-Agent to "claude-desktop/1.0"
-   * - `cursor`: Uses frontmcp/* + ui/* keys, sets User-Agent to "cursor/1.0"
-   * - Other platforms follow similar patterns
-   *
-   * @example
-   * ```typescript
-   * const client = await McpTestClient.create({ baseUrl })
-   *   .withPlatform('openai')
-   *   .buildAndConnect();
-   *
-   * // ext-apps automatically sets the io.modelcontextprotocol/ui capability
-   * const extAppsClient = await McpTestClient.create({ baseUrl })
-   *   .withPlatform('ext-apps')
-   *   .buildAndConnect();
-   * ```
+   * Add a request interceptor
    */
-  withPlatform(platform) {
-    this.config.platform = platform;
-    this.config.clientInfo = getPlatformClientInfo(platform);
-    this.config.capabilities = getPlatformCapabilities(platform);
-    return this;
+  addRequestInterceptor(interceptor) {
+    this.request.push(interceptor);
+    return () => {
+      const index = this.request.indexOf(interceptor);
+      if (index !== -1) {
+        this.request.splice(index, 1);
+      }
+    };
   }
   /**
-   * Set custom client capabilities for MCP initialization.
-   * Use this for fine-grained control over capabilities sent during initialization.
-   *
-   * @example
-   * ```typescript
-   * const client = await McpTestClient.create({ baseUrl })
-   *   .withCapabilities({
-   *     sampling: {},
-   *     experimental: {
-   *       'io.modelcontextprotocol/ui': { mimeTypes: ['text/html;profile=mcp-app'] }
-   *     }
-   *   })
-   *   .buildAndConnect();
-   * ```
+   * Add a response interceptor
    */
-  withCapabilities(capabilities) {
-    this.config.capabilities = capabilities;
-    return this;
+  addResponseInterceptor(interceptor) {
+    this.response.push(interceptor);
+    return () => {
+      const index = this.response.indexOf(interceptor);
+      if (index !== -1) {
+        this.response.splice(index, 1);
+      }
+    };
   }
   /**
-   * Set query parameters to append to the connection URL.
-   * Useful for testing mode switches like `?mode=skills_only`.
-   *
-   * @example
-   * ```typescript
-   * const client = await McpTestClient.create({ baseUrl })
-   *   .withQueryParams({ mode: 'skills_only' })
-   *   .buildAndConnect();
-   * ```
+   * Process a request through the interceptor chain
+   * Returns either:
+   * - { type: 'continue', request } - continue with (possibly modified) request
+   * - { type: 'mock', response } - return mock response immediately
+   * - { type: 'error', error } - throw error
    */
-  withQueryParams(params) {
-    this.config.queryParams = { ...this.config.queryParams, ...params };
-    return this;
+  async processRequest(request, meta) {
+    let currentRequest = request;
+    const mockDef = this.mocks.match(request);
+    if (mockDef) {
+      if (mockDef.delay && mockDef.delay > 0) {
+        await sleep(mockDef.delay);
+      }
+      let mockResponse2;
+      if (typeof mockDef.response === "function") {
+        mockResponse2 = await mockDef.response(request);
+      } else {
+        mockResponse2 = mockDef.response;
+      }
+      return {
+        type: "mock",
+        response: { ...mockResponse2, id: request.id ?? mockResponse2.id }
+      };
+    }
+    for (const interceptor of this.request) {
+      const ctx = {
+        request: currentRequest,
+        meta
+      };
+      const result = await interceptor(ctx);
+      switch (result.action) {
+        case "passthrough":
+          break;
+        case "modify":
+          currentRequest = result.request;
+          break;
+        case "mock":
+          return {
+            type: "mock",
+            response: { ...result.response, id: request.id ?? result.response.id }
+          };
+        case "error":
+          return { type: "error", error: result.error };
+      }
+    }
+    return { type: "continue", request: currentRequest };
   }
   /**
-   * Build the McpTestClient instance (does not connect)
+   * Process a response through the interceptor chain
    */
-  build() {
-    return new McpTestClient(this.config);
+  async processResponse(request, response, durationMs) {
+    let currentResponse = response;
+    for (const interceptor of this.response) {
+      const ctx = {
+        request,
+        response: currentResponse,
+        durationMs
+      };
+      const result = await interceptor(ctx);
+      switch (result.action) {
+        case "passthrough":
+          break;
+        case "modify":
+          currentResponse = result.response;
+          break;
+      }
+    }
+    return currentResponse;
   }
   /**
-   * Build the McpTestClient and connect to the server
+   * Clear all interceptors and mocks
    */
-  async buildAndConnect() {
-    const client = this.build();
-    await client.connect();
-    return client;
+  clear() {
+    this.request = [];
+    this.response = [];
+    this.mocks.clear();
   }
 };
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // libs/testing/src/transport/streamable-http.transport.ts
 var DEFAULT_TIMEOUT = 3e4;
+var NOTIFICATION_STREAM_REOPEN_DELAY_MS = 250;
 var StreamableHttpTransport = class {
   config;
   state = "disconnected";
@@ -456,10 +501,15 @@ var StreamableHttpTransport = class {
   interceptors;
   publicMode;
   elicitationHandler;
+  notificationHandler;
+  notificationStream;
+  notificationProtocolVersion = "";
+  notificationStreamReopenTimer;
   constructor(config) {
     this.config = {
       baseUrl: config.baseUrl.replace(/\/$/, ""),
       // Remove trailing slash
+      entryPath: config.entryPath,
       timeout: config.timeout ?? DEFAULT_TIMEOUT,
       auth: config.auth ?? {},
       publicMode: config.publicMode ?? false,
@@ -471,6 +521,7 @@ var StreamableHttpTransport = class {
     this.interceptors = config.interceptors;
     this.publicMode = config.publicMode ?? false;
     this.elicitationHandler = config.elicitationHandler;
+    this.notificationHandler = config.notificationHandler;
   }
   async connect() {
     this.state = "connecting";
@@ -552,7 +603,7 @@ var StreamableHttpTransport = class {
     }
     const headers = this.buildHeaders();
     this.lastRequestHeaders = headers;
-    const url = `${this.config.baseUrl}/`;
+    const url = this.mcpUrl();
     this.log(`POST ${url}`, message);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -622,7 +673,7 @@ var StreamableHttpTransport = class {
     this.ensureConnected();
     const headers = this.buildHeaders();
     this.lastRequestHeaders = headers;
-    const url = `${this.config.baseUrl}/`;
+    const url = this.mcpUrl();
     this.log(`POST ${url} (notification)`, message);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -653,7 +704,7 @@ var StreamableHttpTransport = class {
     this.ensureConnected();
     const headers = this.buildHeaders();
     this.lastRequestHeaders = headers;
-    const url = `${this.config.baseUrl}/`;
+    const url = this.mcpUrl();
     this.log(`POST ${url} (raw)`, data);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -690,7 +741,12 @@ var StreamableHttpTransport = class {
       };
     }
   }
+  async openNotificationStream(protocolVersion) {
+    this.notificationProtocolVersion = protocolVersion;
+    await this.connectNotificationStream();
+  }
   async close() {
+    this.closeNotificationStream();
     this.state = "disconnected";
     this.sessionId = void 0;
     this.log("StreamableHTTP transport closed");
@@ -729,6 +785,7 @@ var StreamableHttpTransport = class {
     return { ...this.lastRequestHeaders };
   }
   async simulateDisconnect() {
+    this.closeNotificationStream();
     this.state = "disconnected";
     this.sessionId = void 0;
   }
@@ -747,6 +804,72 @@ var StreamableHttpTransport = class {
   // ═══════════════════════════════════════════════════════════════════
   // PRIVATE HELPERS
   // ═══════════════════════════════════════════════════════════════════
+  closeNotificationStream() {
+    clearTimeout(this.notificationStreamReopenTimer);
+    this.notificationStream?.abort();
+    this.notificationStream = void 0;
+  }
+  /** Opens the stream without holding up the caller past the request timeout; close() aborts it at any point. */
+  async connectNotificationStream() {
+    if (!this.sessionId || this.notificationStream) return;
+    const controller = new AbortController();
+    this.notificationStream = controller;
+    const { "Content-Type": _contentType, ...headers } = this.buildHeaders();
+    const established = fetch(this.mcpUrl(), {
+      method: "GET",
+      headers: { ...headers, Accept: "text/event-stream", "MCP-Protocol-Version": this.notificationProtocolVersion },
+      signal: controller.signal
+    }).then(
+      async (response) => {
+        const isEventStream = response.headers.get("content-type")?.includes("text/event-stream") ?? false;
+        if (!response.ok || !response.body || !isEventStream) {
+          await response.body?.cancel();
+          this.log(`Server offers no notification stream (HTTP ${response.status})`);
+          this.releaseNotificationStream(controller);
+          return;
+        }
+        void this.readNotificationStream(controller, response.body.getReader());
+      },
+      (error) => {
+        this.log("Failed to open the notification stream:", error);
+        this.releaseNotificationStream(controller);
+      }
+    );
+    let establishTimer;
+    const establishDeadline = new Promise((resolve) => {
+      establishTimer = setTimeout(resolve, this.config.timeout);
+    });
+    await Promise.race([established, establishDeadline]);
+    clearTimeout(establishTimer);
+  }
+  releaseNotificationStream(controller) {
+    if (this.notificationStream === controller) this.notificationStream = void 0;
+  }
+  async readNotificationStream(controller, reader) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+        const { completeEvents, remainder } = splitSSEEvents(buffer + decoder.decode(chunk.value, { stream: true }));
+        buffer = remainder;
+        for (const eventText of completeEvents) {
+          for (const event of this.parseSSEEvents(eventText, void 0).events) {
+            await this.handleSSEEvent(event);
+          }
+        }
+      }
+    } catch (error) {
+      this.log("Notification stream ended:", error);
+    } finally {
+      reader.releaseLock();
+    }
+    if (controller.signal.aborted || this.notificationStream !== controller) return;
+    this.releaseNotificationStream(controller);
+    this.notificationStreamReopenTimer = setTimeout(
+      () => void this.connectNotificationStream(),
+      NOTIFICATION_STREAM_REOPEN_DELAY_MS
+    );
+  }
   /**
    * Handle SSE response with elicitation support.
    *
@@ -884,6 +1007,13 @@ var StreamableHttpTransport = class {
           response: { jsonrpc: "2.0", id: null, result: void 0 }
         };
       }
+      if ("method" in parsed && parsed.id === void 0) {
+        this.notificationHandler?.(parsed);
+        return {
+          isFinal: false,
+          response: { jsonrpc: "2.0", id: null, result: void 0 }
+        };
+      }
       if ("result" in parsed || "error" in parsed) {
         return { isFinal: true, response: parsed };
       }
@@ -936,7 +1066,7 @@ var StreamableHttpTransport = class {
    */
   async sendElicitationResponse(requestId, response) {
     const headers = this.buildHeaders();
-    const url = `${this.config.baseUrl}/`;
+    const url = this.mcpUrl();
     const rpcResponse = {
       jsonrpc: "2.0",
       id: requestId,
@@ -956,6 +1086,18 @@ var StreamableHttpTransport = class {
       this.log("Failed to send elicitation response:", error);
     }
   }
+  /**
+   * The MCP endpoint URL. `entryPath` is where the server mounts MCP; the
+   * trailing slash is kept because both hosts normalize it and the original
+   * behaviour (`${baseUrl}/`) relied on it (issue #543).
+   */
+  mcpUrl() {
+    const url = new URL(this.config.baseUrl);
+    const entry = (this.config.entryPath ?? "").replace(/^\/+|\/+$/g, "");
+    const basePath = url.pathname.replace(/\/+$/, "");
+    url.pathname = entry ? `${basePath}/${entry}` : `${basePath}/`;
+    return url.toString();
+  }
   buildHeaders() {
     const headers = {
       "Content-Type": "application/json",
@@ -1042,286 +1184,266 @@ var StreamableHttpTransport = class {
     };
   }
 };
+function splitSSEEvents(buffer) {
+  const endsWithCarriageReturn = buffer.endsWith("\r");
+  const normalized = (endsWithCarriageReturn ? buffer.slice(0, -1) : buffer).replace(/\r\n?/g, "\n");
+  const completeEvents = normalized.split("\n\n");
+  const remainder = completeEvents.pop() ?? "";
+  return { completeEvents, remainder: endsWithCarriageReturn ? `${remainder}\r` : remainder };
+}
 
-// libs/testing/src/interceptor/mock-registry.ts
-var DefaultMockRegistry = class {
-  mocks = [];
-  add(mock) {
-    const entry = {
-      definition: mock,
-      callCount: 0,
-      calls: [],
-      remainingUses: mock.times ?? Infinity
-    };
-    this.mocks.push(entry);
+// libs/testing/src/platform/platform-client-info.ts
+var MCP_APPS_EXTENSION_KEY = "io.modelcontextprotocol/ui";
+function getPlatformClientInfo(platform) {
+  switch (platform) {
+    case "openai":
+      return {
+        name: "ChatGPT",
+        version: "1.0"
+      };
+    case "ext-apps":
+      return {
+        name: "mcp-ext-apps",
+        version: "1.0"
+      };
+    case "claude":
+      return {
+        name: "claude-desktop",
+        version: "1.0"
+      };
+    case "cursor":
+      return {
+        name: "cursor",
+        version: "1.0"
+      };
+    case "continue":
+      return {
+        name: "continue",
+        version: "1.0"
+      };
+    case "cody":
+      return {
+        name: "cody",
+        version: "1.0"
+      };
+    case "gemini":
+      return {
+        name: "gemini",
+        version: "1.0"
+      };
+    case "generic-mcp":
+      return {
+        name: "generic-mcp-client",
+        version: "1.0"
+      };
+    case "unknown":
+    default:
+      return {
+        name: "mcp-test-client",
+        version: "1.0"
+      };
+  }
+}
+function getPlatformCapabilities(platform) {
+  const baseCapabilities = {
+    sampling: {},
+    // Include elicitation.form by default for testing elicitation workflows
+    // Note: MCP SDK expects form to be an object, not boolean
+    elicitation: {
+      form: {}
+    }
+  };
+  if (platform === "ext-apps") {
     return {
-      remove: () => {
-        const index = this.mocks.indexOf(entry);
-        if (index !== -1) {
-          this.mocks.splice(index, 1);
+      ...baseCapabilities,
+      experimental: {
+        [MCP_APPS_EXTENSION_KEY]: {
+          mimeTypes: ["text/html;profile=mcp-app"]
         }
-      },
-      callCount: () => entry.callCount,
-      calls: () => [...entry.calls]
+      }
     };
   }
-  clear() {
-    this.mocks = [];
-  }
-  getAll() {
-    return this.mocks.map((e) => e.definition);
-  }
-  match(request) {
-    for (const entry of this.mocks) {
-      if (entry.remainingUses <= 0) continue;
-      const { definition } = entry;
-      if (definition.method !== request.method) continue;
-      if (definition.params !== void 0) {
-        const params = request.params ?? {};
-        if (typeof definition.params === "function") {
-          if (!definition.params(params)) continue;
-        } else {
-          if (!this.paramsMatch(definition.params, params)) continue;
-        }
-      }
-      entry.callCount++;
-      entry.calls.push(request);
-      entry.remainingUses--;
-      return definition;
-    }
-    return void 0;
+  return baseCapabilities;
+}
+
+// libs/testing/src/client/mcp-test-client.builder.ts
+var McpTestClientBuilder = class {
+  config;
+  constructor(config) {
+    this.config = { ...config };
   }
   /**
-   * Check if request params match the mock params definition
+   * Set the authentication configuration
    */
-  paramsMatch(expected, actual) {
-    for (const [key, value] of Object.entries(expected)) {
-      if (!(key in actual)) return false;
-      const actualValue = actual[key];
-      if (Array.isArray(value)) {
-        if (!Array.isArray(actualValue)) return false;
-        if (value.length !== actualValue.length) return false;
-        for (let i = 0; i < value.length; i++) {
-          const expectedItem = value[i];
-          const actualItem = actualValue[i];
-          if (typeof expectedItem === "object" && expectedItem !== null) {
-            if (typeof actualItem !== "object" || actualItem === null) return false;
-            if (!this.paramsMatch(expectedItem, actualItem)) {
-              return false;
-            }
-          } else if (actualItem !== expectedItem) {
-            return false;
-          }
-        }
-      } else if (typeof value === "object" && value !== null) {
-        if (typeof actualValue !== "object" || actualValue === null) return false;
-        if (!this.paramsMatch(value, actualValue)) {
-          return false;
-        }
-      } else if (actualValue !== value) {
-        return false;
-      }
-    }
-    return true;
+  withAuth(auth) {
+    this.config.auth = { ...this.config.auth, ...auth };
+    return this;
   }
-};
-var mockResponse = {
   /**
-   * Create a successful JSON-RPC response
+   * Set the bearer token for authentication
    */
-  success(result, id = 1) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      result
-    };
-  },
+  withToken(token) {
+    this.config.auth = { ...this.config.auth, token };
+    return this;
+  }
   /**
-   * Create an error JSON-RPC response
+   * Add custom headers to all requests
    */
-  error(code, message, data, id = 1) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      error: { code, message, data }
+  withHeaders(headers) {
+    this.config.auth = {
+      ...this.config.auth,
+      headers: { ...this.config.auth?.headers, ...headers }
     };
-  },
+    return this;
+  }
   /**
-   * Create a tool result response
+   * Set the transport type
    */
-  toolResult(content, id = 1) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      result: { content }
-    };
-  },
+  withTransport(transport) {
+    this.config.transport = transport;
+    return this;
+  }
   /**
-   * Create a tools/list response
+   * Set the request timeout in milliseconds
    */
-  toolsList(tools, id = 1) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      result: { tools }
-    };
-  },
+  withTimeout(timeoutMs) {
+    this.config.timeout = timeoutMs;
+    return this;
+  }
   /**
-   * Create a resources/list response
+   * Enable debug logging
    */
-  resourcesList(resources, id = 1) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      result: { resources }
-    };
-  },
+  withDebug(enabled = true) {
+    this.config.debug = enabled;
+    return this;
+  }
   /**
-   * Create a resources/read response
+   * Enable public mode - skip authentication entirely.
+   * When true, no Authorization header is sent and anonymous token is not requested.
+   * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.
    */
-  resourceRead(contents, id = 1) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      result: { contents }
-    };
-  },
+  withPublicMode(enabled = true) {
+    this.config.publicMode = enabled;
+    return this;
+  }
   /**
-   * Common MCP errors
+   * Set the MCP protocol version to request (default '2025-06-18').
+   * '2026-07-28' has no initialize handshake, so `build()` throws for it.
    */
-  errors: {
-    methodNotFound: (method, id = 1) => mockResponse.error(-32601, `Method not found: ${method}`, void 0, id),
-    invalidParams: (message, id = 1) => mockResponse.error(-32602, message, void 0, id),
-    internalError: (message, id = 1) => mockResponse.error(-32603, message, void 0, id),
-    resourceNotFound: (uri, id = 1) => mockResponse.error(-32002, `Resource not found: ${uri}`, { uri }, id),
-    toolNotFound: (name, id = 1) => mockResponse.error(-32601, `Tool not found: ${name}`, { name }, id),
-    unauthorized: (id = 1) => mockResponse.error(-32001, "Unauthorized", void 0, id),
-    forbidden: (id = 1) => mockResponse.error(-32003, "Forbidden", void 0, id)
+  withProtocolVersion(version) {
+    this.config.protocolVersion = version;
+    return this;
   }
-};
-
-// libs/testing/src/interceptor/interceptor-chain.ts
-var DefaultInterceptorChain = class {
-  request = [];
-  response = [];
-  mocks;
-  constructor() {
-    this.mocks = new DefaultMockRegistry();
+  /**
+   * Set the client info sent during initialization
+   */
+  withClientInfo(info) {
+    this.config.clientInfo = info;
+    return this;
   }
   /**
-   * Add a request interceptor
+   * Set the platform type for testing platform-specific meta keys.
+   * Automatically configures clientInfo and capabilities for platform detection.
+   *
+   * Platform-specific behavior:
+   * - `openai`: Uses openai/* meta keys, sets User-Agent to "ChatGPT/1.0"
+   * - `ext-apps`: Uses ui/* meta keys per SEP-1865, sets io.modelcontextprotocol/ui capability
+   * - `claude`: Uses frontmcp/* + ui/* keys, sets User-Agent to "claude-desktop/1.0"
+   * - `cursor`: Uses frontmcp/* + ui/* keys, sets User-Agent to "cursor/1.0"
+   * - Other platforms follow similar patterns
+   *
+   * @example
+   * ```typescript
+   * const client = await McpTestClient.create({ baseUrl })
+   *   .withPlatform('openai')
+   *   .buildAndConnect();
+   *
+   * // ext-apps automatically sets the io.modelcontextprotocol/ui capability
+   * const extAppsClient = await McpTestClient.create({ baseUrl })
+   *   .withPlatform('ext-apps')
+   *   .buildAndConnect();
+   * ```
    */
-  addRequestInterceptor(interceptor) {
-    this.request.push(interceptor);
-    return () => {
-      const index = this.request.indexOf(interceptor);
-      if (index !== -1) {
-        this.request.splice(index, 1);
-      }
-    };
+  withPlatform(platform) {
+    this.config.platform = platform;
+    this.config.clientInfo = getPlatformClientInfo(platform);
+    this.config.capabilities = getPlatformCapabilities(platform);
+    return this;
   }
   /**
-   * Add a response interceptor
+   * Set custom client capabilities for MCP initialization.
+   * Use this for fine-grained control over capabilities sent during initialization.
+   *
+   * @example
+   * ```typescript
+   * const client = await McpTestClient.create({ baseUrl })
+   *   .withCapabilities({
+   *     sampling: {},
+   *     experimental: {
+   *       'io.modelcontextprotocol/ui': { mimeTypes: ['text/html;profile=mcp-app'] }
+   *     }
+   *   })
+   *   .buildAndConnect();
+   * ```
    */
-  addResponseInterceptor(interceptor) {
-    this.response.push(interceptor);
-    return () => {
-      const index = this.response.indexOf(interceptor);
-      if (index !== -1) {
-        this.response.splice(index, 1);
-      }
-    };
+  withCapabilities(capabilities) {
+    this.config.capabilities = capabilities;
+    return this;
   }
   /**
-   * Process a request through the interceptor chain
-   * Returns either:
-   * - { type: 'continue', request } - continue with (possibly modified) request
-   * - { type: 'mock', response } - return mock response immediately
-   * - { type: 'error', error } - throw error
+   * Set query parameters to append to the connection URL.
+   * Useful for testing mode switches like `?mode=skills_only`.
+   *
+   * @example
+   * ```typescript
+   * const client = await McpTestClient.create({ baseUrl })
+   *   .withQueryParams({ mode: 'skills_only' })
+   *   .buildAndConnect();
+   * ```
    */
-  async processRequest(request, meta) {
-    let currentRequest = request;
-    const mockDef = this.mocks.match(request);
-    if (mockDef) {
-      if (mockDef.delay && mockDef.delay > 0) {
-        await sleep(mockDef.delay);
-      }
-      let mockResponse2;
-      if (typeof mockDef.response === "function") {
-        mockResponse2 = await mockDef.response(request);
-      } else {
-        mockResponse2 = mockDef.response;
-      }
-      return {
-        type: "mock",
-        response: { ...mockResponse2, id: request.id ?? mockResponse2.id }
-      };
-    }
-    for (const interceptor of this.request) {
-      const ctx = {
-        request: currentRequest,
-        meta
-      };
-      const result = await interceptor(ctx);
-      switch (result.action) {
-        case "passthrough":
-          break;
-        case "modify":
-          currentRequest = result.request;
-          break;
-        case "mock":
-          return {
-            type: "mock",
-            response: { ...result.response, id: request.id ?? result.response.id }
-          };
-        case "error":
-          return { type: "error", error: result.error };
-      }
-    }
-    return { type: "continue", request: currentRequest };
+  withQueryParams(params) {
+    this.config.queryParams = { ...this.config.queryParams, ...params };
+    return this;
   }
   /**
-   * Process a response through the interceptor chain
+   * Build the McpTestClient instance (does not connect)
    */
-  async processResponse(request, response, durationMs) {
-    let currentResponse = response;
-    for (const interceptor of this.response) {
-      const ctx = {
-        request,
-        response: currentResponse,
-        durationMs
-      };
-      const result = await interceptor(ctx);
-      switch (result.action) {
-        case "passthrough":
-          break;
-        case "modify":
-          currentResponse = result.response;
-          break;
-      }
-    }
-    return currentResponse;
+  build() {
+    return new McpTestClient(this.config);
   }
   /**
-   * Clear all interceptors and mocks
+   * Build the McpTestClient and connect to the server
    */
-  clear() {
-    this.request = [];
-    this.response = [];
-    this.mocks.clear();
+  async buildAndConnect() {
+    const client = this.build();
+    await client.connect();
+    return client;
   }
 };
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // libs/testing/src/client/mcp-test-client.ts
 var DEFAULT_TIMEOUT2 = 3e4;
 var DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+var UNSUPPORTED_PROTOCOL_VERSIONS = ["2026-07-28"];
 var DEFAULT_CLIENT_INFO = {
   name: "@frontmcp/testing",
   version: "0.4.0"
 };
+function extractEntryPaths(data) {
+  let payload = data;
+  if (typeof payload === "string") {
+    try {
+      payload = JSON.parse(payload);
+    } catch {
+      return void 0;
+    }
+  }
+  if (!payload || typeof payload !== "object") return void 0;
+  const paths = payload.entryPaths;
+  if (!Array.isArray(paths)) return void 0;
+  const strings = paths.filter((p) => typeof p === "string");
+  return strings.length > 0 ? strings : void 0;
+}
 var McpTestClient = class {
   // Platform, capabilities, and queryParams are optional - only set when needed
   config;
@@ -1330,6 +1452,8 @@ var McpTestClient = class {
   requestIdCounter = 0;
   _lastRequestId = 0;
   _sessionId;
+  /** #543 — discovery is attempted at most once per connect. */
+  triedDiscoveredEntryPath = false;
   _sessionInfo = null;
   _authState = { isAnonymous: true, scopes: [] };
   // Logging and tracing
@@ -1337,6 +1461,8 @@ var McpTestClient = class {
   _traces = [];
   _notifications = [];
   _progressUpdates = [];
+  collectingProgress = false;
+  progressTokenCounter = 0;
   // Interceptor chain
   _interceptors;
   // Elicitation handler for server→client elicit requests
@@ -1345,8 +1471,14 @@ var McpTestClient = class {
   // CONSTRUCTOR & FACTORY
   // ═══════════════════════════════════════════════════════════════════
   constructor(config) {
+    if (config.protocolVersion && UNSUPPORTED_PROTOCOL_VERSIONS.includes(config.protocolVersion)) {
+      throw new Error(
+        `McpTestClient does not support protocol version ${config.protocolVersion}: it has no initialize handshake. Use ${DEFAULT_PROTOCOL_VERSION} or earlier.`
+      );
+    }
     this.config = {
       baseUrl: config.baseUrl,
+      entryPath: config.entryPath,
       transport: config.transport ?? "streamable-http",
       auth: config.auth ?? {},
       publicMode: config.publicMode ?? false,
@@ -1382,11 +1514,13 @@ var McpTestClient = class {
    */
   async connect() {
     this.log("debug", `Connecting to ${this.config.baseUrl}...`);
+    this.triedDiscoveredEntryPath = false;
     this.transport = this.createTransport();
     await this.transport.connect();
     const maxRetries = 3;
     const retryDelayMs = 500;
     let lastError;
+    let reportedEntryPaths;
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
       const initResponse = await this.initialize();
       if (initResponse.success && initResponse.data) {
@@ -1394,13 +1528,27 @@ var McpTestClient = class {
         break;
       }
       lastError = initResponse.error?.message ?? "Unknown error";
+      reportedEntryPaths = extractEntryPaths(initResponse.error?.data) ?? reportedEntryPaths;
+      if (reportedEntryPaths?.length === 1 && !this.triedDiscoveredEntryPath) {
+        this.triedDiscoveredEntryPath = true;
+        const discovered = reportedEntryPaths[0];
+        this.log("info", `Server serves MCP at ${discovered}; reconnecting there (configured: ${this.mcpPathLabel()})`);
+        this.config.entryPath = discovered;
+        await this.transport.close();
+        this.transport = this.createTransport();
+        await this.transport.connect();
+        continue;
+      }
       if (attempt < maxRetries) {
         this.log("debug", `MCP init attempt ${attempt} failed (${lastError}), retrying in ${retryDelayMs}ms...`);
         await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
       }
     }
     if (!this.initResult) {
-      throw new Error(`Failed to initialize MCP connection after ${maxRetries} attempts: ${lastError}`);
+      const served = reportedEntryPaths?.length ? ` The server reports it serves MCP at ${reportedEntryPaths.join(", ")}; set \`entryPath\` in test.use() (or \`http.entryPath\` on the server) to match.` : "";
+      throw new Error(
+        `Failed to initialize MCP connection to ${this.config.baseUrl}${this.mcpPathLabel()} after ${maxRetries} attempts: ${lastError}.${served}`
+      );
     }
     this._sessionId = this.transport.getSessionId();
     this._sessionInfo = {
@@ -1413,6 +1561,7 @@ var McpTestClient = class {
       jsonrpc: "2.0",
       method: "notifications/initialized"
     });
+    await this.transport.openNotificationStream?.(this.initResult.protocolVersion);
     this.log("info", `Connected to ${this.initResult.serverInfo?.name ?? "MCP Server"}`);
     return this.initResult;
   }
@@ -1523,8 +1672,8 @@ var McpTestClient = class {
     /**
      * Call a tool by name with arguments
      */
-    call: async (name, args) => {
-      const response = await this.callTool(name, args);
+    call: async (name, args, options = {}) => {
+      const response = await this.callTool(name, args, this.progressTokenFor(options));
       return this.wrapToolResult(response);
     }
   };
@@ -1666,6 +1815,7 @@ var McpTestClient = class {
      * Collect progress notifications specifically
      */
     collectProgress: () => {
+      this.collectingProgress = true;
       return new ProgressCollector(this._progressUpdates);
     },
     /**
@@ -1971,12 +2121,29 @@ var McpTestClient = class {
   async listTools() {
     return this.request("tools/list", {});
   }
-  async callTool(name, args) {
+  async callTool(name, args, progressToken) {
     return this.request("tools/call", {
       name,
-      arguments: args ?? {}
+      arguments: args ?? {},
+      ...progressToken !== void 0 && { _meta: { progressToken } }
     });
   }
+  progressTokenFor(options) {
+    if (options.progressToken !== void 0) return options.progressToken;
+    return this.collectingProgress ? `progress-${++this.progressTokenCounter}` : void 0;
+  }
+  recordNotification = (notification) => {
+    const timestamp = /* @__PURE__ */ new Date();
+    this._notifications.push({ method: notification.method, params: notification.params, timestamp });
+    if (notification.method !== "notifications/progress") return;
+    const { progress, total, progressToken } = notification.params ?? {};
+    this._progressUpdates.push({
+      progress: Number(progress),
+      total: typeof total === "number" ? total : void 0,
+      progressToken: typeof progressToken === "string" || typeof progressToken === "number" ? progressToken : void 0,
+      timestamp
+    });
+  };
   async listResources() {
     return this.request("resources/list", {});
   }
@@ -1998,6 +2165,11 @@ var McpTestClient = class {
   // ═══════════════════════════════════════════════════════════════════
   // PRIVATE: TRANSPORT & REQUEST HELPERS
   // ═══════════════════════════════════════════════════════════════════
+  /** The MCP path this client is currently pointed at, for log and error text. */
+  mcpPathLabel() {
+    const entry = (this.config.entryPath ?? "").replace(/^\/+|\/+$/g, "");
+    return entry ? `/${entry}` : "/";
+  }
   createTransport() {
     let baseUrl = this.config.baseUrl;
     if (this.config.queryParams && Object.keys(this.config.queryParams).length > 0) {
@@ -2011,13 +2183,15 @@ var McpTestClient = class {
       case "streamable-http":
         return new StreamableHttpTransport({
           baseUrl,
+          entryPath: this.config.entryPath,
           timeout: this.config.timeout,
           auth: this.config.auth,
           publicMode: this.config.publicMode,
           debug: this.config.debug,
           interceptors: this._interceptors,
           clientInfo: this.config.clientInfo,
-          elicitationHandler: this._elicitationHandler
+          elicitationHandler: this._elicitationHandler,
+          notificationHandler: this.recordNotification
         });
       case "sse":
         throw new Error("SSE transport not yet implemented");
@@ -3002,13 +3176,17 @@ var currentConfig = {};
 var serverInstance = null;
 var tokenFactory = null;
 var serverStartedByUs = false;
+var skipScopes = [{ skipped: false }];
+function currentSkipScope() {
+  return skipScopes[skipScopes.length - 1];
+}
 async function initializeSharedResources() {
   if (!tokenFactory) {
     const sharedSecret = currentConfig.env?.["JWT_SECRET"];
     tokenFactory = new TestTokenFactory(sharedSecret ? { hmacSecret: sharedSecret } : {});
   }
   if (!serverInstance) {
-    if (currentConfig.baseUrl) {
+    if (currentConfig.baseUrl && !currentConfig.server) {
       serverInstance = TestServer.connect(currentConfig.baseUrl);
       serverStartedByUs = false;
     } else if (currentConfig.server) {
@@ -3058,7 +3236,8 @@ async function createTestFixtures() {
     throw new Error("Token factory not initialized");
   }
   const clientInstance = McpTestClient.create({
-    baseUrl: serverInstance.info.baseUrl,
+    baseUrl: resolveClientBaseUrl(serverInstance),
+    entryPath: currentConfig.entryPath,
     transport: currentConfig.transport ?? "streamable-http",
     publicMode: currentConfig.publicMode
   }).build();
@@ -3107,6 +3286,9 @@ async function cleanupSharedResources() {
   tokenFactory = null;
   serverStartedByUs = false;
 }
+function resolveClientBaseUrl(server) {
+  return currentConfig.baseUrl ?? server.info.baseUrl;
+}
 function createAuthFixture(factory) {
   const users = {
     admin: {
@@ -3156,7 +3338,8 @@ function createServerFixture(server) {
     info: server.info,
     createClient: async (opts) => {
       return McpTestClient.create({
-        baseUrl: server.info.baseUrl,
+        baseUrl: resolveClientBaseUrl(server),
+        entryPath: opts?.entryPath ?? currentConfig.entryPath,
         transport: opts?.transport ?? "streamable-http",
         auth: opts?.token ? { token: opts.token } : void 0,
         clientInfo: opts?.clientInfo,
@@ -3165,7 +3348,8 @@ function createServerFixture(server) {
     },
     createClientBuilder: () => {
       const builder = new McpTestClientBuilder({
-        baseUrl: server.info.baseUrl,
+        baseUrl: resolveClientBaseUrl(server),
+        entryPath: currentConfig.entryPath,
         publicMode: currentConfig.publicMode
       });
       return builder;
@@ -3181,8 +3365,8 @@ function resolveServerCommand(server) {
   }
   return `npx tsx ${server}`;
 }
-function testWithFixtures(name, fn) {
-  it(name, async () => {
+function runWithFixtures(fn) {
+  return async () => {
     const fixtures = await createTestFixtures();
     let testFailed = false;
     try {
@@ -3193,7 +3377,15 @@ function testWithFixtures(name, fn) {
     } finally {
       await cleanupTestFixtures(fixtures, testFailed);
     }
-  });
+  };
+}
+function testWithFixtures(name, fn) {
+  const scope = currentSkipScope();
+  if (scope.skipped) {
+    it.skip(scope.reason ? `${name} (skipped: ${scope.reason})` : name, runWithFixtures(fn));
+    return;
+  }
+  it(name, runWithFixtures(fn));
 }
 function use(config) {
   currentConfig = { ...currentConfig, ...config };
@@ -3201,40 +3393,60 @@ function use(config) {
     await cleanupSharedResources();
   });
 }
-function skip(name, fn) {
-  it.skip(name, async () => {
-    const fixtures = await createTestFixtures();
-    let testFailed = false;
-    try {
-      await fn(fixtures);
-    } catch (error) {
-      testFailed = true;
-      throw error;
-    } finally {
-      await cleanupTestFixtures(fixtures, testFailed);
+function skip(nameOrCondition, fnOrReason) {
+  if (typeof nameOrCondition === "boolean") {
+    if (nameOrCondition) {
+      const scope = currentSkipScope();
+      scope.skipped = true;
+      scope.reason = typeof fnOrReason === "string" ? fnOrReason : void 0;
     }
-  });
+    return;
+  }
+  if (typeof fnOrReason !== "function") {
+    throw new TypeError(
+      `test.skip expects either (name: string, fn) or (condition: boolean, reason?: string); received (${typeof nameOrCondition}, ${typeof fnOrReason}).`
+    );
+  }
+  it.skip(nameOrCondition, runWithFixtures(fnOrReason));
 }
 function only(name, fn) {
-  it.only(name, async () => {
-    const fixtures = await createTestFixtures();
-    let testFailed = false;
-    try {
-      await fn(fixtures);
-    } catch (error) {
-      testFailed = true;
-      throw error;
-    } finally {
-      await cleanupTestFixtures(fixtures, testFailed);
-    }
-  });
+  const scope = currentSkipScope();
+  if (scope.skipped) {
+    it.skip(scope.reason ? `${name} (skipped: ${scope.reason})` : name, runWithFixtures(fn));
+    return;
+  }
+  it.only(name, runWithFixtures(fn));
 }
 function todo(name) {
   it.todo(name);
 }
+function withSkipScope(register) {
+  return (name, fn) => {
+    register(name, () => {
+      const parent = currentSkipScope();
+      skipScopes.push({ skipped: parent.skipped, reason: parent.reason });
+      try {
+        fn();
+      } finally {
+        skipScopes.pop();
+      }
+    });
+  };
+}
+function eachWithSkipScope(each) {
+  return ((...eachArgs) => {
+    const register = each(...eachArgs);
+    return withSkipScope(register);
+  });
+}
+var describeWithSkipScope = Object.assign(withSkipScope(describe), describe, {
+  only: Object.assign(withSkipScope(describe.only), { each: eachWithSkipScope(describe.only.each) }),
+  skip: Object.assign(withSkipScope(describe.skip), { each: eachWithSkipScope(describe.skip.each) }),
+  each: eachWithSkipScope(describe.each)
+});
 var test = testWithFixtures;
 test.use = use;
-test.describe = describe;
+test.describe = describeWithSkipScope;
 test.beforeAll = beforeAll;
 test.beforeEach = beforeEach;
 test.afterEach = afterEach;