@dotsetlabs/bellwether 2.0.0 → 2.1.0

package/dist/transport/mcp-client.js

@@ -5,6 +5,7 @@ import { HTTPTransport } from './http-transport.js';
 import { getLogger, startTiming } from '../logging/logger.js';
 import { TIMEOUTS, MCP, TRANSPORT_ERRORS } from '../constants.js';
 import { VERSION } from '../version.js';
+import { getFeatureFlags, isKnownProtocolVersion, } from '../protocol/index.js';
 /**
  * Environment variables to filter out when spawning MCP server processes.
  * These may contain sensitive credentials that should not be exposed.
@@ -75,6 +76,7 @@ export class MCPClient {
     requestId = 0;
     pendingRequests = new Map();
     serverCapabilities = null;
+    serverInstructions;
     timeout;
     startupDelay;
     serverReady = false;
@@ -92,6 +94,8 @@ export class MCPClient {
     transportErrors = [];
     /** Connection state for diagnostic error messages */
     connectionState = { attempted: false };
+    /** Protocol version negotiated with the server during initialization */
+    negotiatedProtocolVersion = null;
     constructor(options) {
         this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
         this.startupDelay = options?.startupDelay ?? DEFAULT_STARTUP_DELAY;
@@ -444,9 +448,19 @@ export class MCPClient {
                 },
             });
             this.serverCapabilities = result.capabilities;
+            this.serverInstructions = result.instructions;
+            this.negotiatedProtocolVersion = result.protocolVersion;
+            // Warn if server returned an unknown protocol version
+            if (result.protocolVersion && !isKnownProtocolVersion(result.protocolVersion)) {
+                this.logger.warn({ protocolVersion: result.protocolVersion }, 'Server returned unknown protocol version');
+            }
+            // Update HTTP transport with negotiated version for subsequent requests
+            if (this.transport instanceof HTTPTransport && result.protocolVersion) {
+                this.transport.setNegotiatedVersion(result.protocolVersion);
+            }
             // Send initialized notification
             this.sendNotification('notifications/initialized', {});
