mock-mcp 0.3.1 → 0.5.0

package/dist/connect.d.cts

@@ -1,82 +0,0 @@
-/**
- * Shape of the mock data that needs to be returned for a request.
- */
-interface MockResponseDescriptor {
-    requestId: string;
-    data: unknown;
-    status?: number;
-    headers?: Record<string, string>;
-    delayMs?: number;
-}
-interface ResolvedMock<T = unknown> extends Omit<MockResponseDescriptor, "data"> {
-    data: T;
-}
-
-type Logger = Pick<Console, "log" | "warn" | "error"> & {
-    debug?: (...args: unknown[]) => void;
-};
-interface BatchMockCollectorOptions {
-    /**
-     * TCP port exposed by {@link TestMockMCPServer}.
-     *
-     * @default 3002
-     */
-    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;
-    /**
-     * Interval for WebSocket heartbeats in milliseconds. Set to 0 to disable.
-     *
-     * @default 15000
-     */
-    heartbeatIntervalMs?: number;
-    /**
-     * Automatically attempt to reconnect when the WebSocket closes unexpectedly.
-     *
-     * @default true
-     */
-    enableReconnect?: boolean;
-}
-interface RequestMockOptions {
-    body?: unknown;
-    headers?: Record<string, string>;
-    metadata?: Record<string, unknown>;
-}
-
-type ConnectOptions = number | BatchMockCollectorOptions | undefined;
-interface MockClient {
-    waitUntilReady(): Promise<void>;
-    requestMock<T = unknown>(endpoint: string, method: string, options?: RequestMockOptions): Promise<ResolvedMock<T>>;
-    waitForPendingRequests(): Promise<void>;
-    close(code?: number): Promise<void>;
-}
-/**
- * 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<MockClient>;
-
-export { type ConnectOptions, type MockClient, connect };

package/dist/server/index.d.ts

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

package/dist/server/index.js

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

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

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

package/dist/server/test-mock-mcp-server.js

@@ -1,419 +0,0 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { WebSocketServer, WebSocket } from "ws";
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-import packageJson from "../../package.json" with { type: "json" };
-import { BATCH_MOCK_REQUEST, BATCH_MOCK_RESPONSE, } from "../types.js";
-const DEFAULT_PORT = 3002;
-const DEFAULT_BATCH_TTL_MS = 5 * 60 * 1000;
-/**
- * Bridges the integration-test process and the MCP client, making it possible
- * to generate realistic mock data on demand.
- */
-export class TestMockMCPServer {
-    logger;
-    options;
-    wss;
-    cleanupTimer;
-    mcpServer;
-    transport;
-    started = false;
-    actualPort;
-    pendingBatches = new Map();
-    clients = new Set();
-    batchCounter = 0;
-    constructor(options = {}) {
-        this.logger = options.logger ?? console;
-        this.options = {
-            port: options.port,
-            logger: this.logger,
-            batchTtlMs: options.batchTtlMs ?? DEFAULT_BATCH_TTL_MS,
-            sweepIntervalMs: options.sweepIntervalMs,
-            enableMcpTransport: options.enableMcpTransport ?? true,
-            transportFactory: options.transportFactory,
-            serverName: options.serverName ?? "test-mock-server",
-            serverVersion: options.serverVersion ?? packageJson.version ?? "0.0.0",
-            mockLogOptions: options.mockLogOptions,
-        };
-    }
-    /**
-     * Start both the WebSocket server (for the test runner) and the MCP server
-     * (for the AI client).
-     */
-    async start() {
-        if (this.started) {
-            return;
-        }
-        await this.startWebSocketServer();
-        if (this.options.enableMcpTransport) {
-            await this.startMcpServer();
-        }
-        this.started = true;
-    }
-    /**
-     * Shut down all transports and clear pending batches.
-     */
-    async stop() {
-        if (this.cleanupTimer) {
-            clearInterval(this.cleanupTimer);
-            this.cleanupTimer = undefined;
-        }
-        for (const ws of this.clients) {
-            ws.close();
-        }
-        this.clients.clear();
-        await new Promise((resolve) => {
-            if (!this.wss) {
-                resolve();
-                return;
-            }
-            this.wss.close(() => resolve());
-            this.wss = undefined;
-        });
-        if (this.transport) {
-            await this.transport.close().catch((error) => {
-                this.logger.warn("Failed to close MCP transport:", error);
-            });
-            this.transport = undefined;
-        }
-        this.pendingBatches.clear();
-        this.mcpServer = undefined;
-        this.started = false;
-    }
-    /**
-     * Expose the TCP port that the WebSocket server is listening on. Useful when
-     * `port=0` is supplied for ephemeral environments or tests.
-     */
-    get port() {
-        return this.actualPort ?? this.options.port;
-    }
-    /**
-     * Return summaries of all batches that are awaiting AI-provided mock data.
-     */
-    getPendingBatches() {
-        return Array.from(this.pendingBatches.values()).map(({ batchId, timestamp, requests }) => ({
-            batchId,
-            timestamp,
-            requestCount: requests.length,
-            requests,
-        }));
-    }
-    /**
-     * Send AI-generated mock data back to the corresponding test process.
-     */
-    async provideMockData(args) {
-        const { batchId, mocks } = args;
-        const batch = this.pendingBatches.get(batchId);
-        if (!batch) {
-            throw new Error(`Batch not found: ${batchId}`);
-        }
-        const expectedIds = new Set(batch.requests.map((request) => request.requestId));
-        const providedIds = new Set();
-        const unknownMock = mocks.find((mock) => !expectedIds.has(mock.requestId));
-        if (unknownMock) {
-            throw new Error(`Mock data references unknown requestId: ${unknownMock.requestId}`);
-        }
-        for (const mock of mocks) {
-            if (providedIds.has(mock.requestId)) {
-                throw new Error(`Duplicate mock data provided for requestId: ${mock.requestId}`);
-            }
-            providedIds.add(mock.requestId);
-        }
-        const missingIds = Array.from(expectedIds).filter((requestId) => !providedIds.has(requestId));
-        if (missingIds.length > 0) {
-            throw new Error(`Missing mock data for requestId(s): ${missingIds.join(", ")}`);
-        }
-        if (batch.ws.readyState !== WebSocket.OPEN) {
-            this.pendingBatches.delete(batchId);
-            throw new Error(`Test process disconnected before mocks were provided for ${batchId}`);
-        }
-        try {
-            await this.persistMockBatch(batch, mocks);
-        }
-        catch (error) {
-            this.logger.warn(`Failed to persist mock batch ${batchId}:`, error);
-        }
-        const payload = {
-            type: BATCH_MOCK_RESPONSE,
-            batchId,
-            mocks,
-        };
-        batch.ws.send(JSON.stringify(payload));
-        this.pendingBatches.delete(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}`,
-        }));
-    }
-    async startWebSocketServer() {
-        if (this.wss) {
-            return;
-        }
-        const desiredPort = this.options.port ?? DEFAULT_PORT;
-        await new Promise((resolve, reject) => {
-            const wss = new WebSocketServer({ port: desiredPort });
-            this.wss = wss;
-            wss.once("listening", () => {
-                const address = wss.address();
-                this.actualPort = address?.port ?? desiredPort;
-                this.logger.error(`🚀 WebSocket server listening on ws://localhost:${this.actualPort}`);
-                resolve();
-            });
-            wss.once("error", (error) => {
-                this.logger.error("Failed to start WebSocket server:", error);
-                reject(error);
-            });
-            wss.on("connection", (ws) => this.handleConnection(ws));
-        });
-        if (this.options.batchTtlMs > 0) {
-            const interval = this.options.sweepIntervalMs ??
-                Math.min(this.options.batchTtlMs, 30_000);
-            this.cleanupTimer = setInterval(() => this.sweepExpiredBatches(), interval);
-            this.cleanupTimer.unref?.();
-        }
-    }
-    async startMcpServer() {
-        if (this.mcpServer) {
-            return;
-        }
-        const serverName = this.options.serverName ?? "test-mock-server";
-        const serverVersion = this.options.serverVersion ??
-            packageJson.version ??
-            "0.0.0";
-        this.mcpServer = new Server({
-            name: serverName,
-            version: serverVersion,
-        }, {
-            capabilities: { tools: {} },
-        });
-        this.mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools: [
-                {
-                    name: "get_pending_batches",
-                    description: "Inspect pending mock batches produced by the test run",
-                    inputSchema: {
-                        type: "object",
-                        properties: {},
-                        required: [],
-                    },
-                },
-                {
-                    name: "provide_batch_mock_data",
-                    description: "Provide mock data for a specific batch",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            batchId: {
-                                type: "string",
-                            },
-                            mocks: {
-                                type: "array",
-                                items: {
-                                    type: "object",
-                                    properties: {
-                                        requestId: { type: "string" },
-                                        data: {
-                                            anyOf: [
-                                                { type: "object" },
-                                                { type: "array" },
-                                                { type: "string" },
-                                                { type: "number" },
-                                                { type: "boolean" },
-                                                { type: "null" },
-                                            ],
-                                        },
-                                        status: {
-                                            type: "number",
-                                        },
-                                        headers: {
-                                            type: "object",
-                                        },
-                                        delayMs: {
-                                            type: "number",
-                                        },
-                                    },
-                                    required: ["requestId", "data"],
-                                },
-                            },
-                        },
-                        required: ["batchId", "mocks"],
-                    },
-                },
-            ],
-        }));
-        this.mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
-            const toolName = request.params.name;
-            if (toolName === "get_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") {
-                const args = request.params.arguments;
-                if (!isProvideBatchMockDataArgs(args)) {
-                    throw new Error("Invalid arguments for provide_batch_mock_data");
-                }
-                return this.provideMockData(args);
-            }
-            throw new Error(`Unknown tool: ${toolName}`);
-        });
-        this.transport =
-            this.options.transportFactory?.() ?? new StdioServerTransport();
-        await this.mcpServer.connect(this.transport);
-        this.logger.error("✅ MCP server is ready (stdio transport)");
-    }
-    handleConnection(ws) {
-        this.logger.error("🔌 Test process connected");
-        this.clients.add(ws);
-        ws.on("message", (data) => this.handleClientMessage(ws, data));
-        ws.on("ping", () => {
-            try {
-                ws.pong();
-            }
-            catch (error) {
-                this.logger.warn("Failed to respond to ping:", error);
-            }
-        });
-        ws.on("close", () => {
-            this.logger.error("🔌 Test process disconnected");
-            this.clients.delete(ws);
-            this.dropBatchesForClient(ws);
-        });
-        ws.on("error", (error) => {
-            this.logger.error("Test process WebSocket error:", error);
-            this.dropBatchesForClient(ws);
-        });
-    }
-    handleClientMessage(ws, data) {
-        let payload;
-        try {
-            payload = JSON.parse(data.toString());
-        }
-        catch (error) {
-            this.logger.error("Failed to parse WebSocket message:", error);
-            return;
-        }
-        if (payload.type !== BATCH_MOCK_REQUEST) {
-            this.logger.warn("Unsupported message type received:", payload.type);
-            return;
-        }
-        if (!Array.isArray(payload.requests) || payload.requests.length === 0) {
-            this.logger.warn("Received a batch without requests");
-            return;
-        }
-        this.handleBatchRequest(ws, payload.requests);
-    }
-    handleBatchRequest(ws, requests) {
-        const batchId = `batch-${++this.batchCounter}`;
-        const timestamp = new Date().toISOString();
-        const expiresAt = this.options.batchTtlMs
-            ? Date.now() + this.options.batchTtlMs
-            : undefined;
-        this.pendingBatches.set(batchId, {
-            batchId,
-            timestamp,
-            requestCount: requests.length,
-            requests,
-            ws,
-            expiresAt,
-        });
-        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.error("⏳ Awaiting mock data from MCP client...");
-    }
-    dropBatchesForClient(ws) {
-        for (const [batchId, batch] of this.pendingBatches) {
-            if (batch.ws === ws) {
-                this.pendingBatches.delete(batchId);
-                this.logger.warn(`🧹 Dropped pending batch ${batchId} because the test client disconnected`);
-            }
-        }
-    }
-    sweepExpiredBatches() {
-        const now = Date.now();
-        for (const [batchId, batch] of this.pendingBatches) {
-            if (batch.expiresAt && batch.expiresAt <= now) {
-                this.pendingBatches.delete(batchId);
-                this.logger.warn(`🧹 Removed expired batch ${batchId} (waited more than ${this.options.batchTtlMs / 1000}s)`);
-            }
-        }
-    }
-    async persistMockBatch(batch, mocks) {
-        const mockLogOptions = this.options.mockLogOptions;
-        if (!mockLogOptions?.enabled) {
-            return;
-        }
-        const directory = path.resolve(process.cwd(), mockLogOptions.directory ?? "logs");
-        await mkdir(directory, { recursive: true });
-        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.error(`📝 Saved mock batch ${batch.batchId} to ${filePath}`);
-    }
-    buildLogEntry(batch, mocks) {
-        const mockMap = new Map(mocks.map((mock) => [mock.requestId, mock]));
-        return {
-            batchId: batch.batchId,
-            timestamp: batch.timestamp,
-            requestCount: batch.requestCount,
-            context: this.extractBatchContext(batch.requests),
-            requests: batch.requests.map((request) => ({
-                ...request,
-                mock: mockMap.get(request.requestId),
-            })),
-            mocks,
-        };
-    }
-    extractBatchContext(requests) {
-        const contextKeys = ["testCaseId", "testFile", "testTitle", "testName"];
-        const context = {};
-        for (const key of contextKeys) {
-            const requestWithValue = requests.find((request) => request.metadata && request.metadata[key] !== undefined);
-            if (requestWithValue?.metadata) {
-                context[key] = requestWithValue.metadata[key];
-            }
-        }
-        const metadataSnapshots = requests
-            .map((request) => request.metadata)
-            .filter((metadata) => {
-            if (!metadata) {
-                return false;
-            }
-            return Object.keys(metadata).length > 0;
-        });
-        if (metadataSnapshots.length > 0) {
-            context.metadata = metadataSnapshots;
-        }
-        return Object.keys(context).length > 0 ? context : undefined;
-    }
-    buildToolResponse(text) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text,
-                },
-            ],
-        };
-    }
-}
-function isProvideBatchMockDataArgs(value) {
-    if (!value || typeof value !== "object") {
-        return false;
-    }
-    const candidate = value;
-    if (typeof candidate.batchId !== "string" || !Array.isArray(candidate.mocks)) {
-        return false;
-    }
-    return candidate.mocks.every((mock) => {
-        if (!mock || typeof mock !== "object") {
-            return false;
-        }
-        const descriptor = mock;
-        return typeof descriptor.requestId === "string" && "data" in descriptor;
-    });
-}

