mock-mcp 0.3.0 → 0.5.0

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

@@ -1,392 +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 missing = mocks.find((mock) => !batch.requests.some((request) => request.requestId === mock.requestId));
-        if (missing) {
-            throw new Error(`Mock data references unknown requestId: ${missing.requestId}`);
-        }
-        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: {
-                                            type: "object",
-                                        },
-                                        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("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,42 +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 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";