@frontmcp/testing 0.5.0 → 0.6.0

package/src/auth/mock-oauth-server.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * @file mock-oauth-server.ts
+ * @description Mock OAuth server for testing transparent auth mode
+ *
+ * This module provides a mock OAuth/OIDC server that serves:
+ * - JWKS endpoint for token verification
+ * - OAuth metadata endpoint (optional)
+ * - Token endpoint for anonymous tokens (optional)
+ *
+ * @example
+ * ```typescript
+ * import { MockOAuthServer, TestTokenFactory } from '@frontmcp/testing';
+ *
+ * const tokenFactory = new TestTokenFactory();
+ * const oauthServer = new MockOAuthServer(tokenFactory);
+ *
+ * // Start the mock server
+ * await oauthServer.start();
+ *
+ * // Configure your MCP server to use this mock
+ * // IDP_PROVIDER_URL = oauthServer.baseUrl
+ *
+ * // Create tokens using the same factory
+ * const token = await tokenFactory.createTestToken({ sub: 'user-123' });
+ *
+ * // Stop when done
+ * await oauthServer.stop();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockOAuthServer = void 0;
+const http_1 = require("http");
+// ═══════════════════════════════════════════════════════════════════
+// MOCK OAUTH SERVER
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Mock OAuth/OIDC server for testing transparent auth mode
+ *
+ * Serves JWKS from a TestTokenFactory so that MCP servers can
+ * validate test tokens without connecting to a real IdP.
+ */
+class MockOAuthServer {
+    tokenFactory;
+    options;
+    server = null;
+    _info = null;
+    connections = new Set();
+    constructor(tokenFactory, options = {}) {
+        this.tokenFactory = tokenFactory;
+        this.options = options;
+    }
+    /**
+     * Start the mock OAuth server
+     */
+    async start() {
+        if (this.server) {
+            throw new Error('Mock OAuth server is already running');
+        }
+        const port = this.options.port ?? 0; // 0 = random available port
+        return new Promise((resolve, reject) => {
+            const server = (0, http_1.createServer)(this.handleRequest.bind(this));
+            this.server = server;
+            // Track connections for proper cleanup
+            server.on('connection', (socket) => {
+                this.connections.add(socket);
+                socket.on('close', () => this.connections.delete(socket));
+            });
+            server.on('error', (err) => {
+                this.log(`Server error: ${err.message}`);
+                reject(err);
+            });
+            server.listen(port, () => {
+                const address = server.address();
+                if (!address || typeof address === 'string') {
+                    reject(new Error('Failed to get server address'));
+                    return;
+                }
+                const actualPort = address.port;
+                const issuer = this.options.issuer ?? `http://localhost:${actualPort}`;
+                this._info = {
+                    baseUrl: `http://localhost:${actualPort}`,
+                    port: actualPort,
+                    issuer,
+                    jwksUrl: `http://localhost:${actualPort}/.well-known/jwks.json`,
+                };
+                this.log(`Mock OAuth server started at ${this._info.baseUrl}`);
+                resolve(this._info);
+            });
+        });
+    }
+    /**
+     * Stop the mock OAuth server
+     */
+    async stop() {
+        const server = this.server;
+        if (!server) {
+            return;
+        }
+        // Destroy all active connections to allow server.close() to complete
+        for (const socket of this.connections) {
+            socket.destroy();
+        }
+        this.connections.clear();
+        return new Promise((resolve, reject) => {
+            server.close((err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    this.server = null;
+                    this._info = null;
+                    this.log('Mock OAuth server stopped');
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Get server info
+     */
+    get info() {
+        if (!this._info) {
+            throw new Error('Mock OAuth server is not running');
+        }
+        return this._info;
+    }
+    /**
+     * Get the token factory (for creating tokens)
+     */
+    getTokenFactory() {
+        return this.tokenFactory;
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // PRIVATE
+    // ═══════════════════════════════════════════════════════════════════
+    async handleRequest(req, res) {
+        const url = req.url ?? '/';
+        this.log(`${req.method} ${url}`);
+        // CORS headers
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        try {
+            if (url === '/.well-known/jwks.json' || url === '/.well-known/jwks') {
+                await this.handleJwks(req, res);
+            }
+            else if (url === '/.well-known/openid-configuration') {
+                await this.handleOidcConfig(req, res);
+            }
+            else if (url === '/.well-known/oauth-authorization-server') {
+                await this.handleOAuthMetadata(req, res);
+            }
+            else if (url === '/oauth/token') {
+                await this.handleTokenEndpoint(req, res);
+            }
+            else {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'not_found', error_description: 'Endpoint not found' }));
+            }
+        }
+        catch (error) {
+            this.log(`Error handling request: ${error}`);
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'server_error', error_description: 'Internal server error' }));
+        }
+    }
+    async handleJwks(_req, res) {
+        const jwks = await this.tokenFactory.getPublicJwks();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(jwks));
+        this.log('Served JWKS');
+    }
+    async handleOidcConfig(_req, res) {
+        const issuer = this._info?.issuer ?? 'http://localhost';
+        const config = {
+            issuer,
+            authorization_endpoint: `${issuer}/oauth/authorize`,
+            token_endpoint: `${issuer}/oauth/token`,
+            jwks_uri: `${issuer}/.well-known/jwks.json`,
+            response_types_supported: ['code', 'token'],
+            subject_types_supported: ['public'],
+            id_token_signing_alg_values_supported: ['RS256'],
+            scopes_supported: ['openid', 'profile', 'email'],
+            token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],
+            claims_supported: ['sub', 'iss', 'aud', 'exp', 'iat', 'email', 'name'],
+            grant_types_supported: ['authorization_code', 'refresh_token', 'client_credentials', 'anonymous'],
+        };
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(config));
+        this.log('Served OIDC configuration');
+    }
+    async handleOAuthMetadata(_req, res) {
+        const issuer = this._info?.issuer ?? 'http://localhost';
+        const metadata = {
+            issuer,
+            authorization_endpoint: `${issuer}/oauth/authorize`,
+            token_endpoint: `${issuer}/oauth/token`,
+            jwks_uri: `${issuer}/.well-known/jwks.json`,
+            response_types_supported: ['code', 'token'],
+            grant_types_supported: ['authorization_code', 'refresh_token', 'client_credentials', 'anonymous'],
+            token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],
+            scopes_supported: ['openid', 'profile', 'email', 'anonymous'],
+        };
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(metadata));
+        this.log('Served OAuth metadata');
+    }
+    async handleTokenEndpoint(req, res) {
+        // Parse request body
+        const body = await this.readBody(req);
+        const params = new URLSearchParams(body);
+        const grantType = params.get('grant_type');
+        if (grantType === 'anonymous') {
+            // Issue an anonymous token
+            const token = await this.tokenFactory.createAnonymousToken();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                access_token: token,
+                token_type: 'Bearer',
+                expires_in: 3600,
+            }));
+            this.log('Issued anonymous token');
+        }
+        else {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'unsupported_grant_type',
+                error_description: 'Only anonymous grant type is supported in mock server',
+            }));
+        }
+    }
+    readBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+            req.on('error', reject);
+        });
+    }
+    log(message) {
+        if (this.options.debug) {
+            console.log(`[MockOAuthServer] ${message}`);
+        }
+    }
+}
+exports.MockOAuthServer = MockOAuthServer;
+//# sourceMappingURL=mock-oauth-server.js.map