package/dist/types.d.ts

@@ -1,45 +0,0 @@
-export declare const BATCH_MOCK_REQUEST: "BATCH_MOCK_REQUEST";
-export declare const BATCH_MOCK_RESPONSE: "BATCH_MOCK_RESPONSE";
-/**
- * Shape of a mock request emitted by the test process.
- */
-export interface MockRequestDescriptor {
-    requestId: string;
-    endpoint: string;
-    method: string;
-    body?: unknown;
-    headers?: Record<string, string>;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Shape of the mock data that needs to be returned for a request.
- */
-export interface MockResponseDescriptor {
-    requestId: string;
-    data: unknown;
-    status?: number;
-    headers?: Record<string, string>;
-    delayMs?: number;
-}
-export interface ResolvedMock<T = unknown> extends Omit<MockResponseDescriptor, "data"> {
-    data: T;
-}
-export interface BatchMockRequestMessage {
-    type: typeof BATCH_MOCK_REQUEST;
-    requests: MockRequestDescriptor[];
-}
-export interface BatchMockResponseMessage {
-    type: typeof BATCH_MOCK_RESPONSE;
-    batchId: string;
-    mocks: MockResponseDescriptor[];
-}
-export interface PendingBatchSummary {
-    batchId: string;
-    timestamp: string;
-    requestCount: number;
-    requests: MockRequestDescriptor[];
-}
-export interface ProvideBatchMockDataArgs {
-    batchId: string;
-    mocks: MockResponseDescriptor[];
-}

package/dist/types.js

@@ -1,2 +0,0 @@
-export const BATCH_MOCK_REQUEST = "BATCH_MOCK_REQUEST";
-export const BATCH_MOCK_RESPONSE = "BATCH_MOCK_RESPONSE";