mock-mcp 0.3.1 → 0.5.1

package/dist/connect.cjs

@@ -1,400 +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 DEFAULT_HEARTBEAT_INTERVAL_MS = 15e3;
-var BatchMockCollector = class {
-  ws;
-  pendingRequests = /* @__PURE__ */ new Map();
-  queuedRequestIds = /* @__PURE__ */ new Set();
-  timeout;
-  batchDebounceMs;
-  maxBatchSize;
-  logger;
-  heartbeatIntervalMs;
-  enableReconnect;
-  port;
-  batchTimer = null;
-  heartbeatTimer = null;
-  reconnectTimer = null;
-  requestIdCounter = 0;
-  closed = false;
-  readyResolve;
-  readyReject;
-  readyPromise = Promise.resolve();
-  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;
-    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
-    this.enableReconnect = options.enableReconnect ?? true;
-    this.port = options.port ?? DEFAULT_PORT;
-    this.resetReadyPromise();
-    this.ws = this.createWebSocket();
-    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: (mock) => {
-          settleCompletion({ status: "fulfilled", value: void 0 });
-          resolve(this.buildResolvedMock(mock));
-        },
-        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;
-    }
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-    }
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = 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.startHeartbeat();
-    });
-    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.stopHeartbeat();
-      this.failAllPending(new Error("WebSocket connection closed"));
-      if (!this.closed && this.enableReconnect) {
-        this.scheduleReconnect();
-      }
-    });
-  }
-  createWebSocket() {
-    const wsUrl = `ws://localhost:${this.port}`;
-    return new import_ws.default(wsUrl);
-  }
-  resetReadyPromise() {
-    this.readyPromise = new Promise((resolve, reject) => {
-      this.readyResolve = resolve;
-      this.readyReject = reject;
-    });
-  }
-  startHeartbeat() {
-    if (this.heartbeatIntervalMs <= 0 || this.heartbeatTimer) {
-      return;
-    }
-    let lastPong = Date.now();
-    this.ws.on("pong", () => {
-      lastPong = Date.now();
-    });
-    this.heartbeatTimer = setInterval(() => {
-      if (this.ws.readyState !== import_ws.default.OPEN) {
-        return;
-      }
-      const now = Date.now();
-      if (now - lastPong > this.heartbeatIntervalMs * 2) {
-        this.logger.warn(
-          "Heartbeat missed; closing socket to trigger reconnect..."
-        );
-        this.ws.close();
-        return;
-      }
-      this.ws.ping();
-    }, this.heartbeatIntervalMs);
-    this.heartbeatTimer.unref?.();
-  }
-  stopHeartbeat() {
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-      this.heartbeatTimer = null;
-    }
-  }
-  scheduleReconnect() {
-    if (this.reconnectTimer || this.closed) {
-      return;
-    }
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.logger.warn("\u{1F504} Reconnecting to mock MCP WebSocket endpoint...");
-      this.stopHeartbeat();
-      this.resetReadyPromise();
-      this.ws = this.createWebSocket();
-      this.setupWebSocket();
-    }, 1e3);
-    this.reconnectTimer.unref?.();
-  }
-  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);
-    const resolve = () => pending.resolve(mock);
-    if (mock.delayMs && mock.delayMs > 0) {
-      setTimeout(resolve, mock.delayMs);
-    } else {
-      resolve();
-    }
-  }
-  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));
-  }
-  buildResolvedMock(mock) {
-    return {
-      requestId: mock.requestId,
-      data: mock.data,
-      status: mock.status,
-      headers: mock.headers,
-      delayMs: mock.delayMs
-    };
-  }
-  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 DisabledMockClient = class {
-  async waitUntilReady() {
-    return;
-  }
-  async requestMock() {
-    throw new Error(
-      "[mock-mcp] MOCK_MCP is not enabled. Set MOCK_MCP=1 to enable mock generation."
-    );
-  }
-  async waitForPendingRequests() {
-    return;
-  }
-  async close() {
-    return;
-  }
-};
-var connect = async (options) => {
-  const resolvedOptions = typeof options === "number" ? { port: options } : options ?? {};
-  if (!isEnabled()) {
-    console.log("[mock-mcp] Skipping (set MOCK_MCP=1 to enable)");
-    return new DisabledMockClient();
-  }
-  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,82 +0,0 @@
-/**
- * Shape of the mock data that needs to be returned for a request.
- */
-interface MockResponseDescriptor {
-    requestId: string;
-    data: unknown;
-    status?: number;
-    headers?: Record<string, string>;
-    delayMs?: number;
-}
-interface ResolvedMock<T = unknown> extends Omit<MockResponseDescriptor, "data"> {
-    data: T;
-}
-
-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;
-    /**
-     * Interval for WebSocket heartbeats in milliseconds. Set to 0 to disable.
-     *
-     * @default 15000
-     */
-    heartbeatIntervalMs?: number;
-    /**
-     * Automatically attempt to reconnect when the WebSocket closes unexpectedly.
-     *
-     * @default true
-     */
-    enableReconnect?: boolean;
-}
-interface RequestMockOptions {
-    body?: unknown;
-    headers?: Record<string, string>;
-    metadata?: Record<string, unknown>;
-}
-
-type ConnectOptions = number | BatchMockCollectorOptions | undefined;
-interface MockClient {
-    waitUntilReady(): Promise<void>;
-    requestMock<T = unknown>(endpoint: string, method: string, options?: RequestMockOptions): Promise<ResolvedMock<T>>;
-    waitForPendingRequests(): Promise<void>;
-    close(code?: number): Promise<void>;
-}
-/**
- * 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<MockClient>;
-
-export { type ConnectOptions, type MockClient, 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 {};