@skyramp/mcp 0.2.8 → 0.2.150-rc.local.de

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

@@ -1,18 +1,93 @@
 import { z } from "zod";
-import { baseSchema, HttpMethod, TestType } from "../../types/TestTypes.js";
+import { baseSchema, MockProtocol, MOCK_TYPE } from "../../types/TestTypes.js";
+export { MockProtocol } from "../../types/TestTypes.js";
 import { TestGenerationService } from "../../services/TestGenerationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getEntryPoint } from "../../utils/telemetry.js";
+import { getRestMockMethodValidationError, normalizeRestMockMethod, } from "../../utils/httpMethodValidation.js";
+import { getGrpcMockResponseValidationError } from "../../utils/grpcMockValidation.js";
+import { isLocalDevEnabled } from "../../utils/featureFlags.js";
+export const MOCK_PROTOCOL_EXAMPLES = `
+<example protocol="rest">
+Generate a REST mock for one HTTP endpoint. Required fields: protocol="rest", endpointURL, method. Use apiSchema with an empty method only when intentionally generating all schema methods.
+{
+  "protocol": "rest",
+  "endpointURL": "http://payment-service:5001/orders/:order_id/payment_authorizations",
+  "method": "PUT",
+  "requestAware": true,
+  "requestData": "{\"payment_method_id\":\"pm_123\"}",
+  "responseData": "{\"accepted\":true}",
+  "responseStatusCode": "200"
+}
+</example>
+
+<example protocol="grpc">
+Generate a gRPC mock. Required fields: protocol="grpc", endpointURL as host:port, protoPath, grpcServiceName. method is the RPC method name; omit or leave empty to generate all service methods. responseData must be a successful protobuf-shaped response, not a gRPC status error.
+{
+  "protocol": "grpc",
+  "endpointURL": "profile-service:50051",
+  "protoPath": "/repo/proto/profiles.proto",
+  "grpcServiceName": "ProfileService",
+  "method": "GetProfile",
+  "responseData": "{\"eligible\":true}"
+}
+</example>
+
+<example protocol="kafka-producer">
+Generate a Kafka producer validation mock. Required fields: protocol="kafka", endpointURL as broker host:port, kafkaTopic, and requestData. Do not pass method or responseData.
+{
+  "protocol": "kafka",
+  "endpointURL": "broker:9092",
+  "kafkaTopic": "events",
+  "requestData": "{\"name\":\"order.created\"}"
+}
+</example>
+
+<example protocol="kafka-consumer">
+Generate a Kafka consumer message mock. Required fields: protocol="kafka", endpointURL as broker host:port, kafkaTopic, and responseData. Do not pass method or requestData.
+{
+  "protocol": "kafka",
+  "endpointURL": "broker:9092",
+  "kafkaTopic": "events",
+  "responseData": "{\"accepted\":true}"
+}
+</example>`;
 const mockSchema = {
+    protocol: z
+        .nativeEnum(MockProtocol)
+        .default(MockProtocol.Rest)
+        .describe("Protocol for the mock to generate. Use 'rest' for HTTP/OpenAPI mocks, 'grpc' for protobuf/gRPC mocks, and 'kafka' for Kafka topic mocks. See <example> blocks in the tool description for protocol-specific required fields."),
     endpointURL: z
         .string()
-        .describe("The base URL or endpoint URL to generate a mock for. " +
-        "If only a base URL is provided (e.g., https://api.example.com) and an apiSchema is given, mocks will be generated for ALL endpoints and methods in the schema — do NOT append paths to the URL. " +
-        "Only include a specific path (e.g., https://api.example.com/api/v1/products) if the user explicitly requests mocking a single endpoint."),
+        .describe("For REST: the base URL or endpoint URL to generate a mock for. " +
+        "For gRPC: the target service address as host:port (for example, profile-service:50051); do not include http://. " +
+        "For Kafka: the broker address as host:port (for example, broker:9092); do not include http://. " +
+        "If only a base URL is provided (e.g., https://api.example.com) and an apiSchema is given, REST mocks will be generated for ALL endpoints and methods in the schema — do NOT append paths to the URL. " +
+        "Only include a specific path (e.g., https://api.example.com/api/v1/products) if the user explicitly requests mocking a single REST endpoint."),
+    protoPath: z
+        .string()
+        .optional()
+        .describe("Required for protocol='grpc'. Absolute or repo-relative path to the .proto file that defines the gRPC service."),
+    grpcServiceName: z
+        .string()
+        .optional()
+        .describe("Required for protocol='grpc'. gRPC service name from the proto file, e.g. Greeter or ProfileService."),
+    protobufExtraFiles: z
+        .array(z.string())
+        .optional()
+        .describe("Optional extra .proto files needed to compile the primary proto for gRPC mocks."),
+    protobufExtraImportPath: z
+        .array(z.string())
+        .optional()
+        .describe("Optional extra import directories used when compiling protobuf files for gRPC mocks."),
+    kafkaTopic: z
+        .string()
+        .optional()
+        .describe("Required for protocol='kafka'. Kafka topic name to mock, e.g. order.created or orders."),
     method: z
-        .union([z.nativeEnum(HttpMethod), z.literal("")])
+        .string()
         .default("")
-        .describe('HTTP method to mock. DEFAULT: Use empty string ("") to mock ALL available methods from the OpenAPI schema. Only specify a specific method (GET, POST, PUT, DELETE, etc.) if the user explicitly requests mocking a single method.'),
+        .describe('For REST: HTTP method to mock; required unless apiSchema is provided for schema-wide generation. Empty string ("") with apiSchema mocks ALL available schema methods. For gRPC: RPC method name to mock; empty string generates all service methods. For Kafka: MUST be empty; use kafkaTopic for the topic name.'),
     apiSchema: z
         .string()
         .default("")
@@ -20,16 +95,18 @@ const mockSchema = {
     responseData: z
         .string()
         .optional()
-        .describe("Sample response body data to use in the mock, provided either as an inline JSON/YAML string or as an absolute file path prefixed with '@' (e.g., @/absolute/path/to/file)."),
+        .describe("REST/gRPC: sample response body data to return. Kafka: consumer messages to inject. Provide inline JSON/YAML or an absolute file path prefixed with '@' (e.g., @/absolute/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" })
+        .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'). DO NOT ASSUME a status code if not provided."),
     requestData: z
         .string()
         .default("")
-        .describe("Sample request body data for request-aware mocks, provided either as an inline JSON/YAML string or as an absolute file path prefixed with '@' (e.g., @/absolute/path/to/file)."),
+        .describe("REST: request body sample for request-aware matching. Kafka: producer validation payload/schema. Provide inline JSON/YAML or an absolute file path prefixed with '@' (e.g., @/absolute/path/to/file)."),
     formParams: z
         .string()
         .default("")
@@ -42,17 +119,18 @@ const mockSchema = {
         .string()
         .optional()
         .describe("MUST be absolute path to a trace file (e.g., /path/to/trace.json) to generate the mock from captured traffic."),
-    ...(({ authHeader, insecure, ...rest }) => rest)(baseSchema.shape),
+    ...(({ authHeader: _authHeader, insecure: _insecure, ...rest }) => rest)(baseSchema.shape),
 };
 export class MockGenerationService extends TestGenerationService {
     getTestType() {
-        return TestType.MOCK;
+        return MOCK_TYPE;
     }
     async generateTest(params) {
         const result = await super.generateTest(params);
         if (result.isError)
             return result;
-        if (!params.apiSchema)
+        if (!params.apiSchema ||
+            (params.protocol ?? MockProtocol.Rest) !== MockProtocol.Rest)
             return result;
         return {
             ...result,
@@ -123,11 +201,68 @@ This file must:
 - Do NOT modify any mock logic, response data, or function signatures — only reorganize and add import/export wiring.
 `;
     }
-    buildGenerationOptions(params) {
+    validateInputs(params) {
+        const result = super.validateInputs(params);
+        const protocol = params.protocol ?? MockProtocol.Rest;
+        if (protocol === MockProtocol.Rest) {
+            const methodError = getRestMockMethodValidationError(params.method);
+            if (methodError) {
+                result.content.push({
+                    type: "text",
+                    text: `Error: ${methodError}.`,
+                });
+                result.isError = true;
+            }
+            if (!params.apiSchema && !params.method) {
+                result.content.push({
+                    type: "text",
+                    text: "Error: REST mock method is required unless apiSchema is provided for schema-wide generation.",
+                });
+                result.isError = true;
+            }
+            return result;
+        }
+        const missing = [];
+        if (protocol === MockProtocol.Grpc) {
+            if (!params.protoPath)
+                missing.push("protoPath is required for protocol='grpc'");
+            if (!params.grpcServiceName)
+                missing.push("grpcServiceName is required for protocol='grpc'");
+            const grpcResponseError = getGrpcMockResponseValidationError(params.responseData);
+            if (grpcResponseError)
+                missing.push(grpcResponseError);
+        }
+        if (protocol === MockProtocol.Kafka) {
+            if (!params.kafkaTopic) {
+                missing.push("kafkaTopic is required for protocol='kafka'");
+            }
+            if (params.method) {
+                missing.push("Kafka mock method must be empty; use kafkaTopic for the topic name. Produce validation uses requestData and consumer messages use responseData");
+            }
+            const hasRequestData = Boolean(params.requestData && params.requestData.trim());
+            const hasResponseData = Boolean(params.responseData && params.responseData.trim());
+            if (hasRequestData === hasResponseData) {
+                missing.push("Kafka mock requires exactly one of requestData (producer validation) or responseData (consumer messages)");
+            }
+        }
+        if (missing.length === 0) {
+            return result;
+        }
         return {
-            uri: params.endpointURL,
-            method: params.method,
-            apiSchema: params.apiSchema ? [params.apiSchema] : [],
+            content: [
+                ...result.content,
+                {
+                    type: "text",
+                    text: `Error: ${missing.join("; ")}.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    buildGenerationOptions(params) {
+        const protocol = params.protocol ?? MockProtocol.Rest;
+        const common = {
+            protocol,
             language: params.language ?? "python",
             framework: params.framework ??
                 (params.language === "typescript" || params.language === "javascript"
@@ -143,20 +278,51 @@ This file must:
             k8sNamespace: params.k8sNamespace,
             k8sConfig: params.k8sConfig,
             k8sContext: params.k8sContext,
-            requestData: params.requestData,
             responseData: params.responseData,
+            entrypoint: getEntryPoint(),
+        };
+        if (protocol === MockProtocol.Grpc) {
+            return {
+                ...common,
+                method: params.method,
+                url: params.endpointURL,
+                protoPath: params.protoPath,
+                service: params.grpcServiceName,
+                extraFiles: params.protobufExtraFiles ?? [],
+                extraImports: params.protobufExtraImportPath ?? [],
+            };
+        }
+        if (protocol === MockProtocol.Kafka) {
+            return {
+                ...common,
+                url: params.endpointURL,
+                topic: params.kafkaTopic,
+                requestData: params.requestData?.trim() ? params.requestData : undefined,
+            };
+        }
+        return {
+            ...common,
+            method: normalizeRestMockMethod(params.method),
+            uri: params.endpointURL,
+            apiSchema: params.apiSchema ? [params.apiSchema] : [],
+            requestData: params.requestData,
             responseStatusCode: params.responseStatusCode,
             formParams: params.formParams,
             requestAware: params.requestAware,
             traceFilePath: params.trace,
-            entrypoint: getEntryPoint(),
             mockPort: params.mockPort ?? 0,
             optionalFields: params.optionalFields ?? false,
         };
     }
     async executeGeneration(generateOptions) {
         try {
-            const result = await this.client.generateRestMock(generateOptions);
+            const protocol = generateOptions.protocol ?? MockProtocol.Rest;
+            const client = this.client;
+            const result = protocol === MockProtocol.Grpc
+                ? await client.generateGrpcMock(generateOptions)
+                : protocol === MockProtocol.Kafka
+                    ? await client.generateKafkaMock(generateOptions)
+                    : await client.generateRestMock(generateOptions);
             if (result && result.length > 0) {
                 const lowerResult = result.toLowerCase();
                 if (!lowerResult.includes("success")) {
@@ -177,12 +343,18 @@ ${result}`;
         }
     }
 }
+const LOCAL_DEV_GUARD = `
+**LOCAL-DEV GUARD:** If the user asked to run a local-dev workflow, test local changes, validate a feature branch, test against a base/prod/main branch, or mock downstream services for local testing, do NOT start with this tool. First call \`skyramp_one_click_tool\` with workflow \`local_dev_test_changes\`, \`callingAgent\` set to the current MCP client, \`repositoryPath\`, and \`baseBranch\`; that workflow installs skills, initializes the workspace, analyzes the diff, and then calls mock generation at the correct phase.
+`;
+function getLocalDevGuard() {
+    return isLocalDevEnabled() ? LOCAL_DEV_GUARD : "";
+}
 const TOOL_NAME = "skyramp_mock_generation";
 export function registerMockTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Generate a mock server implementation using Skyramp's deterministic mock generation platform.
+        description: `${getLocalDevGuard()}Generate a mock server implementation using Skyramp's deterministic mock generation platform.
 
-Mocks simulate API endpoints so that consumers can develop and test against them without requiring a live backend. They are useful for parallel development, isolating dependencies, and simulating edge-case responses.
+Mocks simulate REST, gRPC, or Kafka dependencies so that consumers can develop and test against them without requiring a live backend. They are useful for parallel development, isolating dependencies, and simulating edge-case responses.
 
 **IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. Simply pass the path/URL to the tool — the backend will handle reading and processing the schema file.**
 

package/build/tools/generate-tests/generateMockRestTool.test.d.ts

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

package/build/tools/generate-tests/generateMockRestTool.test.js

@@ -0,0 +1,340 @@
+import { jest, describe, it, expect } from "@jest/globals";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushTestGenerationToolEvent: jest.fn() },
+}));
+const { MockGenerationService, MockProtocol, MOCK_PROTOCOL_EXAMPLES } = await import("./generateMockRestTool.js");
+class TestableMockGenerationService extends MockGenerationService {
+    options(params) {
+        return this.buildGenerationOptions(params);
+    }
+    run(options) {
+        return this.executeGeneration(options);
+    }
+    validate(params) {
+        return this.validateInputs(params);
+    }
+    setMockClient(client) {
+        this.client = client;
+    }
+}
+describe("MockGenerationService", () => {
+    it("keeps REST generation as the default protocol", () => {
+        const service = new TestableMockGenerationService();
+        const options = service.options({
+            endpointURL: "http://ams:4000/api/v1/validate",
+            method: "POST",
+            apiSchema: "/repo/openapi.json",
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(options.protocol).toBe("rest");
+        expect(options.uri).toBe("http://ams:4000/api/v1/validate");
+        expect(options.apiSchema).toEqual(["/repo/openapi.json"]);
+        expect(options.method).toBe("POST");
+        expect(options).not.toHaveProperty("url");
+        expect(options).not.toHaveProperty("protoPath");
+    });
+    it("documents protocol-specific required fields with Claude-style example tags", () => {
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain('<example protocol="rest">');
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain('<example protocol="grpc">');
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain('<example protocol="kafka-producer">');
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain('<example protocol="kafka-consumer">');
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain('Required fields: protocol="rest", endpointURL, method');
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain("protoPath");
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain("grpcServiceName");
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain("kafkaTopic");
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain("Do not pass method");
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain("Kafka producer validation mock");
+        expect(MOCK_PROTOCOL_EXAMPLES).toContain("Kafka consumer message mock");
+    });
+    it("requires REST method unless apiSchema is provided for schema-wide generation", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Rest,
+            endpointURL: "http://ams:4000/api/v1/validate",
+            method: "",
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content.at(-1)).toEqual({
+            type: "text",
+            text: "Error: REST mock method is required unless apiSchema is provided for schema-wide generation.",
+        });
+    });
+    it("allows empty REST method when apiSchema is provided", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Rest,
+            endpointURL: "http://ams:4000",
+            method: "",
+            apiSchema: "/repo/openapi.json",
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(false);
+    });
+    it("rejects invalid REST HTTP methods before backend generation", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Rest,
+            endpointURL: "http://ams:4000/api/v1/validate",
+            method: "POTS",
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0]).toEqual({
+            type: "text",
+            text: 'Error: REST mock method must be one of GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS or empty string (got "POTS").',
+        });
+    });
+    it("rejects gRPC error-shaped responseData because it does not produce a gRPC status error", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Grpc,
+            endpointURL: "partner-accounts:50051",
+            method: "GetCustomerConfigurations",
+            protoPath: "/repo/proto/customer_configurations.proto",
+            grpcServiceName: "CustomerConfigurationsService",
+            responseData: JSON.stringify({
+                error: "UNAVAILABLE",
+                message: "deadline exceeded",
+            }),
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content.at(-1)).toEqual({
+            type: "text",
+            text: 'Error: gRPC mock responseData cannot simulate gRPC status errors such as "UNAVAILABLE". Generate a successful protobuf-shaped response, use a real failing service, or record this scenario as blocked.',
+        });
+    });
+    it("maps gRPC params to the SDK generateGrpcMock options", () => {
+        const service = new TestableMockGenerationService();
+        const options = service.options({
+            protocol: MockProtocol.Grpc,
+            endpointURL: "partner-accounts:50051",
+            method: "GetCustomerConfiguration",
+            protoPath: "/repo/proto/partner_accounts.proto",
+            grpcServiceName: "PartnerAccountsService",
+            protobufExtraFiles: ["/repo/proto/common.proto"],
+            protobufExtraImportPath: ["/repo/proto"],
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(options.protocol).toBe(MockProtocol.Grpc);
+        expect(options.url).toBe("partner-accounts:50051");
+        expect(options.protoPath).toBe("/repo/proto/partner_accounts.proto");
+        expect(options.service).toBe("PartnerAccountsService");
+        expect(options.method).toBe("GetCustomerConfiguration");
+        expect(options.extraFiles).toEqual(["/repo/proto/common.proto"]);
+        expect(options.extraImports).toEqual(["/repo/proto"]);
+        expect(options).not.toHaveProperty("uri");
+        expect(options).not.toHaveProperty("apiSchema");
+    });
+    it("normalizes padded lowercase REST HTTP methods before backend generation", () => {
+        const service = new TestableMockGenerationService();
+        const options = service.options({
+            endpointURL: "http://ams:4000/api/v1/validate",
+            method: " post\n",
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(options.method).toBe("POST");
+    });
+    it("maps Kafka params to the SDK generateKafkaMock options", () => {
+        const service = new TestableMockGenerationService();
+        const options = service.options({
+            protocol: MockProtocol.Kafka,
+            endpointURL: "redpanda:9092",
+            kafkaTopic: "account.created",
+            requestData: JSON.stringify({ id: "string" }),
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(options.protocol).toBe(MockProtocol.Kafka);
+        expect(options.url).toBe("redpanda:9092");
+        expect(options.topic).toBe("account.created");
+        expect(options.requestData).toBe(JSON.stringify({ id: "string" }));
+        expect(options.responseData).toBeUndefined();
+        expect(options).not.toHaveProperty("method");
+        expect(options).not.toHaveProperty("uri");
+        expect(options).not.toHaveProperty("apiSchema");
+    });
+    it("omits blank Kafka requestData for consumer mocks", () => {
+        const service = new TestableMockGenerationService();
+        const options = service.options({
+            protocol: MockProtocol.Kafka,
+            endpointURL: "redpanda:9092",
+            kafkaTopic: "account.created",
+            requestData: "",
+            responseData: JSON.stringify({ accepted: true }),
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(options.protocol).toBe(MockProtocol.Kafka);
+        expect(options.responseData).toBe(JSON.stringify({ accepted: true }));
+        expect(options.requestData).toBeUndefined();
+    });
+    it("dispatches gRPC generation to generateGrpcMock", async () => {
+        const service = new TestableMockGenerationService();
+        const client = {
+            generateGrpcMock: jest
+                .fn()
+                .mockResolvedValue("success: grpc mock generated"),
+            generateRestMock: jest.fn(),
+        };
+        service.setMockClient(client);
+        const result = await service.run({
+            protocol: MockProtocol.Grpc,
+            outputDir: "/repo/tests/skyramp/mocks",
+            language: "python",
+            framework: "pytest",
+        });
+        expect(client.generateGrpcMock).toHaveBeenCalledTimes(1);
+        expect(client.generateRestMock).not.toHaveBeenCalled();
+        expect(result).toContain("success: grpc mock generated");
+    });
+    it("dispatches Kafka generation to generateKafkaMock", async () => {
+        const service = new TestableMockGenerationService();
+        const client = {
+            generateKafkaMock: jest
+                .fn()
+                .mockResolvedValue("success: kafka mock generated"),
+            generateGrpcMock: jest.fn(),
+            generateRestMock: jest.fn(),
+        };
+        service.setMockClient(client);
+        const result = await service.run({
+            protocol: MockProtocol.Kafka,
+            outputDir: "/repo/tests/skyramp/mocks",
+            language: "python",
+            framework: "pytest",
+        });
+        expect(client.generateKafkaMock).toHaveBeenCalledTimes(1);
+        expect(client.generateGrpcMock).not.toHaveBeenCalled();
+        expect(client.generateRestMock).not.toHaveBeenCalled();
+        expect(result).toContain("success: kafka mock generated");
+    });
+    it("rejects Kafka method because kafkaTopic carries the topic and produce/consume are inferred", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Kafka,
+            endpointURL: "redpanda:9092",
+            kafkaTopic: "events",
+            method: "produce",
+            requestData: JSON.stringify({ type: "account.created" }),
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content.at(-1)).toEqual({
+            type: "text",
+            text: "Error: Kafka mock method must be empty; use kafkaTopic for the topic name. Produce validation uses requestData and consumer messages use responseData.",
+        });
+    });
+    it("rejects Kafka mocks with both requestData and responseData", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Kafka,
+            endpointURL: "redpanda:9092",
+            kafkaTopic: "events",
+            requestData: JSON.stringify({ type: "account.created" }),
+            responseData: JSON.stringify({ accepted: true }),
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content.at(-1)).toEqual({
+            type: "text",
+            text: "Error: Kafka mock requires exactly one of requestData (producer validation) or responseData (consumer messages).",
+        });
+    });
+    it("rejects Kafka mocks with neither requestData nor responseData", () => {
+        const service = new TestableMockGenerationService();
+        const result = service.validate({
+            protocol: MockProtocol.Kafka,
+            endpointURL: "redpanda:9092",
+            kafkaTopic: "events",
+            language: "python",
+            outputDir: "/repo/tests/skyramp/mocks",
+            force: true,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content.at(-1)).toEqual({
+            type: "text",
+            text: "Error: Kafka mock requires exactly one of requestData (producer validation) or responseData (consumer messages).",
+        });
+    });
+    it("requires kafkaTopic for Kafka mocks", async () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-mock-gen-"));
+        try {
+            const service = new TestableMockGenerationService();
+            const client = {
+                generateKafkaMock: jest.fn(),
+                generateGrpcMock: jest.fn(),
+                generateRestMock: jest.fn(),
+            };
+            service.setMockClient(client);
+            const result = await service.generateTest({
+                protocol: MockProtocol.Kafka,
+                endpointURL: "redpanda:9092",
+                language: "python",
+                outputDir: tempDir,
+                force: true,
+            });
+            expect(result.isError).toBe(true);
+            const message = result.content[0].type === "text" ? result.content[0].text : "";
+            expect(message).toContain("kafkaTopic is required");
+            expect(client.generateKafkaMock).not.toHaveBeenCalled();
+            expect(client.generateGrpcMock).not.toHaveBeenCalled();
+            expect(client.generateRestMock).not.toHaveBeenCalled();
+        }
+        finally {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+    it("requires protoPath and grpcServiceName for gRPC mocks", async () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-mock-gen-"));
+        try {
+            const service = new TestableMockGenerationService();
+            const client = {
+                generateGrpcMock: jest.fn(),
+                generateRestMock: jest.fn(),
+            };
+            service.setMockClient(client);
+            const result = await service.generateTest({
+                protocol: MockProtocol.Grpc,
+                endpointURL: "partner-accounts:50051",
+                method: "GetCustomerConfiguration",
+                language: "python",
+                outputDir: tempDir,
+                force: true,
+            });
+            expect(result.isError).toBe(true);
+            const message = result.content[0].type === "text" ? result.content[0].text : "";
+            expect(message).toContain("protoPath is required");
+            expect(message).toContain("grpcServiceName is required");
+            expect(client.generateGrpcMock).not.toHaveBeenCalled();
+            expect(client.generateRestMock).not.toHaveBeenCalled();
+        }
+        finally {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+});

package/build/tools/generateEnrichedIntegrationTestTool.d.ts

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * skyramp_generate_enriched_integration_test
+ *
+ * Combines integration test generation (from a scenario file) and mock enrichment
+ * into a single atomic operation. Eliminates the need to call
+ * skyramp_integration_test_generation and skyramp_enrich_test_with_mocks separately.
+ */
+export declare function registerGenerateEnrichedIntegrationTestTool(server: McpServer): void;
+export declare function executeGenerateEnrichedIntegrationTest(params: {
+    scenarioFile: string;
+    mockFiles: string[];
+    scenarioName: string;
+    outputDir: string;
+    output?: string;
+    runtime?: string;
+    dockerNetwork?: string;
+    authHeader?: string;
+    authScheme?: string;
+    language?: string;
+    framework?: string;
+    traceComments?: string[];
+}): Promise<CallToolResult>;