mock-mcp 0.1.0 → 0.2.1

package/README.md

@@ -4,9 +4,10 @@
 [![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 orchestrates AI-generated mock data via the Model Context Protocol (MCP). 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. 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)
@@ -44,7 +45,7 @@ Mock MCP orchestrates AI-generated mock data via the Model Context Protocol (MCP
    ```ts
    import { render, screen, fireEvent } from "@testing-library/react";
    import { connect } from "mock-mcp";
-   
+
    const userSchema = {
      summary: "Fetch the current user",
      response: {
@@ -52,23 +53,23 @@ Mock MCP orchestrates AI-generated mock data via the Model Context Protocol (MCP
        required: ["id", "name"],
        properties: {
          id: { type: "number" },
-         name: { type: "string" }
-       }
-     }
+         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."
+       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" });
@@ -98,13 +99,13 @@ const mockUsers = [
 
 **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 |
+| 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
 
@@ -133,10 +134,10 @@ Mock MCP pairs a WebSocket batch bridge with MCP tooling to move intercepted req
 
 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 |
+| 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.
 
@@ -205,21 +206,22 @@ const listProductsSchema = {
       properties: {
         id: { type: "string" },
         name: { type: "string" },
-        price: { type: "number" }
-      }
-    }
-  }
+        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",
+    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
-  }
+    testFile: expect.getState().testPath,
+  },
 });
 ```
 
@@ -265,20 +267,20 @@ Each class accepts logger overrides, timeout tweaks, and other ergonomics surfac
 
 ## Environment Variables
 
-| Variable          | Description                                                                 | Default |
-| ----------------- | --------------------------------------------------------------------------- | ------- |
-| `MCP_SERVER_PORT` | Overrides the WebSocket port used by both the CLI and any spawned MCP host. | `3002`  |
+| 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                  |
+| 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
 

package/dist/{src/index.js → index.js}

@@ -27,9 +27,9 @@ async function runCli() {
         enableMcpTransport,
     });
     await server.start();
-    console.log(`🎯 Test Mock MCP server ready on ws://localhost:${server.port ?? port}`);
+    console.error(`🎯 Test Mock MCP server ready on ws://localhost:${server.port ?? port}`);
     const shutdown = async () => {
-        console.log("👋 Shutting down Test Mock MCP server...");
+        console.error("👋 Shutting down Test Mock MCP server...");
         await server.stop();
         process.exit(0);
     };

package/dist/{src/server → server}/test-mock-mcp-server.js

@@ -130,7 +130,7 @@ export class TestMockMCPServer {
         };
         batch.ws.send(JSON.stringify(payload));
         this.pendingBatches.delete(batchId);
-        this.logger.log(`✅ Delivered ${mocks.length} mock(s) to test process for ${batchId}`);
+        this.logger.error(`✅ Delivered ${mocks.length} mock(s) to test process for ${batchId}`);
         return this.buildToolResponse(JSON.stringify({
             success: true,
             message: `Provided mock data for ${batchId}`,
@@ -147,7 +147,7 @@ export class TestMockMCPServer {
             wss.once("listening", () => {
                 const address = wss.address();
                 this.actualPort = address?.port ?? desiredPort;
-                this.logger.log(`🚀 WebSocket server listening on ws://localhost:${this.actualPort}`);
+                this.logger.error(`🚀 WebSocket server listening on ws://localhost:${this.actualPort}`);
                 resolve();
             });
             wss.once("error", (error) => {
@@ -228,7 +228,7 @@ export class TestMockMCPServer {
         this.mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             const toolName = request.params.name;
             if (toolName === "get_pending_batches") {
-                this.logger.log("📋 MCP client inspected pending batches");
+                this.logger.error("📋 MCP client inspected pending batches");
                 return this.buildToolResponse(JSON.stringify(this.getPendingBatches(), null, 2));
             }
             if (toolName === "provide_batch_mock_data") {
@@ -243,14 +243,14 @@ export class TestMockMCPServer {
         this.transport =
             this.options.transportFactory?.() ?? new StdioServerTransport();
         await this.mcpServer.connect(this.transport);
-        this.logger.log("✅ MCP server is ready (stdio transport)");
+        this.logger.error("✅ MCP server is ready (stdio transport)");
     }
     handleConnection(ws) {
-        this.logger.log("🔌 Test process connected");
+        this.logger.error("🔌 Test process connected");
         this.clients.add(ws);
         ws.on("message", (data) => this.handleClientMessage(ws, data));
         ws.on("close", () => {
-            this.logger.log("🔌 Test process disconnected");
+            this.logger.error("🔌 Test process disconnected");
             this.clients.delete(ws);
             this.dropBatchesForClient(ws);
         });
@@ -292,11 +292,11 @@ export class TestMockMCPServer {
             ws,
             expiresAt,
         });
-        this.logger.log([
+        this.logger.error([
             `📥 Received ${requests.length} request(s) (${batchId})`,
             ...requests.map((req, index) => `   ${index + 1}. ${req.method} ${req.endpoint} (${req.requestId})`),
         ].join("\n"));
-        this.logger.log("⏳ Awaiting mock data from MCP client...");
+        this.logger.error("⏳ Awaiting mock data from MCP client...");
     }
     dropBatchesForClient(ws) {
         for (const [batchId, batch] of this.pendingBatches) {
@@ -325,7 +325,7 @@ export class TestMockMCPServer {
         const entry = this.buildLogEntry(batch, mocks);
         const filePath = path.join(directory, `mock-${batch.batchId}.json`);
         await writeFile(filePath, JSON.stringify(entry, null, 2), "utf8");
-        this.logger.log(`📝 Saved mock batch ${batch.batchId} to ${filePath}`);
+        this.logger.error(`📝 Saved mock batch ${batch.batchId} to ${filePath}`);
     }
     buildLogEntry(batch, mocks) {
         const mockMap = new Map(mocks.map((mock) => [mock.requestId, mock]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mock-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "An MCP server enabling LLMs to write integration tests through live test environment interaction",
   "main": "./dist/connect.cjs",
   "type": "module",

package/dist/package.json

@@ -1,73 +0,0 @@
-{
-    "name": "mock-mcp",
-    "version": "0.1.0",
-    "description": "An MCP server enabling LLMs to write integration tests through live test environment interaction",
-    "main": "./dist/connect.cjs",
-    "type": "module",
-    "bin": {
-        "mock-mcp": "dist/index.js"
-    },
-    "files": [
-        "dist"
-    ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "engines": {
-        "node": ">=18.0.0"
-    },
-    "scripts": {
-        "build": "tsc && tsup src/client/connect.ts --dts",
-        "start": "node dist/index.js",
-        "dev": "tsx src/index.ts",
-        "lint": "eslint . --ext .ts",
-        "test": "vitest run",
-        "test:watch": "vitest --watch",
-        "prepublishOnly": "npm run build",
-        "link": "npm link",
-        "unlink": "npm unlink",
-        "commit": "yarn git-cz"
-    },
-    "keywords": [
-        "mcp",
-        "model-context-protocol",
-        "mock",
-        "mock-mcp"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/mcpland/mock-mcp.git"
-    },
-    "author": "unadlib",
-    "license": "MIT",
-    "dependencies": {
-        "@cfworker/json-schema": "^4.1.1",
-        "@modelcontextprotocol/sdk": "^1.20.2",
-        "ts-morph": "^27.0.2",
-        "ws": "^8.18.3",
-        "zod": "^4.1.12"
-    },
-    "devDependencies": {
-        "@types/node": "^24.0.15",
-        "@types/ws": "^8.18.1",
-        "@typescript-eslint/eslint-plugin": "^8.38.0",
-        "@typescript-eslint/parser": "^8.38.0",
-        "@vitest/coverage-v8": "^3.2.4",
-        "commitizen": "^4.3.1",
-        "eslint": "^9.31.0",
-        "node-fetch": "^3.3.2",
-        "tsup": "^8.5.0",
-        "tsx": "^4.20.3",
-        "typescript": "^5.8.3",
-        "vite": "^7.0.5",
-        "vitest": "^3.2.4"
-    },
-    "resolutions": {
-        "rollup": "4.52.5"
-    },
-    "config": {
-        "commitizen": {
-            "path": "cz-conventional-changelog"
-        }
-    }
-}