@gleanwork/mcp-server-tester 0.12.0

package/dist/index.d.cts

@@ -0,0 +1,3857 @@
+import { z, ZodType } from 'zod';
+import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import { OAuthClientMetadata, OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import * as oauth from 'oauth4webapi';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { CallToolResult, Tool, Implementation, ServerCapabilities, Resource, Prompt } from '@modelcontextprotocol/sdk/types.js';
+import { TestInfo, Expect } from '@playwright/test';
+import * as playwright_test from 'playwright/test';
+
+/**
+ * OAuth configuration for MCP authentication
+ */
+interface MCPOAuthConfig {
+    /**
+     * OAuth authorization server metadata URL
+     * (e.g., https://auth.example.com/.well-known/oauth-authorization-server)
+     */
+    serverUrl: string;
+    /**
+     * Scopes to request during authorization
+     */
+    scopes?: Array<string>;
+    /**
+     * Resource indicator (RFC 8707, required by MCP 2025-06-18 spec)
+     */
+    resource?: string;
+    /**
+     * Path to Playwright auth state file
+     * (e.g., playwright/.auth/oauth-state.json)
+     */
+    authStatePath?: string;
+    /**
+     * Client ID (if pre-registered; otherwise uses Dynamic Client Registration)
+     */
+    clientId?: string;
+    /**
+     * Client secret (for confidential clients)
+     */
+    clientSecret?: string;
+    /**
+     * Redirect URI for OAuth callback
+     */
+    redirectUri?: string;
+}
+/**
+ * Authentication configuration for MCP connections
+ */
+interface MCPAuthConfig {
+    /**
+     * Pre-acquired access token (simplest authentication mode)
+     */
+    accessToken?: string;
+    /**
+     * Full OAuth configuration for browser-based authentication
+     */
+    oauth?: MCPOAuthConfig;
+}
+/**
+ * MCP host capabilities that can be registered with the server
+ */
+interface MCPHostCapabilities {
+    /**
+     * Sampling capabilities (for LLM sampling)
+     */
+    sampling?: Record<string, unknown>;
+    /**
+     * Roots capabilities (for file system roots)
+     */
+    roots?: {
+        /**
+         * Whether the client can notify the server when roots change
+         */
+        listChanged: boolean;
+    };
+}
+/**
+ * Configuration for MCP client connection
+ *
+ * Supports both stdio (local) and HTTP (remote) transports
+ */
+interface MCPConfig {
+    /**
+     * Transport type
+     */
+    transport: 'http' | 'stdio';
+    /**
+     * Server URL (required when transport === 'http')
+     */
+    serverUrl?: string;
+    /**
+     * HTTP headers (optional for http transport, e.g., Authorization)
+     */
+    headers?: Record<string, string>;
+    /**
+     * Command to execute (required when transport === 'stdio')
+     */
+    command?: string;
+    /**
+     * Command arguments (optional for stdio)
+     */
+    args?: Array<string>;
+    /**
+     * Working directory for the command (optional for stdio)
+     */
+    cwd?: string;
+    /**
+     * Host capabilities to register with the server
+     */
+    capabilities?: MCPHostCapabilities;
+    /**
+     * Connection timeout in milliseconds
+     */
+    connectTimeoutMs?: number;
+    /**
+     * Request timeout in milliseconds
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Suppress stderr output from the server process (stdio only)
+     * When true, server stderr is ignored instead of inherited
+     */
+    quiet?: boolean;
+    /**
+     * Authentication configuration (optional for http transport)
+     */
+    auth?: MCPAuthConfig;
+}
+/**
+ * Union schema for MCPConfig (validates based on transport type)
+ */
+declare const MCPConfigSchema: z.ZodDiscriminatedUnion<"transport", [z.ZodObject<{
+    transport: z.ZodLiteral<"stdio">;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    cwd: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        sampling: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        roots: z.ZodOptional<z.ZodObject<{
+            listChanged: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            listChanged: boolean;
+        }, {
+            listChanged: boolean;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    }, {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    }>>;
+    connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    quiet: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    transport: "stdio";
+    command: string;
+    args?: string[] | undefined;
+    cwd?: string | undefined;
+    capabilities?: {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    } | undefined;
+    connectTimeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    quiet?: boolean | undefined;
+}, {
+    transport: "stdio";
+    command: string;
+    args?: string[] | undefined;
+    cwd?: string | undefined;
+    capabilities?: {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    } | undefined;
+    connectTimeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    quiet?: boolean | undefined;
+}>, z.ZodObject<{
+    transport: z.ZodLiteral<"http">;
+    serverUrl: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        sampling: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        roots: z.ZodOptional<z.ZodObject<{
+            listChanged: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            listChanged: boolean;
+        }, {
+            listChanged: boolean;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    }, {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    }>>;
+    connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    auth: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        accessToken: z.ZodOptional<z.ZodString>;
+        oauth: z.ZodOptional<z.ZodObject<{
+            serverUrl: z.ZodString;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            resource: z.ZodOptional<z.ZodString>;
+            authStatePath: z.ZodOptional<z.ZodString>;
+            clientId: z.ZodOptional<z.ZodString>;
+            clientSecret: z.ZodOptional<z.ZodString>;
+            redirectUri: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        }, {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        accessToken?: string | undefined;
+        oauth?: {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        } | undefined;
+    }, {
+        accessToken?: string | undefined;
+        oauth?: {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        } | undefined;
+    }>, {
+        accessToken?: string | undefined;
+        oauth?: {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        } | undefined;
+    }, {
+        accessToken?: string | undefined;
+        oauth?: {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    serverUrl: string;
+    transport: "http";
+    capabilities?: {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    } | undefined;
+    connectTimeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        accessToken?: string | undefined;
+        oauth?: {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    serverUrl: string;
+    transport: "http";
+    capabilities?: {
+        sampling?: Record<string, unknown> | undefined;
+        roots?: {
+            listChanged: boolean;
+        } | undefined;
+    } | undefined;
+    connectTimeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    headers?: Record<string, string> | undefined;
+    auth?: {
+        accessToken?: string | undefined;
+        oauth?: {
+            serverUrl: string;
+            scopes?: string[] | undefined;
+            resource?: string | undefined;
+            authStatePath?: string | undefined;
+            clientId?: string | undefined;
+            clientSecret?: string | undefined;
+            redirectUri?: string | undefined;
+        } | undefined;
+    } | undefined;
+}>]>;
+/**
+ * Validates an MCPConfig object
+ *
+ * @param config - The config to validate
+ * @returns The validated config
+ * @throws {z.ZodError} If validation fails
+ */
+declare function validateMCPConfig(config: unknown): MCPConfig;
+/**
+ * Type guard to check if a config is for stdio transport
+ */
+declare function isStdioConfig(config: MCPConfig): config is MCPConfig & {
+    transport: 'stdio';
+    command: string;
+};
+/**
+ * Type guard to check if a config is for HTTP transport
+ */
+declare function isHttpConfig(config: MCPConfig): config is MCPConfig & {
+    transport: 'http';
+    serverUrl: string;
+};
+
+/**
+ * Auth types for MCP OAuth integration
+ */
+/**
+ * Stored OAuth tokens
+ */
+interface StoredTokens {
+    /**
+     * OAuth access token
+     */
+    accessToken: string;
+    /**
+     * OAuth refresh token (if provided)
+     */
+    refreshToken?: string;
+    /**
+     * Token expiration timestamp (Unix milliseconds)
+     */
+    expiresAt?: number;
+    /**
+     * Token type (typically "Bearer")
+     */
+    tokenType: string;
+    /**
+     * Client ID that was used to obtain these tokens.
+     * Required for token refresh since refresh tokens are bound to the client.
+     */
+    clientId?: string;
+}
+/**
+ * Stored client information from Dynamic Client Registration
+ */
+interface StoredClientInfo {
+    /**
+     * Client ID from DCR
+     */
+    clientId: string;
+    /**
+     * Client secret from DCR (for confidential clients)
+     */
+    clientSecret?: string;
+    /**
+     * Client ID issued at timestamp
+     */
+    clientIdIssuedAt?: number;
+    /**
+     * Client secret expiration timestamp
+     */
+    clientSecretExpiresAt?: number;
+}
+/**
+ * Complete OAuth state persisted to disk for Playwright auth state pattern
+ */
+interface StoredOAuthState {
+    /**
+     * OAuth tokens
+     */
+    tokens?: StoredTokens;
+    /**
+     * DCR client information
+     */
+    clientInfo?: StoredClientInfo;
+    /**
+     * PKCE code verifier (used during authorization flow)
+     */
+    codeVerifier?: string;
+    /**
+     * OAuth state parameter (for CSRF protection)
+     */
+    state?: string;
+    /**
+     * Timestamp when this state was saved
+     */
+    savedAt: number;
+}
+/**
+ * Configuration for OAuth setup flow
+ */
+interface OAuthSetupConfig {
+    /**
+     * OAuth authorization server metadata URL
+     */
+    authServerUrl: string;
+    /**
+     * Scopes to request
+     */
+    scopes: Array<string>;
+    /**
+     * Resource indicator (RFC 8707)
+     */
+    resource?: string;
+    /**
+     * Login form selectors for automation
+     */
+    loginSelectors: {
+        /**
+         * Selector for username/email input field
+         */
+        usernameInput: string;
+        /**
+         * Selector for password input field
+         */
+        passwordInput: string;
+        /**
+         * Selector for login submit button
+         */
+        submitButton: string;
+        /**
+         * Selector for consent/authorize button (optional)
+         */
+        consentButton?: string;
+    };
+    /**
+     * Test user credentials
+     */
+    credentials: {
+        username: string;
+        password: string;
+    };
+    /**
+     * Path to save OAuth state file
+     */
+    outputPath: string;
+    /**
+     * Pre-registered client ID (optional, uses DCR if not provided)
+     */
+    clientId?: string;
+    /**
+     * Pre-registered client secret (optional)
+     */
+    clientSecret?: string;
+    /**
+     * Redirect URI for OAuth callback
+     */
+    redirectUri?: string;
+    /**
+     * Timeout for login flow in milliseconds (default: 30000)
+     */
+    timeoutMs?: number;
+}
+/**
+ * Result of token exchange or refresh
+ */
+interface TokenResult {
+    /**
+     * Access token
+     */
+    accessToken: string;
+    /**
+     * Token type (typically "Bearer")
+     */
+    tokenType: string;
+    /**
+     * Expires in seconds
+     */
+    expiresIn?: number;
+    /**
+     * Refresh token (if provided)
+     */
+    refreshToken?: string;
+    /**
+     * Granted scopes (space-separated)
+     */
+    scope?: string;
+}
+
+/**
+ * OAuth client provider implementation for MCP SDK
+ *
+ * Implements the MCP SDK's OAuthClientProvider interface using file-based storage
+ * for integration with Playwright's auth state pattern.
+ */
+
+/**
+ * Configuration for the Playwright OAuth client provider
+ */
+interface PlaywrightOAuthClientProviderConfig {
+    /**
+     * Path to the auth state file (e.g., playwright/.auth/oauth-state.json)
+     */
+    storagePath: string;
+    /**
+     * OAuth redirect URI for callback
+     */
+    redirectUri: string;
+    /**
+     * Client metadata for DCR or display
+     */
+    clientMetadata?: Partial<OAuthClientMetadata>;
+    /**
+     * Pre-registered client ID (if not using DCR)
+     */
+    clientId?: string;
+    /**
+     * Pre-registered client secret (if not using DCR)
+     */
+    clientSecret?: string;
+}
+/**
+ * OAuth client provider that implements the MCP SDK's OAuthClientProvider interface
+ *
+ * Uses file-based storage for integration with Playwright's auth state pattern.
+ * Auth state is persisted to disk so it can be reused across test runs.
+ *
+ * @example
+ * ```typescript
+ * const provider = new PlaywrightOAuthClientProvider({
+ *   storagePath: 'playwright/.auth/oauth-state.json',
+ *   redirectUri: 'http://localhost:3000/callback',
+ * });
+ *
+ * const transport = new StreamableHTTPClientTransport(serverUrl, {
+ *   authProvider: provider,
+ * });
+ * ```
+ */
+declare class PlaywrightOAuthClientProvider implements OAuthClientProvider {
+    private readonly config;
+    private cachedState;
+    private stateParam;
+    constructor(config: PlaywrightOAuthClientProviderConfig);
+    /**
+     * The URL to redirect the user agent to after authorization
+     */
+    get redirectUrl(): string;
+    /**
+     * Metadata about this OAuth client
+     */
+    get clientMetadata(): OAuthClientMetadata;
+    /**
+     * Returns an OAuth2 state parameter
+     */
+    state(): string;
+    /**
+     * Loads information about this OAuth client
+     */
+    clientInformation(): Promise<OAuthClientInformationFull | undefined>;
+    /**
+     * Saves client information from Dynamic Client Registration
+     */
+    saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>;
+    /**
+     * Loads any existing OAuth tokens for the current session
+     */
+    tokens(): Promise<OAuthTokens | undefined>;
+    /**
+     * Stores new OAuth tokens for the current session
+     */
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * Invoked to redirect the user agent to the given URL
+     *
+     * In a testing context, this is typically handled by Playwright automation.
+     * This implementation throws an error to signal that the caller needs to
+     * handle the redirect externally.
+     */
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /**
+     * Saves a PKCE code verifier for the current session
+     */
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    /**
+     * Loads the PKCE code verifier for the current session
+     */
+    codeVerifier(): Promise<string>;
+    /**
+     * Invalidates the specified credentials
+     */
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier'): Promise<void>;
+    private loadState;
+    private saveState;
+    private deleteState;
+    private createEmptyState;
+    private generateRandomString;
+}
+
+/**
+ * Static token authentication utilities
+ *
+ * Simple utilities for pre-acquired token authentication
+ */
+/**
+ * Creates HTTP headers for static token authentication
+ *
+ * @param accessToken - The pre-acquired access token
+ * @param tokenType - The token type (default: "Bearer")
+ * @returns HTTP headers with Authorization header
+ *
+ * @example
+ * ```typescript
+ * const headers = createTokenAuthHeaders(process.env.MCP_ACCESS_TOKEN);
+ * // { Authorization: 'Bearer eyJ...' }
+ * ```
+ */
+declare function createTokenAuthHeaders(accessToken: string, tokenType?: string): Record<string, string>;
+/**
+ * Validates that an access token is present and non-empty
+ *
+ * @param accessToken - The access token to validate
+ * @throws Error if token is missing or empty
+ */
+declare function validateAccessToken(accessToken: string | undefined): void;
+/**
+ * Checks if a token appears to be expired based on common JWT structure
+ *
+ * Note: This is a best-effort check and may not work for all token formats.
+ * For reliable expiration checking, use the token's associated expiration time.
+ *
+ * @param accessToken - The access token to check
+ * @returns true if the token appears to be expired, false otherwise
+ */
+declare function isTokenExpired(accessToken: string): boolean;
+/**
+ * Checks if a token will expire within the specified buffer time
+ *
+ * @param expiresAt - Token expiration timestamp in milliseconds
+ * @param bufferMs - Buffer time in milliseconds (default: 60000 = 1 minute)
+ * @returns true if the token will expire within the buffer time
+ */
+declare function isTokenExpiringSoon(expiresAt: number | undefined, bufferMs?: number): boolean;
+
+/**
+ * OAuth setup utility for Playwright globalSetup
+ *
+ * Performs the browser-based OAuth flow and saves the auth state
+ * for reuse across tests following Playwright's auth state pattern.
+ */
+
+/**
+ * Performs the OAuth authorization flow using Playwright browser automation
+ *
+ * This function is designed to be used in Playwright's globalSetup to
+ * authenticate once before running tests. The resulting auth state is
+ * saved to disk and reused across tests.
+ *
+ * @param config - OAuth setup configuration
+ *
+ * @example
+ * ```typescript
+ * // global-setup.ts
+ * import { performOAuthSetup } from '@gleanwork/mcp-server-tester';
+ *
+ * export default async function globalSetup() {
+ *   await performOAuthSetup({
+ *     authServerUrl: 'https://auth.example.com',
+ *     scopes: ['mcp:read', 'mcp:write'],
+ *     loginSelectors: {
+ *       usernameInput: '#username',
+ *       passwordInput: '#password',
+ *       submitButton: 'button[type="submit"]',
+ *     },
+ *     credentials: {
+ *       username: process.env.TEST_USER!,
+ *       password: process.env.TEST_PASSWORD!,
+ *     },
+ *     outputPath: 'playwright/.auth/oauth-state.json',
+ *   });
+ * }
+ * ```
+ */
+declare function performOAuthSetup(config: OAuthSetupConfig): Promise<void>;
+/**
+ * Performs OAuth setup only if valid state doesn't already exist
+ *
+ * Use this in globalSetup to avoid re-authenticating on every test run.
+ *
+ * @param config - OAuth setup configuration
+ *
+ * @example
+ * ```typescript
+ * // global-setup.ts
+ * export default async function globalSetup() {
+ *   await performOAuthSetupIfNeeded({
+ *     authServerUrl: 'https://auth.example.com',
+ *     scopes: ['mcp:read'],
+ *     loginSelectors: { ... },
+ *     credentials: { ... },
+ *     outputPath: 'playwright/.auth/oauth-state.json',
+ *   });
+ * }
+ * ```
+ */
+declare function performOAuthSetupIfNeeded(config: OAuthSetupConfig): Promise<void>;
+
+/**
+ * OAuth flow utilities using oauth4webapi
+ *
+ * Implements OAuth 2.1 with PKCE as required by MCP specification
+ */
+
+/**
+ * Discovered OAuth authorization server metadata
+ */
+interface AuthServerMetadata {
+    /**
+     * The oauth4webapi AuthorizationServer object
+     */
+    server: oauth.AuthorizationServer;
+    /**
+     * Issuer URL
+     */
+    issuer: string;
+}
+
+/**
+ * OAuth Protected Resource and Authorization Server discovery
+ *
+ * Implements RFC 9728 (OAuth Protected Resource Metadata) and
+ * RFC 8414 (Authorization Server Metadata) for MCP servers.
+ */
+
+/**
+ * MCP Protocol version header value
+ */
+declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * Protected Resource Metadata (RFC 9728)
+ */
+interface ProtectedResourceMetadata {
+    /**
+     * The protected resource URL
+     */
+    resource: string;
+    /**
+     * Array of authorization server URLs
+     */
+    authorization_servers?: Array<string>;
+    /**
+     * Scopes supported by the protected resource
+     */
+    scopes_supported?: Array<string>;
+    /**
+     * Bearer token formats supported
+     */
+    bearer_methods_supported?: Array<string>;
+    /**
+     * Resource documentation URL
+     */
+    resource_documentation?: string;
+    /**
+     * Resource signing algorithms
+     */
+    resource_signing_alg_values_supported?: Array<string>;
+}
+/**
+ * Result of protected resource discovery
+ */
+interface ProtectedResourceDiscoveryResult {
+    /**
+     * The discovered metadata
+     */
+    metadata: ProtectedResourceMetadata;
+    /**
+     * The URL where metadata was found
+     */
+    discoveryUrl: string;
+    /**
+     * Whether path-aware discovery was used (vs base discovery)
+     */
+    usedPathAwareDiscovery: boolean;
+}
+/**
+ * Discovers protected resource metadata per RFC 9728
+ *
+ * Follows RFC 9728 Section 4.1 for path-aware discovery:
+ * 1. First tries: {origin}/.well-known/oauth-protected-resource{pathname}
+ * 2. Falls back to: {origin}/.well-known/oauth-protected-resource
+ *
+ * @param mcpServerUrl - The MCP server URL
+ * @returns Protected resource discovery result
+ * @throws Error if discovery fails completely
+ *
+ * @example
+ * const result = await discoverProtectedResource('https://api.example.com/mcp/default');
+ * console.log(result.metadata.authorization_servers);
+ */
+declare function discoverProtectedResource(mcpServerUrl: string): Promise<ProtectedResourceDiscoveryResult>;
+/**
+ * Error thrown when discovery fails
+ */
+declare class DiscoveryError extends Error {
+    readonly status?: number | undefined;
+    readonly url?: string | undefined;
+    constructor(message: string, status?: number | undefined, url?: string | undefined);
+}
+/**
+ * Discovers OAuth Authorization Server metadata per RFC 8414
+ *
+ * Wraps oauth4webapi's discovery with MCP-specific headers.
+ *
+ * @param authServerUrl - The authorization server URL
+ * @returns Authorization server metadata
+ * @throws Error if discovery fails
+ *
+ * @example
+ * const authServer = await discoverAuthorizationServer('https://auth.example.com');
+ * console.log(authServer.server.token_endpoint);
+ */
+declare function discoverAuthorizationServer(authServerUrl: string): Promise<AuthServerMetadata>;
+
+/**
+ * OAuth token storage with environment variable support for CI/CD
+ *
+ * Provides file-based storage for OAuth state per MCP server, with support
+ * for token injection via environment variables for automated testing.
+ */
+
+/**
+ * Combined server metadata (auth server + protected resource)
+ */
+interface StoredServerMetadata {
+    /**
+     * Authorization server metadata
+     */
+    authServer: AuthServerMetadata;
+    /**
+     * Protected resource metadata
+     */
+    protectedResource: ProtectedResourceMetadata;
+    /**
+     * Timestamp when metadata was discovered
+     */
+    discoveredAt: number;
+}
+/**
+ * Environment variable names for CI/CD token injection
+ */
+declare const ENV_VAR_NAMES: {
+    readonly accessToken: "MCP_ACCESS_TOKEN";
+    readonly refreshToken: "MCP_REFRESH_TOKEN";
+    readonly tokenType: "MCP_TOKEN_TYPE";
+    readonly expiresAt: "MCP_TOKEN_EXPIRES_AT";
+};
+/**
+ * Reads tokens from environment variables (for CI/CD)
+ *
+ * @returns StoredTokens if MCP_ACCESS_TOKEN is set, null otherwise
+ */
+declare function loadTokensFromEnv(): StoredTokens | null;
+/**
+ * Programmatically inject tokens into storage (for CI/CD setup)
+ *
+ * @param serverUrl - The MCP server URL
+ * @param tokens - The tokens to inject
+ * @param stateDir - Optional custom state directory
+ */
+declare function injectTokens(serverUrl: string, tokens: StoredTokens, stateDir?: string): Promise<void>;
+/**
+ * Load stored OAuth tokens for an MCP server
+ *
+ * Reads tokens from the standard storage location for the given server URL.
+ * Tokens are stored by `mcp-server-tester login` or `injectTokens()`.
+ *
+ * @param serverUrl - The MCP server URL
+ * @param stateDir - Optional custom state directory
+ * @returns StoredTokens if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // After running: npx mcp-server-tester login https://api.example.com/mcp
+ * const tokens = await loadTokens('https://api.example.com/mcp');
+ * if (tokens) {
+ *   console.log('Access token:', tokens.accessToken);
+ * }
+ * ```
+ */
+declare function loadTokens(serverUrl: string, stateDir?: string): Promise<StoredTokens | null>;
+/**
+ * Check if valid OAuth tokens exist for an MCP server
+ *
+ * Returns true if tokens exist and are not expired (with buffer).
+ * Use this to check if authentication is needed before making requests.
+ *
+ * @param serverUrl - The MCP server URL
+ * @param options - Optional configuration
+ * @param options.stateDir - Custom state directory
+ * @param options.bufferMs - Buffer time before expiration (default: 60000ms)
+ * @returns true if valid (non-expired) tokens exist
+ *
+ * @example
+ * ```typescript
+ * if (await hasValidTokens('https://api.example.com/mcp')) {
+ *   // Use stored tokens
+ *   const tokens = await loadTokens('https://api.example.com/mcp');
+ * } else {
+ *   console.log('Run: npx mcp-server-tester login https://api.example.com/mcp');
+ * }
+ * ```
+ */
+declare function hasValidTokens(serverUrl: string, options?: {
+    stateDir?: string;
+    bufferMs?: number;
+}): Promise<boolean>;
+
+/**
+ * CLI OAuth client for command-line authentication flows
+ *
+ * Provides browser-based OAuth authentication for CLI environments,
+ * with support for environment variable token injection for CI/CD.
+ */
+/**
+ * Configuration for CLI OAuth client
+ */
+interface CLIOAuthClientConfig {
+    /**
+     * MCP server URL (for protected resource discovery)
+     */
+    mcpServerUrl: string;
+    /**
+     * Scopes to request (optional, uses discovered scopes if not provided)
+     */
+    scopes?: Array<string>;
+    /**
+     * Custom storage directory
+     */
+    stateDir?: string;
+    /**
+     * Pre-registered client ID (skips DCR if provided)
+     */
+    clientId?: string;
+    /**
+     * Pre-registered client secret
+     */
+    clientSecret?: string;
+    /**
+     * Preferred callback port (default: random available port)
+     */
+    callbackPort?: number;
+    /**
+     * Timeout for OAuth flow in milliseconds (default: 300000 = 5 min)
+     */
+    timeoutMs?: number;
+    /**
+     * Client name for DCR registration
+     */
+    clientName?: string;
+}
+/**
+ * Result of CLI OAuth authentication
+ */
+interface CLIOAuthResult {
+    /**
+     * Access token
+     */
+    accessToken: string;
+    /**
+     * Token type (typically "Bearer")
+     */
+    tokenType: string;
+    /**
+     * Expiration timestamp (Unix ms)
+     */
+    expiresAt?: number;
+    /**
+     * Whether token was refreshed vs newly acquired
+     */
+    refreshed: boolean;
+    /**
+     * Scopes that were requested (only set for new authentications)
+     */
+    requestedScopes?: string[];
+    /**
+     * Whether token came from environment variables
+     */
+    fromEnv: boolean;
+}
+/**
+ * CLI OAuth client for command-line authentication flows
+ */
+declare class CLIOAuthClient {
+    private readonly config;
+    private readonly storage;
+    constructor(config: CLIOAuthClientConfig);
+    /**
+     * Get a valid access token, authenticating if necessary
+     *
+     * Token resolution priority:
+     * 1. Check environment variables (for CI/CD)
+     * 2. Check file storage for cached tokens
+     * 3. Try to refresh if expired but refresh token exists
+     * 4. Run full OAuth flow if needed
+     */
+    getAccessToken(): Promise<CLIOAuthResult>;
+    /**
+     * Try to get a valid access token without triggering browser auth
+     *
+     * Returns null if no valid token is available (no stored tokens,
+     * expired without refresh token, or refresh failed). Unlike getAccessToken(),
+     * this will NOT open a browser for authentication.
+     *
+     * Use this for CLI commands that should prompt the user to run `login`
+     * instead of automatically starting the OAuth flow.
+     */
+    tryGetAccessToken(): Promise<CLIOAuthResult | null>;
+    /**
+     * Force a new authentication flow
+     */
+    authenticate(): Promise<CLIOAuthResult>;
+    /**
+     * Check if stored credentials exist (may be expired)
+     */
+    hasStoredCredentials(): Promise<boolean>;
+    /**
+     * Clear stored credentials
+     */
+    clearCredentials(): Promise<void>;
+    /**
+     * Discover protected resource and authorization server
+     */
+    private discoverServers;
+    /**
+     * Get existing client or register new one via DCR
+     */
+    private getOrRegisterClient;
+    /**
+     * Register a new client via Dynamic Client Registration
+     */
+    private registerClient;
+    /**
+     * Perform the full OAuth authorization flow
+     */
+    private performOAuthFlow;
+    /**
+     * Refresh an expired token
+     *
+     * Uses the clientId stored with the tokens (if available) to ensure
+     * the refresh request uses the same client that obtained the original tokens.
+     * This is important because refresh tokens are bound to the client_id.
+     */
+    private refreshStoredToken;
+    /**
+     * Start local callback server
+     */
+    private startCallbackServer;
+    /**
+     * Open browser or print URL for headless environments
+     */
+    private openBrowserOrPrintUrl;
+    /**
+     * Convert TokenResult to StoredTokens
+     *
+     * @param result - Token result from exchange or refresh
+     * @param clientId - Client ID that was used to obtain these tokens
+     */
+    private tokenResultToStoredTokens;
+    /**
+     * HTML page for successful authentication
+     */
+    private successHtml;
+    /**
+     * HTML page for authentication error
+     */
+    private errorHtml;
+}
+
+/**
+ * Options for creating an MCP client
+ */
+interface CreateMCPClientOptions {
+    /**
+     * Client information (name and version)
+     */
+    clientInfo?: {
+        name?: string;
+        version?: string;
+    };
+    /**
+     * OAuth client provider for authentication
+     *
+     * When provided, the MCP SDK handles OAuth flow automatically.
+     * This takes precedence over static token auth in config.auth.accessToken.
+     */
+    authProvider?: OAuthClientProvider;
+}
+/**
+ * Creates and connects an MCP client based on the provided configuration
+ *
+ * @param config - MCP configuration (will be validated)
+ * @param options - Optional client options including auth provider
+ * @returns Connected MCP Client instance
+ * @throws {Error} If config is invalid or connection fails
+ *
+ * @example
+ * // Stdio transport
+ * const client = await createMCPClientForConfig({
+ *   transport: 'stdio',
+ *   command: 'node',
+ *   args: ['server.js']
+ * });
+ *
+ * @example
+ * // HTTP transport with static token auth
+ * const client = await createMCPClientForConfig({
+ *   transport: 'http',
+ *   serverUrl: 'http://localhost:3000/mcp',
+ *   auth: { accessToken: 'your-token' }
+ * });
+ *
+ * @example
+ * // HTTP transport with OAuth provider
+ * const client = await createMCPClientForConfig(
+ *   { transport: 'http', serverUrl: 'http://localhost:3000/mcp' },
+ *   { authProvider: myOAuthProvider }
+ * );
+ */
+declare function createMCPClientForConfig(config: MCPConfig, options?: CreateMCPClientOptions): Promise<Client>;
+/**
+ * Safely closes an MCP client connection
+ *
+ * @param client - The client to close
+ */
+declare function closeMCPClient(client: Client): Promise<void>;
+
+/**
+ * A single content block from an MCP response
+ */
+interface ContentBlock {
+    type: string;
+    text?: string;
+    data?: unknown;
+    mimeType?: string;
+}
+/**
+ * Normalized representation of an MCP tool response
+ *
+ * This provides a consistent interface regardless of the response format
+ * returned by the MCP server.
+ */
+interface NormalizedToolResponse {
+    /**
+     * Extracted text content (concatenated from all text blocks)
+     */
+    text: string;
+    /**
+     * Original raw response from the MCP SDK
+     */
+    raw: CallToolResult;
+    /**
+     * Whether the tool call resulted in an error
+     */
+    isError: boolean;
+    /**
+     * Parsed content blocks from the response
+     */
+    contentBlocks: ContentBlock[];
+    /**
+     * Structured content if present (parsed JSON or raw data)
+     */
+    structuredContent: unknown;
+}
+/**
+ * Normalizes an MCP CallToolResult into a consistent format
+ *
+ * @param result - Raw CallToolResult from the MCP SDK
+ * @returns Normalized response with extracted text, content blocks, etc.
+ *
+ * @example
+ * ```typescript
+ * const result = await client.callTool({ name: 'read_file', arguments: { path: 'readme.txt' } });
+ * const normalized = normalizeToolResponse(result);
+ *
+ * console.log(normalized.text);           // "Hello World"
+ * console.log(normalized.isError);        // false
+ * console.log(normalized.contentBlocks);  // [{ type: 'text', text: 'Hello World' }]
+ * ```
+ */
+declare function normalizeToolResponse(result: CallToolResult): NormalizedToolResponse;
+/**
+ * Extracts just the text content from a normalized or raw response
+ *
+ * This is a convenience function that works with both:
+ * - Raw CallToolResult from the MCP SDK
+ * - NormalizedToolResponse from normalizeToolResponse()
+ * - Plain strings or other legacy formats
+ *
+ * @param response - Response in any supported format
+ * @returns Extracted text content
+ */
+declare function extractText(response: unknown): string;
+
+/**
+ * Validator Types
+ *
+ * Core types for the unified assertion architecture.
+ * These types are used by both Playwright matchers and the eval runner.
+ */
+
+/**
+ * Result of a validation operation
+ */
+interface ValidationResult {
+    /** Whether the validation passed */
+    pass: boolean;
+    /** Human-readable message explaining the result */
+    message: string;
+    /** Additional structured details about the validation */
+    details?: Record<string, unknown>;
+}
+/**
+ * Options for text validation
+ */
+interface TextValidatorOptions {
+    /** Whether to perform case-sensitive matching (default: true) */
+    caseSensitive?: boolean;
+}
+/**
+ * Options for response size validation
+ */
+interface SizeValidatorOptions {
+    /** Maximum allowed size in bytes */
+    maxBytes?: number;
+    /** Minimum required size in bytes */
+    minBytes?: number;
+}
+/**
+ * Options for schema validation
+ */
+interface SchemaValidatorOptions {
+    /** Whether to use strict mode (fail on extra properties) */
+    strict?: boolean;
+}
+/**
+ * Options for pattern validation
+ */
+interface PatternValidatorOptions {
+    /** Whether to perform case-sensitive matching (default: true) */
+    caseSensitive?: boolean;
+}
+/**
+ * Built-in sanitizer names for common variable patterns
+ */
+type BuiltInSanitizer = 'timestamp' | 'uuid' | 'iso-date' | 'objectId' | 'jwt';
+/**
+ * Custom regex-based sanitizer
+ */
+interface RegexSanitizer {
+    /** Regex pattern to match */
+    pattern: string | RegExp;
+    /** Replacement string (default: "[SANITIZED]") */
+    replacement?: string;
+}
+/**
+ * Field removal sanitizer - removes specified fields from objects
+ */
+interface FieldRemovalSanitizer {
+    /** Field paths to remove (supports dot notation for nested fields) */
+    remove: string[];
+}
+/**
+ * Snapshot sanitizer configuration
+ *
+ * Sanitizers transform response data before snapshot comparison,
+ * allowing variable content (timestamps, IDs, etc.) to be normalized.
+ *
+ * Can be:
+ * - A built-in sanitizer name: 'timestamp', 'uuid', 'iso-date', 'objectId', 'jwt'
+ * - A regex sanitizer: { pattern: /regex/, replacement: '[REPLACED]' }
+ * - A field removal sanitizer: { remove: ['field1', 'nested.field'] }
+ */
+type SnapshotSanitizer = BuiltInSanitizer | RegexSanitizer | FieldRemovalSanitizer;
+/**
+ * Schema registry for named schemas in datasets
+ */
+type SchemaRegistry = Record<string, ZodType>;
+
+/**
+ * Response Validator
+ *
+ * Validates that a response exactly matches an expected value.
+ */
+
+/**
+ * Validates that a response exactly matches the expected value
+ *
+ * Performs deep equality comparison using JSON serialization.
+ *
+ * @param actual - The actual response
+ * @param expected - The expected response
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateResponse(response, { status: 'ok', count: 42 });
+ * if (!result.pass) {
+ *   console.log(result.message);
+ * }
+ * ```
+ */
+declare function validateResponse(actual: unknown, expected: unknown): ValidationResult;
+
+/**
+ * Schema Validator
+ *
+ * Validates that a response matches a Zod schema.
+ */
+
+/**
+ * Validates that a response matches a Zod schema
+ *
+ * Attempts to parse the response with the provided Zod schema.
+ * If the response is a text representation of JSON, it will be parsed first.
+ *
+ * @param response - The response to validate
+ * @param schema - The Zod schema to validate against
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const WeatherSchema = z.object({
+ *   temperature: z.number(),
+ *   conditions: z.string(),
+ * });
+ *
+ * const result = validateSchema(response, WeatherSchema);
+ * if (!result.pass) {
+ *   console.log(result.message);
+ * }
+ * ```
+ */
+declare function validateSchema(response: unknown, schema: ZodType, options?: SchemaValidatorOptions): ValidationResult;
+
+/**
+ * Text Validator
+ *
+ * Validates that a response contains expected text substrings.
+ */
+
+/**
+ * Validates that a response contains all expected text substrings
+ *
+ * Extracts text from the response and checks that each expected substring
+ * is present. By default, matching is case-sensitive.
+ *
+ * @param response - The response to validate
+ * @param expected - Expected substring(s) to find
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateText(response, ['temperature', 'conditions']);
+ * if (!result.pass) {
+ *   console.log(result.message);
+ * }
+ *
+ * // Case-insensitive matching
+ * const result2 = validateText(response, 'HELLO', { caseSensitive: false });
+ * ```
+ */
+declare function validateText(response: unknown, expected: string | string[], options?: TextValidatorOptions): ValidationResult;
+
+/**
+ * Pattern Validator
+ *
+ * Validates that a response matches regex patterns.
+ */
+
+/**
+ * Validates that a response matches all expected regex patterns
+ *
+ * Extracts text from the response and checks that each pattern matches.
+ * Patterns can be strings (which are compiled to RegExp) or RegExp objects.
+ *
+ * @param response - The response to validate
+ * @param patterns - Expected pattern(s) to match
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * // String pattern
+ * const result = validatePattern(response, 'temperature: \\d+');
+ *
+ * // RegExp pattern
+ * const result2 = validatePattern(response, /temperature: \d+/);
+ *
+ * // Multiple patterns
+ * const result3 = validatePattern(response, [
+ *   /temperature: \d+/,
+ *   /humidity: \d+%/,
+ * ]);
+ *
+ * // Case-insensitive matching
+ * const result4 = validatePattern(response, 'HELLO', { caseSensitive: false });
+ * ```
+ */
+declare function validatePattern(response: unknown, patterns: string | RegExp | (string | RegExp)[], options?: PatternValidatorOptions): ValidationResult;
+
+/**
+ * Error Validator
+ *
+ * Validates error response behavior.
+ */
+
+/**
+ * Validates that a response is (or is not) an error
+ *
+ * Can check for:
+ * - Any error (expected = true)
+ * - No error (expected = false)
+ * - Error with specific message(s) (expected = string or string[])
+ *
+ * @param response - The response to validate
+ * @param expected - What to expect (true for any error, false for no error, string for specific message)
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * // Expect any error
+ * const result = validateError(response, true);
+ *
+ * // Expect no error
+ * const result2 = validateError(response, false);
+ *
+ * // Expect error with specific message
+ * const result3 = validateError(response, 'File not found');
+ *
+ * // Expect error containing one of several messages
+ * const result4 = validateError(response, ['not found', 'does not exist']);
+ * ```
+ */
+declare function validateError(response: unknown, expected?: boolean | string | string[]): ValidationResult;
+
+/**
+ * Size Validator
+ *
+ * Validates that a response meets size constraints.
+ */
+
+/**
+ * Validates that a response meets size constraints
+ *
+ * Checks that the response size in bytes is within the specified bounds.
+ * At least one of minBytes or maxBytes must be provided.
+ *
+ * @param response - The response to validate
+ * @param options - Size constraints
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * // Maximum size check
+ * const result = validateSize(response, { maxBytes: 10000 });
+ *
+ * // Minimum size check
+ * const result2 = validateSize(response, { minBytes: 100 });
+ *
+ * // Both bounds
+ * const result3 = validateSize(response, { minBytes: 100, maxBytes: 10000 });
+ * ```
+ */
+declare function validateSize(response: unknown, options: SizeValidatorOptions): ValidationResult;
+
+/**
+ * Validator Utilities
+ *
+ * Shared utility functions for validation operations.
+ * Re-exports core utilities from mcp/response.ts and adds validation-specific helpers.
+ */
+
+/**
+ * Gets the size of a response in bytes
+ *
+ * Serializes the response to JSON (with pretty printing for consistency)
+ * and returns the byte length using UTF-8 encoding.
+ *
+ * @param response - Response in any format
+ * @returns Size in bytes
+ */
+declare function getResponseSizeBytes(response: unknown): number;
+/**
+ * Normalizes whitespace in text for consistent comparison
+ *
+ * Collapses multiple whitespace characters (spaces, tabs, newlines) into single spaces
+ * and trims leading/trailing whitespace.
+ *
+ * @param text - Text to normalize
+ * @returns Normalized text with collapsed whitespace
+ *
+ * @example
+ * ```typescript
+ * normalizeWhitespace('  hello\n\n  world  ');
+ * // Returns: "hello world"
+ * ```
+ */
+declare function normalizeWhitespace(text: string): string;
+
+/**
+ * Usage metrics from Claude Agent SDK response
+ */
+interface UsageMetrics {
+    /**
+     * Number of input tokens consumed
+     */
+    inputTokens: number;
+    /**
+     * Number of output tokens generated
+     */
+    outputTokens: number;
+    /**
+     * Total cost in USD
+     */
+    totalCostUsd: number;
+    /**
+     * Execution duration in milliseconds
+     */
+    durationMs: number;
+    /**
+     * API call duration in milliseconds (excluding network overhead)
+     */
+    durationApiMs?: number;
+    /**
+     * Number of tokens read from cache
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Number of tokens written to cache
+     */
+    cacheCreationInputTokens?: number;
+}
+/**
+ * Supported LLM provider types
+ */
+type ProviderKind = 'claude' | 'anthropic' | 'openai' | 'custom-http';
+/**
+ * Configuration for an LLM judge
+ */
+interface JudgeConfig {
+    /**
+     * LLM provider to use
+     * @default 'claude'
+     */
+    provider?: ProviderKind;
+    /**
+     * Environment variable name containing the API key
+     * @default 'ANTHROPIC_API_KEY'
+     */
+    apiKeyEnvVar?: string;
+    /**
+     * Model to use for judging
+     * @default 'claude-sonnet-4-20250514'
+     */
+    model?: string;
+    /**
+     * Maximum tokens for response
+     * @default 1000
+     */
+    maxTokens?: number;
+    /**
+     * Temperature (0-1, lower is more deterministic)
+     * @default 0.0
+     */
+    temperature?: number;
+    /**
+     * Maximum budget in USD for the judge evaluation
+     * @default 0.10
+     */
+    maxBudgetUsd?: number;
+    /**
+     * Maximum size (in bytes) for tool output before failing the test
+     * When set, the judge will fail if the candidate response exceeds this size
+     */
+    maxToolOutputSize?: number;
+}
+/**
+ * Result from LLM judge evaluation
+ */
+interface JudgeResult {
+    /**
+     * Whether the evaluation passed
+     */
+    pass: boolean;
+    /**
+     * Numeric score (0-1, where 1 is best)
+     */
+    score?: number;
+    /**
+     * Reasoning/explanation from the judge
+     */
+    reasoning?: string;
+    /**
+     * Usage metrics from the Claude Agent SDK
+     */
+    usage?: UsageMetrics;
+    /**
+     * Size of the candidate response in bytes (for maxToolOutputSize tracking)
+     */
+    candidateSizeBytes?: number;
+    /**
+     * Whether the candidate exceeded maxToolOutputSize
+     */
+    exceedsMaxToolOutputSize?: boolean;
+}
+/**
+ * LLM judge client interface
+ */
+interface Judge {
+    /**
+     * Evaluates a candidate response against a reference
+     *
+     * @param candidate - The actual response to evaluate
+     * @param reference - The expected/reference response (or null if not applicable)
+     * @param rubric - The evaluation rubric/criteria
+     * @returns Evaluation result with usage metrics
+     */
+    evaluate(candidate: unknown, reference: unknown, rubric: string): Promise<JudgeResult>;
+}
+
+/**
+ * Matcher Types
+ *
+ * TypeScript declarations for custom Playwright matchers.
+ */
+
+/**
+ * Options for the LLM judge matcher
+ */
+interface JudgeMatcherOptions {
+    /** Reference response to compare against */
+    reference?: unknown;
+    /** Score threshold for passing (default: 0.7) */
+    passingThreshold?: number;
+    /** Judge configuration override */
+    judgeConfig?: JudgeConfig;
+}
+/**
+ * Declaration merging for Playwright matchers
+ */
+declare global {
+    namespace PlaywrightTest {
+        interface Matchers<R, T = unknown> {
+            /**
+             * Validates that a response exactly matches the expected value
+             *
+             * @param expected - The expected response value
+             *
+             * @example
+             * ```typescript
+             * expect(result).toMatchToolResponse({ status: 'ok', count: 42 });
+             * ```
+             */
+            toMatchToolResponse(expected: unknown): R;
+            /**
+             * Validates that a response matches a Zod schema
+             *
+             * @param schema - The Zod schema to validate against
+             * @param options - Validation options
+             *
+             * @example
+             * ```typescript
+             * const WeatherSchema = z.object({
+             *   temperature: z.number(),
+             *   conditions: z.string(),
+             * });
+             * expect(result).toMatchToolSchema(WeatherSchema);
+             * ```
+             */
+            toMatchToolSchema(schema: ZodType, options?: SchemaValidatorOptions): R;
+            /**
+             * Validates that a response contains expected text substrings
+             *
+             * @param expected - Expected substring(s) to find
+             * @param options - Validation options
+             *
+             * @example
+             * ```typescript
+             * expect(result).toContainToolText('temperature');
+             * expect(result).toContainToolText(['temperature', 'conditions']);
+             * expect(result).toContainToolText('HELLO', { caseSensitive: false });
+             * ```
+             */
+            toContainToolText(expected: string | string[], options?: TextValidatorOptions): R;
+            /**
+             * Validates that a response matches regex patterns
+             *
+             * @param patterns - Expected pattern(s) to match
+             * @param options - Validation options
+             *
+             * @example
+             * ```typescript
+             * expect(result).toMatchToolPattern(/temperature: \d+/);
+             * expect(result).toMatchToolPattern(['temp: \\d+', 'humidity: \\d+%']);
+             * ```
+             */
+            toMatchToolPattern(patterns: string | RegExp | (string | RegExp)[], options?: PatternValidatorOptions): R;
+            /**
+             * Validates that a response matches a saved snapshot
+             *
+             * @param name - Snapshot name
+             * @param sanitizers - Optional sanitizers for non-deterministic values
+             *
+             * @example
+             * ```typescript
+             * expect(result).toMatchToolSnapshot('weather-response');
+             * expect(result).toMatchToolSnapshot('user-data', [
+             *   { pattern: /\d{4}-\d{2}-\d{2}/, replacement: '[DATE]' },
+             * ]);
+             * ```
+             */
+            toMatchToolSnapshot(name: string, sanitizers?: SnapshotSanitizer[]): Promise<R>;
+            /**
+             * Validates that a response is (or is not) an error
+             *
+             * @param expected - What to expect (true for error, false for success, string for specific message)
+             *
+             * @example
+             * ```typescript
+             * expect(result).toBeToolError();  // Expects any error
+             * expect(result).not.toBeToolError();  // Expects success
+             * expect(result).toBeToolError('File not found');  // Expects specific error
+             * ```
+             */
+            toBeToolError(expected?: boolean | string | string[]): R;
+            /**
+             * Validates that a response passes LLM-as-judge evaluation
+             *
+             * @param rubric - Evaluation rubric/criteria
+             * @param options - Judge options
+             *
+             * @example
+             * ```typescript
+             * expect(result).toPassToolJudge('Response should be helpful and accurate');
+             * expect(result).toPassToolJudge('Response should match reference', {
+             *   reference: expectedOutput,
+             *   passingThreshold: 0.8,
+             * });
+             * ```
+             */
+            toPassToolJudge(rubric: string, options?: JudgeMatcherOptions): Promise<R>;
+            /**
+             * Validates that a response meets size constraints
+             *
+             * @param options - Size constraints (maxBytes, minBytes)
+             *
+             * @example
+             * ```typescript
+             * expect(result).toHaveToolResponseSize({ maxBytes: 10000 });
+             * expect(result).toHaveToolResponseSize({ minBytes: 100, maxBytes: 50000 });
+             * ```
+             */
+            toHaveToolResponseSize(options: SizeValidatorOptions): R;
+            /**
+             * Validates that a response satisfies a custom predicate function
+             *
+             * Use this as an escape hatch when built-in matchers don't cover your use case.
+             * The predicate receives both the raw response and extracted text for convenience.
+             *
+             * @param predicate - Function that validates the response
+             * @param description - Optional description for error messages
+             *
+             * @example
+             * ```typescript
+             * // Simple boolean predicate
+             * expect(result).toSatisfyToolPredicate((response) => {
+             *   return response.data?.items?.length > 0;
+             * });
+             *
+             * // Predicate with custom message
+             * expect(result).toSatisfyToolPredicate(
+             *   (response, text) => ({
+             *     pass: text.includes('success'),
+             *     message: 'Expected response to contain "success"',
+             *   }),
+             *   'success check'
+             * );
+             *
+             * // Async predicate
+             * expect(result).toSatisfyToolPredicate(async (response) => {
+             *   return await validateWithExternalService(response);
+             * });
+             * ```
+             */
+            toSatisfyToolPredicate(predicate: ToolPredicate, description?: string): Promise<R>;
+        }
+    }
+}
+/**
+ * Predicate result returned by the user's predicate function
+ */
+interface PredicateResult {
+    /** Whether the predicate passed */
+    pass: boolean;
+    /** Message explaining the result (shown on failure) */
+    message?: string;
+}
+/**
+ * A predicate function that validates a response
+ */
+type ToolPredicate = (response: unknown, text: string) => boolean | PredicateResult | Promise<boolean | PredicateResult>;
+
+/**
+ * Canonical type definitions for @gleanwork/mcp-server-tester
+ *
+ * This module is the single source of truth for shared types.
+ * All other modules should import from here rather than defining their own.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Authentication type for MCP connections
+ *
+ * - 'oauth': Interactive OAuth 2.1 with PKCE (browser-based authentication)
+ * - 'api-token': Static API token (e.g., from a dashboard or environment variable)
+ * - 'none': No authentication
+ */
+type AuthType = 'oauth' | 'api-token' | 'none';
+/**
+ * Source of test results
+ *
+ * - 'eval': From runEvalDataset() using JSON eval datasets
+ * - 'test': From direct API test tracking (MCP fixture calls)
+ */
+type ResultSource = 'eval' | 'test';
+/**
+ * Known expectation types supported by the framework
+ */
+type ExpectationType = 'exact' | 'schema' | 'textContains' | 'regex' | 'snapshot' | 'judge' | 'error' | 'size';
+/**
+ * Result of an expectation check
+ */
+interface EvalExpectationResult {
+    /**
+     * Whether the expectation passed
+     */
+    pass: boolean;
+    /**
+     * Optional details about the result
+     */
+    details?: string;
+}
+/**
+ * Map of expectation type to result
+ */
+type ExpectationResultMap = Partial<Record<ExpectationType, EvalExpectationResult>>;
+/**
+ * Breakdown of expectation types used in a run
+ */
+type ExpectationBreakdown = Record<ExpectationType, number>;
+
+/**
+ * Options for creating an MCP fixture
+ */
+interface MCPFixtureOptions {
+    /**
+     * Authentication type used for this test
+     * - 'oauth': Interactive OAuth 2.1 with PKCE (browser-based authentication)
+     * - 'api-token': Static API token (e.g., from a dashboard or environment variable)
+     * - 'none': No authentication
+     */
+    authType?: AuthType;
+    /**
+     * Playwright project name for this test
+     * Used for filtering and grouping in the reporter
+     */
+    project?: string;
+}
+/**
+ * High-level API for interacting with MCP servers in tests
+ *
+ * This interface wraps the raw MCP Client with test-friendly methods
+ */
+interface MCPFixtureApi {
+    /**
+     * The underlying MCP client (for advanced usage)
+     */
+    client: Client;
+    /**
+     * Authentication type used for this test session
+     */
+    authType: AuthType;
+    /**
+     * Playwright project name for this test session
+     */
+    project?: string;
+    /**
+     * Lists all available tools from the MCP server
+     *
+     * @returns Array of tool definitions
+     */
+    listTools(): Promise<Array<Tool>>;
+    /**
+     * Calls a tool on the MCP server
+     *
+     * @param name - Tool name
+     * @param args - Tool arguments
+     * @returns Tool call result
+     */
+    callTool<TArgs extends Record<string, unknown> = Record<string, unknown>>(name: string, args: TArgs): Promise<CallToolResult>;
+    /**
+     * Gets information about the connected server
+     */
+    getServerInfo(): {
+        name?: string;
+        version?: string;
+    } | null;
+}
+/**
+ * Creates an MCP fixture wrapper around a Client
+ *
+ * When testInfo is provided, automatically tracks all MCP operations with test.step()
+ * and creates attachments for the MCP Test Reporter.
+ *
+ * @param client - The MCP client to wrap
+ * @param testInfo - Optional Playwright TestInfo for auto-tracking
+ * @returns MCPFixtureApi instance
+ *
+ * @example
+ * ```typescript
+ * // With tracking (recommended)
+ * const test = base.extend<{ mcp: MCPFixtureApi }>({
+ *   mcp: async ({}, use, testInfo) => {
+ *     const client = await createMCPClientForConfig(config);
+ *     const api = createMCPFixture(client, testInfo);
+ *     await use(api);
+ *     await closeMCPClient(client);
+ *   }
+ * });
+ *
+ * // Without tracking
+ * const api = createMCPFixture(client);
+ * ```
+ */
+declare function createMCPFixture(client: Client, testInfo?: TestInfo, options?: MCPFixtureOptions): MCPFixtureApi;
+
+/**
+ * toMatchToolResponse Matcher
+ *
+ * Validates that a response exactly matches an expected value.
+ */
+/**
+ * Creates the toMatchToolResponse matcher function
+ */
+declare function toMatchToolResponse(this: {
+    isNot: boolean;
+}, received: unknown, expected: unknown): {
+    pass: boolean;
+    message: () => string;
+};
+
+/**
+ * toMatchToolSchema Matcher
+ *
+ * Validates that a response matches a Zod schema.
+ */
+
+/**
+ * Creates the toMatchToolSchema matcher function
+ */
+declare function toMatchToolSchema(this: {
+    isNot: boolean;
+}, received: unknown, schema: ZodType, options?: SchemaValidatorOptions): {
+    pass: boolean;
+    message: () => string;
+};
+
+/**
+ * toContainToolText Matcher
+ *
+ * Validates that a response contains expected text substrings.
+ */
+
+/**
+ * Creates the toContainToolText matcher function
+ */
+declare function toContainToolText(this: {
+    isNot: boolean;
+}, received: unknown, expected: string | string[], options?: TextValidatorOptions): {
+    pass: boolean;
+    message: () => string;
+};
+
+/**
+ * toMatchToolPattern Matcher
+ *
+ * Validates that a response matches regex patterns.
+ */
+
+/**
+ * Creates the toMatchToolPattern matcher function
+ */
+declare function toMatchToolPattern(this: {
+    isNot: boolean;
+}, received: unknown, patterns: string | RegExp | (string | RegExp)[], options?: PatternValidatorOptions): {
+    pass: boolean;
+    message: () => string;
+};
+
+/**
+ * toMatchToolSnapshot Matcher
+ *
+ * Validates that a response matches a saved snapshot.
+ * Uses Playwright's native snapshot testing functionality.
+ */
+
+/**
+ * Creates the toMatchToolSnapshot matcher function
+ *
+ * Note: This is an async matcher that uses Playwright's snapshot testing.
+ */
+declare function toMatchToolSnapshot(this: {
+    isNot: boolean;
+}, received: unknown, name: string, sanitizers?: SnapshotSanitizer[]): Promise<{
+    pass: boolean;
+    message: () => string;
+}>;
+
+/**
+ * toBeToolError Matcher
+ *
+ * Validates that a response is (or is not) an error.
+ */
+/**
+ * Creates the toBeToolError matcher function
+ */
+declare function toBeToolError(this: {
+    isNot: boolean;
+}, received: unknown, expected?: boolean | string | string[]): {
+    pass: boolean;
+    message: () => string;
+};
+
+/**
+ * toPassToolJudge Matcher
+ *
+ * Validates that a response passes LLM-as-judge evaluation.
+ */
+
+/**
+ * Creates the toPassToolJudge matcher function
+ *
+ * Note: This is an async matcher that calls an LLM for evaluation.
+ */
+declare function toPassToolJudge(this: {
+    isNot: boolean;
+}, received: unknown, rubric: string, options?: JudgeMatcherOptions): Promise<{
+    pass: boolean;
+    message: () => string;
+}>;
+
+/**
+ * toHaveToolResponseSize Matcher
+ *
+ * Validates that a response meets size constraints.
+ */
+
+/**
+ * Creates the toHaveToolResponseSize matcher function
+ */
+declare function toHaveToolResponseSize(this: {
+    isNot: boolean;
+}, received: unknown, options: SizeValidatorOptions): {
+    pass: boolean;
+    message: () => string;
+};
+
+/**
+ * toSatisfyToolPredicate Matcher
+ *
+ * Validates that a response satisfies a custom predicate function.
+ * This is an escape hatch for custom validation logic when built-in
+ * matchers don't cover the use case.
+ */
+
+/**
+ * Creates the toSatisfyToolPredicate matcher function
+ *
+ * This matcher allows custom validation logic via a predicate function.
+ * The predicate receives both the raw response and extracted text.
+ *
+ * @example
+ * ```typescript
+ * // Simple boolean predicate
+ * expect(result).toSatisfyToolPredicate((response) => {
+ *   return response.data?.length > 0;
+ * });
+ *
+ * // Predicate with custom message
+ * expect(result).toSatisfyToolPredicate((response, text) => {
+ *   const hasTemperature = text.includes('temperature');
+ *   return {
+ *     pass: hasTemperature,
+ *     message: hasTemperature
+ *       ? 'Found temperature in response'
+ *       : 'Expected response to contain temperature',
+ *   };
+ * });
+ *
+ * // Async predicate
+ * expect(result).toSatisfyToolPredicate(async (response) => {
+ *   const isValid = await validateWithExternalService(response);
+ *   return isValid;
+ * });
+ * ```
+ */
+declare function toSatisfyToolPredicate(this: {
+    isNot: boolean;
+}, received: unknown, predicate: ToolPredicate, description?: string): Promise<{
+    pass: boolean;
+    message: () => string;
+}>;
+
+/**
+ * Extended Playwright expect with MCP tool matchers
+ *
+ * @example
+ * ```typescript
+ * import { expect } from '@gleanwork/mcp-server-tester';
+ *
+ * test('weather tool', async ({ mcp }) => {
+ *   const result = await mcp.callTool('get_weather', { city: 'London' });
+ *
+ *   expect(result).toContainToolText('temperature');
+ *   expect(result).toMatchToolSchema(WeatherSchema);
+ *   expect(result).not.toBeToolError();
+ * });
+ * ```
+ */
+declare const expect: playwright_test.Expect<{
+    toMatchToolResponse: typeof toMatchToolResponse;
+    toMatchToolSchema: typeof toMatchToolSchema;
+    toContainToolText: typeof toContainToolText;
+    toMatchToolPattern: typeof toMatchToolPattern;
+    toMatchToolSnapshot: typeof toMatchToolSnapshot;
+    toBeToolError: typeof toBeToolError;
+    toPassToolJudge: typeof toPassToolJudge;
+    toHaveToolResponseSize: typeof toHaveToolResponseSize;
+    toSatisfyToolPredicate: typeof toSatisfyToolPredicate;
+}>;
+
+/**
+ * Internal fixture state for passing auth type between fixtures
+ */
+interface MCPFixtureState {
+    /**
+     * The resolved authentication type (may differ from config if CLI tokens are used)
+     */
+    resolvedAuthType: AuthType;
+}
+/**
+ * Extended test fixtures for MCP testing
+ */
+type MCPFixtures = {
+    /**
+     * Raw MCP client instance (automatically connected and cleaned up)
+     */
+    mcpClient: Client;
+    /**
+     * High-level MCP API for tests
+     */
+    mcp: MCPFixtureApi;
+    /**
+     * Internal fixture state (not for external use)
+     */
+    _mcpFixtureState: MCPFixtureState;
+};
+/**
+ * Extended Playwright test with MCP fixtures
+ *
+ * @example
+ * import { test, expect } from '@gleanwork/mcp-server-tester';
+ *
+ * test('lists tools from MCP server', async ({ mcp }) => {
+ *   const tools = await mcp.listTools();
+ *   expect(tools.length).toBeGreaterThan(0);
+ * });
+ */
+declare const test: playwright_test.TestType<playwright_test.PlaywrightTestArgs & playwright_test.PlaywrightTestOptions & MCPFixtures, playwright_test.PlaywrightWorkerArgs & playwright_test.PlaywrightWorkerOptions>;
+
+/**
+ * Types and interfaces for LLM host simulation mode
+ *
+ * This module provides types for testing MCP servers through LLM hosts,
+ * validating tool descriptions, parameter clarity, and discoverability.
+ */
+
+/**
+ * LLM provider for host simulation
+ */
+type LLMProvider = 'openai' | 'anthropic';
+/**
+ * Configuration for LLM host simulation
+ */
+interface LLMHostConfig {
+    /**
+     * LLM provider to use
+     */
+    provider: LLMProvider;
+    /**
+     * Environment variable name containing the API key
+     * @default 'OPENAI_API_KEY' for openai, 'ANTHROPIC_API_KEY' for anthropic
+     */
+    apiKeyEnvVar?: string;
+    /**
+     * Model to use
+     * @default 'gpt-4' for openai, 'claude-3-5-sonnet-20241022' for anthropic
+     */
+    model?: string;
+    /**
+     * Maximum tokens for response
+     */
+    maxTokens?: number;
+    /**
+     * Temperature (0-1, lower is more deterministic)
+     * @default 0.0
+     */
+    temperature?: number;
+    /**
+     * Maximum number of tool calls to allow in a single conversation
+     * @default 10
+     */
+    maxToolCalls?: number;
+}
+/**
+ * A tool call made by the LLM
+ */
+interface LLMToolCall {
+    /**
+     * Tool name
+     */
+    name: string;
+    /**
+     * Tool arguments (as provided by LLM)
+     */
+    arguments: Record<string, unknown>;
+    /**
+     * Optional tool call ID (for tracking)
+     */
+    id?: string;
+}
+/**
+ * Result of a tool call validation
+ */
+interface ToolCallValidationResult {
+    /**
+     * Whether the tool call was valid
+     */
+    valid: boolean;
+    /**
+     * List of actual tool calls made
+     */
+    actualCalls: Array<LLMToolCall>;
+    /**
+     * Expected tool calls (if specified in eval case)
+     */
+    expectedCalls?: Array<LLMToolCall>;
+    /**
+     * Details about validation (e.g., missing calls, incorrect arguments)
+     */
+    details?: string;
+}
+/**
+ * Result from an LLM host simulation
+ */
+interface LLMHostSimulationResult {
+    /**
+     * Whether the simulation succeeded
+     */
+    success: boolean;
+    /**
+     * Tool calls made by the LLM
+     */
+    toolCalls: Array<LLMToolCall>;
+    /**
+     * Final response from the LLM
+     */
+    response?: string;
+    /**
+     * Error message if simulation failed
+     */
+    error?: string;
+    /**
+     * Full conversation history (for debugging)
+     */
+    conversationHistory?: Array<{
+        role: 'user' | 'assistant' | 'tool';
+        content: string;
+    }>;
+}
+/**
+ * Interface for LLM host simulators
+ *
+ * Implementations communicate with MCP servers via the actual MCP protocol
+ */
+interface LLMHostSimulator {
+    /**
+     * Simulates an LLM host interacting with an MCP server
+     *
+     * @param mcp - MCP fixture API
+     * @param scenario - Natural language prompt describing what the LLM should do
+     * @param config - LLM host configuration
+     * @returns Simulation result with tool calls and response
+     */
+    simulate(mcp: MCPFixtureApi, scenario: string, config: LLMHostConfig): Promise<LLMHostSimulationResult>;
+}
+/**
+ * Expected tool call specification (for validation)
+ */
+interface ExpectedToolCall {
+    /**
+     * Tool name
+     */
+    name: string;
+    /**
+     * Expected arguments (partial match)
+     */
+    arguments?: Record<string, unknown>;
+    /**
+     * Whether this call is required
+     * @default true
+     */
+    required?: boolean;
+}
+
+/**
+ * Evaluation mode
+ */
+type EvalMode = 'direct' | 'llm_host';
+/**
+ * A single eval test case
+ *
+ * For 'direct' mode: toolName and args are required
+ * For 'llm_host' mode: scenario and llmHostConfig are required
+ */
+interface EvalCase {
+    /**
+     * Unique identifier for this test case
+     */
+    id: string;
+    /**
+     * Human-readable description of what this test case validates
+     */
+    description?: string;
+    /**
+     * Evaluation mode
+     * - 'direct': Direct API calls to MCP tools (default)
+     * - 'llm_host': LLM-driven tool selection via natural language
+     *
+     * @default 'direct'
+     */
+    mode?: EvalMode;
+    /**
+     * Name of the MCP tool to call (required for 'direct' mode, optional for 'llm_host' mode)
+     */
+    toolName?: string;
+    /**
+     * Arguments to pass to the tool (required for 'direct' mode, optional for 'llm_host' mode)
+     */
+    args?: Record<string, unknown>;
+    /**
+     * Natural language scenario for LLM to execute (optional, required for 'llm_host' mode)
+     *
+     * @example "Get the weather for London and tell me if I need an umbrella"
+     */
+    scenario?: string;
+    /**
+     * LLM host configuration (optional for 'llm_host' mode)
+     *
+     * If not specified, uses default configuration from test environment
+     */
+    llmHostConfig?: LLMHostConfig;
+    /**
+     * Additional metadata for this test case
+     *
+     * For 'llm_host' mode, can include 'expectedToolCalls' for validation
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Expectations to validate against the tool response
+     *
+     * Multiple expectations can be combined and will all be validated.
+     *
+     * @example
+     * ```json
+     * {
+     *   "id": "weather-london",
+     *   "toolName": "get_weather",
+     *   "args": { "city": "London" },
+     *   "expect": {
+     *     "containsText": ["temperature", "conditions"],
+     *     "schema": "WeatherResponse",
+     *     "responseSize": { "maxBytes": 10000 },
+     *     "isError": false
+     *   }
+     * }
+     * ```
+     */
+    expect?: EvalExpectBlock;
+}
+/**
+ * Unified expectation block for eval cases
+ *
+ * Mirrors the Playwright matcher API for consistency.
+ */
+interface EvalExpectBlock {
+    /**
+     * Exact response match (toMatchToolResponse)
+     */
+    response?: unknown;
+    /**
+     * Name of schema to validate against (toMatchToolSchema)
+     */
+    schema?: string;
+    /**
+     * Text substring(s) that must be present (toContainToolText)
+     */
+    containsText?: string | string[];
+    /**
+     * Regex pattern(s) that must match (toMatchToolPattern)
+     */
+    matchesPattern?: string | string[];
+    /**
+     * Snapshot name for comparison (toMatchToolSnapshot)
+     */
+    snapshot?: string;
+    /**
+     * Snapshot sanitizers to apply
+     */
+    snapshotSanitizers?: SnapshotSanitizer[];
+    /**
+     * Error expectation (toBeToolError)
+     * - true: expects any error
+     * - false: expects no error
+     * - string: expects error containing this message
+     */
+    isError?: boolean | string | string[];
+    /**
+     * LLM-as-judge evaluation (toPassToolJudge)
+     */
+    passesJudge?: {
+        /** Evaluation rubric/criteria */
+        rubric: string;
+        /** Reference response to compare against */
+        reference?: unknown;
+        /** Score threshold for passing (0-1, default: 0.7) */
+        threshold?: number;
+        /** Judge configuration ID */
+        configId?: string;
+    };
+    /**
+     * Response size validation (toHaveToolResponseSize)
+     */
+    responseSize?: {
+        /** Maximum allowed size in bytes */
+        maxBytes?: number;
+        /** Minimum required size in bytes */
+        minBytes?: number;
+    };
+}
+/**
+ * A complete eval dataset containing multiple test cases
+ */
+interface EvalDataset {
+    /**
+     * Dataset name
+     */
+    name: string;
+    /**
+     * Dataset description
+     */
+    description?: string;
+    /**
+     * Test cases in this dataset
+     */
+    cases: Array<EvalCase>;
+    /**
+     * Optional schema definitions referenced by test cases
+     */
+    schemas?: Record<string, z.ZodSchema>;
+    /**
+     * Additional dataset metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Zod schema for EvalCase
+ *
+ * toolName and args are optional for llm_host mode (which uses scenario instead)
+ */
+declare const EvalCaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<["direct", "llm_host"]>>;
+    toolName: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    scenario: z.ZodOptional<z.ZodString>;
+    llmHostConfig: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodEnum<["openai", "anthropic"]>;
+        apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        maxToolCalls: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "anthropic" | "openai";
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        apiKeyEnvVar?: string | undefined;
+        temperature?: number | undefined;
+        maxToolCalls?: number | undefined;
+    }, {
+        provider: "anthropic" | "openai";
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        apiKeyEnvVar?: string | undefined;
+        temperature?: number | undefined;
+        maxToolCalls?: number | undefined;
+    }>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    expect: z.ZodOptional<z.ZodObject<{
+        response: z.ZodOptional<z.ZodUnknown>;
+        schema: z.ZodOptional<z.ZodString>;
+        containsText: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        matchesPattern: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        snapshot: z.ZodOptional<z.ZodString>;
+        snapshotSanitizers: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["timestamp", "uuid", "iso-date", "objectId", "jwt"]>, z.ZodObject<{
+            pattern: z.ZodString;
+            replacement: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            pattern: string;
+            replacement?: string | undefined;
+        }, {
+            pattern: string;
+            replacement?: string | undefined;
+        }>, z.ZodObject<{
+            remove: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            remove: string[];
+        }, {
+            remove: string[];
+        }>]>, "many">>;
+        isError: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+        passesJudge: z.ZodOptional<z.ZodObject<{
+            rubric: z.ZodString;
+            reference: z.ZodOptional<z.ZodUnknown>;
+            threshold: z.ZodOptional<z.ZodNumber>;
+            configId: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            rubric: string;
+            reference?: unknown;
+            threshold?: number | undefined;
+            configId?: string | undefined;
+        }, {
+            rubric: string;
+            reference?: unknown;
+            threshold?: number | undefined;
+            configId?: string | undefined;
+        }>>;
+        responseSize: z.ZodOptional<z.ZodObject<{
+            maxBytes: z.ZodOptional<z.ZodNumber>;
+            minBytes: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            maxBytes?: number | undefined;
+            minBytes?: number | undefined;
+        }, {
+            maxBytes?: number | undefined;
+            minBytes?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        isError?: string | boolean | string[] | undefined;
+        schema?: string | undefined;
+        snapshot?: string | undefined;
+        response?: unknown;
+        containsText?: string | string[] | undefined;
+        matchesPattern?: string | string[] | undefined;
+        snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+            pattern: string;
+            replacement?: string | undefined;
+        } | {
+            remove: string[];
+        })[] | undefined;
+        passesJudge?: {
+            rubric: string;
+            reference?: unknown;
+            threshold?: number | undefined;
+            configId?: string | undefined;
+        } | undefined;
+        responseSize?: {
+            maxBytes?: number | undefined;
+            minBytes?: number | undefined;
+        } | undefined;
+    }, {
+        isError?: string | boolean | string[] | undefined;
+        schema?: string | undefined;
+        snapshot?: string | undefined;
+        response?: unknown;
+        containsText?: string | string[] | undefined;
+        matchesPattern?: string | string[] | undefined;
+        snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+            pattern: string;
+            replacement?: string | undefined;
+        } | {
+            remove: string[];
+        })[] | undefined;
+        passesJudge?: {
+            rubric: string;
+            reference?: unknown;
+            threshold?: number | undefined;
+            configId?: string | undefined;
+        } | undefined;
+        responseSize?: {
+            maxBytes?: number | undefined;
+            minBytes?: number | undefined;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    args?: Record<string, unknown> | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    mode?: "direct" | "llm_host" | undefined;
+    description?: string | undefined;
+    toolName?: string | undefined;
+    scenario?: string | undefined;
+    llmHostConfig?: {
+        provider: "anthropic" | "openai";
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        apiKeyEnvVar?: string | undefined;
+        temperature?: number | undefined;
+        maxToolCalls?: number | undefined;
+    } | undefined;
+    expect?: {
+        isError?: string | boolean | string[] | undefined;
+        schema?: string | undefined;
+        snapshot?: string | undefined;
+        response?: unknown;
+        containsText?: string | string[] | undefined;
+        matchesPattern?: string | string[] | undefined;
+        snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+            pattern: string;
+            replacement?: string | undefined;
+        } | {
+            remove: string[];
+        })[] | undefined;
+        passesJudge?: {
+            rubric: string;
+            reference?: unknown;
+            threshold?: number | undefined;
+            configId?: string | undefined;
+        } | undefined;
+        responseSize?: {
+            maxBytes?: number | undefined;
+            minBytes?: number | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    id: string;
+    args?: Record<string, unknown> | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    mode?: "direct" | "llm_host" | undefined;
+    description?: string | undefined;
+    toolName?: string | undefined;
+    scenario?: string | undefined;
+    llmHostConfig?: {
+        provider: "anthropic" | "openai";
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        apiKeyEnvVar?: string | undefined;
+        temperature?: number | undefined;
+        maxToolCalls?: number | undefined;
+    } | undefined;
+    expect?: {
+        isError?: string | boolean | string[] | undefined;
+        schema?: string | undefined;
+        snapshot?: string | undefined;
+        response?: unknown;
+        containsText?: string | string[] | undefined;
+        matchesPattern?: string | string[] | undefined;
+        snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+            pattern: string;
+            replacement?: string | undefined;
+        } | {
+            remove: string[];
+        })[] | undefined;
+        passesJudge?: {
+            rubric: string;
+            reference?: unknown;
+            threshold?: number | undefined;
+            configId?: string | undefined;
+        } | undefined;
+        responseSize?: {
+            maxBytes?: number | undefined;
+            minBytes?: number | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+/**
+ * Zod schema for EvalDataset (without schemas field, as schemas aren't serializable)
+ */
+declare const EvalDatasetSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    cases: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<["direct", "llm_host"]>>;
+        toolName: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        scenario: z.ZodOptional<z.ZodString>;
+        llmHostConfig: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodEnum<["openai", "anthropic"]>;
+            apiKeyEnvVar: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            maxTokens: z.ZodOptional<z.ZodNumber>;
+            temperature: z.ZodOptional<z.ZodNumber>;
+            maxToolCalls: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            provider: "anthropic" | "openai";
+            model?: string | undefined;
+            maxTokens?: number | undefined;
+            apiKeyEnvVar?: string | undefined;
+            temperature?: number | undefined;
+            maxToolCalls?: number | undefined;
+        }, {
+            provider: "anthropic" | "openai";
+            model?: string | undefined;
+            maxTokens?: number | undefined;
+            apiKeyEnvVar?: string | undefined;
+            temperature?: number | undefined;
+            maxToolCalls?: number | undefined;
+        }>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        expect: z.ZodOptional<z.ZodObject<{
+            response: z.ZodOptional<z.ZodUnknown>;
+            schema: z.ZodOptional<z.ZodString>;
+            containsText: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+            matchesPattern: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+            snapshot: z.ZodOptional<z.ZodString>;
+            snapshotSanitizers: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodEnum<["timestamp", "uuid", "iso-date", "objectId", "jwt"]>, z.ZodObject<{
+                pattern: z.ZodString;
+                replacement: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                pattern: string;
+                replacement?: string | undefined;
+            }, {
+                pattern: string;
+                replacement?: string | undefined;
+            }>, z.ZodObject<{
+                remove: z.ZodArray<z.ZodString, "many">;
+            }, "strip", z.ZodTypeAny, {
+                remove: string[];
+            }, {
+                remove: string[];
+            }>]>, "many">>;
+            isError: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+            passesJudge: z.ZodOptional<z.ZodObject<{
+                rubric: z.ZodString;
+                reference: z.ZodOptional<z.ZodUnknown>;
+                threshold: z.ZodOptional<z.ZodNumber>;
+                configId: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            }, {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            }>>;
+            responseSize: z.ZodOptional<z.ZodObject<{
+                maxBytes: z.ZodOptional<z.ZodNumber>;
+                minBytes: z.ZodOptional<z.ZodNumber>;
+            }, "strip", z.ZodTypeAny, {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            }, {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            isError?: string | boolean | string[] | undefined;
+            schema?: string | undefined;
+            snapshot?: string | undefined;
+            response?: unknown;
+            containsText?: string | string[] | undefined;
+            matchesPattern?: string | string[] | undefined;
+            snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+                pattern: string;
+                replacement?: string | undefined;
+            } | {
+                remove: string[];
+            })[] | undefined;
+            passesJudge?: {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            } | undefined;
+            responseSize?: {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            } | undefined;
+        }, {
+            isError?: string | boolean | string[] | undefined;
+            schema?: string | undefined;
+            snapshot?: string | undefined;
+            response?: unknown;
+            containsText?: string | string[] | undefined;
+            matchesPattern?: string | string[] | undefined;
+            snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+                pattern: string;
+                replacement?: string | undefined;
+            } | {
+                remove: string[];
+            })[] | undefined;
+            passesJudge?: {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            } | undefined;
+            responseSize?: {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            } | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        args?: Record<string, unknown> | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        mode?: "direct" | "llm_host" | undefined;
+        description?: string | undefined;
+        toolName?: string | undefined;
+        scenario?: string | undefined;
+        llmHostConfig?: {
+            provider: "anthropic" | "openai";
+            model?: string | undefined;
+            maxTokens?: number | undefined;
+            apiKeyEnvVar?: string | undefined;
+            temperature?: number | undefined;
+            maxToolCalls?: number | undefined;
+        } | undefined;
+        expect?: {
+            isError?: string | boolean | string[] | undefined;
+            schema?: string | undefined;
+            snapshot?: string | undefined;
+            response?: unknown;
+            containsText?: string | string[] | undefined;
+            matchesPattern?: string | string[] | undefined;
+            snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+                pattern: string;
+                replacement?: string | undefined;
+            } | {
+                remove: string[];
+            })[] | undefined;
+            passesJudge?: {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            } | undefined;
+            responseSize?: {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        id: string;
+        args?: Record<string, unknown> | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        mode?: "direct" | "llm_host" | undefined;
+        description?: string | undefined;
+        toolName?: string | undefined;
+        scenario?: string | undefined;
+        llmHostConfig?: {
+            provider: "anthropic" | "openai";
+            model?: string | undefined;
+            maxTokens?: number | undefined;
+            apiKeyEnvVar?: string | undefined;
+            temperature?: number | undefined;
+            maxToolCalls?: number | undefined;
+        } | undefined;
+        expect?: {
+            isError?: string | boolean | string[] | undefined;
+            schema?: string | undefined;
+            snapshot?: string | undefined;
+            response?: unknown;
+            containsText?: string | string[] | undefined;
+            matchesPattern?: string | string[] | undefined;
+            snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+                pattern: string;
+                replacement?: string | undefined;
+            } | {
+                remove: string[];
+            })[] | undefined;
+            passesJudge?: {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            } | undefined;
+            responseSize?: {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+    }>, "many">;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    cases: {
+        id: string;
+        args?: Record<string, unknown> | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        mode?: "direct" | "llm_host" | undefined;
+        description?: string | undefined;
+        toolName?: string | undefined;
+        scenario?: string | undefined;
+        llmHostConfig?: {
+            provider: "anthropic" | "openai";
+            model?: string | undefined;
+            maxTokens?: number | undefined;
+            apiKeyEnvVar?: string | undefined;
+            temperature?: number | undefined;
+            maxToolCalls?: number | undefined;
+        } | undefined;
+        expect?: {
+            isError?: string | boolean | string[] | undefined;
+            schema?: string | undefined;
+            snapshot?: string | undefined;
+            response?: unknown;
+            containsText?: string | string[] | undefined;
+            matchesPattern?: string | string[] | undefined;
+            snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+                pattern: string;
+                replacement?: string | undefined;
+            } | {
+                remove: string[];
+            })[] | undefined;
+            passesJudge?: {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            } | undefined;
+            responseSize?: {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+    }[];
+    metadata?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+}, {
+    name: string;
+    cases: {
+        id: string;
+        args?: Record<string, unknown> | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        mode?: "direct" | "llm_host" | undefined;
+        description?: string | undefined;
+        toolName?: string | undefined;
+        scenario?: string | undefined;
+        llmHostConfig?: {
+            provider: "anthropic" | "openai";
+            model?: string | undefined;
+            maxTokens?: number | undefined;
+            apiKeyEnvVar?: string | undefined;
+            temperature?: number | undefined;
+            maxToolCalls?: number | undefined;
+        } | undefined;
+        expect?: {
+            isError?: string | boolean | string[] | undefined;
+            schema?: string | undefined;
+            snapshot?: string | undefined;
+            response?: unknown;
+            containsText?: string | string[] | undefined;
+            matchesPattern?: string | string[] | undefined;
+            snapshotSanitizers?: ("timestamp" | "uuid" | "iso-date" | "objectId" | "jwt" | {
+                pattern: string;
+                replacement?: string | undefined;
+            } | {
+                remove: string[];
+            })[] | undefined;
+            passesJudge?: {
+                rubric: string;
+                reference?: unknown;
+                threshold?: number | undefined;
+                configId?: string | undefined;
+            } | undefined;
+            responseSize?: {
+                maxBytes?: number | undefined;
+                minBytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+    }[];
+    metadata?: Record<string, unknown> | undefined;
+    description?: string | undefined;
+}>;
+/**
+ * Type for serialized eval dataset (without Zod schemas)
+ */
+type SerializedEvalDataset = z.infer<typeof EvalDatasetSchema>;
+/**
+ * Validates an eval case
+ *
+ * @param evalCase - The eval case to validate
+ * @returns The validated eval case
+ * @throws {z.ZodError} If validation fails
+ */
+declare function validateEvalCase(evalCase: unknown): EvalCase;
+/**
+ * Validates a serialized eval dataset
+ *
+ * @param dataset - The dataset to validate
+ * @returns The validated dataset
+ * @throws {z.ZodError} If validation fails
+ */
+declare function validateEvalDataset(dataset: unknown): SerializedEvalDataset;
+
+/**
+ * Options for loading an eval dataset
+ */
+interface LoadDatasetOptions {
+    /**
+     * Optional schema definitions to attach to the dataset
+     *
+     * Keys should match the expectedSchemaName in eval cases
+     */
+    schemas?: Record<string, z.ZodSchema>;
+    /**
+     * Whether to validate the loaded dataset
+     * @default true
+     */
+    validate?: boolean;
+}
+/**
+ * Loads an eval dataset from a JSON file
+ *
+ * @param filePath - Absolute path to the JSON file
+ * @param options - Load options
+ * @returns The loaded and validated dataset
+ * @throws {Error} If file cannot be read or JSON is invalid
+ * @throws {z.ZodError} If validation fails
+ *
+ * @example
+ * const dataset = await loadEvalDataset('./data/my-evals.json', {
+ *   schemas: {
+ *     'weather-response': WeatherResponseSchema,
+ *   },
+ * });
+ */
+declare function loadEvalDataset(filePath: string, options?: LoadDatasetOptions): Promise<EvalDataset>;
+/**
+ * Loads an eval dataset from a plain object
+ *
+ * Useful for programmatically creating datasets in tests
+ *
+ * @param data - The dataset data
+ * @param options - Load options
+ * @returns The loaded and validated dataset
+ * @throws {z.ZodError} If validation fails
+ *
+ * @example
+ * const dataset = loadEvalDatasetFromObject({
+ *   name: 'my-test-dataset',
+ *   cases: [
+ *     {
+ *       id: 'case-1',
+ *       toolName: 'get_weather',
+ *       args: { city: 'London' },
+ *     },
+ *   ],
+ * });
+ */
+declare function loadEvalDatasetFromObject(data: unknown, options?: LoadDatasetOptions): EvalDataset;
+
+/**
+ * Context passed to the eval runner
+ */
+interface EvalContext {
+    /**
+     * MCP fixture API for interacting with the server
+     */
+    mcp: MCPFixtureApi;
+    /**
+     * Optional Playwright TestInfo for reporter integration
+     * When provided, eval results will be attached to the test for the MCP reporter
+     */
+    testInfo?: TestInfo;
+    /**
+     * Optional Playwright expect function for snapshot testing
+     * Required for snapshot expectations to work properly
+     */
+    expect?: Expect;
+}
+
+/**
+ * Result of a single eval case
+ */
+interface EvalCaseResult$1 {
+    /**
+     * Case ID
+     */
+    id: string;
+    /**
+     * Dataset name this case belongs to
+     */
+    datasetName: string;
+    /**
+     * MCP tool name that was called
+     */
+    toolName: string;
+    /**
+     * Evaluation mode (direct or llm_host)
+     * @deprecated Mode is inferred from test context, not displayed in reports
+     */
+    mode?: 'direct' | 'llm_host';
+    /**
+     * Source of this result
+     * - 'eval': From runEvalDataset() using JSON eval datasets
+     * - 'test': From direct API test tracking (MCP fixture calls)
+     */
+    source: ResultSource;
+    /**
+     * Overall pass/fail status
+     */
+    pass: boolean;
+    /**
+     * Tool response
+     */
+    response?: unknown;
+    /**
+     * Error if tool call failed
+     */
+    error?: string;
+    /**
+     * Expectation results
+     */
+    expectations: Partial<Record<ExpectationType, EvalExpectationResult>>;
+    /**
+     * Authentication type used for this test
+     */
+    authType?: AuthType;
+    /**
+     * Playwright project name this test belongs to
+     * Used for filtering/grouping results by project in the reporter
+     */
+    project?: string;
+    /**
+     * Execution time in milliseconds
+     */
+    durationMs: number;
+}
+/**
+ * Overall result of running an eval dataset
+ */
+interface EvalRunnerResult {
+    /**
+     * Total number of cases
+     */
+    total: number;
+    /**
+     * Number of passing cases
+     */
+    passed: number;
+    /**
+     * Number of failing cases
+     */
+    failed: number;
+    /**
+     * Individual case results
+     */
+    caseResults: Array<EvalCaseResult$1>;
+    /**
+     * Overall execution time in milliseconds
+     */
+    durationMs: number;
+}
+/**
+ * Options for running eval dataset
+ */
+interface EvalRunnerOptions {
+    /**
+     * The dataset to run
+     */
+    dataset: EvalDataset;
+    /**
+     * Schema registry for schema validation by name
+     *
+     * Maps schema names to Zod schemas for use with expect.schema
+     *
+     * @example
+     * ```typescript
+     * {
+     *   schemas: {
+     *     WeatherResponse: z.object({ temperature: z.number() }),
+     *     ErrorResponse: z.object({ error: z.string() }),
+     *   }
+     * }
+     * ```
+     */
+    schemas?: Record<string, ZodType>;
+    /**
+     * Judge configuration registry by ID
+     *
+     * Maps config IDs to JudgeConfig for use with expect.passesJudge.configId
+     */
+    judgeConfigs?: Record<string, JudgeConfig>;
+    /**
+     * Whether to stop on first failure
+     * @default false
+     */
+    stopOnFailure?: boolean;
+    /**
+     * Optional callback called after each case
+     */
+    onCaseComplete?: (result: EvalCaseResult$1) => void | Promise<void>;
+}
+/**
+ * Options for running a single eval case
+ */
+interface EvalCaseOptions {
+    /**
+     * Dataset name for the result (defaults to 'single-case')
+     */
+    datasetName?: string;
+    /**
+     * Schema registry for schema validation by name
+     */
+    schemas?: Record<string, ZodType>;
+    /**
+     * Judge configuration registry by ID
+     */
+    judgeConfigs?: Record<string, JudgeConfig>;
+}
+/**
+ * Runs a single eval case and returns the result
+ *
+ * @param evalCase - The eval case to run
+ * @param context - Context containing mcp, testInfo, expect
+ * @param options - Optional configuration (datasetName, schemas, judgeConfigs)
+ * @returns The result of running the eval case
+ *
+ * @example
+ * ```typescript
+ * const result = await runEvalCase(
+ *   evalCase,
+ *   { mcp, testInfo, expect },
+ *   { schemas: { WeatherResponse: WeatherSchema } }
+ * );
+ *
+ * expect(result.pass).toBe(true);
+ * ```
+ */
+declare function runEvalCase(evalCase: EvalCase, context: EvalContext, options?: EvalCaseOptions): Promise<EvalCaseResult$1>;
+/**
+ * Runs an eval dataset against an MCP server
+ *
+ * This function composes runEvalCase() for each case in the dataset,
+ * adding dataset-level features like stopOnFailure and callbacks.
+ *
+ * @param options - Eval runner options (dataset, schemas, judgeConfigs)
+ * @param context - Eval context (mcp fixture, optional testInfo, optional expect)
+ * @returns Eval results
+ *
+ * @example
+ * // Basic usage
+ * const result = await runEvalDataset(
+ *   {
+ *     dataset,
+ *     schemas: { WeatherResponse: WeatherSchema },
+ *   },
+ *   { mcp }
+ * );
+ *
+ * @example
+ * // With MCP reporter integration
+ * test('eval dataset', async ({ mcp }, testInfo) => {
+ *   const result = await runEvalDataset(
+ *     { dataset },
+ *     { mcp, testInfo }  // testInfo enables MCP reporter
+ *   );
+ * });
+ */
+declare function runEvalDataset(options: EvalRunnerOptions, context: EvalContext): Promise<EvalRunnerResult>;
+
+/**
+ * LLM Host Simulation - Main entry point
+ *
+ * Provides the public API for simulating LLM hosts interacting
+ * with MCP servers through actual LLM providers.
+ */
+
+/**
+ * Simulates an LLM host interacting with an MCP server
+ *
+ * This function uses actual LLM providers (OpenAI or Anthropic) to test
+ * MCP servers through natural language scenarios. The LLM chooses which
+ * tools to call based on their descriptions, testing discoverability and
+ * parameter clarity.
+ *
+ * @param mcp - MCP fixture API
+ * @param scenario - Natural language prompt describing what to do
+ * @param config - LLM host configuration
+ * @returns Simulation result with tool calls and final response
+ *
+ * @example
+ * ```typescript
+ * const result = await simulateLLMHost(mcp,
+ *   "Get the weather for London",
+ *   {
+ *     provider: 'openai',
+ *     model: 'gpt-4o'
+ *   }
+ * );
+ *
+ * expect(result.success).toBe(true);
+ * expect(result.toolCalls).toContainEqual({
+ *   name: 'get_weather',
+ *   arguments: { city: 'London' }
+ * });
+ * ```
+ */
+declare function simulateLLMHost(mcp: MCPFixtureApi, scenario: string, config: LLMHostConfig): Promise<LLMHostSimulationResult>;
+/**
+ * Checks if the required SDK is available for a given provider
+ *
+ * This performs a quick check without actually loading the SDK.
+ * The actual SDK loading happens in the adapter when simulation runs.
+ *
+ * @param provider - LLM provider to check
+ * @returns true if an adapter is registered for the provider
+ */
+declare function isProviderAvailable(provider: LLMProvider): boolean;
+/**
+ * Gets a helpful error message for missing dependencies
+ *
+ * @param provider - LLM provider
+ * @returns Error message with installation instructions
+ */
+declare function getMissingDependencyMessage(provider: LLMProvider): string;
+
+/**
+ * Tool call validator for LLM host mode
+ *
+ * Validates that the LLM made the expected tool calls with correct arguments
+ */
+
+/**
+ * Tool call validation function signature
+ */
+type ToolCallValidator = (evalCase: EvalCase, response: unknown) => Promise<EvalExpectationResult>;
+/**
+ * Creates a tool call validator for LLM host mode
+ *
+ * Validates that the LLM made the expected tool calls with correct arguments.
+ * Supports partial argument matching and optional calls.
+ *
+ * @returns Validator function
+ *
+ * @example
+ * ```typescript
+ * // In your eval case:
+ * {
+ *   "id": "weather-london",
+ *   "mode": "llm_host",
+ *   "scenario": "Get the weather for London",
+ *   "expectedToolCalls": [
+ *     {
+ *       "name": "get_weather",
+ *       "arguments": { "city": "London" },
+ *       "required": true
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+declare function createToolCallValidator(): ToolCallValidator;
+
+/**
+ * Creates an LLM judge for evaluating tool responses
+ *
+ * Uses Claude Agent SDK for evaluation with usage metrics tracking.
+ *
+ * @param config - Judge configuration
+ * @returns Judge instance
+ * @throws {Error} If provider is unsupported or configuration is invalid
+ *
+ * @example
+ * // Default Claude judge
+ * const judge = createJudge();
+ *
+ * @example
+ * // With configuration
+ * const judge = createJudge({
+ *   model: 'claude-sonnet-4-20250514',
+ *   maxToolOutputSize: 50000, // Fail if response > 50KB
+ *   maxBudgetUsd: 0.05,
+ * });
+ *
+ * // Evaluate a response
+ * const result = await judge.evaluate(
+ *   candidateResponse,
+ *   referenceResponse,
+ *   'Evaluate for accuracy and completeness'
+ * );
+ *
+ * // Access usage metrics
+ * console.log('Cost:', result.usage?.totalCostUsd);
+ * console.log('Tokens:', result.usage?.inputTokens, result.usage?.outputTokens);
+ */
+declare function createJudge(config?: JudgeConfig): Judge;
+
+/**
+ * Options for conformance checks
+ */
+interface MCPConformanceOptions {
+    /**
+     * List of tools that must be present
+     */
+    requiredTools?: Array<string>;
+    /**
+     * Whether to validate tool schemas
+     * @default true
+     */
+    validateSchemas?: boolean;
+    /**
+     * Whether to check server info is present
+     * @default true
+     */
+    checkServerInfo?: boolean;
+    /**
+     * Whether to check resources capability (if declared by server)
+     * @default true
+     */
+    checkResources?: boolean;
+    /**
+     * Whether to check prompts capability (if declared by server)
+     * @default true
+     */
+    checkPrompts?: boolean;
+}
+/**
+ * Individual check result
+ */
+interface MCPConformanceCheck$1 {
+    name: string;
+    pass: boolean;
+    message: string;
+}
+/**
+ * Raw MCP responses for snapshotting
+ */
+interface MCPConformanceRaw {
+    /**
+     * Server info (name, version)
+     * null if not available
+     */
+    serverInfo: Implementation | null;
+    /**
+     * Server capabilities
+     * null if not available
+     */
+    capabilities: ServerCapabilities | null;
+    /**
+     * List of tools from the server
+     */
+    tools: Tool[];
+    /**
+     * List of resources from the server
+     * null if server doesn't declare resources capability
+     */
+    resources: Resource[] | null;
+    /**
+     * List of prompts from the server
+     * null if server doesn't declare prompts capability
+     */
+    prompts: Prompt[] | null;
+}
+/**
+ * Result of conformance checks
+ */
+interface MCPConformanceResult {
+    /**
+     * Whether all checks passed
+     */
+    pass: boolean;
+    /**
+     * List of check results
+     */
+    checks: MCPConformanceCheck$1[];
+    /**
+     * Raw MCP responses for snapshotting
+     *
+     * @example
+     * ```typescript
+     * const result = await runConformanceChecks(mcp);
+     * expect(result.raw.tools).toMatchSnapshot();
+     * expect(result.raw.capabilities).toMatchSnapshot();
+     * ```
+     */
+    raw: MCPConformanceRaw;
+}
+/**
+ * Runs MCP protocol conformance checks
+ *
+ * Validates that the MCP server conforms to expected protocol behavior.
+ * Returns both assertion results and raw MCP responses for snapshotting.
+ *
+ * When testInfo is provided, results are automatically attached for the MCP reporter.
+ *
+ * @param mcp - MCP fixture API
+ * @param options - Conformance check options
+ * @param testInfo - Optional Playwright TestInfo for reporter integration
+ * @returns Conformance check results with raw responses
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await runConformanceChecks(mcp, {
+ *   requiredTools: ['get_weather', 'search_docs'],
+ *   validateSchemas: true,
+ * });
+ *
+ * // Check assertions
+ * expect(result.pass).toBe(true);
+ *
+ * // With reporter integration (recommended in Playwright tests)
+ * const result = await runConformanceChecks(mcp, {
+ *   requiredTools: ['search'],
+ * }, testInfo);
+ *
+ * // Snapshot raw responses
+ * expect(result.raw.tools).toMatchSnapshot();
+ * expect(result.raw.capabilities).toMatchSnapshot();
+ * ```
+ */
+declare function runConformanceChecks(mcp: MCPFixtureApi, options?: MCPConformanceOptions, testInfo?: TestInfo): Promise<MCPConformanceResult>;
+
+/**
+ * Reporter-specific type definitions
+ *
+ * These types are used by the MCP reporter and UI.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Individual conformance check result
+ */
+interface MCPConformanceCheck {
+    /**
+     * Check name (e.g., 'server_info_present', 'list_tools_succeeds')
+     */
+    name: string;
+    /**
+     * Whether the check passed
+     */
+    pass: boolean;
+    /**
+     * Human-readable message describing the result
+     */
+    message: string;
+}
+/**
+ * Conformance check result as stored in reporter data
+ */
+interface MCPConformanceResultData {
+    /**
+     * Test title where conformance check was run
+     */
+    testTitle: string;
+    /**
+     * Whether all checks passed
+     */
+    pass: boolean;
+    /**
+     * Individual check results
+     */
+    checks: MCPConformanceCheck[];
+    /**
+     * Server info if available
+     */
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    /**
+     * Number of tools discovered
+     */
+    toolCount: number;
+    /**
+     * Auth type used for this check
+     */
+    authType?: AuthType;
+    /**
+     * Project name
+     */
+    project?: string;
+}
+/**
+ * Server capabilities data from mcp-list-tools attachment
+ */
+interface MCPServerCapabilitiesData {
+    /**
+     * Test title where listTools was called
+     */
+    testTitle: string;
+    /**
+     * List of tools available on the server
+     */
+    tools: Array<{
+        name: string;
+        description?: string;
+    }>;
+    /**
+     * Total number of tools
+     */
+    toolCount: number;
+    /**
+     * Auth type used for this test
+     */
+    authType?: AuthType;
+    /**
+     * Project name
+     */
+    project?: string;
+}
+/**
+ * Result of a single eval case
+ */
+interface EvalCaseResult {
+    /**
+     * Case ID
+     */
+    id: string;
+    /**
+     * Dataset name this case belongs to
+     */
+    datasetName: string;
+    /**
+     * MCP tool name that was called
+     */
+    toolName: string;
+    /**
+     * Source of this result
+     */
+    source: ResultSource;
+    /**
+     * Overall pass/fail status
+     */
+    pass: boolean;
+    /**
+     * Tool response
+     */
+    response?: unknown;
+    /**
+     * Error if tool call failed
+     */
+    error?: string;
+    /**
+     * Expectation results
+     */
+    expectations: Partial<Record<ExpectationType, EvalExpectationResult>>;
+    /**
+     * Authentication type used for this test
+     */
+    authType?: AuthType;
+    /**
+     * Playwright project name this test belongs to
+     */
+    project?: string;
+    /**
+     * Execution time in milliseconds
+     */
+    durationMs: number;
+    /**
+     * @deprecated Mode is inferred from test context, not displayed in reports
+     */
+    mode?: 'direct' | 'llm_host';
+}
+/**
+ * Aggregated MCP eval run data
+ */
+interface MCPEvalRunData {
+    /**
+     * Run timestamp (ISO 8601)
+     */
+    timestamp: string;
+    /**
+     * Total duration in milliseconds
+     */
+    durationMs: number;
+    /**
+     * Environment info
+     */
+    environment: {
+        ci: boolean;
+        node: string;
+        platform: string;
+    };
+    /**
+     * Aggregate metrics
+     */
+    metrics: {
+        /**
+         * Total number of eval cases
+         */
+        total: number;
+        /**
+         * Number of passed cases
+         */
+        passed: number;
+        /**
+         * Number of failed cases
+         */
+        failed: number;
+        /**
+         * Pass rate (0-1)
+         */
+        passRate: number;
+        /**
+         * Dataset breakdown: dataset name -> count
+         */
+        datasetBreakdown: Record<string, number>;
+        /**
+         * Expectation type breakdown
+         */
+        expectationBreakdown: ExpectationBreakdown;
+    };
+    /**
+     * All eval results from this run
+     */
+    results: EvalCaseResult[];
+    /**
+     * Conformance check results (optional)
+     */
+    conformanceChecks?: MCPConformanceResultData[];
+    /**
+     * Server capabilities discovered via listTools (optional)
+     */
+    serverCapabilities?: MCPServerCapabilitiesData[];
+}
+/**
+ * Historical summary for trend charts
+ */
+interface MCPEvalHistoricalSummary {
+    timestamp: string;
+    total: number;
+    passed: number;
+    failed: number;
+    passRate: number;
+    durationMs: number;
+}
+/**
+ * Complete data structure passed to UI
+ */
+interface MCPEvalData {
+    runData: MCPEvalRunData;
+    historical: MCPEvalHistoricalSummary[];
+}
+
+/**
+ * Reporter types - re-exported from canonical source
+ *
+ * This module re-exports types from the canonical types module for backwards compatibility.
+ * All type definitions now live in src/types/.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Configuration options for MCP Eval Reporter
+ */
+interface MCPEvalReporterConfig {
+    /**
+     * Output directory for reports and historical data
+     * @default '.mcp-test-results'
+     */
+    outputDir?: string;
+    /**
+     * Auto-open report in browser after test run
+     * @default true (disabled in CI)
+     */
+    autoOpen?: boolean;
+    /**
+     * Number of historical runs to keep
+     * @default 10
+     */
+    historyLimit?: number;
+    /**
+     * Suppress console output (report still generated)
+     * @default false
+     */
+    quiet?: boolean;
+    /**
+     * Include auto-tracked MCP tool calls from tests without explicit eval results.
+     * When true, any test using the MCP fixture will have its tool calls
+     * included in the report, even without using runEvalCase/runEvalDataset.
+     * When false, only tests with explicit eval results are included.
+     * @default true
+     */
+    includeAutoTracking?: boolean;
+}
+
+export { type AuthType, type BuiltInSanitizer, CLIOAuthClient, type CLIOAuthClientConfig, type CLIOAuthResult, type ContentBlock, type CreateMCPClientOptions, DiscoveryError, ENV_VAR_NAMES, type EvalCase, type EvalCaseResult$1 as EvalCaseResult, EvalCaseSchema, type EvalContext, type EvalDataset, EvalDatasetSchema, type EvalExpectBlock, type EvalExpectationResult, type EvalMode, type EvalRunnerOptions, type EvalRunnerResult, type ExpectationBreakdown, type ExpectationResultMap, type ExpectationType, type ExpectedToolCall, type FieldRemovalSanitizer, type Judge, type JudgeConfig, type JudgeMatcherOptions, type JudgeResult, type LLMHostConfig, type LLMHostSimulationResult, type LLMHostSimulator, type LLMProvider, type LLMToolCall, type LoadDatasetOptions, type MCPAuthConfig, type MCPConfig, MCPConfigSchema, type MCPConformanceCheck$1 as MCPConformanceCheck, type MCPConformanceOptions, type MCPConformanceRaw, type MCPConformanceResult, type MCPConformanceResultData, type MCPEvalData, type MCPEvalHistoricalSummary, type MCPEvalReporterConfig, type MCPEvalRunData, type MCPFixtureApi, type MCPFixtureOptions, type MCPHostCapabilities, type MCPOAuthConfig, type MCPServerCapabilitiesData, MCP_PROTOCOL_VERSION, type NormalizedToolResponse, type OAuthSetupConfig, type PatternValidatorOptions, PlaywrightOAuthClientProvider, type PlaywrightOAuthClientProviderConfig, type PredicateResult, type ProtectedResourceDiscoveryResult, type ProtectedResourceMetadata, type ProviderKind, type RegexSanitizer, type ResultSource, type SchemaRegistry, type SchemaValidatorOptions, type SerializedEvalDataset, type SizeValidatorOptions, type SnapshotSanitizer, type StoredClientInfo, type StoredOAuthState, type StoredServerMetadata, type StoredTokens, type TextValidatorOptions, type TokenResult, type ToolCallValidationResult, type ToolCallValidator, type ToolPredicate, type UsageMetrics, type ValidationResult, closeMCPClient, createJudge, createMCPClientForConfig, createMCPFixture, createTokenAuthHeaders, createToolCallValidator, discoverAuthorizationServer, discoverProtectedResource, expect, extractText, extractText as extractTextFromResponse, getMissingDependencyMessage, getResponseSizeBytes, hasValidTokens, injectTokens, isHttpConfig, isProviderAvailable, isStdioConfig, isTokenExpired, isTokenExpiringSoon, loadEvalDataset, loadEvalDatasetFromObject, loadTokens, loadTokensFromEnv, normalizeToolResponse, normalizeWhitespace, performOAuthSetup, performOAuthSetupIfNeeded, runConformanceChecks, runEvalCase, runEvalDataset, simulateLLMHost, test, validateAccessToken, validateError, validateEvalCase, validateEvalDataset, validateMCPConfig, validatePattern, validateResponse, validateSchema, validateSize, validateText };