-            this.logger.info({ capabilities: result.capabilities }, 'MCP server initialized successfully');
+            this.logger.info({ capabilities: result.capabilities, protocolVersion: result.protocolVersion }, 'MCP server initialized successfully');
             return result;
         }
         catch (error) {
@@ -477,24 +491,71 @@ export class MCPClient {
     }
     /**
      * List all tools available on the server.
+     * Handles pagination via nextCursor per MCP 2025-11-25 spec.
      */
     async listTools(options) {
-        const result = await this.sendRequest('tools/list', {}, options);
-        return result.tools;
+        const allTools = [];
+        let cursor;
+        do {
+            const params = {};
+            if (cursor)
+                params.cursor = cursor;
+            const result = await this.sendRequest('tools/list', params, options);
+            allTools.push(...result.tools);
+            cursor = result.nextCursor;
+        } while (cursor);
+        return allTools;
     }
     /**
      * List all prompts available on the server.
+     * Handles pagination via nextCursor per MCP 2025-11-25 spec.
      */
     async listPrompts(options) {
-        const result = await this.sendRequest('prompts/list', {}, options);
-        return result.prompts;
+        const allPrompts = [];
+        let cursor;
+        do {
+            const params = {};
+            if (cursor)
+                params.cursor = cursor;
+            const result = await this.sendRequest('prompts/list', params, options);
+            allPrompts.push(...result.prompts);
+            cursor = result.nextCursor;
+        } while (cursor);
+        return allPrompts;
     }
     /**
      * List all resources available on the server.
+     * Handles pagination via nextCursor per MCP 2025-11-25 spec.
      */
     async listResources(options) {
-        const result = await this.sendRequest('resources/list', {}, options);
-        return result.resources;
+        const allResources = [];
+        let cursor;
+        do {
+            const params = {};
+            if (cursor)
+                params.cursor = cursor;
+            const result = await this.sendRequest('resources/list', params, options);
+            allResources.push(...result.resources);
+            cursor = result.nextCursor;
+        } while (cursor);
+        return allResources;
+    }
+    /**
+     * List all resource templates available on the server.
+     * Handles pagination via nextCursor per MCP 2025-11-25 spec.
+     */
+    async listResourceTemplates(options) {
+        const allTemplates = [];
+        let cursor;
+        do {
+            const params = {};
+            if (cursor)
+                params.cursor = cursor;
+            const result = await this.sendRequest('resources/templates/list', params, options);
+            allTemplates.push(...result.resourceTemplates);
+            cursor = result.nextCursor;
+        } while (cursor);
+        return allTemplates;
     }
     /**
      * Read a resource from the server by URI.
@@ -555,6 +616,28 @@ export class MCPClient {
     getCapabilities() {
         return this.serverCapabilities;
     }
+    /**
+     * Get server instructions from initialization.
+     */
+    getInstructions() {
+        return this.serverInstructions;
+    }
+    /**
+     * Get the protocol version negotiated with the server during initialization.
+     * Returns null if initialization hasn't completed yet.
+     */
+    getNegotiatedProtocolVersion() {
+        return this.negotiatedProtocolVersion;
+    }
+    /**
+     * Get feature flags based on the negotiated protocol version.
+     * Returns null if initialization hasn't completed yet.
+     */
+    getFeatureFlags() {
+        if (!this.negotiatedProtocolVersion)
+            return null;
+        return getFeatureFlags(this.negotiatedProtocolVersion);
+    }
     /**
      * Check if the server is ready (startup delay complete and initialized).
      * Note: This only indicates if startup delay has passed - true readiness
@@ -764,6 +847,8 @@ export class MCPClient {
         this.transport = null;
         this.process = null;
         this.serverCapabilities = null;
+        this.serverInstructions = undefined;
+        this.negotiatedProtocolVersion = null;
         this.serverReady = false;
     }
 }

package/dist/transport/sse-transport.js

@@ -316,10 +316,11 @@ export class SSETransport extends BaseTransport {
         // Use the endpoint provided by the server, or default to /message
         const endpoint = this.messageEndpoint || `${this.baseUrl}/message`;
         this.log('Sending message', { endpoint, message });
-        // Create a new abort controller for this request
-        this.abortController = new AbortController();
+        // Create a local abort controller for this request to avoid overwriting
+        // the instance controller and leaking previous controllers
+        const requestController = new AbortController();
         const timeoutId = setTimeout(() => {
-            this.abortController?.abort();
+            requestController.abort();
         }, this.timeout);
         fetch(endpoint, {
             method: 'POST',
@@ -328,7 +329,7 @@ export class SSETransport extends BaseTransport {
                 ...this.headers,
             },
             body: JSON.stringify(message),
-            signal: this.abortController.signal,
+            signal: requestController.signal,
         })
             .then(async (response) => {
             clearTimeout(timeoutId);

package/dist/transport/types.d.ts

@@ -25,41 +25,122 @@ export interface JSONRPCNotification {
 }
 export type JSONRPCMessage = JSONRPCRequest | JSONRPCResponse | JSONRPCNotification;
 /**
- * MCP Protocol types
+ * MCP Protocol types (aligned with MCP specification 2025-11-25)
  */
+/**
+ * Icon for MCP entities (tools, resources, prompts, server).
+ */
+export interface MCPIcon {
+    /** URI or data URI for the icon */
+    src: string;
+    /** MIME type of the icon */
+    mimeType?: string;
+    /** Supported sizes (e.g., ['16x16', '32x32']) */
+    sizes?: string[];
+    /** Theme hint for the icon */
+    theme?: 'light' | 'dark';
+}
+/**
+ * Annotations for content blocks and resources.
+ * Provides metadata about intended audience, priority, and freshness.
+ */
+export interface MCPAnnotations {
+    /** Intended audience for the content */
+    audience?: ('user' | 'assistant')[];
+    /** Priority hint (0.0 = lowest, 1.0 = highest) */
+    priority?: number;
+    /** ISO 8601 timestamp of when the content was last modified */
+    lastModified?: string;
+}
+/**
+ * Behavioral annotations for tools.
+ * Provides hints about tool behavior to help clients make decisions.
+ */
+export interface MCPToolAnnotations {
+    /** Human-readable title for the annotation group */
+    title?: string;
+    /** Whether the tool only reads data and does not modify state */
+    readOnlyHint?: boolean;
+    /** Whether the tool may perform destructive operations */
+    destructiveHint?: boolean;
+    /** Whether calling the tool multiple times with the same args has the same effect */
+    idempotentHint?: boolean;
+    /** Whether the tool interacts with entities outside the server's controlled environment */
+    openWorldHint?: boolean;
+}
 export interface MCPTool {
     name: string;
     description?: string;
     inputSchema?: Record<string, unknown>;
+    /** Human-readable title for the tool */
+    title?: string;
+    /** Icons for the tool */
+    icons?: MCPIcon[];
+    /** JSON Schema for the tool's output (structured content) */
+    outputSchema?: Record<string, unknown>;
+    /** Behavioral annotations/hints */
+    annotations?: MCPToolAnnotations;
+    /** Task execution configuration */
+    execution?: {
+        taskSupport?: 'forbidden' | 'optional' | 'required';
+    };
+    /** Extension metadata */
+    _meta?: Record<string, unknown>;
 }
 export interface MCPPrompt {
     name: string;
     description?: string;
     arguments?: MCPPromptArgument[];
+    /** Human-readable title for the prompt */
+    title?: string;
+    /** Icons for the prompt */
+    icons?: MCPIcon[];
+    /** Extension metadata */
+    _meta?: Record<string, unknown>;
 }
 export interface MCPPromptArgument {
     name: string;
     description?: string;
     required?: boolean;
+    /** Human-readable title for the argument */
+    title?: string;
 }
 export interface MCPServerCapabilities {
     tools?: Record<string, unknown>;
     prompts?: Record<string, unknown>;
     resources?: Record<string, unknown>;
     logging?: Record<string, unknown>;
+    /** Server supports completions (autocomplete) */
+    completions?: Record<string, unknown>;
+    /** Server supports task management */
+    tasks?: Record<string, unknown>;
+    /** Experimental/vendor-specific capabilities */
+    experimental?: Record<string, unknown>;
 }
 export interface MCPServerInfo {
     name: string;
     version: string;
+    /** Human-readable title for the server */
+    title?: string;
+    /** Description of the server */
+    description?: string;
+    /** Icons for the server */
+    icons?: MCPIcon[];
+    /** Website URL for the server */
+    websiteUrl?: string;
 }
 export interface MCPInitializeResult {
     protocolVersion: string;
     capabilities: MCPServerCapabilities;
     serverInfo: MCPServerInfo;
+    /** Server-provided instructions for the client */
+    instructions?: string;
 }
 export interface MCPToolCallResult {
     content: MCPContentBlock[];
     isError?: boolean;
+    /** Structured output content (validated against tool's outputSchema) */
+    structuredContent?: Record<string, unknown>;
 }
 /**
  * MCP content block types per MCP specification (2025-11-25).
@@ -75,12 +156,26 @@ export interface MCPContentBlock {
     mimeType?: string;
     /** URI reference (for type: 'resource_link') */
     uri?: string;
+    /** Content/resource annotations */
+    annotations?: MCPAnnotations;
+    /** Extension metadata */
+    _meta?: Record<string, unknown>;
+    /** Embedded resource content (for type: 'resource') */
+    resource?: MCPResourceContent;
+    /** Resource name (for type: 'resource_link') */
+    name?: string;
+    /** Resource description (for type: 'resource_link') */
+    description?: string;
 }
 export interface MCPToolsListResult {
     tools: MCPTool[];
+    /** Cursor for pagination */
+    nextCursor?: string;
 }
 export interface MCPPromptsListResult {
     prompts: MCPPrompt[];
+    /** Cursor for pagination */
+    nextCursor?: string;
 }
 /**
  * MCP Resource types
@@ -94,9 +189,21 @@ export interface MCPResource {
     description?: string;
     /** MIME type of the resource content */
     mimeType?: string;
