mock-mcp 0.0.1 → 0.2.0

package/dist/client/connect.js

@@ -0,0 +1,16 @@
+import { BatchMockCollector } from "./batch-mock-collector.js";
+/**
+ * Convenience helper that creates a {@link BatchMockCollector} and waits for the
+ * underlying WebSocket connection to become ready before resolving.
+ */
+export const connect = async (options) => {
+    const isEnabled = process.env.MOCK_MCP !== undefined && process.env.MOCK_MCP !== "0";
+    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;
+};

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { BatchMockCollector, type BatchMockCollectorOptions, type RequestMockOptions, } from "./batch-mock-collector.js";
+export { connect, type ConnectOptions } from "./connect.js";

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { BatchMockCollector, } from "./batch-mock-collector.js";
+export { connect } from "./connect.js";

package/dist/connect.cjs

@@ -0,0 +1,269 @@
+"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/batch-mock-collector.ts
+var DEFAULT_TIMEOUT = 6e4;
+var DEFAULT_BATCH_DEBOUNCE_MS = 0;
+var DEFAULT_MAX_BATCH_SIZE = 50;
+var DEFAULT_PORT = 8080;
+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
+    };
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(
+          new Error(
+            `Mock request timed out after ${this.timeout}ms: ${method} ${endpoint}`
+          )
+        );
+      }, this.timeout);
+      this.pendingRequests.set(requestId, {
+        request,
+        resolve: (data) => {
+          resolve(data);
+        },
+        reject: (error) => {
+          reject(error);
+        },
+        timeoutId
+      });
+      this.enqueueRequest(requestId);
+    });
+  }
+  /**
+   * 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) => {
+  const isEnabled = process.env.MOCK_MCP !== void 0 && process.env.MOCK_MCP !== "0";
+  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

@@ -0,0 +1,90 @@
+type Logger = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+interface BatchMockCollectorOptions {
+    /**
+     * TCP port exposed by {@link TestMockMCPServer}.
+     *
+     * @default 8080
+     */
+    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>;
+    /**
+     * 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/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { TestMockMCPServer, type TestMockMCPServerOptions } from "./server/test-mock-mcp-server.js";
+import { BatchMockCollector, type BatchMockCollectorOptions, type RequestMockOptions } from "./client/batch-mock-collector.js";
+import { connect, type ConnectOptions } from "./client/connect.js";
+export { TestMockMCPServer };
+export type { TestMockMCPServerOptions };
+export { BatchMockCollector };
+export type { BatchMockCollectorOptions, RequestMockOptions };
+export { connect };
+export type { ConnectOptions };

package/dist/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import process from "node:process";
+import { TestMockMCPServer, } from "./server/test-mock-mcp-server.js";
+import { BatchMockCollector, } from "./client/batch-mock-collector.js";
+import { connect } from "./client/connect.js";
+const DEFAULT_PORT = 3002;
+async function runCli() {
+    const cliArgs = process.argv.slice(2);
+    let port = Number.parseInt(process.env.MCP_SERVER_PORT ?? "", 10);
+    let enableMcpTransport = true;
+    if (Number.isNaN(port)) {
+        port = DEFAULT_PORT;
+    }
+    for (let i = 0; i < cliArgs.length; i += 1) {
+        const arg = cliArgs[i];
+        if ((arg === "--port" || arg === "-p") && cliArgs[i + 1]) {
+            port = Number.parseInt(cliArgs[i + 1], 10);
+            i += 1;
+        }
+        else if (arg === "--no-stdio") {
+            enableMcpTransport = false;
+        }
+    }
+    const server = new TestMockMCPServer({
+        port,
+        enableMcpTransport,
+    });
+    await server.start();
+    console.log(`🎯 Test Mock MCP server ready on ws://localhost:${server.port ?? port}`);
+    const shutdown = async () => {
+        console.log("👋 Shutting down Test Mock MCP server...");
+        await server.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+const isCliExecution = (() => {
+    if (typeof process === "undefined" || !process.argv?.[1]) {
+        return false;
+    }
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+})();
+if (isCliExecution) {
+    runCli().catch((error) => {
+        console.error("Failed to start Test Mock MCP server:", error);
+        process.exitCode = 1;
+    });
+}
+export { TestMockMCPServer };
+export { BatchMockCollector };
+export { connect };

package/dist/server/index.d.ts

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

package/dist/server/index.js

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

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

@@ -0,0 +1,73 @@
+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 {};