@dotsetlabs/bellwether 2.1.1 → 2.1.2

package/dist/discovery/discovery.js

@@ -8,6 +8,7 @@ const logger = getLogger('discovery');
 export async function discover(client, command, args) {
     // Initialize connection
     const initResult = await client.initialize();
+    const capabilityWarnings = [];
     // Discover tools
     let tools = [];
     if (initResult.capabilities.tools) {
@@ -16,6 +17,7 @@ export async function discover(client, command, args) {
         }
         catch (error) {
             logger.error({ error }, 'Failed to list tools');
+            throw new Error(`Failed to list tools despite advertised tools capability: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
     // Discover prompts
@@ -26,6 +28,11 @@ export async function discover(client, command, args) {
         }
         catch (error) {
             logger.error({ error }, 'Failed to list prompts');
+            capabilityWarnings.push({
+                level: 'warning',
+                message: `Failed to list prompts: ${error instanceof Error ? error.message : String(error)}`,
+                recommendation: 'Check server prompt implementation and transport health.',
+            });
         }
     }
     // Discover resources
@@ -37,18 +44,30 @@ export async function discover(client, command, args) {
         }
         catch (error) {
             logger.error({ error }, 'Failed to list resources');
+            capabilityWarnings.push({
+                level: 'warning',
+                message: `Failed to list resources: ${error instanceof Error ? error.message : String(error)}`,
+                recommendation: 'Check server resource implementation and transport health.',
+            });
         }
         try {
             resourceTemplates = await client.listResourceTemplates();
         }
         catch (error) {
             logger.debug({ error }, 'Failed to list resource templates (server may not support them)');
+            capabilityWarnings.push({
+                level: 'info',
+                message: `Failed to list resource templates: ${error instanceof Error ? error.message : String(error)}`,
+            });
         }
     }
     // Collect transport errors from the client
     const transportErrors = client.getTransportErrors();
     // Generate warnings based on discovery results
-    const warnings = generateDiscoveryWarnings(initResult.capabilities, tools, prompts, resources, transportErrors, initResult.protocolVersion);
+    const warnings = [
+        ...capabilityWarnings,
+        ...generateDiscoveryWarnings(initResult.capabilities, tools, prompts, resources, transportErrors, initResult.protocolVersion),
+    ];
     return {
         serverInfo: initResult.serverInfo,
         protocolVersion: initResult.protocolVersion,

package/dist/discovery/types.d.ts

@@ -60,7 +60,7 @@ export interface PropertySchema {
  * Classification of transport-level errors.
  * Used to differentiate between server bugs, protocol issues, and environment problems.
  */
-export type TransportErrorCategory = 'invalid_json' | 'buffer_overflow' | 'connection_refused' | 'connection_lost' | 'protocol_violation' | 'timeout' | 'shutdown_error' | 'unknown';
+export type TransportErrorCategory = 'invalid_json' | 'buffer_overflow' | 'connection_refused' | 'auth_failed' | 'connection_lost' | 'protocol_violation' | 'timeout' | 'shutdown_error' | 'unknown';
 /**
  * Record of a transport-level error that occurred during MCP communication.
  */

package/dist/docs/contract.js

@@ -624,9 +624,13 @@ function generateTransportIssuesSection(transportErrors, warnings) {
         // Recommendations
         const hasInvalidJson = transportErrors.some((e) => e.category === 'invalid_json');
         const hasProtocolError = transportErrors.some((e) => e.category === 'protocol_violation');
-        if (hasInvalidJson || hasProtocolError) {
+        const hasAuthError = transportErrors.some((e) => e.category === 'auth_failed');
+        if (hasInvalidJson || hasProtocolError || hasAuthError) {
             lines.push('### Recommendations');
             lines.push('');
+            if (hasAuthError) {
+                lines.push('- **Auth Failed**: Configure remote authentication headers (for example `Authorization: Bearer <token>`) and verify credentials are valid.');
+            }
             if (hasInvalidJson) {
                 lines.push('- **Invalid JSON**: The server may be writing debug output to stdout. Ensure all non-JSON-RPC output goes to stderr.');
             }
@@ -649,6 +653,8 @@ function formatTransportErrorCategory(category) {
             return 'Buffer Overflow';
         case 'connection_refused':
             return 'Connection Refused';
+        case 'auth_failed':
+            return 'Auth Failed';
         case 'connection_lost':
             return 'Connection Lost';
         case 'protocol_violation':

package/dist/errors/retry.js

@@ -2,7 +2,7 @@
  * Retry logic with exponential backoff.
  */
 import { getLogger } from '../logging/logger.js';
-import { BellwetherError, LLMRateLimitError, isRetryable, wrapError, createTimingContext, } from './types.js';
+import { BellwetherError, LLMRateLimitError, ServerAuthError, isRetryable, wrapError, createTimingContext, } from './types.js';
 import { RETRY_STRATEGIES, CIRCUIT_BREAKER, MATH_FACTORS } from '../constants.js';
 const DEFAULT_OPTIONS = {
     maxAttempts: RETRY_STRATEGIES.DEFAULT.maxAttempts,
@@ -191,7 +191,21 @@ export const TRANSPORT_RETRY_OPTIONS = {
     backoffMultiplier: RETRY_STRATEGIES.TRANSPORT.backoffMultiplier,
     jitter: RETRY_STRATEGIES.TRANSPORT.jitter,
     shouldRetry: (error) => {
+        if (error instanceof ServerAuthError) {
+            return false;
+        }
         const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        // Authentication/authorization failures are terminal until credentials change
+        if (message.includes('401') ||
+            message.includes('403') ||
+            message.includes('407') ||
+            message.includes('unauthorized') ||
+            message.includes('forbidden') ||
+            message.includes('authentication') ||
+            message.includes('authorization') ||
+            message.includes('access denied')) {
+            return false;
+        }
         // Timeouts might be transient
         if (message.includes('timeout')) {
             return true;

package/dist/errors/types.d.ts

@@ -120,6 +120,16 @@ export declare class ServerExitError extends TransportError {
 export declare class ProtocolError extends TransportError {
     constructor(message: string, context?: ErrorContext, cause?: Error);
 }
+/**
+ * Remote server authentication/authorization failed.
+ */
+export declare class ServerAuthError extends TransportError {
+    /** HTTP status code if available */
+    readonly statusCode?: number;
+    /** Suggested remediation hint */
+    readonly hint?: string;
+    constructor(message: string, statusCode?: number, hint?: string, context?: ErrorContext, cause?: Error);
+}
 /**
  * Buffer overflow during message processing.
  */

package/dist/errors/types.js

@@ -146,6 +146,34 @@ export class ProtocolError extends TransportError {
         this.name = 'ProtocolError';
     }
 }
+/**
+ * Remote server authentication/authorization failed.
+ */
+export class ServerAuthError extends TransportError {
+    /** HTTP status code if available */
+    statusCode;
+    /** Suggested remediation hint */
+    hint;
+    constructor(message, statusCode, hint, context, cause) {
+        super(message, {
+            code: 'TRANSPORT_AUTH_FAILED',
+            severity: 'high',
+            retryable: 'terminal',
+            context: {
+                ...context,
+                metadata: {
+                    ...context?.metadata,
+                    statusCode,
+                    hint,
+                },
+            },
+            cause,
+        });
+        this.name = 'ServerAuthError';
+        this.statusCode = statusCode;
+        this.hint = hint;
+    }
+}
 /**
  * Buffer overflow during message processing.
  */

package/dist/transport/http-transport.js

@@ -1,5 +1,6 @@
 import { BaseTransport } from './base-transport.js';
 import { TIMEOUTS, DISPLAY_LIMITS, MCP } from '../constants.js';
+import { ServerAuthError } from '../errors/types.js';
 /**
  * HTTPTransport connects to MCP servers over HTTP using POST requests.
  *
@@ -111,6 +112,15 @@ export class HTTPTransport extends BaseTransport {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
+                if (response.status === 401) {
+                    throw new ServerAuthError('Remote MCP server authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
+                }
+                if (response.status === 403) {
+                    throw new ServerAuthError('Remote MCP server authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
+                }
+                if (response.status === 407) {
+                    throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+                }
                 // MCP 2025-11-25: 404 means session expired, clear session ID
                 if (response.status === 404 && this.sessionId) {
                     this.log('Session expired (404), clearing session ID');

package/dist/transport/mcp-client.d.ts

@@ -19,6 +19,8 @@ export interface MCPClientOptions {
     sseConfig?: Omit<SSETransportConfig, 'debug'>;
     /** Configuration for HTTP transport */
     httpConfig?: Omit<HTTPTransportConfig, 'debug'>;
+    /** Optional preflight check for remote transports (default: true) */
+    remotePreflight?: boolean;
 }
 /**
  * MCPClient connects to an MCP server via various transports and provides
@@ -55,7 +57,21 @@ export declare class MCPClient {
     private connectionState;
     /** Protocol version negotiated with the server during initialization */
     private negotiatedProtocolVersion;
+    /** Whether to run an explicit preflight before remote connection */
+    private remotePreflight;
     constructor(options?: MCPClientOptions);
+    /**
+     * Merge two header maps, giving precedence to override values.
+     */
+    private mergeHeaders;
+    /**
+     * Optional remote connectivity/auth preflight (enabled by default).
+     * Uses GET (not HEAD/OPTIONS) for broader compatibility.
+     *
+     * Any successful HTTP response (including 404/405/etc.) confirms network reachability.
+     * Only auth failures and hard network/timeouts are treated as terminal preflight failures.
+     */
+    private preflightRemote;
     /**
      * Classify a transport error based on its message.
      */

package/dist/transport/mcp-client.js

@@ -7,6 +7,7 @@ import { TIMEOUTS, MCP, TRANSPORT_ERRORS } from '../constants.js';
 import { VERSION } from '../version.js';
 import { getFeatureFlags, isKnownProtocolVersion, } from '../protocol/index.js';
 import { filterSpawnEnv } from './env-filter.js';
+import { ConnectionError, ServerAuthError } from '../errors/types.js';
 const DEFAULT_TIMEOUT = TIMEOUTS.DEFAULT;
 const DEFAULT_STARTUP_DELAY = TIMEOUTS.SERVER_STARTUP;
 /**
@@ -44,6 +45,8 @@ export class MCPClient {
     connectionState = { attempted: false };
     /** Protocol version negotiated with the server during initialization */
     negotiatedProtocolVersion = null;
+    /** Whether to run an explicit preflight before remote connection */
+    remotePreflight;
     constructor(options) {
         this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
         this.startupDelay = options?.startupDelay ?? DEFAULT_STARTUP_DELAY;
@@ -51,6 +54,96 @@ export class MCPClient {
         this.transportType = options?.transport ?? 'stdio';
         this.sseConfig = options?.sseConfig;
         this.httpConfig = options?.httpConfig;
+        this.remotePreflight = options?.remotePreflight ?? true;
+    }
+    /**
+     * Merge two header maps, giving precedence to override values.
+     */
+    mergeHeaders(base, override) {
+        if (!base && !override)
+            return undefined;
+        const merged = {};
+        const apply = (headers) => {
+            if (!headers)
+                return;
+            for (const [name, value] of Object.entries(headers)) {
+                const normalized = name.toLowerCase();
+                for (const existing of Object.keys(merged)) {
+                    if (existing.toLowerCase() === normalized) {
+                        delete merged[existing];
+                        break;
+                    }
+                }
+                merged[name] = value;
+            }
+        };
+        apply(base);
+        apply(override);
+        return Object.keys(merged).length > 0 ? merged : undefined;
+    }
+    /**
+     * Optional remote connectivity/auth preflight (enabled by default).
+     * Uses GET (not HEAD/OPTIONS) for broader compatibility.
+     *
+     * Any successful HTTP response (including 404/405/etc.) confirms network reachability.
+     * Only auth failures and hard network/timeouts are treated as terminal preflight failures.
+     */
+    async preflightRemote(url, transport, headers) {
+        if (!this.remotePreflight) {
+            return;
+        }
+        const endpoint = transport === 'sse' ? `${url.replace(/\/$/, '')}/sse` : url;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), Math.min(this.timeout, 5000));
+        try {
+            const response = await fetch(endpoint, {
+                method: 'GET',
+                headers: {
+                    Accept: transport === 'sse' ? 'text/event-stream' : 'application/json, text/event-stream',
+                    ...(headers ?? {}),
+                },
+                signal: controller.signal,
+            });
+            const closePreflightBody = async () => {
+                try {
+                    await response.body?.cancel();
+                }
+                catch {
+                    // Ignore body cancellation failures; preflight status handling is primary.
+                }
+            };
+            if (response.status === 401) {
+                await closePreflightBody();
+                throw new ServerAuthError(`Remote MCP preflight failed: unauthorized (${response.status})`, response.status, 'Add authentication headers (for example Authorization) and retry.');
+            }
+            if (response.status === 403) {
+                await closePreflightBody();
+                throw new ServerAuthError(`Remote MCP preflight failed: forbidden (${response.status})`, response.status, 'Credentials are valid but lack required permissions/scopes.');
+            }
+            if (response.status === 407) {
+                await closePreflightBody();
+                throw new ServerAuthError(`Remote MCP preflight failed: proxy authentication required (${response.status})`, response.status, 'Configure proxy credentials and retry.');
+            }
+            if (!response.ok) {
+                // Non-auth HTTP statuses are compatibility-safe to continue:
+                // some MCP servers reject generic GET preflight paths but still
+                // support their actual protocol endpoints for normal operation.
+                this.logger.debug({ endpoint, status: response.status }, 'Remote preflight received non-auth HTTP status; continuing to transport connect');
+            }
+            await closePreflightBody();
+        }
+        catch (error) {
+            if (error instanceof ServerAuthError || error instanceof ConnectionError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new ConnectionError(`Remote MCP preflight timed out for ${endpoint}`);
+            }
+            throw new ConnectionError(`Remote MCP preflight failed for ${endpoint}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     /**
      * Classify a transport error based on its message.
@@ -75,6 +168,12 @@ export class MCPClient {
                 return { category: 'connection_refused', likelyServerBug: false };
             }
         }
+        // Check for authentication failures (environment/config issue)
+        for (const pattern of TRANSPORT_ERRORS.AUTH_FAILURE_PATTERNS) {
+            if (pattern.test(msg)) {
+                return { category: 'auth_failed', likelyServerBug: false };
+            }
+        }
         // Check for connection lost
         for (const pattern of TRANSPORT_ERRORS.CONNECTION_LOST_PATTERNS) {
             if (pattern.test(msg)) {
@@ -138,6 +237,8 @@ export class MCPClient {
                 return 'Server response exceeded buffer limits';
             case 'connection_refused':
                 return 'Failed to connect to server process';
+            case 'auth_failed':
+                return 'Authentication failed when connecting to remote MCP server';
             case 'connection_lost':
                 return 'Connection to server was lost unexpectedly';
             case 'protocol_violation':
@@ -228,6 +329,7 @@ export class MCPClient {
         this.transport.on('error', (error) => {
             this.logger.error({ error: error.message }, 'Transport error');
             this.recordTransportError(error, 'stdio_transport');
+            this.clearPendingRequests(error.message);
         });
         this.transport.on('close', () => {
             this.logger.debug('Transport closed');
@@ -279,27 +381,36 @@ export class MCPClient {
         // Reset flags for new connection
         this.cleaningUp = false;
         this.disconnecting = false;
+        // Track connection state for diagnostics
+        this.connectionState = {
+            attempted: true,
+            url,
+        };
         this.logger.info({ url, transport }, 'Connecting to remote MCP server');
+        const mergedHeaders = transport === 'sse'
+            ? this.mergeHeaders(this.sseConfig?.headers, options?.headers)
+            : this.mergeHeaders(this.httpConfig?.headers, options?.headers);
+        await this.preflightRemote(url, transport, mergedHeaders);
         if (transport === 'sse') {
             const sseTransport = new SSETransport({
+                ...this.sseConfig,
                 baseUrl: url,
                 sessionId: options?.sessionId ?? this.sseConfig?.sessionId,
-                headers: options?.headers ?? this.sseConfig?.headers,
+                headers: mergedHeaders,
                 timeout: this.timeout,
                 debug: this.debug,
-                ...this.sseConfig,
             });
             await sseTransport.connect();
             this.transport = sseTransport;
         }
         else if (transport === 'streamable-http') {
             const httpTransport = new HTTPTransport({
+                ...this.httpConfig,
                 baseUrl: url,
                 sessionId: options?.sessionId ?? this.httpConfig?.sessionId,
-                headers: options?.headers ?? this.httpConfig?.headers,
+                headers: mergedHeaders,
                 timeout: this.timeout,
                 debug: this.debug,
-                ...this.httpConfig,
             });
             await httpTransport.connect();
             this.transport = httpTransport;
@@ -324,6 +435,7 @@ export class MCPClient {
         this.transport.on('error', (error) => {
             this.logger.error({ error: error.message }, 'Transport error');
             this.recordTransportError(error, 'remote_transport');
+            this.clearPendingRequests(error.message);
         });
         this.transport.on('close', () => {
             this.logger.debug('Transport closed');

package/dist/transport/sse-transport.js

@@ -1,6 +1,7 @@
 import { BaseTransport } from './base-transport.js';
 import { TIME_CONSTANTS, TIMEOUTS } from '../constants.js';
 import { isLocalhost } from '../utils/index.js';
+import { ServerAuthError } from '../errors/types.js';
 /**
  * Validate that a URL uses HTTPS in production contexts.
  * Allows HTTP only for localhost/127.0.0.1 for local development.
@@ -161,6 +162,15 @@ export class SSETransport extends BaseTransport {
             signal: this.streamAbortController.signal,
         });
         if (!response.ok) {
+            if (response.status === 401) {
+                throw new ServerAuthError('Remote MCP SSE authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
+            }
+            if (response.status === 403) {
+                throw new ServerAuthError('Remote MCP SSE authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
+            }
+            if (response.status === 407) {
+                throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+            }
             throw new Error(`Failed to connect to SSE endpoint: HTTP ${response.status}`);
         }
         if (!response.body) {
@@ -334,6 +344,15 @@ export class SSETransport extends BaseTransport {
             .then(async (response) => {
             clearTimeout(timeoutId);
             if (!response.ok) {
+                if (response.status === 401) {
+                    throw new ServerAuthError('Remote MCP message authentication failed (401 Unauthorized)', 401, 'Add server.headers.Authorization (for example: Bearer token) in bellwether.yaml or pass --header.');
+                }
+                if (response.status === 403) {
+                    throw new ServerAuthError('Remote MCP message authorization failed (403 Forbidden)', 403, 'Credentials are recognized but lack required permissions. Verify token scopes/roles.');
+                }
+                if (response.status === 407) {
+                    throw new ServerAuthError('Proxy authentication required (407)', 407, 'Configure proxy credentials and retry.');
+                }
                 const errorText = await response.text().catch(() => 'Unknown error');
                 throw new Error(`HTTP ${response.status}: ${errorText}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotsetlabs/bellwether",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "The open-source MCP testing tool. Structural drift detection and behavioral documentation for Model Context Protocol servers.",
   "type": "module",
   "main": "dist/index.js",
@@ -36,9 +36,7 @@
     "clean": "rm -rf dist",
     "docs:generate": "npm --prefix website run build",
     "docs:dev": "npm --prefix website run start",
-    "man:generate": "./scripts/generate-manpage.sh",
-    "prepare": "husky install || true",
-    "prepublishOnly": "npm run build && npm run man:generate"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "mcp",
@@ -75,7 +73,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.72.1",
+    "@anthropic-ai/sdk": "^0.74.0",
     "ajv": "^8.17.1",
     "chalk": "^5.4.1",
     "cli-progress": "^3.12.0",
@@ -98,25 +96,16 @@
     "@typescript-eslint/parser": "^6.21.0",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^8.57.1",
-    "husky": "^9.1.0",
-    "lint-staged": "^16.2.7",
     "prettier": "^3.3.0",
     "tsx": "^4.21.0",
     "typescript": "^5.3.0",
     "vitest": "^4.0.17"
   },
-  "lint-staged": {
-    "*.ts": [
-      "eslint --fix",
-      "prettier --write"
-    ]
-  },
   "files": [
     "dist",
     "!dist/**/*.map",
     "schemas",
     "scripts/completions",
-    "man",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",