@skyramp/mcp 0.0.63 → 0.0.64-rc.2

package/build/index.js

@@ -32,6 +32,7 @@ import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { initCheck } from "./utils/initAgent.js";
+import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -51,7 +52,9 @@ const server = new McpServer({
 
 ## Rules
 - NEVER show CLI commands. ALWAYS use the MCP tools provided.
-- For UI and E2E tests, use the trace collection start/stop tools.
+- For UI and E2E tests, there are TWO recording modes:
+  1. **AI-driven recording** (default): Use the browser_* tools (browser_navigate, browser_click, etc.) to record interactions, then call skyramp_export_zip to export the trace, then call skyramp_ui_test_generation with the zip path.
+  2. **Manual recording**: ONLY when the user explicitly says "manual recording", "record myself", "I will interact", or "Docker trace" — use skyramp_start_trace_collection / skyramp_stop_trace_collection to let the user interact with the browser themselves.
 - When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.
 - When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
 
@@ -103,10 +106,12 @@ Before calling ANY test generation tool, you MUST follow this flow:
 5. **CRITICAL — scenario generation**: When calling \`skyramp_scenario_test_generation\`, ALWAYS pass:
    - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
    - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to skip auth entirely (unauthenticated endpoints or \`api.authType: "none"\`).
-   - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). Common values: \`"Bearer"\`, \`"Basic"\`, \`"Token"\`. Leave empty if the API uses raw tokens with no prefix. Ignored for non-Authorization headers. **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware (\`passport.use\`, \`jwt.verify\`, header parsing logic), (3) workspace \`api.authType\`. **Do NOT guess.**
-   - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated (combined with \`authScheme\` for Authorization headers). Only provide when the header needs a specific format — e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie. For Authorization headers, use \`authScheme\` instead. **Do NOT fabricate token values.**
+   - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware, (3) workspace \`api.authType\`. **Do NOT guess.**
+   - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated. Only provide when the header needs a specific format (e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie). **Do NOT fabricate token values.**
    - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.
-6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`, ALSO pass \`authHeader\` and the same auth parameters used in scenario generation (\`authScheme\` for Authorization headers, or \`authToken\` for non-Authorization headers).
+6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`:
+   - If workspace has \`api.authType\` set: omit auth params entirely — passing auth here alongside workspace \`authType\` causes "Auth header and auth type cannot be supported at the same time".
+   - If workspace has no \`api.authType\`: pass \`authHeader\` only (no \`authScheme\`).
 7. **If the workspace file does not exist**, or the needed values (language, framework, outputDir) are missing from the workspace config, ASK the user which language and framework they want before calling the tool.
 8. The user can always override workspace defaults by explicitly specifying values in their request.
 `,
@@ -160,6 +165,7 @@ const prompts = [
     registerStartTraceCollectionPrompt,
     registerTestHealthPrompt,
     registerRecommendTestsPrompt,
+    registerTraceRecordingPrompt,
 ];
 if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     prompts.push(registerTestbotPrompt);
@@ -213,6 +219,10 @@ if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     logger.info("TestBot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
+// Register Playwright browser tools (trace recording via browser automation)
+registerPlaywrightTools(server).catch((err) => {
+    logger.error("Failed to register Playwright tools", { error: err });
+});
 // Global error handlers for crash telemetry
 process.on("uncaughtException", async (error) => {
     // Don't send analytics for EPIPE errors
@@ -245,8 +255,15 @@ async function main() {
             return;
         isShuttingDown = true;
         logger.info(`Parent process disconnected (${event}). Cleaning up and exiting...`);
-        server.close().finally(() => {
-            process.exit(0);
+        // Shut down Playwright browser before exiting
+        const playwrightService = getPlaywrightTraceService();
+        const cleanupPlaywright = playwrightService
+            ? playwrightService.shutdown().catch(() => { })
+            : Promise.resolve();
+        cleanupPlaywright.finally(() => {
+            server.close().finally(() => {
+                process.exit(0);
+            });
         });
     };
     process.stdin.on("end", () => handleParentDisconnect("stdin end"));

package/build/playwright/PlaywrightTraceService.js

@@ -0,0 +1,74 @@
+/**
+ * Service that manages a Playwright TraceRecordingBackend instance,
+ * exposing browser tools + skyramp_export_zip for use by the Skyramp MCP.
+ *
+ * The Playwright fork is CJS; this project is ESM. We use createRequire
+ * to bridge the module systems.
+ */
+import { createRequire } from "module";
+import { logger } from "../utils/logger.js";
+export class PlaywrightTraceService {
+    _backend = null;
+    _tools = [];
+    _options;
+    constructor(options) {
+        this._options = options || {};
+    }
+    async initialize() {
+        if (this._backend) {
+            logger.info("PlaywrightTraceService already initialized");
+            return;
+        }
+        try {
+            // Dynamic require of CJS Playwright module from ESM context
+            const require = createRequire(import.meta.url);
+            const { TraceRecordingBackend } = require("playwright/lib/mcp/skyramp");
+            this._backend = new TraceRecordingBackend({
+                headless: this._options.headless,
+                outputDir: this._options.outputDir || process.cwd(),
+            });
+            // Initialize with a synthetic client info
+            await this._backend.initialize({
+                name: "skyramp-mcp",
+                version: "1.0.0",
+                roots: [],
+                timestamp: Date.now(),
+            });
+            this._tools = await this._backend.listTools();
+            logger.info(`PlaywrightTraceService initialized with ${this._tools.length} tools`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to initialize PlaywrightTraceService: ${msg}`);
+            throw error;
+        }
+    }
+    isInitialized() {
+        return this._backend !== null;
+    }
+    getTools() {
+        return this._tools;
+    }
+    async callTool(name, args) {
+        if (!this._backend) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "### Error\nPlaywright trace service not initialized. This is an internal error.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return this._backend.callTool(name, args);
+    }
+    async shutdown() {
+        if (this._backend) {
+            this._backend.serverClosed?.();
+            this._backend = null;
+            this._tools = [];
+            logger.info("PlaywrightTraceService shut down");
+        }
+    }
+}

package/build/playwright/index.js

@@ -0,0 +1,3 @@
+export { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
+export { registerPlaywrightTools, getPlaywrightTraceService, } from "./registerPlaywrightTools.js";
+export { registerTraceRecordingPrompt } from "./traceRecordingPrompt.js";

package/build/playwright/registerPlaywrightTools.js

@@ -0,0 +1,117 @@
+/**
+ * Registers all Playwright browser tools (+ skyramp_export_zip) as passthrough
+ * tools in the Skyramp MCP server, delegating calls to PlaywrightTraceService.
+ */
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
+let _service = null;
+export function getPlaywrightTraceService() {
+    return _service;
+}
+export async function registerPlaywrightTools(server, options) {
+    _service = new PlaywrightTraceService(options);
+    try {
+        await _service.initialize();
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to initialize Playwright tools — browser tools will not be available: ${msg}`);
+        _service = null;
+        return;
+    }
+    const tools = _service.getTools();
+    logger.info(`Registering ${tools.length} Playwright browser tools`);
+    // Only expose essential browser tools to reduce LLM confusion.
+    // The full set (23 tools) overwhelms the LLM and causes it to use
+    // browser_evaluate/browser_run_code instead of the simpler tools.
+    const ESSENTIAL_TOOLS = new Set([
+        'browser_navigate',
+        'browser_snapshot',
+        'browser_click',
+        'browser_type',
+        'browser_select_option',
+        'browser_press_key',
+        'browser_hover',
+        'browser_tabs',
+        'browser_navigate_back',
+        'browser_wait_for',
+        'browser_take_screenshot',
+        'skyramp_export_zip',
+    ]);
+    const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
+    logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
+    for (const tool of filteredTools) {
+        const zodSchema = jsonSchemaToZod(tool.inputSchema);
+        server.registerTool(tool.name, {
+            description: tool.description || `Playwright tool: ${tool.name}`,
+            inputSchema: zodSchema,
+        }, async (params) => {
+            if (!_service?.isInitialized()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "### Error\nPlaywright browser tools are not available. The service failed to initialize.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return _service.callTool(tool.name, params);
+        });
+    }
+    logger.info(`Registered ${filteredTools.length} Playwright tools: ${filteredTools.map((t) => t.name).join(", ")}`);
+}
+function jsonSchemaToZod(schema) {
+    const properties = schema.properties || {};
+    const required = new Set(schema.required || []);
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        let field;
+        switch (prop.type) {
+            case "string":
+                field = prop.enum
+                    ? z.enum(prop.enum)
+                    : z.string();
+                break;
+            case "number":
+            case "integer":
+                field = z.number();
+                break;
+            case "boolean":
+                field = z.boolean();
+                break;
+            case "array":
+                field = z.array(prop.items ? jsonSchemaPropertyToZod(prop.items) : z.unknown());
+                break;
+            default:
+                field = z.unknown();
+        }
+        if (prop.description)
+            field = field.describe(prop.description);
+        if (prop.default !== undefined)
+            field = field.default(prop.default);
+        if (!required.has(key))
+            field = field.optional();
+        shape[key] = field;
+    }
+    return z.object(shape);
+}
+function jsonSchemaPropertyToZod(prop) {
+    switch (prop.type) {
+        case "string":
+            return prop.enum
+                ? z.enum(prop.enum)
+                : z.string();
+        case "number":
+        case "integer":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "array":
+            return z.array(prop.items ? jsonSchemaPropertyToZod(prop.items) : z.unknown());
+        default:
+            return z.unknown();
+    }
+}

package/build/playwright/traceRecordingPrompt.js

@@ -0,0 +1,54 @@
+/**
+ * MCP prompt that guides the LLM through the Playwright-based trace recording
+ * and Skyramp test generation flow.
+ */
+import { logger } from "../utils/logger.js";
+export function registerTraceRecordingPrompt(server) {
+    logger.info("Registering trace recording prompt");
+    server.registerPrompt("skyramp_trace_recording_prompt", {
+        description: "Guide for recording browser interactions as a Skyramp trace and generating UI tests",
+        argsSchema: {},
+    }, () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `## Skyramp Trace Recording & UI Test Generation
+
+You have access to Playwright browser tools that let you interact with web applications.
+Use these tools to record a trace of browser interactions, then generate a Skyramp UI test from that trace.
+
+### Flow
+
+1. **Navigate**: ALWAYS call \`browser_navigate\` with the target URL as the very first step, even if the browser seems to already be on that page. This ensures a clean state.
+2. **Understand the page**: Call \`browser_snapshot\` to see the current page state (ARIA tree).
+3. **Interact**: Use \`browser_click\`, \`browser_type\`, \`browser_select_option\`, \`browser_press_key\`, etc. to perform the user interactions described in the prompt.
+4. **Repeat steps 2-3** until all interactions are complete.
+5. **Export the trace**: Call \`skyramp_export_zip\` with an output path (e.g. \`skyramp_export.zip\`). This produces a zip containing the JSONL trace and HAR network recording.
+6. **Generate the test**: Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute path of the zip file from step 5.
+
+### Tips
+- If a \`browser_click\` or \`browser_type\` fails because the element reference is stale (page updated), call \`browser_snapshot\` to refresh the page state and retry.
+- Use \`browser_snapshot\` liberally — it helps you understand what elements are available.
+- The trace automatically deduplicates retries: if you navigate back to the start URL and redo steps, only the last complete attempt is exported.
+- After generating the test, the tool will suggest running \`skyramp_modularization\` for code quality.
+- **Dropdown/Select components**: For custom dropdowns (Radix, MUI, etc.) that show as \`combobox\` in the snapshot, do NOT use \`browser_select_option\` — it only works on native \`<select>\` elements. Instead: (1) click the combobox to open the dropdown, (2) call \`browser_snapshot\` to see the options in a \`listbox\`, (3) click the desired \`option\`. This three-step pattern is required for all custom dropdown components.
+- **Always take a snapshot after each interaction** that changes the page (click, form submit, navigation) to see the updated state before proceeding.
+
+### Critical rules for clicking
+- **NEVER click container/wrapper divs** (e.g. elements with "container" in their test-id). Always click the actual interactive element inside: a \`button\`, \`link\`, or \`input\`.
+- When the snapshot shows a container with a button inside, click the **button**, not the container. For example, if you see \`div "add-order-products-container" > button "Add"\`, click the button "Add", not the container.
+- To submit forms, click the submit \`button\` (e.g. "Add Order", "Submit"), never the form container.
+- After selecting a product from a dropdown, click the "Add" button to confirm, not the surrounding container.
+
+### Important
+- Do NOT ask the user before calling \`skyramp_export_zip\` — call it automatically as the final step.
+- Do NOT write JSONL or HAR files manually — the export tool handles everything.
+- Do NOT reuse existing zip files from previous sessions — always record fresh.
+`,
+                },
+            },
+        ],
+    }));
+}

package/build/prompts/startTraceCollectionPrompts.js

@@ -12,11 +12,13 @@ export function registerStartTraceCollectionPrompt(mcpServer) {
                 content: {
                     type: "text",
                     text: `
-**General information about Skyramp's trace collection:**
+**MANUAL Trace Collection (Docker-based):**
+This is for MANUAL recording where the USER interacts with the browser themselves. Use this ONLY when the user explicitly requests "manual recording", "record myself", "I will interact", or "Docker trace". For AI-driven recording (where the agent drives the browser), use the browser_* tools and skyramp_export_zip instead.
+
 * You can start a Skyramp trace session to capture network traffic from an active terminal window and for activity within a browser.
 * Once you start a Skyramp trace session, you can stop it any time. Once stopped, a new session will be required to start a new trace collection.
 * Please refer to the Skyramp documentation at https://www.skyramp.dev/docs/concepts/trace-collection for more details on trace collection.
-* Once you have all the data call the start trace generation tool to start the trace collection.
+* Once you have all the data call the stop trace collection tool to save the captured data.
 * Always ask user if they want to enable playwright for trace collection.
 
 **Playwright Configuration Options:**