mock-mcp 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MCP Land
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# mock-mcp
+
+![Node CI](https://github.com/mcpland/mock-mcp/workflows/Node%20CI/badge.svg)
+[![npm](https://img.shields.io/npm/v/mock-mcp.svg)](https://www.npmjs.com/package/mock-mcp)
+![license](https://img.shields.io/npm/l/mock-mcp)
+
+Mock MCP Server - AI-generated mock data. The project pairs a WebSocket batch bridge with MCP tooling so Cursor, Claude Desktop, or any compatible client can fulfill intercepted requests in real time.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Why Mock MCP](#why-mock-mcp)
+- [What Mock MCP Does](#what-mock-mcp-does)
+- [Configure MCP Server](#configure-mcp-server)
+- [Connect From Tests](#connect-from-tests)
+- [Describe Requests with Metadata](#describe-requests-with-metadata)
+- [MCP tools](#mcp-tools)
+- [Available APIs](#available-apis)
+- [Environment Variables](#environment-variables)
+- [How It Works](#how-it-works)
+- [Use the development scripts](#use-the-development-scripts)
+- [License](#license)
+
+## Quick Start
+
+1. **Install the package.** Add mock-mcp as a dev dependency inside your project.
+
+   ```bash
+   npm install -D mock-mcp
+   ```
+
+2. **Configure the Model Context Protocol server.** For example, Claude Desktop can launch the binary through npx:
+
+   ```json
+   {
+     "mock-mcp": {
+       "command": "npx",
+       "args": ["-y", "mock-mcp@latest"]
+     }
+   }
+   ```
+
+3. **Connect from your tests.** Use `connect` to retrieve a mock client and request data for intercepted calls.
+
+   ```ts
+   import { render, screen, fireEvent } from "@testing-library/react";
+   import { connect } from "mock-mcp";
+
+   const userSchema = {
+     summary: "Fetch the current user",
+     response: {
+       type: "object",
+       required: ["id", "name"],
+       properties: {
+         id: { type: "number" },
+         name: { type: "string" },
+       },
+     },
+   };
+
+   it("example", async () => {
+     const mockClient = await connect();
+     const metadata = {
+       schemaUrl: "https://example.com/openapi.json#/paths/~1user/get",
+       schema: userSchema,
+       instructions: "Respond with a single user described by the schema.",
+     };
+
+     fetchMock.get("/user", () =>
+       mockClient.requestMock("/user", "GET", { metadata })
+     );
+
+     const result = await fetch("/user");
+     const data = await result.json();
+     expect(data).toEqual({ id: 1, name: "Jane" });
+   }); // 10 minute timeout for AI interaction
+   ```
+
+4. **Run with MCP enabled.** Prompt your AI client to run the persistent test command and provide mocks through the tools.
+
+   ```
+   Please run the persistent test: `MOCK_MCP=true npm test test/example.test.tsx` and mock fetch data with mock-mcp
+   ```
+
+## Why Mock MCP
+
+### The Problem with Traditional Mock Approaches
+
+Testing modern web applications often feels like preparing for a battle—you need the right weapons (test cases), ammunition (mock data), and strategy (test logic). But creating mock data has always been the most tedious part:
+
+```typescript
+// Traditional approach: Manual fixture hell
+const mockUsers = [
+  { id: 1, name: "Alice", email: "alice@example.com", role: "admin", ... },
+  { id: 2, name: "Bob", email: "bob@example.com", role: "user", ... },
+  // ... 50 more lines of boring manual data entry
+];
+```
+
+**Common Pain Points:**
+
+| Challenge                   | Traditional Solutions           | Limitations                                 |
+| --------------------------- | ------------------------------- | ------------------------------------------- |
+| **Creating Realistic Data** | Manual JSON files or faker.js   | ❌ Time-consuming, lacks business logic     |
+| **Complex Scenarios**       | Hardcoded edge cases            | ❌ Difficult to maintain, brittle           |
+| **Evolving Requirements**   | Update fixtures manually        | ❌ High maintenance cost                    |
+| **Learning Curve**          | New team members write fixtures | ❌ Steep learning curve for complex domains |
+| **CI/CD Integration**       | Static fixtures only            | ❌ Can't adapt to new scenarios             |
+
+### The Mock MCP Innovation
+
+Mock MCP introduces a **paradigm shift**: instead of treating mock data as static artifacts, it makes them **AI-generated, interactive, and evolvable**.
+
+```
+Traditional:  Write Test → Create Fixtures → Run Test → Maintain Fixtures
+                                ↑                          ↓
+                                └──────── Pain Loop ───────┘
+
+Mock MCP:     Write Test → AI Generates Data → Run Test → Solidify Code
+                             ↑                           ↓
+                             └─────── Evolution ─────────┘
+```
+
+## What Mock MCP Does
+
+Mock MCP pairs a WebSocket batch bridge with MCP tooling to move intercepted requests from tests to AI helpers and back again.
+
+- **Batch-aware test client** collects every network interception inside a single macrotask and waits for the full response set.
+- **MCP tooling** exposes `get_pending_batches` and `provide_batch_mock_data` so AI agents understand the waiting requests and push data back.
+- **WebSocket bridge** connects the test runner to the MCP server while hiding transport details from both sides.
+- **Timeouts, TTLs, and cleanup** guard the test runner from stale batches or disconnected clients.
+
+## Configure MCP Server
+
+CLI flags keep the WebSocket bridge and the MCP transports aligned. Use them to adapt the server to your local ports while the Environment Variables section covers per-process overrides:
+
+| Option         | Description                                                        | Default |
+| -------------- | ------------------------------------------------------------------ | ------- |
+| `--port`, `-p` | WebSocket port for test runners                                    | `3002`  |
+| `--no-stdio`   | Disable the MCP stdio transport (useful for local debugging/tests) | enabled |
+
+The CLI installs a SIGINT/SIGTERM handler so `Ctrl+C` shuts everything down cleanly.
+
+**Add the server to MCP clients.** MCP clients such as Cursor or Claude Desktop need an entry in their configuration so they can launch the bridge:
+
+```json
+{
+  "mcpServers": {
+    "mock-mcp": {
+      "command": "npx",
+      "args": ["-y", "mock-mcp@latest"],
+      "env": {
+        "MCP_SERVER_PORT": "3002" // 3002 is the default port
+      }
+    }
+  }
+}
+```
+
+Restart the client and confirm that the `mock-mcp` server exposes two tools.
+
+## Connect From Tests
+
+Tests call `connect` to spin up a `BatchMockCollector`, intercept HTTP calls, and wait for fulfilled data:
+
+```ts
+// tests/mocks.ts
+import { connect } from "mock-mcp";
+
+const mockClient = await connect({
+  port: 3002,
+  timeout: 60000,
+});
+
+await page.route("**/api/users", async (route) => {
+  const url = new URL(route.request().url());
+  const data = await mockClient.requestMock(
+    url.pathname,
+    route.request().method()
+  );
+
+  await route.fulfill({
+    status: 200,
+    contentType: "application/json",
+    body: JSON.stringify(data),
+  });
+});
+```
+
+Batch behaviour stays automatic: additional `requestMock` calls issued in the same macrotask are grouped, forwarded, and resolved together.
+
+## Describe Requests with Metadata
+
+`requestMock` accepts an optional third argument (`RequestMockOptions`) that is forwarded without modification to the MCP server. The most important field in that object is `metadata`, which lets the test process describe each request with the exact OpenAPI/JSON Schema fragment, sample payloads, or test context that the AI client needs to build a response.
+
+When an MCP client calls `get_pending_batches`, every `requests[].metadata` entry from the test run is included in the response. That is the channel the LLM uses to understand the requested endpoint before supplying data through `provide_batch_mock_data`. Metadata is also persisted when batch logging is enabled, so you can audit what was sent to the model.
+
+```ts
+const listProductsSchema = {
+  summary: "List products by popularity",
+  response: {
+    type: "array",
+    items: {
+      type: "object",
+      required: ["id", "name", "price"],
+      properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        price: { type: "number" },
+      },
+    },
+  },
+};
+
+await mockClient.requestMock("/api/products", "GET", {
+  metadata: {
+    // Link or embed the authoritative contract for the AI to follow.
+    schemaUrl:
+      "https://shop.example.com/openapi.json#/paths/~1api~1products/get",
+    schema: listProductsSchema,
+    instructions:
+      "Return 3 popular products with stable ids so the UI can snapshot them.",
+    testFile: expect.getState().testPath,
+  },
+});
+```
+
+**Tips for useful metadata**
+
+- Embed the OpenAPI/JSON Schema snippet (or a reference URL) that describes the response structure for the intercepted endpoint.
+- Include contextual hints such as the test name, scenario, user role, or seed data so the model can mirror your expected fixtures.
+- Keep the metadata JSON-serializable and deterministic; large binary blobs or class instances will be dropped.
+- Reuse helper functions to centralize schema definitions so each test only supplies the endpoint-specific instructions.
+
+## MCP tools
+
+Two tools keep the queue visible to AI agents and deliver mocks back to waiting tests:
+
+| Tool                      | Purpose                                    | Response                                                |
+| ------------------------- | ------------------------------------------ | ------------------------------------------------------- |
+| `get_pending_batches`     | Lists queued batches with request metadata | JSON string (array of `{batchId, timestamp, requests}`) |
+| `provide_batch_mock_data` | Sends mock payloads for a specific batch   | JSON string reporting success                           |
+
+Example payload for `provide_batch_mock_data`:
+
+```jsonc
+{
+  "batchId": "batch-3",
+  "mocks": [
+    {
+      "requestId": "req-7",
+      "data": { "users": [{ "id": 1, "name": "Alice" }] }
+    }
+  ]
+}
+```
+
+## Available APIs
+
+The library exports primitives so you can embed the workflow inside bespoke runners or scripts:
+
+- `TestMockMCPServer` starts and stops the WebSocket plus MCP tooling bridge programmatically.
+- `BatchMockCollector` provides a low-level batching client used directly inside test environments.
+- `connect(options)` instantiates `BatchMockCollector` and waits for the WebSocket connection to open.
+
+Each class accepts logger overrides, timeout tweaks, and other ergonomics surfaced in the technical design.
+
+## Environment Variables
+
+| Variable          | Description                                                                  | Default |
+| ----------------- | ---------------------------------------------------------------------------- | ------- |
+| `MCP_SERVER_PORT` | Overrides the WebSocket port used by both the CLI and any spawned MCP host.  | `3002`  |
+| `MOCK_MCP`        | Enables the test runner hook so intercepted requests are routed to mock-mcp. | unset   |
+
+## How It Works
+
+Three collaborating processes share responsibilities while staying loosely coupled:
+
+| Process          | Responsibility                                        | Technology                               | Communication                              |
+| ---------------- | ----------------------------------------------------- | ---------------------------------------- | ------------------------------------------ |
+| **Test Process** | Executes test cases and intercepts HTTP requests      | Playwright/Puppeteer + WebSocket client  | WebSocket → MCP Server                     |
+| **MCP Server**   | Coordinates batches and forwards data between parties | Node.js + WebSocket server + MCP SDK     | stdio ↔ MCP Client · WebSocket ↔ Test Flow |
+| **MCP Client**   | Uses AI to produce mock data via MCP tools            | Cursor / Claude Desktop / custom clients | MCP protocol → MCP Server                  |
+
+### Data flow sequence clarifies message order
+
+```
+┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
+│  Test Process    │         │   MCP Server     │         │  MCP Client      │
+│  (Browser Test)  │         │                  │         │     (AI)         │
+└────────┬─────────┘         └────────┬─────────┘         └────────┬─────────┘
+         │                            │                            │
+         │  1. Start Test             │                            │
+         │     page.goto()            │                            │
+         ├───────────────────────────►│                            │
+         │                            │                            │
+         │  2. Trigger concurrent     │                            │
+         │     requests               │                            │
+         │     fetch /api/users       │                            │
+         │     fetch /api/products    │                            │
+         │     fetch /api/orders      │                            │
+         │     (Promises pending)     │                            │
+         │                            │                            │
+         │  3. setTimeout(0) batches  │                            │
+         │     BATCH_MOCK_REQUEST     │                            │
+         │     [req-1, req-2, req-3]  │                            │
+         ├═══════════════════════════►│                            │
+         │                            │                            │
+         │     Test paused...         │  4. Store batch in queue   │
+         │       Awaiting mocks       │     pendingBatches.set()   │
+         │                            │                            │
+         │                            │  5. Wait for MCP Client    │
+         │                            │     to call tools          │
+         │                            │                            │
+         │                            │◄───────────────────────────┤
+         │                            │  6. Tool Call:             │
+         │                            │     get_pending_batches    │
+         │                            │                            │
+         │                            │  7. Return batch info      │
+         │                            ├───────────────────────────►│
+         │                            │  [{batchId, requests}]     │
+         │                            │                            │
+         │                            │        8. AI analyzes      │
+         │                            │           Generates mocks  │
+         │                            │                            │
+         │                            │◄───────────────────────────┤
+         │                            │  9. Tool Call:             │
+         │                            │     provide_batch_mock_data│
+         │                            │     {mocks: [...]}         │
+         │                            │                            │
+         │  10. BATCH_MOCK_RESPONSE   │                            │
+         │      [mock-1, mock-2, ...] │                            │
+         │◄═══════════════════════════┤                            │
+         │                            │                            │
+         │  11. Batch resolve         │                            │
+         │      req-1.resolve()       │                            │
+         │      req-2.resolve()       │                            │
+         │      req-3.resolve()       │                            │
+         │                            │                            │
+         │  12. Test continues        │                            │
+         │      Assertions &          │                            │
+         │      Verification          │                            │
+         │                            │                            │
+         │  13. Test Complete ✓       │                            │
+         ▼                            ▼                            ▼
+
+Protocol Summary:
+─────────────────
+- Test Process ←→ MCP Server: WebSocket/IPC
+  Message types: BATCH_MOCK_REQUEST, BATCH_MOCK_RESPONSE
+
+- MCP Server ←→ MCP Client: Stdio/JSON-RPC (MCP Protocol)
+  Tools: get_pending_batches, provide_batch_mock_data
+
+Key Features:
+──────────────
+✓ Batch processing of concurrent requests
+✓ Non-blocking test execution during AI mock generation
+✓ Real-time mock data generation by AI
+✓ Automatic promise resolution after mock provision
+```
+
+## Use the development scripts
+
+```bash
+pnpm test        # runs Vitest suites
+pnpm dev         # tsx watch mode for the CLI
+pnpm lint        # eslint --ext .ts
+```
+
+Vitest suites spin up ephemeral WebSocket servers, so avoid running them concurrently with an already running instance on the same port.
+
+## License
+
+MIT

package/dist/client/batch-mock-collector.d.ts

@@ -0,0 +1,82 @@
+type Logger = Pick<Console, "log" | "warn" | "error"> & {
+    debug?: (...args: unknown[]) => void;
+};
+export 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;
+}
+export 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.
+ */
+export 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;
+}
+export {};

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

@@ -0,0 +1,201 @@
+import WebSocket from "ws";
+import { BATCH_MOCK_REQUEST, BATCH_MOCK_RESPONSE, } from "../types.js";
+const DEFAULT_TIMEOUT = 60_000;
+const DEFAULT_BATCH_DEBOUNCE_MS = 0;
+const DEFAULT_MAX_BATCH_SIZE = 50;
+const DEFAULT_PORT = 8080;
+/**
+ * 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,
+        };
+        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("🔌 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/connect.d.ts

@@ -0,0 +1,8 @@
+import { BatchMockCollector } from "./batch-mock-collector.js";
+import type { BatchMockCollectorOptions } from "./batch-mock-collector.js";
+export type ConnectOptions = number | BatchMockCollectorOptions | undefined;
+/**
+ * Convenience helper that creates a {@link BatchMockCollector} and waits for the
+ * underlying WebSocket connection to become ready before resolving.
+ */
+export declare const connect: (options?: ConnectOptions) => Promise<BatchMockCollector | void>;