@skyramp/mcp 0.0.44 → 0.0.45

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

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * Register the state file cleanup tool with the MCP server
+ *
+ * This tool helps manage state files created during test analysis workflows.
+ * It can list existing state files and clean up old ones to save disk space.
+ */
+export function registerStateCleanupTool(server) {
+    server.registerTool("skyramp_state_cleanup", {
+        description: `Manage and cleanup test analysis state files.
+
+**WHAT IT DOES:**
+- List all existing state files with details (size, age, session ID)
+- Delete state files older than specified age
+- Show disk space usage by state files
+
+**WHEN TO USE:**
+- Periodically to clean up old analysis sessions
+- To check current state files in the system
+- To free up disk space from temporary analysis data
+
+**OPTIONS:**
+- action: "list" - Show all state files
+- action: "cleanup" - Delete old state files
+- maxAgeHours: How old files must be before deletion (default: 24 hours)
+
+**Output:**
+Information about state files and cleanup results.`,
+        inputSchema: {
+            action: z
+                .enum(["list", "cleanup"])
+                .describe('Action to perform: "list" shows all state files, "cleanup" deletes old files'),
+            maxAgeHours: z
+                .number()
+                .optional()
+                .default(24)
+                .describe("For cleanup action: delete files older than this many hours (default: 24)"),
+        },
+    }, async (args) => {
+        try {
+            logger.info(`State file ${args.action} requested`);
+            if (args.action === "list") {
+                // List all state files
+                const stateFiles = await AnalysisStateManager.listStateFiles();
+                if (stateFiles.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    message: "No state files found",
+                                    totalFiles: 0,
+                                    totalSize: 0,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const totalSize = stateFiles.reduce((sum, file) => sum + file.size, 0);
+                const formatSize = (bytes) => {
+                    if (bytes === 0)
+                        return "0 B";
+                    const k = 1024;
+                    const sizes = ["B", "KB", "MB", "GB"];
+                    const i = Math.floor(Math.log(bytes) / Math.log(k));
+                    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+                };
+                const fileDetails = stateFiles.map((file) => ({
+                    sessionId: file.sessionId,
+                    path: file.path,
+                    size: formatSize(file.size),
+                    sizeBytes: file.size,
+                    createdAt: file.createdAt.toISOString(),
+                    modifiedAt: file.modifiedAt.toISOString(),
+                    ageHours: ((Date.now() - file.modifiedAt.getTime()) /
+                        (1000 * 60 * 60)).toFixed(1),
+                }));
+                logger.info(`Found ${stateFiles.length} state files, total size: ${formatSize(totalSize)}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                totalFiles: stateFiles.length,
+                                totalSize: formatSize(totalSize),
+                                totalSizeBytes: totalSize,
+                                files: fileDetails,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            else if (args.action === "cleanup") {
+                // Cleanup old state files
+                const maxAgeHours = args.maxAgeHours || 24;
+                const deletedCount = await AnalysisStateManager.cleanupOldStateFiles(maxAgeHours);
+                logger.info(`Cleaned up ${deletedCount} state files older than ${maxAgeHours} hours`);
+                // Get remaining files
+                const remainingFiles = await AnalysisStateManager.listStateFiles();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                deletedCount,
+                                maxAgeHours,
+                                remainingFiles: remainingFiles.length,
+                                message: deletedCount > 0
+                                    ? `Successfully deleted ${deletedCount} state file(s) older than ${maxAgeHours} hours`
+                                    : `No state files found older than ${maxAgeHours} hours`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "Invalid action",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        catch (error) {
+            logger.error(`State cleanup failed: ${error.message}`, error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

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

@@ -20,7 +20,22 @@ const analyzeRepositorySchema = z.object({
 });
 export function registerAnalyzeRepositoryTool(server) {
     server.registerTool("skyramp_analyze_repository", {
-        description: `Analyze a code repository to understand its structure, technology stack, and testing readiness.
+        description: `
+⚠️ MANDATORY FIRST STEP - DISPLAY THIS WARNING:
+Before ANY other response text, you MUST output this exact message:
+"** This tool is currently in Early Preview stage. Please verify the results. **"
+
+DO NOT proceed with tool calls until you have displayed this warning in your response.
+
+❌ WRONG: Calling this tool without first displaying the warning message to the user
+✅ CORRECT: First display the warning message in plain text, THEN call this tool
+
+EXPECTED FLOW:
+1. System displays: "** This tool is currently in Early Preview stage..."
+2. System calls: skyramp_analyze_repository(...)
+3. System processes results
+
+Analyze a code repository to understand its structure, technology stack, and testing readiness.
 
 This tool performs comprehensive repository analysis including:
 - Project type classification (REST API, Frontend, Full-stack, Microservices, etc.)

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

@@ -56,7 +56,9 @@ For each recommended test type, you'll get:
 - 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 JSON 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) => {
         try {
@@ -108,7 +110,9 @@ ${prompt}
 - 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.
 
-After analyzing the data above, return the complete JSON response following the structure defined in the prompt.`,
+After analyzing the data above, return the complete JSON response following the structure defined in the prompt.
+**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. **`,
                     },
                 ],
                 isError: false,

package/build/tools/trace/startTraceCollectionTool.js

@@ -57,7 +57,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 .string()
                 .describe("The prompt user provided to start trace collection"),
         },
-        annotations: {
+        _meta: {
             keywords: ["start trace", "trace collection", "trace generation"],
         },
     }, async (params) => {

package/build/tools/trace/stopTraceCollectionTool.js

@@ -36,7 +36,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/load-test/advance
                 .string()
                 .describe("The prompt user provided to stop trace collection"),
         },
-        annotations: {
+        _meta: {
             keywords: ["stop trace", "collect generated trace"],
         },
     }, async (params) => {

package/build/types/TestAnalysis.js

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

package/build/types/TestDriftAnalysis.js

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

package/build/types/TestExecution.js

@@ -0,0 +1,6 @@
+/**
+ * Types for Test Execution
+ *
+ * These types define the structure for test execution results
+ */
+export {};

package/build/types/TestHealth.js

@@ -0,0 +1,4 @@
+/**
+ * Types for Test Health Analysis and Recommendations
+ */
+export {};

package/build/utils/AnalysisStateManager.js

@@ -0,0 +1,238 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { logger } from "./logger.js";
+/**
+ * Manages persistent state for test analysis workflow
+ * Reduces token usage by storing intermediate results in filesystem
+ */
+export class AnalysisStateManager {
+    stateFile;
+    sessionId;
+    /**
+     * Create a new state manager
+     * @param sessionId Unique session identifier (defaults to timestamp)
+     * @param stateDir Directory to store state files (defaults to /tmp)
+     */
+    constructor(sessionId, stateDir) {
+        this.sessionId = sessionId || Date.now().toString();
+        const baseDir = stateDir || os.tmpdir();
+        this.stateFile = path.join(baseDir, `skyramp-analysis-${this.sessionId}.json`);
+    }
+    /**
+     * Create state manager from existing state file path
+     */
+    static fromStatePath(stateFilePath) {
+        const basename = path.basename(stateFilePath, ".json");
+        const sessionId = basename.replace("skyramp-analysis-", "");
+        const stateDir = path.dirname(stateFilePath);
+        return new AnalysisStateManager(sessionId, stateDir);
+    }
+    /**
+     * Read current state from file
+     * @returns Test analysis results, or empty array if file doesn't exist
+     */
+    async readState() {
+        if (!this.exists()) {
+            logger.debug(`State file does not exist: ${this.stateFile}`);
+            return [];
+        }
+        try {
+            const content = await fs.promises.readFile(this.stateFile, "utf-8");
+            const state = JSON.parse(content);
+            logger.debug(`Read ${state.tests.length} tests from state file: ${this.stateFile}`);
+            return state.tests;
+        }
+        catch (error) {
+            logger.error(`Failed to read state file: ${error.message}`);
+            throw new Error(`Failed to read state file: ${error.message}`);
+        }
+    }
+    /**
+     * Read full state including metadata
+     */
+    async readFullState() {
+        if (!this.exists()) {
+            return null;
+        }
+        try {
+            const content = await fs.promises.readFile(this.stateFile, "utf-8");
+            return JSON.parse(content);
+        }
+        catch (error) {
+            logger.error(`Failed to read state file: ${error.message}`);
+            throw new Error(`Failed to read state file: ${error.message}`);
+        }
+    }
+    /**
+     * Write test results to state file
+     * @param tests Test analysis results
+     * @param options Additional metadata options
+     */
+    async writeState(tests, options) {
+        try {
+            // Read existing metadata if file exists
+            let existingMetadata;
+            if (this.exists()) {
+                const existing = await this.readFullState();
+                existingMetadata = existing?.metadata;
+            }
+            const state = {
+                tests,
+                metadata: {
+                    sessionId: this.sessionId,
+                    repositoryPath: options?.repositoryPath || existingMetadata?.repositoryPath,
+                    createdAt: existingMetadata?.createdAt || new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                    step: options?.step,
+                },
+            };
+            await fs.promises.writeFile(this.stateFile, JSON.stringify(state, null, 2), "utf-8");
+            logger.debug(`Wrote ${tests.length} tests to state file: ${this.stateFile}`);
+        }
+        catch (error) {
+            logger.error(`Failed to write state file: ${error.message}`);
+            throw new Error(`Failed to write state file: ${error.message}`);
+        }
+    }
+    // /**
+    //  * Read state with filtering
+    //  * @param filter Function to filter tests
+    //  */
+    // async readStateFiltered(
+    //   filter: (test: TestAnalysisResult) => boolean,
+    // ): Promise<TestAnalysisResult[]> {
+    //   const allTests = await this.readState();
+    //   return allTests.filter(filter);
+    // }
+    // /**
+    //  * Read state with pagination
+    //  * @param page Page number (0-indexed)
+    //  * @param pageSize Number of tests per page
+    //  */
+    // async readStatePaginated(
+    //   page: number,
+    //   pageSize: number = 100,
+    // ): Promise<{
+    //   tests: TestAnalysisResult[];
+    //   hasMore: boolean;
+    //   total: number;
+    //   page: number;
+    //   pageSize: number;
+    // }> {
+    //   const allTests = await this.readState();
+    //   const start = page * pageSize;
+    //   const end = start + pageSize;
+    //   return {
+    //     tests: allTests.slice(start, end),
+    //     hasMore: end < allTests.length,
+    //     total: allTests.length,
+    //     page,
+    //     pageSize,
+    //   };
+    // }
+    /**
+     * Get the state file path
+     */
+    getStatePath() {
+        return this.stateFile;
+    }
+    /**
+     * Get the session ID
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Check if state file exists
+     */
+    exists() {
+        return fs.existsSync(this.stateFile);
+    }
+    /**
+     * Delete the state file
+     */
+    async delete() {
+        if (this.exists()) {
+            await fs.promises.unlink(this.stateFile);
+            logger.debug(`Deleted state file: ${this.stateFile}`);
+        }
+    }
+    /**
+     * Get state file size in bytes
+     */
+    async getSize() {
+        if (!this.exists()) {
+            return 0;
+        }
+        const stats = await fs.promises.stat(this.stateFile);
+        return stats.size;
+    }
+    /**
+     * Get human-readable state file size
+     */
+    async getSizeFormatted() {
+        const bytes = await this.getSize();
+        if (bytes === 0)
+            return "0 B";
+        const k = 1024;
+        const sizes = ["B", "KB", "MB", "GB"];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+        return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+    }
+    /**
+     * Cleanup old state files
+     * @param maxAgeHours Maximum age in hours
+     * @param stateDir Directory to clean (defaults to /tmp)
+     * @returns Number of files deleted
+     */
+    static async cleanupOldStateFiles(maxAgeHours = 24, stateDir) {
+        const baseDir = stateDir || os.tmpdir();
+        const files = await fs.promises.readdir(baseDir);
+        const stateFiles = files.filter((f) => f.startsWith("skyramp-analysis-"));
+        let deletedCount = 0;
+        const now = Date.now();
+        const maxAge = maxAgeHours * 60 * 60 * 1000;
+        for (const file of stateFiles) {
+            const filePath = path.join(baseDir, file);
+            try {
+                const stats = await fs.promises.stat(filePath);
+                const age = now - stats.mtimeMs;
+                if (age > maxAge) {
+                    await fs.promises.unlink(filePath);
+                    deletedCount++;
+                    logger.debug(`Deleted old state file: ${filePath}`);
+                }
+            }
+            catch (error) {
+                logger.error(`Failed to delete state file ${filePath}: ${error.message}`);
+            }
+        }
+        if (deletedCount > 0) {
+            logger.info(`Cleaned up ${deletedCount} old state files`);
+        }
+        return deletedCount;
+    }
+    /**
+     * List all state files in directory
+     * @param stateDir Directory to search (defaults to /tmp)
+     */
+    static async listStateFiles(stateDir) {
+        const baseDir = stateDir || os.tmpdir();
+        const files = await fs.promises.readdir(baseDir);
+        const stateFiles = files.filter((f) => f.startsWith("skyramp-analysis-"));
+        const fileInfos = await Promise.all(stateFiles.map(async (file) => {
+            const filePath = path.join(baseDir, file);
+            const stats = await fs.promises.stat(filePath);
+            const sessionId = file.replace("skyramp-analysis-", "").replace(".json", "");
+            return {
+                sessionId,
+                path: filePath,
+                size: stats.size,
+                createdAt: stats.birthtime,
+                modifiedAt: stats.mtime,
+            };
+        }));
+        return fileInfos.sort((a, b) => b.modifiedAt.getTime() - a.modifiedAt.getTime());
+    }
+}

package/build/utils/utils.test.js

@@ -12,48 +12,64 @@ describe("validateParams", () => {
     it("should return error for JSON-like input", () => {
         const result = validateParams('{"foo":"bar"}', "testField");
         expect(result?.isError).toBe(true);
-        expect(result?.content?.[0].text).toMatch(/not a JSON object/);
+        const firstContent = result?.content?.[0];
+        expect(firstContent?.type).toBe("text");
+        if (firstContent?.type === "text") {
+            expect(firstContent.text).toMatch(/key=value/);
+        }
     });
     it("should return error for missing value", () => {
         const result = validateParams("foo=", "testField");
         expect(result?.isError).toBe(true);
-        expect(result?.content?.[0].text).toMatch(/key=value/);
+        const firstContent = result?.content?.[0];
+        expect(firstContent?.type).toBe("text");
+        if (firstContent?.type === "text") {
+            expect(firstContent.text).toMatch(/key=value/);
+        }
     });
     it("should return error for missing key", () => {
         const result = validateParams("=bar", "testField");
         expect(result?.isError).toBe(true);
-        expect(result?.content?.[0].text).toMatch(/key=value/);
+        const firstContent = result?.content?.[0];
+        expect(firstContent?.type).toBe("text");
+        if (firstContent?.type === "text") {
+            expect(firstContent.text).toMatch(/key=value/);
+        }
     });
     it("should return error for missing key and value", () => {
         const result = validateParams("=", "testField");
         expect(result?.isError).toBe(true);
-        expect(result?.content?.[0].text).toMatch(/key=value/);
+        const firstContent = result?.content?.[0];
+        expect(firstContent?.type).toBe("text");
+        if (firstContent?.type === "text") {
+            expect(firstContent.text).toMatch(/key=value/);
+        }
     });
 });
 describe("generateSkyrampHeader", () => {
     it("should generate correct header for Python", () => {
         const header = generateSkyrampHeader("python");
-        expect(header).toMatch(/^# Generated by Skyramp v1\.2\.23 on/);
+        expect(header).toMatch(/^# Generated by Skyramp on/);
         expect(header).toContain("\n\n");
     });
     it("should generate correct header for JavaScript", () => {
         const header = generateSkyrampHeader("javascript");
-        expect(header).toMatch(/^\/\/ Generated by Skyramp v1\.2\.23 on/);
+        expect(header).toMatch(/^\/\/ Generated by Skyramp on/);
         expect(header).toContain("\n\n");
     });
     it("should generate correct header for TypeScript", () => {
         const header = generateSkyrampHeader("typescript");
-        expect(header).toMatch(/^\/\/ Generated by Skyramp v1\.2\.23 on/);
+        expect(header).toMatch(/^\/\/ Generated by Skyramp on/);
         expect(header).toContain("\n\n");
     });
     it("should generate correct header for Java", () => {
         const header = generateSkyrampHeader("java");
-        expect(header).toMatch(/^\/\/ Generated by Skyramp v1\.2\.23 on/);
+        expect(header).toMatch(/^\/\/ Generated by Skyramp on/);
         expect(header).toContain("\n\n");
     });
     it("should generate correct header for unknown language", () => {
         const header = generateSkyrampHeader("unknown");
-        expect(header).toMatch(/^# Generated by Skyramp v1\.2\.23 on/);
+        expect(header).toMatch(/^# Generated by Skyramp on/);
         expect(header).toContain("\n\n");
     });
     it("should include timestamp in header", () => {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.0.44",
+  "version": "0.0.45",
   "main": "build/index.js",
   "type": "module",
   "bin": {
     "mcp": "./build/index.js"
   },
   "scripts": {
+    "clean-build": "rm -rf build && npm run build",
     "build": "tsc && chmod 755 build/index.js",
     "build:prod": "tsc --sourceMap false && chmod 755 build/index.js",
     "pack": "npm run build:prod && npm pack",
@@ -41,10 +42,12 @@
     "url": "https://github.com/skyramp/mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.4",
-    "@skyramp/skyramp": "^1.2.37",
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@skyramp/skyramp": "^1.2.38",
     "@playwright/test": "^1.55.0",
     "dockerode": "^4.0.6",
+    "fast-glob": "^3.3.3",
+    "simple-git": "^3.30.0",
     "zod": "^3.25.3"
   },
   "devDependencies": {