package/src/auth/mock-oauth-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-oauth-server.js","sourceRoot":"","sources":["../../../src/auth/mock-oauth-server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @file mock-oauth-server.ts\n * @description Mock OAuth server for testing transparent auth mode\n *\n * This module provides a mock OAuth/OIDC server that serves:\n * - JWKS endpoint for token verification\n * - OAuth metadata endpoint (optional)\n * - Token endpoint for anonymous tokens (optional)\n *\n * @example\n * ```typescript\n * import { MockOAuthServer, TestTokenFactory } from '@frontmcp/testing';\n *\n * const tokenFactory = new TestTokenFactory();\n * const oauthServer = new MockOAuthServer(tokenFactory);\n *\n * // Start the mock server\n * await oauthServer.start();\n *\n * // Configure your MCP server to use this mock\n * // IDP_PROVIDER_URL = oauthServer.baseUrl\n *\n * // Create tokens using the same factory\n * const token = await tokenFactory.createTestToken({ sub: 'user-123' });\n *\n * // Stop when done\n * await oauthServer.stop();\n * ```\n */\n\nimport { createServer, Server, IncomingMessage, ServerResponse } from 'http';\nimport type { TestTokenFactory } from './token-factory';\n\n// ═══════════════════════════════════════════════════════════════════\n// TYPES\n// ═══════════════════════════════════════════════════════════════════\n\nexport interface MockOAuthServerOptions {\n  /** Port to listen on (default: random available port) */\n  port?: number;\n  /** Issuer URL (default: http://localhost:{port}) */\n  issuer?: string;\n  /** Enable debug logging */\n  debug?: boolean;\n}\n\nexport interface MockOAuthServerInfo {\n  /** Base URL of the server */\n  baseUrl: string;\n  /** Port the server is listening on */\n  port: number;\n  /** Issuer URL */\n  issuer: string;\n  /** JWKS endpoint URL */\n  jwksUrl: string;\n}\n\n// ═══════════════════════════════════════════════════════════════════\n// MOCK OAUTH SERVER\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * Mock OAuth/OIDC server for testing transparent auth mode\n *\n * Serves JWKS from a TestTokenFactory so that MCP servers can\n * validate test tokens without connecting to a real IdP.\n */\nexport class MockOAuthServer {\n  private readonly tokenFactory: TestTokenFactory;\n  private readonly options: MockOAuthServerOptions;\n  private server: Server | null = null;\n  private _info: MockOAuthServerInfo | null = null;\n  private connections: Set<import('net').Socket> = new Set();\n\n  constructor(tokenFactory: TestTokenFactory, options: MockOAuthServerOptions = {}) {\n    this.tokenFactory = tokenFactory;\n    this.options = options;\n  }\n\n  /**\n   * Start the mock OAuth server\n   */\n  async start(): Promise<MockOAuthServerInfo> {\n    if (this.server) {\n      throw new Error('Mock OAuth server is already running');\n    }\n\n    const port = this.options.port ?? 0; // 0 = random available port\n\n    return new Promise((resolve, reject) => {\n      const server = createServer(this.handleRequest.bind(this));\n      this.server = server;\n\n      // Track connections for proper cleanup\n      server.on('connection', (socket) => {\n        this.connections.add(socket);\n        socket.on('close', () => this.connections.delete(socket));\n      });\n\n      server.on('error', (err) => {\n        this.log(`Server error: ${err.message}`);\n        reject(err);\n      });\n\n      server.listen(port, () => {\n        const address = server.address();\n        if (!address || typeof address === 'string') {\n          reject(new Error('Failed to get server address'));\n          return;\n        }\n\n        const actualPort = address.port;\n        const issuer = this.options.issuer ?? `http://localhost:${actualPort}`;\n\n        this._info = {\n          baseUrl: `http://localhost:${actualPort}`,\n          port: actualPort,\n          issuer,\n          jwksUrl: `http://localhost:${actualPort}/.well-known/jwks.json`,\n        };\n\n        this.log(`Mock OAuth server started at ${this._info.baseUrl}`);\n        resolve(this._info);\n      });\n    });\n  }\n\n  /**\n   * Stop the mock OAuth server\n   */\n  async stop(): Promise<void> {\n    const server = this.server;\n    if (!server) {\n      return;\n    }\n\n    // Destroy all active connections to allow server.close() to complete\n    for (const socket of this.connections) {\n      socket.destroy();\n    }\n    this.connections.clear();\n\n    return new Promise((resolve, reject) => {\n      server.close((err) => {\n        if (err) {\n          reject(err);\n        } else {\n          this.server = null;\n          this._info = null;\n          this.log('Mock OAuth server stopped');\n          resolve();\n        }\n      });\n    });\n  }\n\n  /**\n   * Get server info\n   */\n  get info(): MockOAuthServerInfo {\n    if (!this._info) {\n      throw new Error('Mock OAuth server is not running');\n    }\n    return this._info;\n  }\n\n  /**\n   * Get the token factory (for creating tokens)\n   */\n  getTokenFactory(): TestTokenFactory {\n    return this.tokenFactory;\n  }\n\n  // ═══════════════════════════════════════════════════════════════════\n  // PRIVATE\n  // ═══════════════════════════════════════════════════════════════════\n\n  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const url = req.url ?? '/';\n    this.log(`${req.method} ${url}`);\n\n    // CORS headers\n    res.setHeader('Access-Control-Allow-Origin', '*');\n    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');\n    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');\n\n    if (req.method === 'OPTIONS') {\n      res.writeHead(204);\n      res.end();\n      return;\n    }\n\n    try {\n      if (url === '/.well-known/jwks.json' || url === '/.well-known/jwks') {\n        await this.handleJwks(req, res);\n      } else if (url === '/.well-known/openid-configuration') {\n        await this.handleOidcConfig(req, res);\n      } else if (url === '/.well-known/oauth-authorization-server') {\n        await this.handleOAuthMetadata(req, res);\n      } else if (url === '/oauth/token') {\n        await this.handleTokenEndpoint(req, res);\n      } else {\n        res.writeHead(404, { 'Content-Type': 'application/json' });\n        res.end(JSON.stringify({ error: 'not_found', error_description: 'Endpoint not found' }));\n      }\n    } catch (error) {\n      this.log(`Error handling request: ${error}`);\n      res.writeHead(500, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify({ error: 'server_error', error_description: 'Internal server error' }));\n    }\n  }\n\n  private async handleJwks(_req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const jwks = await this.tokenFactory.getPublicJwks();\n    res.writeHead(200, { 'Content-Type': 'application/json' });\n    res.end(JSON.stringify(jwks));\n    this.log('Served JWKS');\n  }\n\n  private async handleOidcConfig(_req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const issuer = this._info?.issuer ?? 'http://localhost';\n    const config = {\n      issuer,\n      authorization_endpoint: `${issuer}/oauth/authorize`,\n      token_endpoint: `${issuer}/oauth/token`,\n      jwks_uri: `${issuer}/.well-known/jwks.json`,\n      response_types_supported: ['code', 'token'],\n      subject_types_supported: ['public'],\n      id_token_signing_alg_values_supported: ['RS256'],\n      scopes_supported: ['openid', 'profile', 'email'],\n      token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],\n      claims_supported: ['sub', 'iss', 'aud', 'exp', 'iat', 'email', 'name'],\n      grant_types_supported: ['authorization_code', 'refresh_token', 'client_credentials', 'anonymous'],\n    };\n\n    res.writeHead(200, { 'Content-Type': 'application/json' });\n    res.end(JSON.stringify(config));\n    this.log('Served OIDC configuration');\n  }\n\n  private async handleOAuthMetadata(_req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const issuer = this._info?.issuer ?? 'http://localhost';\n    const metadata = {\n      issuer,\n      authorization_endpoint: `${issuer}/oauth/authorize`,\n      token_endpoint: `${issuer}/oauth/token`,\n      jwks_uri: `${issuer}/.well-known/jwks.json`,\n      response_types_supported: ['code', 'token'],\n      grant_types_supported: ['authorization_code', 'refresh_token', 'client_credentials', 'anonymous'],\n      token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post', 'none'],\n      scopes_supported: ['openid', 'profile', 'email', 'anonymous'],\n    };\n\n    res.writeHead(200, { 'Content-Type': 'application/json' });\n    res.end(JSON.stringify(metadata));\n    this.log('Served OAuth metadata');\n  }\n\n  private async handleTokenEndpoint(req: IncomingMessage, res: ServerResponse): Promise<void> {\n    // Parse request body\n    const body = await this.readBody(req);\n    const params = new URLSearchParams(body);\n    const grantType = params.get('grant_type');\n\n    if (grantType === 'anonymous') {\n      // Issue an anonymous token\n      const token = await this.tokenFactory.createAnonymousToken();\n      res.writeHead(200, { 'Content-Type': 'application/json' });\n      res.end(\n        JSON.stringify({\n          access_token: token,\n          token_type: 'Bearer',\n          expires_in: 3600,\n        }),\n      );\n      this.log('Issued anonymous token');\n    } else {\n      res.writeHead(400, { 'Content-Type': 'application/json' });\n      res.end(\n        JSON.stringify({\n          error: 'unsupported_grant_type',\n          error_description: 'Only anonymous grant type is supported in mock server',\n        }),\n      );\n    }\n  }\n\n  private readBody(req: IncomingMessage): Promise<string> {\n    return new Promise((resolve, reject) => {\n      const chunks: Buffer[] = [];\n      req.on('data', (chunk) => chunks.push(chunk));\n      req.on('end', () => resolve(Buffer.concat(chunks).toString()));\n      req.on('error', reject);\n    });\n  }\n\n  private log(message: string): void {\n    if (this.options.debug) {\n      console.log(`[MockOAuthServer] ${message}`);\n    }\n  }\n}\n"]}