+    /** Human-readable title for the resource */
+    title?: string;
+    /** Icons for the resource */
+    icons?: MCPIcon[];
+    /** Resource annotations */
+    annotations?: MCPAnnotations;
+    /** Size of the resource in bytes */
+    size?: number;
+    /** Extension metadata */
+    _meta?: Record<string, unknown>;
 }
 export interface MCPResourcesListResult {
     resources: MCPResource[];
+    /** Cursor for pagination */
+    nextCursor?: string;
 }
 export interface MCPResourceReadResult {
     contents: MCPResourceContent[];
@@ -111,6 +218,32 @@ export interface MCPResourceContent {
     /** Binary content as base64 (for binary resources) */
     blob?: string;
 }
+/**
+ * MCP Resource Template for URI-templated resources.
+ */
+export interface MCPResourceTemplate {
+    /** URI template (RFC 6570) */
+    uriTemplate: string;
+    /** Human-readable name */
+    name: string;
+    /** Human-readable title */
+    title?: string;
+    /** Description of the resource template */
+    description?: string;
+    /** Expected MIME type of resources matching this template */
+    mimeType?: string;
+    /** Icons for the resource template */
+    icons?: MCPIcon[];
+    /** Resource annotations */
+    annotations?: MCPAnnotations;
+    /** Extension metadata */
+    _meta?: Record<string, unknown>;
+}
+export interface MCPResourceTemplatesListResult {
+    resourceTemplates: MCPResourceTemplate[];
+    /** Cursor for pagination */
+    nextCursor?: string;
+}
 export interface MCPPromptMessage {
     role: 'user' | 'assistant';
     content: MCPPromptContent;

package/dist/utils/concurrency.d.ts

@@ -7,6 +7,8 @@
 export interface ParallelOptions<T> {
     /** Maximum concurrent tasks (default: 3) */
     concurrency?: number;
+    /** Timeout per task in milliseconds (default: no timeout) */
+    taskTimeoutMs?: number;
     /** Callback when a task completes */
     onTaskComplete?: (result: T, index: number) => void;
     /** Callback when a task fails */

package/dist/utils/concurrency.js

@@ -10,7 +10,7 @@
  * @returns Results of all tasks
  */
 export async function parallelLimit(tasks, options = {}) {
-    const { concurrency = 3, onTaskComplete, onTaskError } = options;
+    const { concurrency = 3, taskTimeoutMs, onTaskComplete, onTaskError } = options;
     const results = new Array(tasks.length);
     const errors = new Map();
     let running = 0;
@@ -30,7 +30,14 @@ export async function parallelLimit(tasks, options = {}) {
             while (running < concurrency && index < tasks.length) {
                 const currentIndex = index++;
                 running++;
-                tasks[currentIndex]()
+                const taskPromise = tasks[currentIndex]();
+                const wrappedPromise = taskTimeoutMs
+                    ? Promise.race([
+                        taskPromise,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Task ${currentIndex} timed out after ${taskTimeoutMs}ms`)), taskTimeoutMs)),
+                    ])
+                    : taskPromise;
+                wrappedPromise
                     .then((result) => {
                     results[currentIndex] = result;
                     onTaskComplete?.(result, currentIndex);

package/dist/utils/markdown.js

@@ -15,13 +15,13 @@ import { DISPLAY_LIMITS } from '../constants.js';
 export function escapeTableCell(text) {
     if (!text)
         return '';
-    return text
+    return (text
         // Escape pipe characters (break table columns)
         .replace(/\|/g, '\\|')
         // Escape newlines (break table rows)
         .replace(/\r?\n/g, '<br>')
         // Escape leading/trailing whitespace that might affect rendering
-        .trim();
+        .trim());
 }
 /**
  * Escape a string for use inside a code block.
@@ -47,7 +47,7 @@ export function escapeCodeBlock(text) {
 export function escapeMermaid(text) {
     if (!text)
         return '';
-    return text
+    return (text
         // Escape double quotes (break Mermaid string literals)
         .replace(/"/g, '#quot;')
         // Escape square brackets (node syntax)
@@ -64,7 +64,7 @@ export function escapeMermaid(text) {
         .replace(/->/g, '#rarr;')
         .replace(/\|/g, '#pipe;')
         // Escape newlines
-        .replace(/\r?\n/g, ' ');
+        .replace(/\r?\n/g, ' '));
 }
 /**
  * Escape a string for use as a Mermaid node label.
@@ -81,10 +81,7 @@ export function mermaidLabel(text) {
         return text;
     }
     // Escape and wrap in quotes for complex text
-    const escaped = text
-        .replace(/"/g, "'")
-        .replace(/\r?\n/g, ' ')
-        .trim();
+    const escaped = text.replace(/"/g, "'").replace(/\r?\n/g, ' ').trim();
     return `"${escaped}"`;
 }
 /**
@@ -104,9 +101,7 @@ export function validateJsonForCodeBlock(json, options = {}) {
     if (typeof json === 'string') {
         try {
             const parsed = JSON.parse(json);
-            content = prettyPrint
-                ? JSON.stringify(parsed, null, indent)
-                : JSON.stringify(parsed);
+            content = prettyPrint ? JSON.stringify(parsed, null, indent) : JSON.stringify(parsed);
         }
         catch (e) {
             valid = false;
@@ -116,9 +111,7 @@ export function validateJsonForCodeBlock(json, options = {}) {
     }
     else {
         try {
-            content = prettyPrint
-                ? JSON.stringify(json, null, indent)
-                : JSON.stringify(json);
+            content = prettyPrint ? JSON.stringify(json, null, indent) : JSON.stringify(json);
         }
         catch (e) {
             valid = false;
@@ -164,12 +157,12 @@ export function escapeInlineCode(text) {
 export function escapeLinkTitle(text) {
     if (!text)
         return '';
-    return text
+    return (text
         // Escape quotes
         .replace(/"/g, '\\"')
         // Escape parentheses
         .replace(/\)/g, '\\)')
-        .replace(/\(/g, '\\(');
+        .replace(/\(/g, '\\('));
 }
 /**
  * Escape text for use in a Markdown bullet list item.
@@ -236,7 +229,7 @@ export function wrapTableCell(text, maxWidth = DISPLAY_LIMITS.TABLE_CELL_MAX_WID
 export function buildTable(headers, rows, alignments) {
     const lines = [];
     // Header row
-    const escapedHeaders = headers.map(h => escapeTableCell(h));
+    const escapedHeaders = headers.map((h) => escapeTableCell(h));
     lines.push(`| ${escapedHeaders.join(' | ')} |`);
     // Separator row with alignment
     const separators = headers.map((_, i) => {
@@ -253,11 +246,13 @@ export function buildTable(headers, rows, alignments) {
     lines.push(`| ${separators.join(' | ')} |`);
     // Data rows
     for (const row of rows) {
-        const escapedCells = row.map(cell => escapeTableCell(cell));
+        const escapedCells = row.map((cell) => escapeTableCell(cell));
         // Pad row if needed
         while (escapedCells.length < headers.length) {
             escapedCells.push('');
         }
+        // Truncate excess columns
+        escapedCells.length = headers.length;
         lines.push(`| ${escapedCells.join(' | ')} |`);
     }
     return lines.join('\n');

package/dist/utils/timeout.js

@@ -95,7 +95,8 @@ export async function withTimeout(promise, timeoutMs, operationName, options) {
         return await Promise.race([promise, timeoutPromise]);
     }
     finally {
-        clearTimeout(timeoutId);
+        if (timeoutId)
+            clearTimeout(timeoutId);
     }
 }
 /**

package/dist/version.js

@@ -30,7 +30,7 @@ function getPackageVersion() {
     }
     catch {
         // Fallback version - should match package.json
-        return '2.0.0';
+        return '2.1.0';
     }
 }
 /**

package/man/bellwether.1

@@ -1,4 +1,4 @@
-.TH "BELLWETHER" "1" "2026\-02\-04" "Bellwether 2.0.0" "User Commands"
+.TH "BELLWETHER" "1" "2026\-02\-11" "Bellwether 2.1.0" "User Commands"
 .SH NAME
 .PP
 bellwether \[em] MCP server testing and validation tool

package/man/bellwether.1.md

@@ -2,8 +2,8 @@
 title: BELLWETHER
 section: 1
 header: User Commands
-footer: Bellwether 2.0.0
-date: 2026-02-04
+footer: Bellwether 2.1.0
+date: 2026-02-11
 ---
 
 # NAME

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotsetlabs/bellwether",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "The open-source MCP testing tool. Structural drift detection and behavioral documentation for Model Context Protocol servers.",
   "type": "module",
   "main": "dist/index.js",
@@ -95,6 +95,7 @@
     "@types/node": "^25.0.9",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@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",