@skyramp/mcp 0.3.0 → 0.3.1-ldw-beta

package/build/tools/one-click/oneClickTool.js

@@ -1,8 +1,16 @@
 import { z } from "zod";
-import { lookupCommand, getAllCommands } from "../../commands/commandLibrary.js";
+import fs from "fs/promises";
+import path from "path";
+import { LOCAL_DEV_SKILL_CONTENT } from "../../commands/localDevTestChangesCommand.js";
+import { lookupCommand, getAllCommands, } from "../../commands/commandLibrary.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_one_click_tool";
+export var CallingAgentIde;
+(function (CallingAgentIde) {
+    CallingAgentIde["Cursor"] = "cursor";
+    CallingAgentIde["Claude"] = "claude";
+})(CallingAgentIde || (CallingAgentIde = {}));
 /**
  * Generates the `workflow` parameter description from the live command library.
  * The LLM reads this when filling the tool call, matches the user's intent against
@@ -10,6 +18,92 @@ const TOOL_NAME = "skyramp_one_click_tool";
  * matching workflow ID. No hardcoded enum — adding a new workflow to the library
  * automatically updates this description.
  */
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertRepositoryPathIsSafe(repositoryPath) {
+    const stat = await fs.stat(repositoryPath).catch(() => undefined);
+    if (!stat?.isDirectory()) {
+        throw new Error(`repositoryPath must be an existing directory: ${repositoryPath}`);
+    }
+    if (!(await pathExists(path.join(repositoryPath, ".git")))) {
+        throw new Error(`repositoryPath must point to a git repository: ${repositoryPath}`);
+    }
+}
+function normalizeCallingAgentIde(callingAgent) {
+    switch (callingAgent?.trim().toLowerCase()) {
+        case CallingAgentIde.Cursor:
+            return CallingAgentIde.Cursor;
+        case CallingAgentIde.Claude:
+            return CallingAgentIde.Claude;
+        default:
+            return undefined;
+    }
+}
+function resolveLocalDevSkillTarget(repositoryPath, callingAgent) {
+    switch (callingAgent) {
+        case CallingAgentIde.Cursor:
+            return {
+                agent: CallingAgentIde.Cursor,
+                skillPath: path.join(repositoryPath, ".cursor", "skills", "local-dev", "SKILL.md"),
+            };
+        case CallingAgentIde.Claude:
+            return {
+                agent: CallingAgentIde.Claude,
+                skillPath: path.join(repositoryPath, ".claude", "skills", "local-dev", "SKILL.md"),
+            };
+        default:
+            return undefined;
+    }
+}
+async function ensureLocalDevSkillFile(repositoryPath, callingAgent) {
+    await assertRepositoryPathIsSafe(repositoryPath);
+    const target = resolveLocalDevSkillTarget(repositoryPath, callingAgent);
+    if (!target)
+        return {};
+    if (await pathExists(target.skillPath))
+        return { target };
+    await fs.mkdir(path.dirname(target.skillPath), { recursive: true });
+    await fs.writeFile(target.skillPath, LOCAL_DEV_SKILL_CONTENT, "utf8");
+    return { target, installed: target.skillPath };
+}
+async function buildLocalDevBootstrapStatus(params) {
+    if (params.workflow !== "local_dev_test_changes")
+        return "";
+    const skillResult = await ensureLocalDevSkillFile(params.repositoryPath, params.callingAgent);
+    const workspacePath = path.join(params.repositoryPath, ".skyramp", "workspace.yml");
+    const workspaceExists = await pathExists(workspacePath);
+    const hasUnsupportedCallingAgent = params.rawCallingAgent !== undefined && params.callingAgent === undefined;
+    const skillStatus = skillResult.installed
+        ? `Installed local-dev skill file for ${skillResult.target?.agent}:
+- ${skillResult.installed}`
+        : skillResult.target
+            ? `Local-dev skill file already installed for ${skillResult.target.agent}: ${skillResult.target.skillPath}`
+            : hasUnsupportedCallingAgent
+                ? "Local-dev skill file not installed: this agent does not support repo-local skills, so skill creation was skipped."
+                : "Local-dev skill file not installed: pass `callingAgent` as `cursor` or `claude` to install a repo-local skill. Agents without repo-local skill support can ignore this step.";
+    return `
+## Bootstrap Status
+
+${skillStatus}
+
+Base branch: ${params.baseBranch ?? "main"}
+skyramp_local_dev baseCommit: ${params.baseBranch ?? "main"}
+Services to mock: ${params.servicesToMock ?? "not specified"}
+Real services: ${params.realServices ?? "not specified"}
+Mock protocols: ${params.mockProtocols ?? "not specified"}
+Calling agent: ${params.rawCallingAgent ?? params.callingAgent ?? "not specified"}
+
+Workspace config: ${workspaceExists ? `found at ${workspacePath}` : `missing at ${workspacePath}`}
+
+`;
+}
 function buildWorkflowParamDescription() {
     const commands = getAllCommands();
     const sections = commands.map((cmd) => {
@@ -29,7 +123,31 @@ function buildWorkflowParamDescription() {
     return (`The workflow to execute. Match the user's intent against the available workflows below and pass the matching workflow ID.\n\n` +
         `Available workflows:\n${sections.join("\n\n")}`);
 }
-const oneClickSchema = z.object({
+function isLocalDevWorkflowAvailable() {
+    return getAllCommands().some((cmd) => cmd.id === "local_dev_test_changes");
+}
+function buildToolDescription() {
+    const localDevInstructions = isLocalDevWorkflowAvailable()
+        ? `- When the user asks to run Skyramp local-dev, test local changes, validate a feature branch, test a branch against a base/prod/main branch, or mock downstream services for local testing: MUST call this tool with workflow \`local_dev_test_changes\`, \`callingAgent\` set to the current MCP client (\`cursor\` or \`claude\` for skill installation; VS Code does not support repo-local Agent Skills), \`repositoryPath\`, and \`baseBranch\`. Do NOT self-orchestrate — call this tool first and follow the returned instructions.\n`
+        : "";
+    return `Execute predefined, multi-step testing workflows with a single tool call.
+
+**Purpose**: The One-Click Commands tool provides a mechanism to define and execute complex, multi-step testing workflows by orchestrating multiple MCP tools in sequence. Commands enable users to accomplish high-level testing goals (e.g., "comprehensively test this endpoint") through a single invocation, without requiring new MCP tool implementations for each workflow.
+
+**When to use**:
+${localDevInstructions}- When the user names a specific endpoint and explicitly asks for comprehensive, thorough, or deep testing (e.g. "comprehensively test this endpoint", "thoroughly test the products endpoint"): MUST call this tool with workflow \`test_given_endpoint_comprehensively\`. Do NOT self-orchestrate — call this tool first and follow the returned instructions.
+- When the user wants to scan the entire repo (no specific endpoint, no PR diff) to get ranked recommendations, generate top N types, and execute: MUST call this tool with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
+- Do NOT invoke these workflows for simple single-tool requests such as "generate a smoke test" or "run this test" — call the relevant tool directly instead.
+
+**How it works**: Pass the \`workflow\` ID that matches the user's intent (see the \`workflow\` parameter description for available workflows and their trigger phrases). The tool returns a **workflow specification** (step-by-step instructions). You must then **execute that workflow** by calling the listed MCP tools in order, passing outputs (e.g. state file paths) from one step as inputs to the next. The tool does not execute other tools itself; it provides the declarative workflow for you to run.
+
+**Design**:
+- **MCP-only**: Workflows orchestrate only MCP tools; no CLI execution.
+- **Declarative**: Workflows are sequences of tool calls with dependencies.
+- **State-efficient**: State files are created only by recommendation/map tools (in system temp, e.g. /tmp); do not create any state files in the user repository.
+- **Composable**: Complex workflows are built from existing Skyramp tools.`;
+}
+const baseOneClickSchema = z.object({
     workflow: z.string().describe(buildWorkflowParamDescription()),
     repositoryPath: z
         .string()
@@ -51,10 +169,64 @@ const oneClickSchema = z.object({
         .optional()
         .describe("Authentication/session token for test execution. Always pass this to skyramp_execute_test to avoid auth errors; use empty string '' if no auth required."),
 });
+function buildOneClickSchema() {
+    if (!isLocalDevWorkflowAvailable()) {
+        return baseOneClickSchema;
+    }
+    return baseOneClickSchema.extend({
+        baseBranch: z
+            .string()
+            .optional()
+            .default("main")
+            .describe("Base branch, commit SHA, or tag to diff against. Used by local_dev_test_changes workflow. Default: 'main'. If the user names a branch such as 'prod branch', pass that exact branch only when it exists or ask for clarification; do not silently substitute main."),
+        servicesToMock: z
+            .string()
+            .optional()
+            .describe("Comma-separated downstream service names the user explicitly wants mocked in the local_dev_test_changes workflow. When the user says 'mock all', 'mock everything', 'mock all downstream', or 'mock all except X', pass the sentinel value \"all\" (not an empty string and not omitted). Omit only when the user did not express any intent to mock services."),
+        realServices: z
+            .string()
+            .optional()
+            .describe("Comma-separated service names that should receive real traffic in the local_dev_test_changes workflow, such as infrastructure, the service under test, or first-party local dependencies."),
+        mockProtocols: z
+            .string()
+            .optional()
+            .describe("Comma-separated protocols the user explicitly wants mocked in local_dev_test_changes, such as 'rest', 'grpc', or 'kafka'. Omit to use the workflow default of mocking only true third-party downstream services."),
+        proxyUrl: z
+            .string()
+            .optional()
+            .describe("Direct URL (host:port or full URL, including an ingress route) of a Skyramp worker running as a proxy. When provided, local_dev_test_changes queries it via skyramp_query_proxy_mocks for real recorded downstream traffic. Mutually exclusive with proxyKubeconfig/proxyNamespace."),
+        proxyKubeconfig: z
+            .string()
+            .optional()
+            .describe("Absolute path to a kubeconfig for reaching a Skyramp worker proxy in-cluster (used with proxyNamespace). Mutually exclusive with proxyUrl."),
+        proxyNamespace: z
+            .string()
+            .optional()
+            .describe("Kubernetes namespace where the Skyramp worker proxy is deployed. Required together with proxyKubeconfig."),
+        callingAgent: z
+            .string()
+            .optional()
+            .describe("Calling MCP client for local_dev_test_changes. Pass 'cursor' or 'claude' to install only that agent's local-dev skill file under .cursor or .claude. Pass 'vscode' if calling from VS Code; skill creation will be skipped."),
+    });
+}
+function renderStepGuidance(step, cmd, params) {
+    let guidance = step.conditionalGuidance ?? "";
+    if (!guidance || cmd.id !== "local_dev_test_changes")
+        return guidance;
+    const baseCommit = params.baseBranch ?? "main";
+    guidance = guidance
+        .replaceAll("<BASE_BRANCH from one-click baseBranch, default main>", baseCommit)
+        .replaceAll("<BASE_BRANCH>", baseCommit)
+        .replaceAll("<servicesToMock from one-click params, if provided; use all when the user requested mock all>", params.servicesToMock ?? "not specified")
+        .replaceAll("<realServices from one-click params, if provided>", params.realServices ?? "not specified")
+        .replaceAll("<mockProtocols from one-click params, if provided>", params.mockProtocols ?? "not specified");
+    return guidance;
+}
 /**
  * Build workflow instruction text from any command definition and params.
+ * Optional `stepsPreamble` is inserted between the intro header and Step 0.
  */
-function buildWorkflowFromCommand(cmd, params) {
+function buildWorkflowFromCommand(cmd, params, stepsPreamble = "") {
     const getParamDisplay = (key) => {
         const v = params[key];
         if (v === undefined || v === null)
@@ -90,8 +262,9 @@ function buildWorkflowFromCommand(cmd, params) {
                 block += `\n\nCapture for later steps: ${tc.outputs.join(", ")}.`;
             }
         }
-        if (step.conditionalGuidance) {
-            block += `\n\n**Note**: ${step.conditionalGuidance}`;
+        const conditionalGuidance = renderStepGuidance(step, cmd, params);
+        if (conditionalGuidance) {
+            block += `\n\n**Note**: ${conditionalGuidance}`;
         }
         stepLines.push(block);
     }
@@ -108,6 +281,7 @@ Execute the following steps in order. Pass outputs (e.g. state file path) from o
 
 `;
     return (intro +
+        stepsPreamble +
         stepLines.join("\n\n---\n\n") +
         `
 
@@ -122,23 +296,9 @@ Execute the following steps in order. Pass outputs (e.g. state file path) from o
 `);
 }
 export function registerOneClickTool(server) {
+    const oneClickSchema = buildOneClickSchema();
     server.registerTool(TOOL_NAME, {
-        description: `Execute predefined, multi-step testing workflows with a single tool call.
-
-**Purpose**: The One-Click Commands tool provides a mechanism to define and execute complex, multi-step testing workflows by orchestrating multiple MCP tools in sequence. Commands enable users to accomplish high-level testing goals (e.g., "comprehensively test this endpoint") through a single invocation, without requiring new MCP tool implementations for each workflow.
-
-**When to use**:
-- When the user names a specific endpoint and explicitly asks for comprehensive, thorough, or deep testing (e.g. "comprehensively test this endpoint", "thoroughly test the products endpoint"): MUST call this tool with workflow \`test_given_endpoint_comprehensively\`. Do NOT self-orchestrate — call this tool first and follow the returned instructions.
-- When the user wants to scan the entire repo (no specific endpoint, no PR diff) to get ranked recommendations, generate top N types, and execute: MUST call this tool with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
-- Do NOT invoke these workflows for simple single-tool requests such as "generate a smoke test" or "run this test" — call the relevant tool directly instead.
-
-**How it works**: Pass the \`workflow\` ID that matches the user's intent (see the \`workflow\` parameter description for available workflows and their trigger phrases). The tool returns a **workflow specification** (step-by-step instructions). You must then **execute that workflow** by calling the listed MCP tools in order, passing outputs (e.g. state file paths) from one step as inputs to the next. The tool does not execute other tools itself; it provides the declarative workflow for you to run.
-
-**Design**:
-- **MCP-only**: Workflows orchestrate only MCP tools; no CLI execution.
-- **Declarative**: Workflows are sequences of tool calls with dependencies.
-- **State-efficient**: State files are created only by recommendation/map tools (in system temp, e.g. /tmp); do not create any state files in the user repository.
-- **Composable**: Complex workflows are built from existing Skyramp tools.`,
+        description: buildToolDescription(),
         inputSchema: oneClickSchema.shape,
     }, async (params) => {
         let errorResult;
@@ -148,6 +308,7 @@ export function registerOneClickTool(server) {
                 repositoryPath: params.repositoryPath,
             });
             const cmd = lookupCommand(params.workflow);
+            const normalizedCallingAgent = normalizeCallingAgentIde(params.callingAgent);
             const oneClickParams = {
                 workflow: params.workflow,
                 repositoryPath: params.repositoryPath,
@@ -155,8 +316,18 @@ export function registerOneClickTool(server) {
                 apiSchema: params.apiSchema,
                 topN: params.topN ?? 3,
                 token: params.token ?? "",
+                baseBranch: params.baseBranch,
+                servicesToMock: params.servicesToMock,
+                realServices: params.realServices,
+                mockProtocols: params.mockProtocols,
+                proxyUrl: params.proxyUrl,
+                proxyKubeconfig: params.proxyKubeconfig,
+                proxyNamespace: params.proxyNamespace,
+                callingAgent: normalizedCallingAgent,
+                rawCallingAgent: params.callingAgent,
             };
-            const workflowText = buildWorkflowFromCommand(cmd, oneClickParams);
+            const bootstrapStatus = await buildLocalDevBootstrapStatus(oneClickParams);
+            const workflowText = buildWorkflowFromCommand(cmd, oneClickParams, bootstrapStatus);
             return {
                 content: [
                     {
@@ -182,9 +353,9 @@ export function registerOneClickTool(server) {
             return errorResult;
         }
         finally {
-            AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
+            void Promise.resolve(AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 workflow: params.workflow,
-            }).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
+            })).catch((err) => { logger.warning("Analytics event failed", { error: String(err) }); });
         }
     });
 }

package/build/tools/one-click/oneClickTool.test.d.ts

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

package/build/tools/one-click/oneClickTool.test.js

@@ -0,0 +1,172 @@
+import { jest, describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+jest.unstable_mockModule("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+}));
+const { registerOneClickTool } = await import("./oneClickTool.js");
+function registerToolForTest() {
+    let registered;
+    const server = {
+        registerTool: jest.fn((name, config, handler) => {
+            registered = { name, config, handler };
+        }),
+    };
+    registerOneClickTool(server);
+    if (!registered)
+        throw new Error("tool was not registered");
+    return registered;
+}
+describe("skyramp_one_click_tool", () => {
+    let tmpDir;
+    let originalLocalDevEnv;
+    beforeEach(() => {
+        originalLocalDevEnv = process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+        process.env.SKYRAMP_FEATURE_LOCAL_DEV = "1";
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-one-click-"));
+        execFileSync("git", ["init"], { cwd: tmpDir, stdio: "ignore" });
+    });
+    afterEach(() => {
+        if (originalLocalDevEnv === undefined) {
+            delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+        }
+        else {
+            process.env.SKYRAMP_FEATURE_LOCAL_DEV = originalLocalDevEnv;
+        }
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("routes local-dev requests and installs local-dev skill files", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "cursor",
+            baseBranch: "checkr-prod-flow",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain('skyramp_local_dev baseCommit: checkr-prod-flow');
+        const cursorSkill = fs.readFileSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"), "utf-8");
+        expect(cursorSkill).toContain("mock only true third-party downstream services");
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("installs only the Claude local-dev skill file", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "claude",
+        });
+        expect(result.isError).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("skips skill creation for agents without repo-local skill support", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "vscode",
+        });
+        expect(result.isError).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("does not install a skill file without a recognized calling agent", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "unknown",
+        });
+        expect(result.isError).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+    it("surfaces local-dev mock routing parameters in workflow text", async () => {
+        const tool = registerToolForTest();
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+            callingAgent: "cursor",
+            baseBranch: "checkr-prod-flow",
+            servicesToMock: "stripe",
+            realServices: "partner-accounts,redpanda",
+            mockProtocols: "rest",
+        });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(false);
+        expect(text).toContain("Services to mock: stripe");
+        expect(text).toContain("Real services: partner-accounts,redpanda");
+        expect(text).toContain("Mock protocols: rest");
+        expect(text).toContain("<SERVICE_ROUTING>");
+        expect(text).toContain("<MOCK_SERVICES>stripe</MOCK_SERVICES>");
+        expect(text).toContain("<REAL_SERVICES>partner-accounts,redpanda</REAL_SERVICES>");
+        expect(text).toContain("<MOCK_PROTOCOLS>rest</MOCK_PROTOCOLS>");
+    });
+    it("does not install local-dev skill files outside an existing git repository", async () => {
+        const tool = registerToolForTest();
+        const nonRepo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-one-click-nonrepo-"));
+        try {
+            const result = await tool.handler({
+                workflow: "local_dev_test_changes",
+                repositoryPath: nonRepo,
+                callingAgent: "cursor",
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("repositoryPath must point to a git repository");
+            expect(fs.existsSync(path.join(nonRepo, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(nonRepo, { recursive: true, force: true });
+        }
+    });
+    it("validates repositoryPath even when skill creation is skipped", async () => {
+        const tool = registerToolForTest();
+        const nonRepo = fs.mkdtempSync(path.join(os.tmpdir(), "skyramp-one-click-nonrepo-"));
+        try {
+            const result = await tool.handler({
+                workflow: "local_dev_test_changes",
+                repositoryPath: nonRepo,
+                callingAgent: "vscode",
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("repositoryPath must point to a git repository");
+            expect(fs.existsSync(path.join(nonRepo, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+            expect(fs.existsSync(path.join(nonRepo, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(nonRepo, { recursive: true, force: true });
+        }
+    });
+    it("hides local-dev workflow when the feature flag is disabled", async () => {
+        delete process.env.SKYRAMP_FEATURE_LOCAL_DEV;
+        const tool = registerToolForTest();
+        expect(String(tool.config.description)).not.toContain("local_dev_test_changes");
+        expect(String(tool.config.inputSchema)).not.toContain("local_dev_test_changes");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("baseBranch");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("servicesToMock");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("realServices");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("mockProtocols");
+        expect(Object.keys(tool.config.inputSchema)).not.toContain("callingAgent");
+        const result = await tool.handler({
+            workflow: "local_dev_test_changes",
+            repositoryPath: tmpDir,
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Unknown workflow: "local_dev_test_changes"');
+        expect(fs.existsSync(path.join(tmpDir, ".cursor/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".claude/skills/local-dev/SKILL.md"))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, ".vscode/skills/local-dev/SKILL.md"))).toBe(false);
+    });
+});

package/build/tools/preflightMockCheckTool.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPreflightMockCheckTool(server: McpServer): void;

package/build/tools/preflightMockCheckTool.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { validateMockCompatibility, MockProtocol, } from "../utils/mockCompatibility.js";
+const warningSchema = z.object({
+    code: z.string().describe("Warning code identifier (e.g. REST_LOOPBACK_URL, GRPC_PERSISTENT_CONN)."),
+    message: z.string().describe("Human-readable description of the issue."),
+    suggestion: z.string().describe("Recommended action to resolve or work around the issue."),
+    affectedMocks: z.array(z.string()).describe("Mock identifiers (service name or endpoint URL) affected by this warning."),
+    blocking: z.boolean().optional().describe("When true, the affected mocks cannot intercept traffic and must not be generated or deployed."),
+});
+const preflightOutputSchema = {
+    hasBlockers: z.boolean().describe("True when at least one warning is blocking. Blocking mocks must be removed from the generation list before proceeding."),
+    warnings: z.array(warningSchema).describe("All compatibility warnings. Inspect the blocking field on each entry; blocking ones must be skipped, advisory ones may proceed with caution."),
+};
+const TOOL_NAME = "skyramp_preflight_mock_check";
+const mockSpecSchema = z.object({
+    protocol: z.nativeEnum(MockProtocol).describe("The protocol of the mock"),
+    endpointURL: z.string().describe("The endpoint URL for the mock"),
+    method: z.string().optional().describe("HTTP method (for REST mocks)"),
+    grpcServiceName: z.string().optional().describe("gRPC service name (for gRPC mocks)"),
+    kafkaTopic: z.string().optional().describe("Kafka topic (for Kafka mocks)"),
+});
+const inputSchema = {
+    mocks: z
+        .array(mockSpecSchema)
+        .min(1)
+        .describe("Array of mock specifications to validate for compatibility"),
+    dockerLocalDev: z
+        .boolean()
+        .default(true)
+        .describe("When true, apply Docker local-dev checks such as REST loopback URL blockers. Set false for non-Docker/local runtimes."),
+};
+function formatWarning(warning) {
+    const icon = warning.blocking ? "🚫" : "⚠️ ";
+    return [
+        `${icon} [${warning.code}]${warning.blocking ? " BLOCKING — do not generate or deploy these mocks" : ""}`,
+        `   ${warning.message}`,
+        `   Suggestion: ${warning.suggestion}`,
+        `   Affected: ${warning.affectedMocks.join(", ")}`,
+    ].join("\n");
+}
+export function registerPreflightMockCheckTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: "Pre-flight compatibility check for mock deployments. Validates that a set of mocks " +
+            "can be deployed together without known protocol conflicts (e.g., REST loopback URLs in Docker local-dev " +
+            "and gRPC persistent connection caveats). Returns two classes of " +
+            "issues: advisory warnings (mocks are deployable but may exhibit runtime issues) and " +
+            "blocking warnings (mocks cannot intercept traffic and must not be generated or deployed). " +
+            "Check hasBlockers in the result and the blocking flag on each warning before proceeding.",
+        inputSchema,
+        outputSchema: preflightOutputSchema,
+    }, async (params) => {
+        const mocks = params.mocks;
+        const dockerLocalDev = params.dockerLocalDev !== false;
+        const result = validateMockCompatibility(mocks, { dockerLocalDev });
+        let text;
+        if (result.warnings.length === 0) {
+            text = [
+                "✅ Pre-flight check passed — all clear.",
+                "",
+                `${mocks.length} mock(s) validated. No known compatibility issues detected.`,
+                "Safe to deploy in a single apply_mock() call.",
+            ].join("\n");
+        }
+        else {
+            const blockingCount = result.warnings.filter((w) => w.blocking).length;
+            const advisoryCount = result.warnings.length - blockingCount;
+            const headerParts = [];
+            if (blockingCount > 0)
+                headerParts.push(`${blockingCount} blocking`);
+            if (advisoryCount > 0)
+                headerParts.push(`${advisoryCount} advisory`);
+            text = [
+                `⚠️  Pre-flight check: ${result.warnings.length} issue(s) detected (${headerParts.join(", ")}).`,
+                "",
+                ...result.warnings.map(formatWarning),
+                "",
+                result.hasBlockers
+                    ? "🚫 Blocking mocks must be removed from the generation list — they cannot intercept traffic. Advisory mocks may still be deployed with the caveats noted above."
+                    : "Advisory warnings only — mocks are deployable, but consider the suggestions above to avoid runtime issues.",
+            ].join("\n");
+        }
+        return {
+            structuredContent: {
+                hasBlockers: result.hasBlockers,
+                warnings: result.warnings.map((w) => ({
+                    code: w.code,
+                    message: w.message,
+                    suggestion: w.suggestion,
+                    affectedMocks: w.affectedMocks,
+                    ...(w.blocking !== undefined ? { blocking: w.blocking } : {}),
+                })),
+            },
+            content: [{ type: "text", text }],
+        };
+    });
+}

package/build/tools/queryProxyMocksTool.d.ts

@@ -0,0 +1,70 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MockProtocol } from "../types/TestTypes.js";
+interface RestOrGrpcSampleMetadata {
+    destination?: string;
+    path?: string;
+    method?: string;
+    scheme?: string;
+    service?: string;
+    topic?: string;
+    port?: number;
+}
+interface ProxySample {
+    timestamp?: string;
+    request?: {
+        body?: string;
+        data?: string;
+    };
+    response?: {
+        body?: string;
+        data?: string;
+        statusCode?: number;
+    };
+    metadata?: RestOrGrpcSampleMetadata;
+}
+export interface NormalizedMockSpec {
+    protocol: MockProtocol;
+    endpointURL: string;
+    method?: string;
+    responseData?: string;
+    responseStatusCode?: string;
+    requestData?: string;
+    requestAware?: boolean;
+    grpcServiceName?: string;
+    kafkaTopic?: string;
+}
+declare const PROTOCOLS: readonly ["rest", "grpc", "kafka"];
+type Protocol = (typeof PROTOCOLS)[number];
+/**
+ * Combine a bare destination hostname with the separately-reported port
+ * (`metadata.port`) into `host:port`, which is what mock generation expects for
+ * the endpoint origin. Leaves the destination untouched if it already carries a
+ * port or if no usable port was reported.
+ */
+export declare function withPort(destination: string, port?: number): string;
+/**
+ * Convert raw proxy samples for a single protocol into deduplicated mock specs
+ * whose fields map 1:1 onto skyramp_batch_mock_generation. Deduplication keeps
+ * one representative per distinct (destination, method/path/topic, status).
+ */
+export declare function normalizeSamplesToMockSpecs(protocol: Protocol, samples: ProxySample[]): NormalizedMockSpec[];
+/** Normalize a user-supplied proxy address into a scheme://host:port base. */
+export declare function normalizeProxyBaseUrl(proxyUrl: string): string;
+/**
+ * Validate that exactly one access mode was provided and return a normalized
+ * descriptor. Throws a user-facing error otherwise.
+ */
+export declare function resolveAccessMode(params: {
+    proxyUrl?: string;
+    kubeconfig?: string;
+    namespace?: string;
+}): {
+    mode: "url";
+    proxyUrl: string;
+} | {
+    mode: "kube";
+    kubeconfig: string;
+    namespace: string;
+};
+export declare function registerQueryProxyMocksTool(server: McpServer): void;
+export {};