mock-mcp 0.2.2 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 [![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.
+Mock MCP Server - AI-generated mock data based on your **OpenAPI JSON Schema** definitions. 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, ensuring strict contract compliance.
 
 ## Table of Contents
 
@@ -25,62 +25,66 @@ Mock MCP Server - AI-generated mock data. The project pairs a WebSocket batch br
 
 1. **Install the package.** Add mock-mcp as a dev dependency inside your project.
 
-   ```bash
-   npm install -D mock-mcp
-   ```
+```bash
+npm install -D mock-mcp
+# or
+yarn add -D mock-mcp
+# or
+pnpm add -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"]
-     }
-   }
-   ```
+```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
-   ```
+```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 }) // add mock via mock-mcp
+  );
+
+  const result = await fetch("/user");
+  const data = await result.json();
+  expect(data).toEqual({ id: 1, name: "Jane" });
+}, 10 * 60 * 1000); // 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
-   ```
+```
+Please run the persistent test: `MOCK_MCP=true npm test test/example.test.tsx` and mock fetch data with mock-mcp
+```
 
 ## Why Mock MCP
 
@@ -116,15 +120,20 @@ Traditional:  Write Test → Create Fixtures → Run Test → Maintain Fixtures
                                 ↑                          ↓
                                 └──────── Pain Loop ───────┘
 
-Mock MCP:     Write Test → AI Generates Data → Run Test → Solidify Code
-                             ↑                           ↓
-                             └─────── Evolution ─────────┘
+Mock MCP:     Write Test → AI Generates Data (Schema-Compliant) → Run Test → Solidify Code
+                             ↑                                    ↓
+                             └───────────── Evolution ────────────┘
 ```
 
+### Schema-Driven Accuracy
+
+Unlike "hallucinated" mocks, Mock MCP uses your actual **OpenAPI JSON Schema** definitions to ground the AI. This ensures that generated data not only looks real but strictly adheres to your API contracts, catching integration issues early.
+
 ## 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.
 
+- **Schema-aware generation** uses your provided metadata (OpenAPI JSON Schema) to ensure mocks match production behavior.
 - **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.
@@ -189,9 +198,17 @@ await page.route("**/api/users", async (route) => {
 
 Batch behaviour stays automatic: additional `requestMock` calls issued in the same macrotask are grouped, forwarded, and resolved together.
 
+Need to pause the test until everything in-flight resolves? Call `waitForPendingRequests` to block on the current set of pending requests (anything started after the call is not included):
+
+```ts
+// After routing a few requests
+await mockClient.waitForPendingRequests();
+// Safe to assert on the results produced by the mocked responses
+```
+
 ## 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.
+`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.
 
@@ -261,6 +278,7 @@ The library exports primitives so you can embed the workflow inside bespoke runn
 
 - `TestMockMCPServer` starts and stops the WebSocket plus MCP tooling bridge programmatically.
 - `BatchMockCollector` provides a low-level batching client used directly inside test environments.
+- `BatchMockCollector.waitForPendingRequests()` waits for the currently pending mock requests to settle (resolves when all finish, rejects if any fail).
 - `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.

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

@@ -5,7 +5,7 @@ export interface BatchMockCollectorOptions {
     /**
      * TCP port exposed by {@link TestMockMCPServer}.
      *
-     * @default 8080
+     * @default 3002
      */
     port?: number;
     /**
@@ -66,6 +66,11 @@ export declare class BatchMockCollector {
      * 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.
      */

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

@@ -1,9 +1,10 @@
 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 = 8080;
+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.
@@ -59,24 +60,45 @@ export class BatchMockCollector {
             headers: options.headers,
             metadata: options.metadata,
         };
+        let settleCompletion;
+        const completion = new Promise((resolve) => {
+            settleCompletion = resolve;
+        });
         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.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.
      */

package/dist/client/connect.js

@@ -1,11 +1,11 @@
 import { BatchMockCollector } from "./batch-mock-collector.js";
+import { isEnabled } from "./util.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) {
+    if (!isEnabled()) {
         console.log("[mock-mcp] Skipping (set MOCK_MCP=1 to enable)");
         return;
     }

package/dist/client/util.d.ts

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

package/dist/client/util.js

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

package/dist/connect.cjs

@@ -41,11 +41,16 @@ var import_ws = __toESM(require("ws"), 1);
 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 = 8080;
+var DEFAULT_PORT = 3002;
 var BatchMockCollector = class {
   ws;
   pendingRequests = /* @__PURE__ */ new Map();
@@ -97,10 +102,14 @@ var BatchMockCollector = class {
       headers: options.headers,
       metadata: options.metadata
     };
+    let settleCompletion;
+    const completion = new Promise((resolve) => {
+      settleCompletion = resolve;
+    });
     return new Promise((resolve, reject) => {
       const timeoutId = setTimeout(() => {
-        this.pendingRequests.delete(requestId);
-        reject(
+        this.rejectRequest(
+          requestId,
           new Error(
             `Mock request timed out after ${this.timeout}ms: ${method} ${endpoint}`
           )
@@ -109,16 +118,38 @@ var BatchMockCollector = class {
       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
+        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.
    */
@@ -253,8 +284,7 @@ var BatchMockCollector = class {
 
 // src/client/connect.ts
 var connect = async (options) => {
-  const isEnabled = process.env.MOCK_MCP !== void 0 && process.env.MOCK_MCP !== "0";
-  if (!isEnabled) {
+  if (!isEnabled()) {
     console.log("[mock-mcp] Skipping (set MOCK_MCP=1 to enable)");
     return;
   }

package/dist/connect.d.cts

@@ -5,7 +5,7 @@ interface BatchMockCollectorOptions {
     /**
      * TCP port exposed by {@link TestMockMCPServer}.
      *
-     * @default 8080
+     * @default 3002
      */
     port?: number;
     /**
@@ -66,6 +66,11 @@ declare class BatchMockCollector {
      * 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.
      */

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
 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;
-console.error('mock-mcp running');
 async function runCli() {
     const cliArgs = process.argv.slice(2);
     let port = Number.parseInt(process.env.MCP_SERVER_PORT ?? "", 10);
@@ -41,7 +41,11 @@ const isCliExecution = (() => {
     if (typeof process === "undefined" || !process.argv?.[1]) {
         return false;
     }
-    return import.meta.url === pathToFileURL(process.argv[1]).href;
+    // Resolve symlinks to ensure proper comparison between import.meta.url and argv[1]
+    // This is necessary because import.meta.url contains the real path,
+    // while process.argv[1] may contain symlinks (e.g., /tmp vs /private/tmp on macOS)
+    const scriptPath = realpathSync(process.argv[1]);
+    return import.meta.url === pathToFileURL(scriptPath).href;
 })();
 if (isCliExecution) {
     runCli().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mock-mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "An MCP server enabling LLMs to write integration tests through live test environment interaction",
   "main": "./dist/connect.cjs",
   "type": "module",
@@ -70,4 +70,4 @@
       "path": "cz-conventional-changelog"
     }
   }
-}
+}