mock-mcp 0.3.0 → 0.5.0

package/dist/client/batch-mock-collector.js

@@ -1,223 +0,0 @@
-import WebSocket from "ws";
-import { BATCH_MOCK_REQUEST, BATCH_MOCK_RESPONSE, } from "../types.js";
-import { isEnabled } from "./util.js";
-const DEFAULT_TIMEOUT = 60_000;
-const DEFAULT_BATCH_DEBOUNCE_MS = 0;
-const DEFAULT_MAX_BATCH_SIZE = 50;
-const DEFAULT_PORT = 3002;
-/**
- * Collects HTTP requests issued during a single macrotask and forwards them to
- * the MCP server as a batch for AI-assisted mock generation.
- */
-export class BatchMockCollector {
-    ws;
-    pendingRequests = new Map();
-    queuedRequestIds = new Set();
-    timeout;
-    batchDebounceMs;
-    maxBatchSize;
-    logger;
-    batchTimer = null;
-    requestIdCounter = 0;
-    closed = false;
-    readyResolve;
-    readyReject;
-    readyPromise;
-    constructor(options = {}) {
-        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
-        this.batchDebounceMs = options.batchDebounceMs ?? DEFAULT_BATCH_DEBOUNCE_MS;
-        this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
-        this.logger = options.logger ?? console;
-        const port = options.port ?? DEFAULT_PORT;
-        this.readyPromise = new Promise((resolve, reject) => {
-            this.readyResolve = resolve;
-            this.readyReject = reject;
-        });
-        const wsUrl = `ws://localhost:${port}`;
-        this.ws = new WebSocket(wsUrl);
-        this.setupWebSocket();
-    }
-    /**
-     * Ensures the underlying WebSocket connection is ready for use.
-     */
-    async waitUntilReady() {
-        return this.readyPromise;
-    }
-    /**
-     * Request mock data for a specific endpoint/method pair.
-     */
-    async requestMock(endpoint, method, options = {}) {
-        if (this.closed) {
-            throw new Error("BatchMockCollector has been closed");
-        }
-        await this.waitUntilReady();
-        const requestId = `req-${++this.requestIdCounter}`;
-        const request = {
-            requestId,
-            endpoint,
-            method,
-            body: options.body,
-            headers: options.headers,
-            metadata: options.metadata,
-        };
-        let settleCompletion;
-        const completion = new Promise((resolve) => {
-            settleCompletion = resolve;
-        });
-        return new Promise((resolve, reject) => {
-            const timeoutId = setTimeout(() => {
-                this.rejectRequest(requestId, new Error(`Mock request timed out after ${this.timeout}ms: ${method} ${endpoint}`));
-            }, this.timeout);
-            this.pendingRequests.set(requestId, {
-                request,
-                resolve: (data) => {
-                    settleCompletion({ status: "fulfilled", value: undefined });
-                    resolve(data);
-                },
-                reject: (error) => {
-                    settleCompletion({ status: "rejected", reason: error });
-                    reject(error);
-                },
-                timeoutId,
-                completion,
-            });
-            this.enqueueRequest(requestId);
-        });
-    }
-    /**
-     * Wait for all requests that are currently pending to settle. Requests
-     * created after this method is called are not included.
-     */
-    async waitForPendingRequests() {
-        if (!isEnabled()) {
-            return;
-        }
-        const pendingCompletions = Array.from(this.pendingRequests.values()).map((pending) => pending.completion);
-        const results = await Promise.all(pendingCompletions);
-        const rejected = results.find((result) => result.status === "rejected");
-        if (rejected) {
-            throw rejected.reason;
-        }
-    }
-    /**
-     * Close the underlying connection and fail all pending requests.
-     */
-    async close(code) {
-        if (this.closed) {
-            return;
-        }
-        this.closed = true;
-        if (this.batchTimer) {
-            clearTimeout(this.batchTimer);
-            this.batchTimer = null;
-        }
-        this.queuedRequestIds.clear();
-        const closePromise = new Promise((resolve) => {
-            this.ws.once("close", () => resolve());
-        });
-        this.ws.close(code);
-        this.failAllPending(new Error("BatchMockCollector has been closed"));
-        await closePromise;
-    }
-    setupWebSocket() {
-        this.ws.on("open", () => {
-            this.logger.log("🔌 Connected to mock MCP WebSocket endpoint");
-            this.readyResolve?.();
-        });
-        this.ws.on("message", (data) => this.handleMessage(data));
-        this.ws.on("error", (error) => {
-            this.logger.error("❌ WebSocket error:", error);
-            this.readyReject?.(error instanceof Error ? error : new Error(String(error)));
-            this.failAllPending(error instanceof Error ? error : new Error(String(error)));
-        });
-        this.ws.on("close", () => {
-            this.logger.warn("🔌 WebSocket connection closed");
-            this.failAllPending(new Error("WebSocket connection closed"));
-        });
-    }
-    handleMessage(data) {
-        let parsed;
-        try {
-            parsed = JSON.parse(data.toString());
-        }
-        catch (error) {
-            this.logger.error("Failed to parse server message:", error);
-            return;
-        }
-        if (parsed.type !== BATCH_MOCK_RESPONSE) {
-            this.logger.warn("Received unsupported message type", parsed.type);
-            return;
-        }
-        this.logger.debug?.(`📦 Received mock data for ${parsed.mocks.length} requests (batch ${parsed.batchId})`);
-        for (const mock of parsed.mocks) {
-            this.resolveRequest(mock);
-        }
-    }
-    resolveRequest(mock) {
-        const pending = this.pendingRequests.get(mock.requestId);
-        if (!pending) {
-            this.logger.warn(`Received mock for unknown request: ${mock.requestId}`);
-            return;
-        }
-        clearTimeout(pending.timeoutId);
-        this.pendingRequests.delete(mock.requestId);
-        pending.resolve(mock.data);
-    }
-    enqueueRequest(requestId) {
-        this.queuedRequestIds.add(requestId);
-        if (this.batchTimer) {
-            return;
-        }
-        this.batchTimer = setTimeout(() => {
-            this.batchTimer = null;
-            this.flushQueue();
-        }, this.batchDebounceMs);
-    }
-    flushQueue() {
-        const queuedIds = Array.from(this.queuedRequestIds);
-        this.queuedRequestIds.clear();
-        if (queuedIds.length === 0) {
-            return;
-        }
-        for (let i = 0; i < queuedIds.length; i += this.maxBatchSize) {
-            const chunkIds = queuedIds.slice(i, i + this.maxBatchSize);
-            const requests = [];
-            for (const id of chunkIds) {
-                const pending = this.pendingRequests.get(id);
-                if (pending) {
-                    requests.push(pending.request);
-                }
-            }
-            if (requests.length > 0) {
-                this.sendBatch(requests);
-            }
-        }
-    }
-    sendBatch(requests) {
-        if (this.ws.readyState !== WebSocket.OPEN) {
-            const error = new Error("WebSocket is not open");
-            requests.forEach((request) => this.rejectRequest(request.requestId, error));
-            return;
-        }
-        const payload = {
-            type: BATCH_MOCK_REQUEST,
-            requests,
-        };
-        this.logger.debug?.(`📤 Sending batch with ${requests.length} request(s) to MCP server`);
-        this.ws.send(JSON.stringify(payload));
-    }
-    rejectRequest(requestId, error) {
-        const pending = this.pendingRequests.get(requestId);
-        if (!pending) {
-            return;
-        }
-        clearTimeout(pending.timeoutId);
-        this.pendingRequests.delete(requestId);
-        pending.reject(error);
-    }
-    failAllPending(error) {
-        for (const requestId of Array.from(this.pendingRequests.keys())) {
-            this.rejectRequest(requestId, error);
-        }
-    }
-}

