@skyramp/mcp 0.2.8 → 0.2.150-rc.ldw-

package/build/tools/enrichTestWithMocksTool.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it, beforeEach, afterEach } from "@jest/globals";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { injectMockImports } from "./enrichTestWithMocksTool.js";
+describe("injectMockImports", () => {
+    let tmpDir;
+    let testFile;
+    let mockFile;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-enrich-"));
+        testFile = path.join(tmpDir, "account_integration_test.py");
+        mockFile = path.join(tmpDir, "billing_preferences_PUT_mock.py");
+        fs.writeFileSync(mockFile, [
+            "# Command: skyramp generate mock rest http://billing-service:4000/v1/preferences --method PUT",
+            "def get_all_mocks():",
+            "    return []",
+            "",
+        ].join("\n"));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("applies mocks in every Python test function", () => {
+        const source = [
+            "import skyramp",
+            "",
+            "def test_success():",
+            "    client = skyramp.Client(port=35142)",
+            "    assert True",
+            "",
+            "def test_error():",
+            "    client = skyramp.Client(",
+            "        port=35142,",
+            "    )",
+            "    assert True",
+            "",
+        ].join("\n");
+        const enriched = injectMockImports(source, testFile, "billing", [mockFile]);
+        expect(enriched.match(/^    apply_all_mocks\(client\)$/gm)).toHaveLength(2);
+        expect(enriched).toContain("MOCK_SERVICES");
+    });
+    it("does not duplicate apply calls when rerun", () => {
+        const source = [
+            "import skyramp",
+            "",
+            "def test_success():",
+            "    client = skyramp.Client(port=35142)",
+            "    assert True",
+            "",
+            "def test_error():",
+            "    client = skyramp.Client(port=35142)",
+            "    assert True",
+            "",
+        ].join("\n");
+        const once = injectMockImports(source, testFile, "billing", [mockFile]);
+        const twice = injectMockImports(once, testFile, "billing", [mockFile]);
+        expect(twice.match(/^    apply_all_mocks\(client\)$/gm)).toHaveLength(2);
+    });
+});

package/build/tools/executeSkyrampTestTool.d.ts

@@ -1,2 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TestType } from "../types/TestTypes.js";
+export declare const CONTRACT_EXECUTION_MODES: readonly ["provider", "consumer"];
+export type ContractExecutionMode = (typeof CONTRACT_EXECUTION_MODES)[number];
+export declare function shouldInjectSkyrampBaseUrl(testType: TestType, contractMode?: ContractExecutionMode): boolean;
 export declare function registerExecuteSkyrampTestTool(server: McpServer): void;

package/build/tools/executeSkyrampTestTool.js

@@ -5,9 +5,13 @@ import { AnalyticsService } from "../services/AnalyticsService.js";
 import { TestExecutionStatus } from "../types/TestExecution.js";
 import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
 import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
-import { StateManager } from "../utils/AnalysisStateManager.js";
+import { StateManager, } from "../utils/AnalysisStateManager.js";
 import { logger } from "../utils/logger.js";
 const TOOL_NAME = "skyramp_execute_test";
+export const CONTRACT_EXECUTION_MODES = ["provider", "consumer"];
+export function shouldInjectSkyrampBaseUrl(testType, contractMode) {
+    return testType !== TestType.CONTRACT || contractMode !== "consumer";
+}
 export function registerExecuteSkyrampTestTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Execute a Skyramp-generated test in isolated containerized environments for reliable, deterministic testing.
@@ -53,10 +57,14 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                 .describe("Programming language of the test file to execute (e.g., python, javascript, typescript, java)"),
             testType: z
                 .nativeEnum(TestType)
-                .describe("Type of the test to execute."),
+                .describe("Type of the test to execute. Note: 'mock' is NOT a valid test type — mock files are deployed via their apply_mock() function, not executed as tests."),
             testFile: z
                 .string()
                 .describe("ALWAYS USE ABSOLUTE PATH to the test file to execute"),