package/src/client/mcp-test-client.builder.d.ts

@@ -2,8 +2,9 @@
  * @file mcp-test-client.builder.ts
  * @description Builder pattern for creating McpTestClient instances
  */
-import type { McpTestClientConfig, TestTransportType, TestAuthConfig } from './mcp-test-client.types';
+import type { McpTestClientConfig, TestTransportType, TestAuthConfig, TestClientCapabilities } from './mcp-test-client.types';
 import { McpTestClient } from './mcp-test-client';
+import type { TestPlatformType } from '../platform/platform-types';
 /**
  * Builder for creating McpTestClient instances with fluent API
  *
@@ -61,6 +62,47 @@ export declare class McpTestClientBuilder {
         name: string;
         version: string;
     }): this;
+    /**
+     * 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();
+     * ```
+     */
+    withPlatform(platform: TestPlatformType): this;
+    /**
+     * 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+mcp'] }
+     *     }
+     *   })
+     *   .buildAndConnect();
+     * ```
+     */
+    withCapabilities(capabilities: TestClientCapabilities): this;
     /**
      * Build the McpTestClient instance (does not connect)
      */

package/src/client/mcp-test-client.builder.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpTestClientBuilder = void 0;
 const mcp_test_client_1 = require("./mcp-test-client");
+const platform_client_info_1 = require("../platform/platform-client-info");
 /**
  * Builder for creating McpTestClient instances with fluent API
  *
@@ -92,6 +93,57 @@ class McpTestClientBuilder {
         this.config.clientInfo = info;
         return this;
     }
+    /**
+     * 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();
+     * ```
+     */
+    withPlatform(platform) {
+        this.config.platform = platform;
+        // Auto-set clientInfo based on platform for User-Agent detection
+        this.config.clientInfo = (0, platform_client_info_1.getPlatformClientInfo)(platform);
+        // Auto-set capabilities based on platform (ext-apps requires io.modelcontextprotocol/ui)
+        this.config.capabilities = (0, platform_client_info_1.getPlatformCapabilities)(platform);
+        return this;
+    }
+    /**
+     * 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+mcp'] }
+     *     }
+     *   })
+     *   .buildAndConnect();
+     * ```
+     */
+    withCapabilities(capabilities) {
+        this.config.capabilities = capabilities;
+        return this;
+    }
     /**
      * Build the McpTestClient instance (does not connect)
      */