package/dist/client/util.d.ts

@@ -1 +0,0 @@
-export declare const isEnabled: () => boolean;

package/dist/client/util.js

@@ -1,3 +0,0 @@
-export const isEnabled = () => {
-    return process.env.MOCK_MCP !== undefined && process.env.MOCK_MCP !== "0";
-};

package/dist/connect.cjs

@@ -1,299 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/client/connect.ts
-var connect_exports = {};
-__export(connect_exports, {
-  connect: () => connect
-});
-module.exports = __toCommonJS(connect_exports);
-
-// src/client/batch-mock-collector.ts
-var import_ws = __toESM(require("ws"), 1);
-
-// src/types.ts
-var BATCH_MOCK_REQUEST = "BATCH_MOCK_REQUEST";
-var BATCH_MOCK_RESPONSE = "BATCH_MOCK_RESPONSE";
-
-// src/client/util.ts
-var isEnabled = () => {
-  return process.env.MOCK_MCP !== void 0 && process.env.MOCK_MCP !== "0";
-};
-
-// src/client/batch-mock-collector.ts
-var DEFAULT_TIMEOUT = 6e4;
-var DEFAULT_BATCH_DEBOUNCE_MS = 0;
-var DEFAULT_MAX_BATCH_SIZE = 50;
-var DEFAULT_PORT = 3002;
-var BatchMockCollector = class {
-  ws;
-  pendingRequests = /* @__PURE__ */ new Map();
-  queuedRequestIds = /* @__PURE__ */ new Set();
-  timeout;
-  batchDebounceMs;
-  maxBatchSize;
-  logger;
-  batchTimer = null;
-  requestIdCounter = 0;
-  closed = false;
-  readyResolve;
-  readyReject;
-  readyPromise;
-  constructor(options = {}) {
-    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
-    this.batchDebounceMs = options.batchDebounceMs ?? DEFAULT_BATCH_DEBOUNCE_MS;
-    this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
-    this.logger = options.logger ?? console;
-    const port = options.port ?? DEFAULT_PORT;
-    this.readyPromise = new Promise((resolve, reject) => {
-      this.readyResolve = resolve;
-      this.readyReject = reject;
-    });
-    const wsUrl = `ws://localhost:${port}`;
-    this.ws = new import_ws.default(wsUrl);
-    this.setupWebSocket();
-  }
-  /**
-   * Ensures the underlying WebSocket connection is ready for use.
-   */
-  async waitUntilReady() {
-    return this.readyPromise;
-  }
-  /**
-   * Request mock data for a specific endpoint/method pair.
-   */
-  async requestMock(endpoint, method, options = {}) {
-    if (this.closed) {
-      throw new Error("BatchMockCollector has been closed");
-    }
-    await this.waitUntilReady();
-    const requestId = `req-${++this.requestIdCounter}`;
-    const request = {
-      requestId,
-      endpoint,
-      method,
-      body: options.body,
-      headers: options.headers,
-      metadata: options.metadata
-    };
-    let settleCompletion;
-    const completion = new Promise((resolve) => {
-      settleCompletion = resolve;
-    });
-    return new Promise((resolve, reject) => {
-      const timeoutId = setTimeout(() => {
-        this.rejectRequest(
-          requestId,
-          new Error(
-            `Mock request timed out after ${this.timeout}ms: ${method} ${endpoint}`
-          )
-        );
-      }, this.timeout);
-      this.pendingRequests.set(requestId, {
-        request,
-        resolve: (data) => {
-          settleCompletion({ status: "fulfilled", value: void 0 });
-          resolve(data);
-        },
-        reject: (error) => {
-          settleCompletion({ status: "rejected", reason: error });
-          reject(error);
-        },
-        timeoutId,
-        completion
-      });
-      this.enqueueRequest(requestId);
-    });
-  }
-  /**
-   * Wait for all requests that are currently pending to settle. Requests
-   * created after this method is called are not included.
-   */
-  async waitForPendingRequests() {
-    if (!isEnabled()) {
-      return;
-    }
-    const pendingCompletions = Array.from(this.pendingRequests.values()).map(
-      (pending) => pending.completion
-    );
-    const results = await Promise.all(pendingCompletions);
-    const rejected = results.find(
-      (result) => result.status === "rejected"
-    );
-    if (rejected) {
-      throw rejected.reason;
-    }
-  }
-  /**
-   * Close the underlying connection and fail all pending requests.
-   */
-  async close(code) {
-    if (this.closed) {
-      return;
-    }
-    this.closed = true;
-    if (this.batchTimer) {
-      clearTimeout(this.batchTimer);
-      this.batchTimer = null;
-    }
-    this.queuedRequestIds.clear();
-    const closePromise = new Promise((resolve) => {
-      this.ws.once("close", () => resolve());
-    });
-    this.ws.close(code);
-    this.failAllPending(new Error("BatchMockCollector has been closed"));
-    await closePromise;
-  }
-  setupWebSocket() {
-    this.ws.on("open", () => {
-      this.logger.log("\u{1F50C} Connected to mock MCP WebSocket endpoint");
-      this.readyResolve?.();
-    });
-    this.ws.on("message", (data) => this.handleMessage(data));
-    this.ws.on("error", (error) => {
-      this.logger.error("\u274C WebSocket error:", error);
-      this.readyReject?.(
-        error instanceof Error ? error : new Error(String(error))
-      );
-      this.failAllPending(
-        error instanceof Error ? error : new Error(String(error))
-      );
-    });
-    this.ws.on("close", () => {
-      this.logger.warn("\u{1F50C} WebSocket connection closed");
-      this.failAllPending(new Error("WebSocket connection closed"));
-    });
-  }
-  handleMessage(data) {
-    let parsed;
-    try {
-      parsed = JSON.parse(data.toString());
-    } catch (error) {
-      this.logger.error("Failed to parse server message:", error);
-      return;
-    }
-    if (parsed.type !== BATCH_MOCK_RESPONSE) {
-      this.logger.warn("Received unsupported message type", parsed.type);
-      return;
-    }
-    this.logger.debug?.(
-      `\u{1F4E6} Received mock data for ${parsed.mocks.length} requests (batch ${parsed.batchId})`
-    );
-    for (const mock of parsed.mocks) {
-      this.resolveRequest(mock);
-    }
-  }
-  resolveRequest(mock) {
-    const pending = this.pendingRequests.get(mock.requestId);
-    if (!pending) {
-      this.logger.warn(`Received mock for unknown request: ${mock.requestId}`);
-      return;
-    }
-    clearTimeout(pending.timeoutId);
-    this.pendingRequests.delete(mock.requestId);
-    pending.resolve(mock.data);
-  }
-  enqueueRequest(requestId) {
-    this.queuedRequestIds.add(requestId);
-    if (this.batchTimer) {
-      return;
-    }
-    this.batchTimer = setTimeout(() => {
-      this.batchTimer = null;
-      this.flushQueue();
-    }, this.batchDebounceMs);
-  }
-  flushQueue() {
-    const queuedIds = Array.from(this.queuedRequestIds);
-    this.queuedRequestIds.clear();
-    if (queuedIds.length === 0) {
-      return;
-    }
-    for (let i = 0; i < queuedIds.length; i += this.maxBatchSize) {
-      const chunkIds = queuedIds.slice(i, i + this.maxBatchSize);
-      const requests = [];
-      for (const id of chunkIds) {
-        const pending = this.pendingRequests.get(id);
-        if (pending) {
-          requests.push(pending.request);
-        }
-      }
-      if (requests.length > 0) {
-        this.sendBatch(requests);
-      }
-    }
-  }
-  sendBatch(requests) {
-    if (this.ws.readyState !== import_ws.default.OPEN) {
-      const error = new Error("WebSocket is not open");
-      requests.forEach(
-        (request) => this.rejectRequest(request.requestId, error)
-      );
-      return;
-    }
-    const payload = {
-      type: BATCH_MOCK_REQUEST,
-      requests
-    };
-    this.logger.debug?.(
-      `\u{1F4E4} Sending batch with ${requests.length} request(s) to MCP server`
-    );
-    this.ws.send(JSON.stringify(payload));
-  }
-  rejectRequest(requestId, error) {
-    const pending = this.pendingRequests.get(requestId);
-    if (!pending) {
-      return;
-    }
-    clearTimeout(pending.timeoutId);
-    this.pendingRequests.delete(requestId);
-    pending.reject(error);
-  }
-  failAllPending(error) {
-    for (const requestId of Array.from(this.pendingRequests.keys())) {
-      this.rejectRequest(requestId, error);
-    }
-  }
-};
-
-// src/client/connect.ts
-var connect = async (options) => {
-  if (!isEnabled()) {
-    console.log("[mock-mcp] Skipping (set MOCK_MCP=1 to enable)");
-    return;
-  }
-  const resolvedOptions = typeof options === "number" ? { port: options } : options ?? {};
-  const collector = new BatchMockCollector(resolvedOptions);
-  await collector.waitUntilReady();
-  return collector;
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  connect
-});