+            contractMode: z
+                .enum(CONTRACT_EXECUTION_MODES)
+                .optional()
+                .describe("Only applies when testType is 'contract'. Use 'provider' for provider contract tests that hit the real service under test and need SKYRAMP_TEST_BASE_URL. Use 'consumer' only for consumer contract tests with inline mocks that do not hit the real service. Defaults to provider behavior when omitted."),
             token: z
                 .string()
                 .describe("Skyramp authentication token for test execution. USE EMPTY STRING WHEN USER CONFIRMS 'No token required'"),
@@ -81,23 +89,33 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
             keywords: ["run test", "execute test"],
         },
     }, async (params, extra) => {
-        let errorResult;
-        // Helper to send progress notifications to the MCP client
+        // Helper to send progress notifications to the MCP client.
+        // Wrapped in try-catch so a broken/disconnected transport never crashes
+        // the tool handler or causes an unhandled rejection.
         const sendProgress = async (progress, total, message) => {
             const progressToken = extra._meta?.progressToken;
             if (progressToken !== undefined) {
-                const notification = {
-                    method: "notifications/progress",
-                    params: {
-                        progressToken,
-                        progress,
-                        total,
-                        message,
-                    },
-                };
-                await extra.sendNotification(notification);
+                try {
+                    const notification = {
+                        method: "notifications/progress",
+                        params: {
+                            progressToken,
+                            progress,
+                            total,
+                            message,
+                        },
+                    };
+                    await extra.sendNotification(notification);
+                }
+                catch {
+                    // Progress notifications are best-effort — swallow failures so
+                    // a flaky or disconnected transport doesn't kill the execution.
+                }
             }
         };
+        // Send immediate acknowledgment
+        await sendProgress(0, 100, "Starting execution...");
+        let errorResult;
         // Progress callback adapter for TestExecutionService
         const onExecutionProgress = async (progress) => {
             await sendProgress(progress.percent, 100, progress.message);
@@ -107,20 +125,22 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
         let useHostNetwork = false;
         try {
             // Send initial progress
-            await sendProgress(0, 100, "Starting test execution...");
+            await sendProgress(5, 100, "Starting test execution...");
             // Always resolve workspace config for dockerNetwork (host networking)
             // and optionally inject SKYRAMP_TEST_BASE_URL if not already set.
             if (params.workspacePath) {
                 const { baseUrl, dockerNetwork, candidates } = await getWorkspaceBaseUrl(params.workspacePath, params.testFile, params.language);
                 useHostNetwork = !!dockerNetwork;
-                if (!process.env.SKYRAMP_TEST_BASE_URL) {
+                const shouldInjectBaseUrl = shouldInjectSkyrampBaseUrl(params.testType, params.contractMode);
+                if (shouldInjectBaseUrl && !process.env.SKYRAMP_TEST_BASE_URL) {
                     if (baseUrl) {
                         process.env.SKYRAMP_TEST_BASE_URL = baseUrl;
                         didSetSkyrampBaseUrl = true;
                     }
                     else if (candidates.length > 0) {
                         return {
-                            content: [{
+                            content: [
+                                {
                                     type: "text",
                                     text: [
                                         `Cannot determine SKYRAMP_TEST_BASE_URL — test file matches multiple services:`,
@@ -128,7 +148,8 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                                         ``,
                                         `Re-invoke with SKYRAMP_TEST_BASE_URL set to the correct service URL, or make each service's testDirectory unique in .skyramp/workspace.yml.`,
                                     ].join("\n"),
-                                }],
+                                },
+                            ],
                             isError: true,
                         };
                     }

package/build/tools/executeSkyrampTestTool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/executeSkyrampTestTool.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "@jest/globals";
+import { TestType } from "../types/TestTypes.js";
+import { shouldInjectSkyrampBaseUrl } from "./executeSkyrampTestTool.js";
+describe("shouldInjectSkyrampBaseUrl", () => {
+    it("injects for provider contract tests by default", () => {
+        expect(shouldInjectSkyrampBaseUrl(TestType.CONTRACT)).toBe(true);
+        expect(shouldInjectSkyrampBaseUrl(TestType.CONTRACT, "provider")).toBe(true);
+    });
+    it("skips injection only for explicit consumer contract tests", () => {
+        expect(shouldInjectSkyrampBaseUrl(TestType.CONTRACT, "consumer")).toBe(false);
+    });
+    it("injects for non-contract tests", () => {
+        expect(shouldInjectSkyrampBaseUrl(TestType.INTEGRATION, "consumer")).toBe(true);
+        expect(shouldInjectSkyrampBaseUrl(TestType.UI)).toBe(true);
+    });
+});

package/build/tools/generate-tests/batchMockGenerationTool.d.ts

@@ -0,0 +1,79 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { MockProtocol } from "../../types/TestTypes.js";
+export { MockProtocol } from "../../types/TestTypes.js";
+export declare const BATCH_MOCK_PROTOCOL_EXAMPLES = "\n<example protocol=\"rest\">\nBatch REST item. Required fields: protocol=\"rest\", endpointURL, method unless apiSchema is provided.\n{\n  \"protocol\": \"rest\",\n  \"endpointURL\": \"http://identity-service:4000/api/internal/v1/users/validate\",\n  \"method\": \"POST\",\n  \"requestAware\": true,\n  \"responseData\": \"{\"valid\":true}\"\n}\n</example>\n\n<example protocol=\"grpc\">\nBatch gRPC item. Required fields: protocol=\"grpc\", endpointURL as host:port, protoPath, grpcServiceName. method is the RPC name; empty means all service methods.\n{\n  \"protocol\": \"grpc\",\n  \"endpointURL\": \"profile-service:50051\",\n  \"protoPath\": \"/repo/proto/profiles.proto\",\n  \"grpcServiceName\": \"ProfileService\",\n  \"method\": \"GetProfile\",\n  \"responseData\": \"{\"id\":\"profile_123\"}\"\n}\n</example>\n\n<example protocol=\"kafka-producer\">\nBatch Kafka producer validation item. Required fields: protocol=\"kafka\", endpointURL as broker host:port, kafkaTopic, and requestData. Do not pass method or responseData.\n{\n  \"protocol\": \"kafka\",\n  \"endpointURL\": \"broker:9092\",\n  \"kafkaTopic\": \"orders\",\n  \"requestData\": \"{\"order_id\":\"ord_123\"}\"\n}\n</example>\n\n<example protocol=\"kafka-consumer\">\nBatch Kafka consumer message item. Required fields: protocol=\"kafka\", endpointURL as broker host:port, kafkaTopic, and responseData. Do not pass method or requestData.\n{\n  \"protocol\": \"kafka\",\n  \"endpointURL\": \"broker:9092\",\n  \"kafkaTopic\": \"orders\",\n  \"responseData\": \"{\"accepted\":true}\"\n}\n</example>";
+declare const mockSpecSchema: z.ZodObject<{
+    protocol: z.ZodDefault<z.ZodNativeEnum<typeof MockProtocol>>;
+    endpointURL: z.ZodString;
+    method: z.ZodDefault<z.ZodString>;
+    responseData: z.ZodOptional<z.ZodString>;
+    responseStatusCode: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    requestData: z.ZodDefault<z.ZodString>;
+    requestAware: z.ZodDefault<z.ZodBoolean>;
+    apiSchema: z.ZodDefault<z.ZodString>;
+    protoPath: z.ZodOptional<z.ZodString>;
+    grpcServiceName: z.ZodOptional<z.ZodString>;
+    protobufExtraFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    protobufExtraImportPath: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    kafkaTopic: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodString>;
+    outputDir: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    method: string;
+    endpointURL: string;
+    apiSchema: string;
+    requestData: string;
+    responseStatusCode: string;
+    protocol: MockProtocol;
+    requestAware: boolean;
+    output?: string | undefined;
+    outputDir?: string | undefined;
+    responseData?: string | undefined;
+    protoPath?: string | undefined;
+    grpcServiceName?: string | undefined;
+    protobufExtraFiles?: string[] | undefined;
+    protobufExtraImportPath?: string[] | undefined;
+    kafkaTopic?: string | undefined;
+}, {
+    endpointURL: string;
+    output?: string | undefined;
+    outputDir?: string | undefined;
+    method?: string | undefined;
+    apiSchema?: string | undefined;
+    requestData?: string | undefined;
+    responseStatusCode?: string | undefined;
+    responseData?: string | undefined;
+    protocol?: MockProtocol | undefined;
+    protoPath?: string | undefined;
+    grpcServiceName?: string | undefined;
+    protobufExtraFiles?: string[] | undefined;
+    protobufExtraImportPath?: string[] | undefined;
+    kafkaTopic?: string | undefined;
+    requestAware?: boolean | undefined;
+}>;
+export type MockSpec = z.infer<typeof mockSpecSchema>;
+export type MockSpecInput = z.input<typeof mockSpecSchema>;
+export interface BatchMockResult {
+    index: number;
+    protocol: string;
+    endpointURL: string;
+    method: string;
+    topic?: string;
+    success: boolean;
+    outputDir?: string;
+    output?: string;
+    error?: string;
+    detail?: string;
+}
+export interface BatchMockParams {
+    mocks: MockSpecInput[];
+    outputDir: string;
+    runtime?: string;
+    dockerNetwork?: string;
+    language?: string;
+    framework?: string;
+}
+export declare function executeBatchMockGeneration(params: BatchMockParams): Promise<CallToolResult>;
+export declare function registerBatchMockTool(server: McpServer): void;

package/build/tools/generate-tests/batchMockGenerationTool.js

@@ -0,0 +1,395 @@
+import { z } from "zod";
+import { SkyrampClient } from "@skyramp/skyramp";
+import { MockProtocol } from "../../types/TestTypes.js";
+export { MockProtocol } from "../../types/TestTypes.js";
+import { AnalyticsService } from "../../services/AnalyticsService.js";
+import { logger } from "../../utils/logger.js";
+import { getEntryPoint } from "../../utils/telemetry.js";
+import fs from "fs";
+import { getRestMockMethodValidationError, normalizeRestMockMethod, } from "../../utils/httpMethodValidation.js";
+import { getGrpcMockResponseValidationError } from "../../utils/grpcMockValidation.js";
+import { validateMockCompatibility } from "../../utils/mockCompatibility.js";
+export const BATCH_MOCK_PROTOCOL_EXAMPLES = `
+<example protocol="rest">
+Batch REST item. Required fields: protocol="rest", endpointURL, method unless apiSchema is provided.
+{
+  "protocol": "rest",
+  "endpointURL": "http://identity-service:4000/api/internal/v1/users/validate",
+  "method": "POST",
+  "requestAware": true,
+  "responseData": "{\"valid\":true}"
+}
+</example>
+
+<example protocol="grpc">
+Batch gRPC item. Required fields: protocol="grpc", endpointURL as host:port, protoPath, grpcServiceName. method is the RPC name; empty means all service methods.
+{
+  "protocol": "grpc",
+  "endpointURL": "profile-service:50051",
+  "protoPath": "/repo/proto/profiles.proto",
+  "grpcServiceName": "ProfileService",
+  "method": "GetProfile",
+  "responseData": "{\"id\":\"profile_123\"}"
+}
+</example>
+
+<example protocol="kafka-producer">
+Batch Kafka producer validation item. Required fields: protocol="kafka", endpointURL as broker host:port, kafkaTopic, and requestData. Do not pass method or responseData.
+{
+  "protocol": "kafka",
+  "endpointURL": "broker:9092",
+  "kafkaTopic": "orders",
+  "requestData": "{\"order_id\":\"ord_123\"}"
+}
+</example>
+
+<example protocol="kafka-consumer">
+Batch Kafka consumer message item. Required fields: protocol="kafka", endpointURL as broker host:port, kafkaTopic, and responseData. Do not pass method or requestData.
+{
+  "protocol": "kafka",
+  "endpointURL": "broker:9092",
+  "kafkaTopic": "orders",
+  "responseData": "{\"accepted\":true}"
+}
+</example>`;
+const mockSpecSchema = z.object({
+    protocol: z
+        .nativeEnum(MockProtocol)
+        .default(MockProtocol.Rest)
+        .describe("Protocol for this mock: 'rest', 'grpc', or 'kafka'. See <example> blocks in the tool description for required fields."),
+    endpointURL: z
+        .string()
+        .describe("For REST: the base URL or endpoint URL. " +
+        "For gRPC: the target service address as host:port. " +
+        "For Kafka: the broker address as host:port."),
+    method: z
+        .string()
+        .default("")
+        .describe("For REST: HTTP method, required unless apiSchema is provided. For gRPC: RPC method name, empty generates all service methods. For Kafka: MUST be empty; use kafkaTopic."),
+    responseData: z
+        .string()
+        .optional()
+        .describe("REST/gRPC response body data; Kafka consumer messages. Inline JSON/YAML or @/path/to/file."),
+    responseStatusCode: z
+        .string()
+        .default("")
+        .refine((val) => !val || /^\d{3}$/.test(val), {
+        message: "Must be a 3-digit HTTP status code (e.g., '200', '201') or empty string",
+    })
+        .describe("HTTP status code the mock should return (e.g., '200', '201')."),
+    requestData: z
+        .string()
+        .default("")
+        .describe("REST request body sample for request-aware mocks; Kafka producer validation payload/schema."),
+    requestAware: z
+        .boolean()
+        .default(false)
+        .describe("When true, generates a dynamic mock that varies by request."),
+    apiSchema: z
+        .string()
+        .default("")
+        .describe("Path or URL to OpenAPI/Swagger schema file."),
+    protoPath: z
+        .string()
+        .optional()
+        .describe("Required for protocol='grpc'. Path to the .proto file."),
+    grpcServiceName: z
+        .string()
+        .optional()
+        .describe("Required for protocol='grpc'. gRPC service name."),
+    protobufExtraFiles: z
+        .array(z.string())
+        .optional()
+        .describe("Optional extra .proto files for gRPC compilation."),
+    protobufExtraImportPath: z
+        .array(z.string())
+        .optional()
+        .describe("Optional extra import directories for protobuf compilation."),
+    kafkaTopic: z
+        .string()
+        .optional()
+        .describe("Required for protocol='kafka'. Kafka topic name."),
+    output: z
+        .string()
+        .optional()
+        .describe("Optional output file name for this mock. Use when multiple mocks share the same endpoint and method so generated files do not overwrite each other."),
+    outputDir: z
+        .string()
+        .optional()
+        .describe("Optional output directory for this mock. Defaults to the batch-level outputDir."),
+});
+function validateMockSpec(spec) {
+    const protocol = spec.protocol ?? MockProtocol.Rest;
+    if (protocol === MockProtocol.Rest) {
+        const methodError = getRestMockMethodValidationError(spec.method);
+        if (methodError)
+            return methodError;
+        if (!spec.apiSchema && !spec.method) {
+            return "REST mock method is required unless apiSchema is provided for schema-wide generation";
+        }
+    }
+    if (protocol === MockProtocol.Grpc) {
+        const missing = [];
+        if (!spec.protoPath)
+            missing.push("protoPath");
+        if (!spec.grpcServiceName)
+            missing.push("grpcServiceName");
+        if (missing.length > 0) {
+            return `gRPC mock requires: ${missing.join(", ")}`;
+        }
+        const grpcResponseError = getGrpcMockResponseValidationError(spec.responseData);
+        if (grpcResponseError)
+            return grpcResponseError;
+    }
+    if (protocol === MockProtocol.Kafka) {
+        if (!spec.kafkaTopic)
+            return "Kafka mock requires: kafkaTopic";
+        if (spec.method) {
+            return "Kafka mock method must be empty; use kafkaTopic for the topic name. Produce validation uses requestData and consumer messages use responseData";
+        }
+        const hasRequestData = Boolean(spec.requestData && spec.requestData.trim());
+        const hasResponseData = Boolean(spec.responseData && spec.responseData.trim());
+        if (hasRequestData === hasResponseData) {
+            return "Kafka mock requires exactly one of requestData (producer validation) or responseData (consumer messages)";
+        }
+    }
+    return null;
+}
+function buildGenerateOptions(spec, shared) {
+    const protocol = spec.protocol ?? MockProtocol.Rest;
+    const language = shared.language ?? "python";
+    const framework = shared.framework ??
+        (language === "typescript" || language === "javascript"
+            ? "playwright"
+            : "");
+    const outputDir = spec.outputDir ?? shared.outputDir;
+    const common = {
+        protocol,
+        language,
+        framework,
+        outputDir,
+        output: spec.output,
+        force: true,
+        overwrite: true,
+        runtime: shared.runtime,
+        dockerNetwork: shared.dockerNetwork,
+        responseData: spec.responseData,
+        entrypoint: getEntryPoint(),
+    };
+    if (protocol === MockProtocol.Grpc) {
+        return {
+            ...common,
+            method: spec.method ?? "",
+            url: spec.endpointURL,
+            protoPath: spec.protoPath,
+            service: spec.grpcServiceName,
+            extraFiles: spec.protobufExtraFiles ?? [],
+            extraImports: spec.protobufExtraImportPath ?? [],
+        };
+    }
+    if (protocol === MockProtocol.Kafka) {
+        return {
+            ...common,
+            url: spec.endpointURL,
+            topic: spec.kafkaTopic,
+            requestData: spec.requestData?.trim() ? spec.requestData : undefined,
+        };
+    }
+    // REST
+    return {
+        ...common,
+        method: normalizeRestMockMethod(spec.method),
+        uri: spec.endpointURL,
+        apiSchema: spec.apiSchema ? [spec.apiSchema] : [],
+        requestData: spec.requestData ?? "",
+        responseStatusCode: spec.responseStatusCode ?? "",
+        requestAware: spec.requestAware ?? false,
+        mockPort: 0,
+        optionalFields: false,
+    };
+}
+export async function executeBatchMockGeneration(params) {
+    const { mocks, outputDir } = params;
+    fs.mkdirSync(outputDir, { recursive: true });
+    const client = new SkyrampClient();
+    const results = [];
+    for (let i = 0; i < mocks.length; i++) {
+        const spec = mocks[i];
+        const protocol = spec.protocol ?? MockProtocol.Rest;
+        const method = spec.method ?? "";
+        // Validate spec
+        const validationError = validateMockSpec(spec);
+        if (validationError) {
+            results.push({
+                index: i,
+                protocol,
+                endpointURL: spec.endpointURL,
+                method,
+                topic: spec.kafkaTopic,
+                success: false,
+                error: validationError,
+            });
+            continue;
+        }
+        const dockerLocalDev = params.runtime === "docker" || Boolean(params.dockerNetwork?.trim());
+        const compatibility = validateMockCompatibility([{ ...spec, protocol }], {
+            dockerLocalDev,
+        });
+        const blockingWarnings = compatibility.warnings.filter((warning) => warning.blocking);
+        if (blockingWarnings.length > 0) {
+            results.push({
+                index: i,
+                protocol,
+                endpointURL: spec.endpointURL,
+                method,
+                topic: spec.kafkaTopic,
+                success: false,
+                error: blockingWarnings
+                    .map((warning) => `${warning.code}: ${warning.message} Suggestion: ${warning.suggestion}`)
+                    .join("\n"),
+            });
+            continue;
+        }
+        const resolvedOutputDir = spec.outputDir ?? outputDir;
+        fs.mkdirSync(resolvedOutputDir, { recursive: true });
+        // Build options and generate
+        const options = buildGenerateOptions(spec, {
+            outputDir,
+            runtime: params.runtime,
+            dockerNetwork: params.dockerNetwork,
+            language: params.language,
+            framework: params.framework,
+        });
+        try {
+            let result;
+            if (protocol === MockProtocol.Grpc) {
+                result = await client.generateGrpcMock(options);
+            }
+            else if (protocol === MockProtocol.Kafka) {
+                result = await client.generateKafkaMock(options);
+            }
+            else {
+                result = await client.generateRestMock(options);
+            }
+            if (!result || !result.toLowerCase().includes("success")) {
+                results.push({
+                    index: i,
+                    protocol,
+                    endpointURL: spec.endpointURL,
+                    method,
+                    topic: spec.kafkaTopic,
+                    success: false,
+                    error: `Mock generation failed: ${result || "no output from backend"}`,
+                });
+                continue;
+            }
+            results.push({
+                index: i,
+                protocol,
+                endpointURL: spec.endpointURL,
+                method,
+                topic: spec.kafkaTopic,
+                success: true,
+                outputDir: resolvedOutputDir,
+                output: spec.output,
+                detail: result,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error("Batch mock generation failed for spec", {
+                index: i,
+                protocol,
+                endpointURL: spec.endpointURL,
+                error: errorMessage,
+            });
+            results.push({
+                index: i,
+                protocol,
+                endpointURL: spec.endpointURL,
+                method,
+                topic: spec.kafkaTopic,
+                success: false,
+                error: errorMessage,
+            });
+        }
+    }
+    const succeeded = results.filter((r) => r.success);
+    const failed = results.filter((r) => !r.success);
+    const summaryLines = [
+        `## Batch Mock Generation Summary`,
+        ``,
+        `- **Total:** ${mocks.length}`,
+        `- **Succeeded:** ${succeeded.length}`,
+        `- **Failed:** ${failed.length}`,
+        `- **Default Output Directory:** ${outputDir}`,
+        ``,
+    ];
+    if (succeeded.length > 0) {
+        summaryLines.push(`### Successful Mocks`);
+        for (const r of succeeded) {
+            summaryLines.push(`- [${r.index}] ${r.protocol.toUpperCase()} ${r.endpointURL} ${r.method || (r.protocol === MockProtocol.Kafka ? `topic:${r.topic ?? "?"}` : "(all methods)")}${r.output ? ` -> ${r.outputDir ?? outputDir}/${r.output}` : ""}`);
+        }
+        summaryLines.push(``);
+    }
+    if (failed.length > 0) {
+        summaryLines.push(`### Failed Mocks`);
+        for (const r of failed) {
+            summaryLines.push(`- [${r.index}] ${r.protocol.toUpperCase()} ${r.endpointURL} ${r.method || (r.protocol === MockProtocol.Kafka ? `topic:${r.topic ?? "?"}` : "(all methods)")}: ${r.error}`);
+        }
+        summaryLines.push(``);
+    }
+    return {
+        content: [{ type: "text", text: summaryLines.join("\n") }],
+        isError: failed.length > 0,
+    };
+}
+const TOOL_NAME = "skyramp_batch_mock_generation";
+const batchMockSchema = {
+    mocks: z
+        .array(mockSpecSchema)
+        .min(1)
+        .describe("Array of mock specifications. Each element describes one mock to generate."),
+    outputDir: z
+        .string()
+        .describe("Directory where generated mock files will be written."),
+    runtime: z
+        .string()
+        .default("local")
+        .describe("Runtime environment: 'local', 'docker', or 'kubernetes'."),
+    dockerNetwork: z
+        .string()
+        .default("")
+        .describe("Docker network name for containerized testing."),
+    language: z
+        .string()
+        .default("python")
+        .describe("Programming language for generated mocks (python, typescript, javascript, java)."),
+    framework: z
+        .string()
+        .default("")
+        .describe("Testing framework (e.g., pytest, playwright)."),
+};
+export function registerBatchMockTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: `Generate multiple mock server implementations in a single call using Skyramp.
+
+This tool accepts an array of mock specifications and generates all mocks in one operation,
+avoiding the need for N separate tool calls when mocking multiple downstream services.
+
+Each mock spec can target REST, gRPC, or Kafka protocols. Partial failures are handled
+gracefully — if some mocks fail, the others still succeed and are reported.
+
+Use this tool when you need to mock 2+ downstream services simultaneously (e.g., for a
+local-dev workflow with multiple dependencies).
+
+${BATCH_MOCK_PROTOCOL_EXAMPLES}`,
+        inputSchema: batchMockSchema,
+    }, async (params) => {
+        const result = await executeBatchMockGeneration(params);
+        AnalyticsService.pushTestGenerationToolEvent(TOOL_NAME, result, params).catch(() => {
+            // Silently ignore analytics errors
+        });
+        return result;
+    });
+}