package/src/client/mcp-test-client.builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-test-client.builder.js","sourceRoot":"","sources":["../../../src/client/mcp-test-client.builder.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,uDAAkD;AAElD;;;;;;;;;;;;GAYG;AACH,MAAa,oBAAoB;IACvB,MAAM,CAAsB;IAEpC,YAAY,MAA2B;QACrC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAoB;QAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAa;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAA+B;QACzC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG;YACjB,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI;YACnB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;SACtD,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,SAA4B;QACxC,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,SAAiB;QAC3B,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,OAAO,GAAG,IAAI;QACtB,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,OAAO,GAAG,IAAI;QAC3B,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,mBAAmB,CAAC,OAAe;QACjC,IAAI,CAAC,MAAM,CAAC,eAAe,GAAG,OAAO,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,IAAuC;QACpD,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK;QACH,OAAO,IAAI,+BAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAnGD,oDAmGC","sourcesContent":["/**\n * @file mcp-test-client.builder.ts\n * @description Builder pattern for creating McpTestClient instances\n */\n\nimport type { McpTestClientConfig, TestTransportType, TestAuthConfig } from './mcp-test-client.types';\nimport { McpTestClient } from './mcp-test-client';\n\n/**\n * Builder for creating McpTestClient instances with fluent API\n *\n * @example\n * ```typescript\n * const client = await McpTestClient.create({ baseUrl: 'http://localhost:3003' })\n *   .withTransport('streamable-http')\n *   .withToken('my-jwt-token')\n *   .withTimeout(5000)\n *   .withDebug()\n *   .buildAndConnect();\n * ```\n */\nexport class McpTestClientBuilder {\n  private config: McpTestClientConfig;\n\n  constructor(config: McpTestClientConfig) {\n    this.config = { ...config };\n  }\n\n  /**\n   * Set the authentication configuration\n   */\n  withAuth(auth: TestAuthConfig): this {\n    this.config.auth = { ...this.config.auth, ...auth };\n    return this;\n  }\n\n  /**\n   * Set the bearer token for authentication\n   */\n  withToken(token: string): this {\n    this.config.auth = { ...this.config.auth, token };\n    return this;\n  }\n\n  /**\n   * Add custom headers to all requests\n   */\n  withHeaders(headers: Record<string, string>): this {\n    this.config.auth = {\n      ...this.config.auth,\n      headers: { ...this.config.auth?.headers, ...headers },\n    };\n    return this;\n  }\n\n  /**\n   * Set the transport type\n   */\n  withTransport(transport: TestTransportType): this {\n    this.config.transport = transport;\n    return this;\n  }\n\n  /**\n   * Set the request timeout in milliseconds\n   */\n  withTimeout(timeoutMs: number): this {\n    this.config.timeout = timeoutMs;\n    return this;\n  }\n\n  /**\n   * Enable debug logging\n   */\n  withDebug(enabled = true): this {\n    this.config.debug = enabled;\n    return this;\n  }\n\n  /**\n   * Enable public mode - skip authentication entirely.\n   * When true, no Authorization header is sent and anonymous token is not requested.\n   * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.\n   */\n  withPublicMode(enabled = true): this {\n    this.config.publicMode = enabled;\n    return this;\n  }\n\n  /**\n   * Set the MCP protocol version to request\n   */\n  withProtocolVersion(version: string): this {\n    this.config.protocolVersion = version;\n    return this;\n  }\n\n  /**\n   * Set the client info sent during initialization\n   */\n  withClientInfo(info: { name: string; version: string }): this {\n    this.config.clientInfo = info;\n    return this;\n  }\n\n  /**\n   * Build the McpTestClient instance (does not connect)\n   */\n  build(): McpTestClient {\n    return new McpTestClient(this.config);\n  }\n\n  /**\n   * Build the McpTestClient and connect to the server\n   */\n  async buildAndConnect(): Promise<McpTestClient> {\n    const client = this.build();\n    await client.connect();\n    return client;\n  }\n}\n"]}
+{"version":3,"file":"mcp-test-client.builder.js","sourceRoot":"","sources":["../../../src/client/mcp-test-client.builder.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @file mcp-test-client.builder.ts\n * @description Builder pattern for creating McpTestClient instances\n */\n\nimport type {\n  McpTestClientConfig,\n  TestTransportType,\n  TestAuthConfig,\n  TestClientCapabilities,\n} from './mcp-test-client.types';\nimport { McpTestClient } from './mcp-test-client';\nimport type { TestPlatformType } from '../platform/platform-types';\nimport { getPlatformClientInfo, getPlatformCapabilities } from '../platform/platform-client-info';\n\n/**\n * Builder for creating McpTestClient instances with fluent API\n *\n * @example\n * ```typescript\n * const client = await McpTestClient.create({ baseUrl: 'http://localhost:3003' })\n *   .withTransport('streamable-http')\n *   .withToken('my-jwt-token')\n *   .withTimeout(5000)\n *   .withDebug()\n *   .buildAndConnect();\n * ```\n */\nexport class McpTestClientBuilder {\n  private config: McpTestClientConfig;\n\n  constructor(config: McpTestClientConfig) {\n    this.config = { ...config };\n  }\n\n  /**\n   * Set the authentication configuration\n   */\n  withAuth(auth: TestAuthConfig): this {\n    this.config.auth = { ...this.config.auth, ...auth };\n    return this;\n  }\n\n  /**\n   * Set the bearer token for authentication\n   */\n  withToken(token: string): this {\n    this.config.auth = { ...this.config.auth, token };\n    return this;\n  }\n\n  /**\n   * Add custom headers to all requests\n   */\n  withHeaders(headers: Record<string, string>): this {\n    this.config.auth = {\n      ...this.config.auth,\n      headers: { ...this.config.auth?.headers, ...headers },\n    };\n    return this;\n  }\n\n  /**\n   * Set the transport type\n   */\n  withTransport(transport: TestTransportType): this {\n    this.config.transport = transport;\n    return this;\n  }\n\n  /**\n   * Set the request timeout in milliseconds\n   */\n  withTimeout(timeoutMs: number): this {\n    this.config.timeout = timeoutMs;\n    return this;\n  }\n\n  /**\n   * Enable debug logging\n   */\n  withDebug(enabled = true): this {\n    this.config.debug = enabled;\n    return this;\n  }\n\n  /**\n   * Enable public mode - skip authentication entirely.\n   * When true, no Authorization header is sent and anonymous token is not requested.\n   * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.\n   */\n  withPublicMode(enabled = true): this {\n    this.config.publicMode = enabled;\n    return this;\n  }\n\n  /**\n   * Set the MCP protocol version to request\n   */\n  withProtocolVersion(version: string): this {\n    this.config.protocolVersion = version;\n    return this;\n  }\n\n  /**\n   * Set the client info sent during initialization\n   */\n  withClientInfo(info: { name: string; version: string }): this {\n    this.config.clientInfo = info;\n    return this;\n  }\n\n  /**\n   * Set the platform type for testing platform-specific meta keys.\n   * Automatically configures clientInfo and capabilities for platform detection.\n   *\n   * Platform-specific behavior:\n   * - `openai`: Uses openai/* meta keys, sets User-Agent to \"ChatGPT/1.0\"\n   * - `ext-apps`: Uses ui/* meta keys per SEP-1865, sets io.modelcontextprotocol/ui capability\n   * - `claude`: Uses frontmcp/* + ui/* keys, sets User-Agent to \"claude-desktop/1.0\"\n   * - `cursor`: Uses frontmcp/* + ui/* keys, sets User-Agent to \"cursor/1.0\"\n   * - Other platforms follow similar patterns\n   *\n   * @example\n   * ```typescript\n   * const client = await McpTestClient.create({ baseUrl })\n   *   .withPlatform('openai')\n   *   .buildAndConnect();\n   *\n   * // ext-apps automatically sets the io.modelcontextprotocol/ui capability\n   * const extAppsClient = await McpTestClient.create({ baseUrl })\n   *   .withPlatform('ext-apps')\n   *   .buildAndConnect();\n   * ```\n   */\n  withPlatform(platform: TestPlatformType): this {\n    this.config.platform = platform;\n    // Auto-set clientInfo based on platform for User-Agent detection\n    this.config.clientInfo = getPlatformClientInfo(platform);\n    // Auto-set capabilities based on platform (ext-apps requires io.modelcontextprotocol/ui)\n    this.config.capabilities = getPlatformCapabilities(platform);\n    return this;\n  }\n\n  /**\n   * Set custom client capabilities for MCP initialization.\n   * Use this for fine-grained control over capabilities sent during initialization.\n   *\n   * @example\n   * ```typescript\n   * const client = await McpTestClient.create({ baseUrl })\n   *   .withCapabilities({\n   *     sampling: {},\n   *     experimental: {\n   *       'io.modelcontextprotocol/ui': { mimeTypes: ['text/html+mcp'] }\n   *     }\n   *   })\n   *   .buildAndConnect();\n   * ```\n   */\n  withCapabilities(capabilities: TestClientCapabilities): this {\n    this.config.capabilities = capabilities;\n    return this;\n  }\n\n  /**\n   * Build the McpTestClient instance (does not connect)\n   */\n  build(): McpTestClient {\n    return new McpTestClient(this.config);\n  }\n\n  /**\n   * Build the McpTestClient and connect to the server\n   */\n  async buildAndConnect(): Promise<McpTestClient> {\n    const client = this.build();\n    await client.connect();\n    return client;\n  }\n}\n"]}