package/dist/connect.d.cts

@@ -1,95 +0,0 @@
-type Logger = Pick<Console, "log" | "warn" | "error"> & {
-    debug?: (...args: unknown[]) => void;
-};
-interface BatchMockCollectorOptions {
-    /**
-     * TCP port exposed by {@link TestMockMCPServer}.
-     *
-     * @default 3002
-     */
-    port?: number;
-    /**
-     * Timeout for individual mock requests in milliseconds.
-     *
-     * @default 60000
-     */
-    timeout?: number;
-    /**
-     * Delay (in milliseconds) that determines how long the collector waits before
-     * flushing the current batch. Setting this to 0 mirrors the "flush on the next
-     * macrotask" approach described in the technical design document.
-     *
-     * @default 0
-     */
-    batchDebounceMs?: number;
-    /**
-     * Maximum number of requests that may be included in a single batch payload.
-     * Requests that exceed this limit will be split into multiple batches.
-     *
-     * @default 50
-     */
-    maxBatchSize?: number;
-    /**
-     * Optional custom logger. Defaults to `console`.
-     */
-    logger?: Logger;
-}
-interface RequestMockOptions {
-    body?: unknown;
-    headers?: Record<string, string>;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Collects HTTP requests issued during a single macrotask and forwards them to
- * the MCP server as a batch for AI-assisted mock generation.
- */
-declare class BatchMockCollector {
-    private readonly ws;
-    private readonly pendingRequests;
-    private readonly queuedRequestIds;
-    private readonly timeout;
-    private readonly batchDebounceMs;
-    private readonly maxBatchSize;
-    private readonly logger;
-    private batchTimer;
-    private requestIdCounter;
-    private closed;
-    private readyResolve?;
-    private readyReject?;
-    private readonly readyPromise;
-    constructor(options?: BatchMockCollectorOptions);
-    /**
-     * Ensures the underlying WebSocket connection is ready for use.
-     */
-    waitUntilReady(): Promise<void>;
-    /**
-     * Request mock data for a specific endpoint/method pair.
-     */
-    requestMock<T = unknown>(endpoint: string, method: string, options?: RequestMockOptions): Promise<T>;
-    /**
-     * Wait for all requests that are currently pending to settle. Requests
-     * created after this method is called are not included.
-     */
-    waitForPendingRequests(): Promise<void>;
-    /**
-     * Close the underlying connection and fail all pending requests.
-     */
-    close(code?: number): Promise<void>;
-    private setupWebSocket;
-    private handleMessage;
-    private resolveRequest;
-    private enqueueRequest;
-    private flushQueue;
-    private sendBatch;
-    private rejectRequest;
-    private failAllPending;
-}
-
-type ConnectOptions = number | BatchMockCollectorOptions | undefined;
-/**
- * Convenience helper that creates a {@link BatchMockCollector} and waits for the
- * underlying WebSocket connection to become ready before resolving.
- */
-declare const connect: (options?: ConnectOptions) => Promise<BatchMockCollector | void>;
-
-export { type ConnectOptions, connect };

package/dist/server/index.d.ts

@@ -1 +0,0 @@
-export { TestMockMCPServer, type TestMockMCPServerOptions, } from "./test-mock-mcp-server.js";

package/dist/server/index.js

@@ -1 +0,0 @@
-export { TestMockMCPServer, } from "./test-mock-mcp-server.js";

package/dist/server/test-mock-mcp-server.d.ts

@@ -1,73 +0,0 @@
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { type PendingBatchSummary, type ProvideBatchMockDataArgs } from "../types.js";
-type Logger = Pick<Console, "log" | "warn" | "error"> & {
-    debug?: (...args: unknown[]) => void;
-};
-export interface TestMockMCPServerOptions {
-    port?: number;
-    logger?: Logger;
-    batchTtlMs?: number;
-    sweepIntervalMs?: number;
-    enableMcpTransport?: boolean;
-    transportFactory?: () => Transport;
-    serverName?: string;
-    serverVersion?: string;
-    mockLogOptions?: MockLogOptions;
-}
-export interface MockLogOptions {
-    enabled?: boolean;
-    directory?: string;
-}
-/**
- * Bridges the integration-test process and the MCP client, making it possible
- * to generate realistic mock data on demand.
- */
-export declare class TestMockMCPServer {
-    private readonly logger;
-    private readonly options;
-    private wss?;
-    private cleanupTimer?;
-    private mcpServer?;
-    private transport?;
-    private started;
-    private actualPort?;
-    private readonly pendingBatches;
-    private readonly clients;
-    private batchCounter;
-    constructor(options?: TestMockMCPServerOptions);
-    /**
-     * Start both the WebSocket server (for the test runner) and the MCP server
-     * (for the AI client).
-     */
-    start(): Promise<void>;
-    /**
-     * Shut down all transports and clear pending batches.
-     */
-    stop(): Promise<void>;
-    /**
-     * Expose the TCP port that the WebSocket server is listening on. Useful when
-     * `port=0` is supplied for ephemeral environments or tests.
-     */
-    get port(): number | undefined;
-    /**
-     * Return summaries of all batches that are awaiting AI-provided mock data.
-     */
-    getPendingBatches(): PendingBatchSummary[];
-    /**
-     * Send AI-generated mock data back to the corresponding test process.
-     */
-    provideMockData(args: ProvideBatchMockDataArgs): Promise<CallToolResult>;
-    private startWebSocketServer;
-    private startMcpServer;
-    private handleConnection;
-    private handleClientMessage;
-    private handleBatchRequest;
-    private dropBatchesForClient;
-    private sweepExpiredBatches;
-    private persistMockBatch;
-    private buildLogEntry;
-    private extractBatchContext;
-    private buildToolResponse;
-}
-export {};