mock-mcp 0.0.1 → 0.1.0

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/package.json

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

package/dist/src/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/src/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/src/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>;

package/dist/src/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/src/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/src/client/index.js

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

package/dist/src/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/src/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/src/server/index.d.ts

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

package/dist/src/server/index.js

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

package/dist/src/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 {};