@skyramp/mcp 0.0.49 → 0.0.51

package/build/tools/test-maintenance/stateCleanupTool.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { StateManager } from "../../utils/AnalysisStateManager.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_state_cleanup";
@@ -11,13 +11,17 @@ const TOOL_NAME = "skyramp_state_cleanup";
  */
 export function registerStateCleanupTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Manage and cleanup test analysis state files.
+        description: `Manage and cleanup Skyramp state files.
 
 **WHAT IT DOES:**
-- List all existing state files with details (size, age, session ID)
+- List all existing state files with details (size, age, session ID, type)
 - Delete state files older than specified age
 - Show disk space usage by state files
 
+**STATE TYPES MANAGED:**
+- analysis: Test maintenance workflow (discovery, drift, execution, health)
+- recommendation: Test recommendation workflow (analyze repo, map tests, recommend)
+
 **WHEN TO USE:**
 - Periodically to clean up old analysis sessions
 - To check current state files in the system
@@ -45,8 +49,8 @@ Information about state files and cleanup results.`,
         try {
             logger.info(`State file ${args.action} requested`);
             if (args.action === "list") {
-                // List all state files
-                const stateFiles = await AnalysisStateManager.listStateFiles();
+                // List all state files (analysis, recommendation)
+                const stateFiles = await StateManager.listStateFiles();
                 if (stateFiles.length === 0) {
                     return {
                         content: [
@@ -72,6 +76,7 @@ Information about state files and cleanup results.`,
                 };
                 const fileDetails = stateFiles.map((file) => ({
                     sessionId: file.sessionId,
+                    stateType: file.stateType,
                     path: file.path,
                     size: formatSize(file.size),
                     sizeBytes: file.size,
@@ -96,12 +101,12 @@ Information about state files and cleanup results.`,
                 };
             }
             else if (args.action === "cleanup") {
-                // Cleanup old state files
+                // Cleanup old state files (all types: analysis, recommendation)
                 const maxAgeHours = args.maxAgeHours || 24;
-                const deletedCount = await AnalysisStateManager.cleanupOldStateFiles(maxAgeHours);
+                const deletedCount = await StateManager.cleanupOldStateFiles(maxAgeHours);
                 logger.info(`Cleaned up ${deletedCount} state files older than ${maxAgeHours} hours`);
                 // Get remaining files
-                const remainingFiles = await AnalysisStateManager.listStateFiles();
+                const remainingFiles = await StateManager.listStateFiles();
                 return {
                     content: [
                         {

package/build/tools/test-recommendation/analyzeRepositoryTool.js

@@ -96,7 +96,11 @@ Use the following tools to gather information:
 
 ${analysisPrompt}
 
-After gathering all information, return a JSON object matching the RepositoryAnalysis structure shown in the prompt above.`,
+After gathering all information:
+1. Return the RepositoryAnalysis JSON in your response
+2. Then call \`skyramp_map_tests\` with:
+   - repositoryPath: \`${params.repositoryPath}\`
+   - analysisReport: <the JSON you just created>`,
                     },
                 ],
                 isError: false,

package/build/tools/test-recommendation/mapTestsTool.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { repositoryAnalysisSchema } from "../../types/RepositoryAnalysis.js";
 import { TestType } from "../../types/TestTypes.js";
 import { ScoringEngine } from "../../utils/scoring-engine.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 /**
@@ -9,6 +10,9 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
  * MCP tool for calculating test priority scores
  */
 const mapTestsSchema = z.object({
+    repositoryPath: z
+        .string()
+        .describe("Absolute path to the repository that was analyzed (used for saving results)"),
     analysisReport: z
         .union([z.string(), repositoryAnalysisSchema])
         .describe("Repository analysis result (JSON string or object from skyramp_analyze_repository)"),
@@ -38,9 +42,10 @@ The scoring algorithm considers:
 - Available artifacts (OpenAPI specs, Playwright recordings)
 - Security requirements (authentication, sensitive data)
 
-Example usage (direct JSON):
+Example usage:
 \`\`\`
 {
+  "repositoryPath": "/Users/dev/my-api",
   "analysisReport": "<RepositoryAnalysis JSON from skyramp_analyze_repository>",
   "customWeights": {
     "load": 1.5,
@@ -49,13 +54,10 @@ Example usage (direct JSON):
 }
 \`\`\`
 
-**CRITICAL RULES**:
-- Return the JSON object directly in your response text.
-- DO NOT create or save any files (no test_mapping.json or .json/.md files).
-- DO NOT use file write tools or save analysis to disk.
-- Output the complete analysis JSON inline in your response.
+**OUTPUT**:
+Returns the state file path to pass to skyramp_recommend_tests
 
-Output: TestMappingResult JSON with priority scores, feasibility, and reasoning for each test type.`,
+Output: TestMappingResult with priority scores, and state file path for next step.`,
         inputSchema: mapTestsSchema.shape,
     }, async (params) => {
         let errorResult;
@@ -142,14 +144,23 @@ Output: TestMappingResult JSON with priority scores, feasibility, and reasoning
                 contextFactors,
                 summary: { highPriority, mediumPriority, lowPriority },
             };
+            // Save results using StateManager (stores in /tmp)
+            const stateManager = new StateManager("recommendation");
+            const stateData = {
+                repositoryPath: params.repositoryPath,
+                analysis,
+                mapping,
+            };
+            await stateManager.writeData(stateData, {
+                repositoryPath: params.repositoryPath,
+                step: "map-tests",
+            });
+            const stateFilePath = stateManager.getStatePath();
+            const sessionId = stateManager.getSessionId();
+            const stateSize = await stateManager.getSizeFormatted();
+            logger.info(`Saved test mapping to: ${stateFilePath} (${stateSize})`);
             // Format output
-            const output = `⚠️ CRITICAL INSTRUCTION - READ FIRST:
-- Return the JSON object directly in your response text.
-- DO NOT create or save any files (no repository_analysis.json or .md files).
-- DO NOT use file write tools or save analysis to disk.
-- Output the complete analysis JSON inline in your response.
-
-# Test Priority Mapping
+            const output = `# Test Priority Mapping
 
 ## Summary
 - **High Priority**: ${mapping.summary.highPriority.join(", ") || "None"}
@@ -173,13 +184,12 @@ ${mapping.contextFactors.applied
                 .map((factor) => `- **${factor.factor}**: ${factor.impact} (×${factor.multiplier})`)
                 .join("\n")}
 
-## Complete Mapping Result (JSON)
+## Results Saved
 
-\`\`\`json
-${JSON.stringify(mapping, null, 2)}
-\`\`\`
+**State File**: \`${stateFilePath}\`
+**Session ID**: \`${sessionId}\`
 
-**Next Step**: Use \`skyramp_recommend_tests\` with this mapping result to get actionable test recommendations.`;
+**Next Step**: Call \`skyramp_recommend_tests\` with stateFile: \`${stateFilePath}\``;
             return {
                 content: [
                     {

package/build/tools/test-recommendation/recommendTestsTool.js

@@ -1,7 +1,6 @@
 import { z } from "zod";
-import { testMappingResultSchema } from "../../types/TestMapping.js";
-import { repositoryAnalysisSchema } from "../../types/RepositoryAnalysis.js";
 import { getTestRecommendationPrompt } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 /**
@@ -9,12 +8,9 @@ import { AnalyticsService } from "../../services/AnalyticsService.js";
  * MCP tool for generating actionable test recommendations
  */
 const recommendTestsSchema = z.object({
-    priorityScores: z
-        .union([z.string(), testMappingResultSchema])
-        .describe("Test mapping result (JSON string or object from skyramp_map_tests)"),
-    analysisReport: z
-        .union([z.string(), repositoryAnalysisSchema])
-        .describe("Repository analysis result (JSON string or object from skyramp_analyze_repository)"),
+    stateFile: z
+        .string()
+        .describe("Path to state file from skyramp_map_tests (contains both analysis and mapping results)"),
     topN: z
         .number()
         .default(7)
@@ -29,7 +25,9 @@ export function registerRecommendTestsTool(server) {
     server.registerTool(TOOL_NAME, {
         description: `Generate actionable test recommendations with ready-to-use generation prompts.
 
-This tool takes test priority and repository analysis to create:
+**PREREQUISITE**: Call skyramp_map_tests first to get the stateFile path.
+
+This tool reads the saved test mapping results and generates:
 - Ordered list of recommended test types (high/medium/low priority)
 - Specific test scenarios based on actual repository endpoints and flows
 - Artifact availability status and guidance for missing artifacts
@@ -56,41 +54,37 @@ For each recommended test type, you'll get:
 - THE PRIORITY SHOULD ONLY BE DEFINED AS HIGH, MEDIUM, OR LOW NOTHING ELSE.
 - DO NOT SHOW ANY PRIORITY BREAKDOWN IN THE OUTPUT.
 - DON'T MARK ANY TEST BLOCKED EVEN IF REQUIRED ARTIFACTS ARE MISSING.
-- DO NOT SHOW RESULTS IN .MD OR .JSON OR ANY OTHER FILE FORMAT.
 
-Output: TestRecommendation JSON with prioritized, actionable test recommendations.
+Output: TestRecommendation with prioritized, actionable test recommendations.
 **CRITICAL:**  At the end of the tool execution, MUST display the below message:
 ** This tool is currently in Early Preview stage. Please verify the results. **`,
         inputSchema: recommendTestsSchema.shape,
     }, async (params) => {
         let errorResult;
-        let prompt;
         try {
             logger.info("Recommend tests tool invoked", {
+                stateFile: params.stateFile,
                 topN: params.topN,
                 minScore: params.minScore,
             });
-            // Parse inputs if they're strings
-            let mapping = params.priorityScores;
-            let analysis = params.analysisReport;
-            if (typeof mapping === "string") {
-                try {
-                    mapping = JSON.parse(mapping);
-                }
-                catch (error) {
-                    throw new Error("priorityScores must be valid JSON string or TestMappingResult object");
-                }
+            // Read state file using StateManager
+            if (!params.stateFile) {
+                throw new Error("stateFile is required");
+            }
+            const stateManager = StateManager.fromStatePath(params.stateFile);
+            if (!stateManager.exists()) {
+                throw new Error(`State file not found: ${params.stateFile}. Run skyramp_map_tests first.`);
             }
-            if (typeof analysis === "string") {
-                try {
-                    analysis = JSON.parse(analysis);
-                }
-                catch (error) {
-                    throw new Error("analysisReport must be valid JSON string or RepositoryAnalysis object");
-                }
+            const stateData = await stateManager.readData();
+            if (!stateData) {
+                throw new Error(`Failed to read state file: ${params.stateFile}. Run skyramp_map_tests first.`);
+            }
+            const { analysis, mapping, repositoryPath } = stateData;
+            if (!analysis || !mapping) {
+                throw new Error("State file is missing required data (analysis or mapping)");
             }
             // Generate the prompt for LLM to create dynamic recommendations
-            prompt = getTestRecommendationPrompt(mapping, analysis, params.topN);
+            const prompt = getTestRecommendationPrompt(mapping, analysis, params.topN);
             // Return prompt for LLM to execute
             return {
                 content: [
@@ -98,6 +92,9 @@ Output: TestRecommendation JSON with prioritized, actionable test recommendation
                         type: "text",
                         text: `# Test Recommendation Request
 
+**State File**: \`${params.stateFile}\`
+**Repository**: \`${repositoryPath}\`
+
 Please generate actionable test recommendations based on the priority scores and repository analysis.
 
 ${prompt}

package/build/tools/trace/startTraceCollectionTool.js

@@ -3,8 +3,9 @@ import { SkyrampClient } from "@skyramp/skyramp";
 import openProxyTerminalTracked from "../../utils/proxy-terminal.js";
 import { TELEMETRY_entrypoint_FIELD_NAME } from "../../utils/utils.js";
 import { logger } from "../../utils/logger.js";
-import { basePlaywrightSchema } from "../../types/TestTypes.js";
+import { basePlaywrightSchema, baseSchema, DEFAULT_SESSION_STORAGE_PATH, SESSION_STORAGE_FILENAME, } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
+import path from "path";
 const TOOL_NAME = "skyramp_start_trace_collection";
 export function registerTraceTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -30,6 +31,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 .describe("Whether to enable Playwright for trace collection. Set to true for UI interactions, false for API-only tracing")
                 .default(true),
             playwrightStoragePath: basePlaywrightSchema.shape.playwrightStoragePath,
+            playwrightSaveStoragePath: basePlaywrightSchema.shape.playwrightSaveStoragePath,
             playwrightViewportSize: basePlaywrightSchema.shape.playwrightViewportSize,
             runtime: z
                 .string()
@@ -55,6 +57,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 .number()
                 .default(35142)
                 .describe("Port number for the Docker worker service during trace collection"),
+            outputDir: baseSchema.shape.outputDir,
             prompt: z
                 .string()
                 .describe("The prompt user provided to start trace collection"),
@@ -62,8 +65,24 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
         _meta: {
             keywords: ["start trace", "trace collection", "trace generation"],
         },
-    }, async (params) => {
+    }, async (params, extra) => {
         let errorResult;
+        // Helper to send progress notifications to the MCP client
+        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);
+            }
+        };
         logger.info("Starting trace collection", {
             playwright: params.playwright,
             runtime: params.runtime,
@@ -72,25 +91,57 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             noProxy: params.noProxy,
             dockerNetwork: params.dockerNetwork,
             dockerWorkerPort: params.dockerWorkerPort,
+            outputDir: params.outputDir,
             prompt: params.prompt,
         });
-        const client = new SkyrampClient();
-        const generateOptions = {
-            testType: "trace",
-            runtime: params.runtime,
-            dockerNetwork: params.dockerNetwork,
-            dockerWorkerPort: params.dockerWorkerPort.toString(),
-            generateInclude: params.include,
-            generateExclude: params.exclude,
-            generateNoProxy: params.noProxy,
-            unblock: true,
-            playwright: params.playwright,
-            playwrightStoragePath: params.playwrightStoragePath,
-            playwrightViewportSize: params.playwrightViewportSize,
-            entrypoint: TELEMETRY_entrypoint_FIELD_NAME,
-        };
+        // Resolve playwrightSaveStoragePath to outputDir if it's the default relative path
+        let saveStoragePath = params.playwrightSaveStoragePath;
+        if (params.outputDir &&
+            saveStoragePath === DEFAULT_SESSION_STORAGE_PATH) {
+            saveStoragePath = path.join(params.outputDir, SESSION_STORAGE_FILENAME);
+        }
         try {
-            const result = await client.generateRestTest(generateOptions);
+            // Send initial progress
+            await sendProgress(0, 100, "Initializing trace collection...");
+            const client = new SkyrampClient();
+            const generateOptions = {
+                testType: "trace",
+                runtime: params.runtime,
+                dockerNetwork: params.dockerNetwork,
+                dockerWorkerPort: params.dockerWorkerPort.toString(),
+                generateInclude: params.include,
+                generateExclude: params.exclude,
+                generateNoProxy: params.noProxy,
+                unblock: true,
+                playwright: params.playwright,
+                playwrightStoragePath: params.playwrightStoragePath,
+                playwrightViewportSize: params.playwrightViewportSize,
+                entrypoint: TELEMETRY_entrypoint_FIELD_NAME,
+            };
+            // Send progress for configuration
+            const traceMode = params.playwright ? "UI + Backend" : "Backend-only";
+            await sendProgress(30, 100, `Configuring ${traceMode} trace collection...`);
+            // Start periodic progress updates during the long-running operation
+            const startTime = Date.now();
+            let progressTick = 0;
+            const progressInterval = setInterval(() => {
+                progressTick++;
+                const elapsed = Math.floor((Date.now() - startTime) / 1000);
+                // Progress moves from 30% to 65% during service startup
+                const percent = Math.min(30 + progressTick * 5, 65);
+                sendProgress(percent, 100, `Starting trace collection service... (${elapsed}s elapsed)`).catch(() => {
+                    // Ignore progress notification errors
+                });
+                // Also log to server for visibility
+                logger.info(`Trace collection progress: ${percent}% (${elapsed}s elapsed)`);
+            }, 10000); // 10 seconds
+            let result;
+            try {
+                result = await client.generateRestTest(generateOptions);
+            }
+            finally {
+                clearInterval(progressInterval);
+            }
             if (result.toLowerCase().includes("failed")) {
                 errorResult = {
                     content: [
@@ -103,7 +154,11 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 };
                 return errorResult;
             }
+            // Send progress for opening proxy terminal
+            await sendProgress(70, 100, "Opening proxy terminal...");
             await openProxyTerminalTracked();
+            // Send completion progress
+            await sendProgress(100, 100, "Trace collection started successfully");
             errorResult = {
                 content: [
                     {

package/build/tools/trace/stopTraceCollectionTool.js

@@ -67,7 +67,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
             if (!existsSync(params.outputDir)) {
                 mkdirSync(params.outputDir, { recursive: true });
             }
-            let errList = {
+            const errList = {
                 content: [],
                 isError: true,
             };

package/build/types/TestTypes.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+export const SESSION_STORAGE_FILENAME = "skyramp_session_storage.json";
+export const DEFAULT_SESSION_STORAGE_PATH = `./${SESSION_STORAGE_FILENAME}`;
 export var TestType;
 (function (TestType) {
     TestType["SMOKE"] = "smoke";
@@ -86,7 +88,11 @@ export const basePlaywrightSchema = z.object({
     playwrightStoragePath: z
         .string()
         .optional()
-        .describe("Path to playwright session storage for trace collection with playwright enabled. THE PATH MUST BE AN ABSOLUTE PATH LIKE /Users/<path>/<filename>.json"),
+        .describe("Path to playwright session storage to load for trace collection with playwright enabled. THE PATH MUST BE AN ABSOLUTE PATH LIKE /Users/<path>/<filename>.json"),
+    playwrightSaveStoragePath: z
+        .string()
+        .default(DEFAULT_SESSION_STORAGE_PATH)
+        .describe(`Path to SAVE Playwright session storage after trace collection. When user says 'with session storage' or 'save session' without specifying a path, use the default '${DEFAULT_SESSION_STORAGE_PATH}'. This SAVES authentication state (cookies, localStorage, sessionStorage) when the browser closes. To LOAD existing auth state, use playwrightStoragePath instead. Can be relative (e.g., 'auth.json') or absolute path.`),
     playwrightViewportSize: z
         .string()
         .default("")