package/src/client/mcp-test-client.js

@@ -21,6 +21,7 @@ const DEFAULT_CLIENT_INFO = {
 // MAIN CLIENT CLASS
 // ═══════════════════════════════════════════════════════════════════
 class McpTestClient {
+    // Platform and capabilities are optional - only set when testing platform-specific behavior
     config;
     transport = null;
     initResult = null;
@@ -49,16 +50,12 @@ class McpTestClient {
             debug: config.debug ?? false,
             protocolVersion: config.protocolVersion ?? DEFAULT_PROTOCOL_VERSION,
             clientInfo: config.clientInfo ?? DEFAULT_CLIENT_INFO,
+            platform: config.platform,
+            capabilities: config.capabilities,
         };
-        // In public mode, user is always anonymous (no token authentication)
-        if (config.publicMode) {
-            this._authState = {
-                isAnonymous: true,
-                scopes: [],
-            };
-        }
-        else if (config.auth?.token) {
-            // Parse auth state from config
+        // If a token is provided, user is authenticated (even in public mode)
+        // Public mode just means anonymous access is allowed, not that tokens are ignored
+        if (config.auth?.token) {
             this._authState = {
                 isAnonymous: false,
                 token: config.auth.token,
@@ -66,6 +63,7 @@ class McpTestClient {
                 user: this.parseUserFromToken(config.auth.token),
             };
         }
+        // Otherwise, user is anonymous (default _authState is already { isAnonymous: true, scopes: [] })
         // Initialize interceptor chain
         this._interceptors = new interceptor_1.DefaultInterceptorChain();
     }
@@ -598,11 +596,13 @@ class McpTestClient {
     // PRIVATE: MCP OPERATIONS
     // ═══════════════════════════════════════════════════════════════════
     async initialize() {
+        // Use configured capabilities or default to base capabilities
+        const capabilities = this.config.capabilities ?? {
+            sampling: {},
+        };
         return this.request('initialize', {
             protocolVersion: this.config.protocolVersion,
-            capabilities: {
-                sampling: {},
-            },
+            capabilities,
             clientInfo: this.config.clientInfo,
         });
     }
@@ -646,6 +646,7 @@ class McpTestClient {
                     publicMode: this.config.publicMode,
                     debug: this.config.debug,
                     interceptors: this._interceptors,
+                    clientInfo: this.config.clientInfo,
                 });
             case 'sse':
                 // TODO: Implement SSE transport
@@ -717,9 +718,16 @@ class McpTestClient {
     wrapToolResult(response) {
         const raw = response.data ?? { content: [] };
         const isError = !response.success || raw.isError === true;
-        // Check for Tool UI response - has structuredContent and ui/html in _meta
+        // Check for Tool UI response - has UI metadata in _meta
+        // Platform-specific HTML keys:
+        // - OpenAI: openai/html
+        // - ext-apps: ui/html
+        // - Others: frontmcp/html (+ ui/html for compatibility)
         const meta = raw._meta;
-        const hasUI = meta?.['ui/html'] !== undefined;
+        const hasUI = meta?.['ui/html'] !== undefined ||
+            meta?.['ui/component'] !== undefined ||
+            meta?.['openai/html'] !== undefined ||
+            meta?.['frontmcp/html'] !== undefined;
         const structuredContent = raw['structuredContent'];
         return {
             raw,