@skyramp/mcp 0.0.55 → 0.0.57

package/build/index.js

@@ -30,9 +30,12 @@ import { registerExecuteBatchTestsTool } from "./tools/test-maintenance/executeB
 import { registerCalculateHealthScoresTool } from "./tools/test-maintenance/calculateHealthScoresTool.js";
 import { registerActionsTool } from "./tools/test-maintenance/actionsTool.js";
 import { registerStateCleanupTool } from "./tools/test-maintenance/stateCleanupTool.js";
-import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
+import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
 import { registerInitTestbotTool } from "./tools/initTestbotTool.js";
+import { registerSubmitReportTool } from "./tools/submitReportTool.js";
+import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
+import { initCheck } from "./utils/initAgent.js";
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -45,7 +48,68 @@ const server = new McpServer({
             listChanged: true,
         },
     },
+    instructions: `Skyramp MCP Server — generates and executes API tests (smoke, fuzz, contract, load, integration, E2E, UI).
+
+## Rules
+- NEVER show CLI commands. ALWAYS use the MCP tools provided.
+- For UI and E2E tests, use the trace collection start/stop tools.
+
+## Workspace Initialization (before ANY other Skyramp tool)
+Follow this flow EVERY time before calling any Skyramp tool:
+
+1. **Check**: Does .skyramp/workspace.yml exist at the workspace root?
+2. **If YES** → proceed with the requested tool.
+3. **If NO** → you MUST call \`skyramp_initialize_workspace\` BEFORE doing anything else.
+   - Do NOT skip this step. Do NOT proceed to the requested tool first.
+   - Scan the repo for ALL services (see the tool description for detailed steps).
+   - A fullstack or monorepo MUST produce multiple services — never just one.
+   - After workspace init completes, THEN proceed with the originally requested tool.
+4. **ONLY skip init if the user EXPLICITLY says** "no", "skip", "don't create workspace", or similar.
+   - A request like "execute tests" or "generate tests" is NOT a signal to skip init.
+   - If the user does decline, respect it — do NOT ask again, and proceed with the requested tool.
+
+## Workspace Defaults for Test Generation (MANDATORY)
+Before calling ANY test generation tool, you MUST follow this flow:
+
+1. **Read** the .skyramp/workspace.yml file to get the configured defaults.
+2. **Extract** the \`language\`, \`framework\`, \`outputDir\`, and \`api.baseUrl\` from the services section.
+3. **Use those values** as defaults for the test generation tool call. Do NOT ask the user for these values if they are already configured in the workspace file.
+4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
+5. **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.
+6. The user can always override workspace defaults by explicitly specifying values in their request.
+`,
 });
+// Check for first-time invocation after version update (runs in background, doesn't block)
+let initCheckInFlight = false;
+let initCheckDone = false;
+const originalRegisterTool = server.registerTool.bind(server);
+server.registerTool = function (name, definition, handler) {
+    const wrappedHandler = async (...args) => {
+        if (!initCheckDone && !initCheckInFlight) {
+            // Guard with inFlight so concurrent tool calls don't each spawn a new initCheck(),
+            // but allow retry on failure (initCheckInFlight is reset to false on error).
+            // SkyrampClient constructor calls checkForUpdate("npm") via synchronous koffi FFI,
+            // which can block the event loop for up to 60 s if the update-check server is
+            // unreachable.  Deferring via setImmediate ensures the tool response is written to
+            // stdout (and acknowledged by the MCP client) before any blocking FFI call runs.
+            initCheckInFlight = true;
+            setImmediate(() => {
+                initCheck()
+                    .then(() => {
+                    initCheckDone = true;
+                })
+                    .catch((err) => {
+                    logger.error("Background initialization check failed", { error: err });
+                })
+                    .finally(() => {
+                    initCheckInFlight = false;
+                });
+            });
+        }
+        return handler(...args);
+    };
+    return originalRegisterTool(name, definition, wrappedHandler);
+};
 // Register prompts
 logger.info("Starting prompt registration process");
 const prompts = [
@@ -55,7 +119,8 @@ const prompts = [
 ];
 if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     prompts.push(registerTestbotPrompt);
-    logger.info("TestBot prompt enabled via SKYRAMP_ENABLE_TESTBOT");
+    registerTestbotResource(server);
+    logger.info("TestBot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 prompts.forEach((registerPrompt) => registerPrompt(server));
 logger.info("All prompts registered successfully");
@@ -89,6 +154,8 @@ registerExecuteBatchTestsTool(server);
 registerCalculateHealthScoresTool(server);
 registerActionsTool(server);
 registerStateCleanupTool(server);
+// Register workspace management tools
+registerInitializeWorkspaceTool(server);
 // Register other Skyramp tools
 const infrastructureTools = [
     registerLoginTool,
@@ -99,7 +166,8 @@ const infrastructureTools = [
 ];
 if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     infrastructureTools.push(registerInitTestbotTool);
-    logger.info("TestBot init tool enabled via SKYRAMP_FEATURE_TESTBOT");
+    infrastructureTools.push(registerSubmitReportTool);
+    logger.info("TestBot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
 // Global error handlers for crash telemetry

package/build/prompts/startTraceCollectionPrompts.js

@@ -22,13 +22,33 @@ export function registerStartTraceCollectionPrompt(mcpServer) {
 **Playwright Configuration Options:**
 When playwright is enabled for trace collection, you can optionally configure:
 
-1. **Playwright Storage Path** (playwrightStoragePath):
+1. **Browser** (browser):
+   - Choose which browser to use for trace collection
+   - Supported browsers:
+     * 'chromium' - Chrome/Chromium browser (default)
+     * 'firefox' - Mozilla Firefox browser
+     * 'webkit' - Safari/WebKit browser
+   - Use firefox or webkit when you need to test cross-browser compatibility or specific browser behaviors
+
+2. **Device** (device):
+   - Device to emulate for mobile/tablet testing
+   - Supported devices include:
+     * 'iPhone 13' - Apple iPhone 13
+     * 'iPhone 13 Pro' - Apple iPhone 13 Pro
+     * 'Pixel 5' - Google Pixel 5
+     * 'Galaxy S9+' - Samsung Galaxy S9 Plus
+     * 'iPad Pro 11' - Apple iPad Pro
+     * And many more Playwright device profiles
+   - Leave empty (default) for desktop/no device emulation
+   - Use specific device names when testing mobile-responsive applications or generating mobile UI tests
+
+3. **Playwright Storage Path** (playwrightStoragePath):
    - Path to a playwright session storage file containing authentication data (cookies, localStorage, sessionStorage, etc.)
    - MUST be an absolute path like /path/to/storage.json
    - Use this when you have manually created a session from the login flow and want to reuse it for future trace collections to avoid manual login every time
    - The session file should be created beforehand using Playwright's storageState feature during the login flow
 
-2. **Playwright Viewport Size** (playwrightViewportSize):
+4. **Playwright Viewport Size** (playwrightViewportSize):
    - Defines the browser window size for trace collection
    - Supported formats:
      * 'hd' - 1280x720
@@ -44,9 +64,20 @@ When playwright is enabled for trace collection, you can optionally configure:
 * To start a playwright trace collection session using agent, run the following command:
   Start playwright trace collection with default settings.
 
+**Example usage prompt for trace collection with device emulation:**
+* To start a trace collection session with mobile device emulation:
+  Start trace collection with iPhone 13 device
+  Collect trace using Pixel 5 device emulation
+  Start playwright trace with iPad Pro device
+
 **Example usage prompt for trace collection with playwright storage and viewport:**
 * Start playwright trace collection with storage path /Users/dev/session-storage.json and viewport size full-hd
 
+**Example usage prompt for trace collection with specific browser:**
+* Start trace collection with Firefox browser
+* Collect UI traces using webkit browser
+* Start playwright trace collection with chromium browser (default)
+
 **CRITICAL: NEVER SHOW THE CLI COMMANDS.**
 `,
                 },

package/build/prompts/test-recommendation/repository-analysis-prompt.js

@@ -2,20 +2,35 @@
  * Repository Analysis Prompt
  * Comprehensive prompt for analyzing code repositories
  */
-export function getRepositoryAnalysisPrompt(repositoryPath) {
+export function getRepositoryAnalysisPrompt(repositoryPath, analysisScope = "full_repo", parsedDiff) {
+    const isDiffScope = analysisScope === "current_branch_diff";
     return `
 Analyze this repository systematically using the guide below.
 
 REPOSITORY PATH: ${repositoryPath}
+ANALYSIS SCOPE: ${analysisScope}${isDiffScope ? " (focus on branch changes only)" : " (full repository)"}
 
 IMPORTANT OUTPUT FORMAT:
 - Return analysis as valid JSON matching the RepositoryAnalysis interface
 - Use empty arrays [] for unavailable data rather than omitting fields
 - Use "unknown" for unknown string values
 - Provide evidence (file paths, line numbers) where possible
+${isDiffScope ? '- MUST include the "branchDiffContext" field in the output JSON' : ""}
 
 ## CRITICAL RULES
 - If user flows are defined in documentation explicitly, follow them strictly and do not generate new ones.
+${isDiffScope ? `- Do NOT run git commands — the diff has already been parsed by the tool
+- Still gather full repo context (tech stack, infra, auth, existing tests) for accurate scoring
+- For branchDiffContext, use the following pre-parsed metadata:
+  - currentBranch: "${parsedDiff?.currentBranch || "unknown"}"
+  - baseBranch: "${parsedDiff?.baseBranch || "main"}"
+  - changedFiles: [${parsedDiff?.changedFiles.map((f) => `"${f}"`).join(", ") || ""}]
+- For newEndpoints and modifiedEndpoints: use the pre-parsed endpoint information provided by the tool as the primary source of truth.
+  - You may refine this list using only the metadata and code/context that is explicitly included in this prompt.
+  - Do NOT attempt to scan or open additional repository files beyond what has been provided here.
+  - It is acceptable if some indirect or transitive impacts are not fully captured; do not speculate beyond the available information.
+  - When you adjust endpoints, clearly explain your reasoning based on the pre-parsed data and any in-prompt context.
+- affectedServices: treat the changed file paths as high-level hints about which services are likely impacted, but do not perform exhaustive dependency tracing beyond the information provided` : ""}
 
 # Repository Analysis Guide
 
@@ -187,7 +202,8 @@ Return a JSON object with this exact structure:
   "metadata": {
     "repositoryName": "name-from-path",
     "analysisDate": "2025-10-15T14:30:00Z",
-    "scanDepth": "full"
+    "scanDepth": "full",
+    "analysisScope": "${analysisScope}"
   },
   "projectClassification": {
     "projectType": "rest-api | frontend | full-stack | microservices | library | cli | other",
@@ -270,7 +286,20 @@ Return a JSON object with this exact structure:
     },
     "hasCoverageReports": true,
     "estimatedCoverage": 78
-  }
+  }${isDiffScope ? `,
+  "branchDiffContext": {
+    "currentBranch": "feature/my-feature",
+    "baseBranch": "main",
+    "changedFiles": ["src/routes/products.ts", "src/models/Product.ts"],
+    "newEndpoints": [
+      { "path": "/api/v1/products/search", "method": "GET", "sourceFile": "src/routes/products.ts:45" }
+    ],
+    "modifiedEndpoints": [
+      { "path": "/api/v1/products", "method": "POST", "sourceFile": "src/routes/products.ts:12" }
+    ],
+    "affectedServices": ["product-service"],
+    "summary": "Added product search endpoint and modified product creation validation"
+  }` : ""}
 }
 \`\`\`
 
@@ -280,14 +309,18 @@ VALIDATION CHECKLIST:
 - [ ] API endpoints counted and categorized
 - [ ] Authentication method determined
 - [ ] Infrastructure flags verified
-- [ ] Existing tests catalogued
+- [ ] Existing tests catalogued${isDiffScope ? `
+- [ ] branchDiffContext.changedFiles matches the list provided above
+- [ ] branchDiffContext.modifiedEndpoints includes ALL endpoints whose behaviour changed — including those affected by model/schema/validator changes (trace: changed file → which models/types → which endpoints use them)
+- [ ] branchDiffContext.newEndpoints includes any brand-new routes added in the diff
+- [ ] branchDiffContext.summary describes what changed in plain English` : ""}
 
 **CRITICAL INSTRUCTIONS**:
-- 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.
+- Construct the complete RepositoryAnalysis JSON object.
+- DO NOT create any .md or documentation files.
+- Save the analysis JSON to the state file path provided in the tool response.
+- Then call \`skyramp_map_tests\` with the \`stateFile\` parameter (NOT analysisReport) to avoid serialization issues.
 
-Begin analysis now. Return the JSON object directly in your response text.
+Begin analysis now.
 `;
 }

package/build/prompts/test-recommendation/test-recommendation-prompt.js

@@ -2,51 +2,90 @@
  * Test Recommendation Prompt
  * Prompt for generating actionable test recommendations
  */
-export function getTestRecommendationPrompt(mapping, analysis, topN = 7) {
+export function getTestRecommendationPrompt(mapping, analysis, topN = 7, analysisScope = "full_repo") {
+    const isDiffScope = analysisScope === "current_branch_diff";
+    const diffContext = analysis.branchDiffContext;
+    // --- Build a compact summary of priority scores (no full JSON dump) ---
+    const topScores = mapping.priorityScores
+        .filter((s) => s.feasibility !== "not-applicable")
+        .slice(0, topN);
+    const scoreLines = topScores
+        .map((s) => {
+        const priority = s._finalScore >= 100 ? "high" : s._finalScore >= 70 ? "medium" : "low";
+        const avail = s.requiredArtifacts.available.join(", ") || "none";
+        const miss = s.requiredArtifacts.missing.join(", ") || "none";
+        return (`- **${s.testType.toUpperCase()}** | priority: ${priority} | feasibility: ${s.feasibility}\n` +
+            `  Reasoning: ${s.reasoning}\n` +
+            `  Artifacts available: ${avail} | missing: ${miss}`);
+    })
+        .join("\n");
+    // --- Build compact repo context (no full JSON dump) ---
+    const endpoints = analysis.apiEndpoints.endpoints
+        .slice(0, 30) // cap at 30 to keep size sane
+        .map((e) => `  ${e.method} ${e.path}${e.authRequired ? " [auth]" : ""}`)
+        .join("\n");
+    const repoContext = `
+Repository: ${analysis.metadata.repositoryName}
+Framework: ${analysis.projectClassification.primaryFramework} (${analysis.projectClassification.primaryLanguage})
+Project type: ${analysis.projectClassification.projectType}
+Auth: ${analysis.authentication.method}
+Base URL: ${analysis.apiEndpoints.baseUrl}
+Endpoints (${analysis.apiEndpoints.totalCount} total):
+${endpoints}
+`.trim();
+    // --- Branch diff context (only the essentials) ---
+    let diffSection = "";
+    if (isDiffScope && diffContext) {
+        const newEps = diffContext.newEndpoints
+            .map((e) => `  ${e.method} ${e.path} (${e.sourceFile})`)
+            .join("\n") || "  none";
+        const modEps = diffContext.modifiedEndpoints
+            .map((e) => `  ${e.method} ${e.path} (${e.sourceFile})`)
+            .join("\n") || "  none";
+        diffSection = `
+## Branch Diff Context
+Branch: \`${diffContext.currentBranch}\` → base: \`${diffContext.baseBranch}\`
+Changed files: ${diffContext.changedFiles.join(", ")}
+New endpoints:
+${newEps}
+Modified endpoints:
+${modEps}
+Affected services: ${diffContext.affectedServices.join(", ") || "N/A"}
+Summary: ${diffContext?.summary ?? "N/A"}
+
+**CRITICAL**: Focus recommendations ONLY on tests that validate the branch changes above.
+`;
+    }
+    const scopeNote = isDiffScope
+        ? "Recommendations are scoped to the current branch changes only. All specific test suggestions MUST target the new/modified endpoints listed in the Branch Diff Context."
+        : "Recommendations cover the full repository.";
     return `
-Generate actionable test recommendations based on priority and repository analysis.
-
-**MANDATORY RULES**:
-1. **Priority Scores Must Remain Unchanged**: When a test type is missing required inputs (e.g., Playwright recordings, traces), do NOT:
-   - Mark the test as "blocked" in the output
-   - Adjust or reduce the priority score
-   - Exclude it from recommendations if it ranks in the top ${topN}
-
-# Priority 
-
-\`\`\`json
-${JSON.stringify(mapping, null, 2)}
-\`\`\`
+Generate actionable test recommendations based on the priority scores and repository analysis below.
 
-# Repository Context
+Scope: ${scopeNote}
+${diffSection}
+## Repository Context
 
-\`\`\`json
-${JSON.stringify(analysis, null, 2)}
-\`\`\`
+${repoContext}
 
-# Your Task
+## Prioritized Test Types (top ${topN})
 
-Generate specific, actionable test recommendations for the top ${topN} highest-scoring test types.
+${scoreLines}
 
-## CRITICAL RULES
-- **SCORING**: Use the numeric scores ONLY internally to:
-  1. Select the top ${topN} test types by score (highest to lowest)
-  2. Assign priority levels based on score ranges:
-     * Score >= 100: priority = "high"
-     * Score 70-99: priority = "medium"  
-     * Score < 70: priority = "low"
-- **DO NOT include the "score" field** in the JSON output (it has been removed from the schema).
-- DO NOT mention or display numerical scores anywhere in user-facing text.
-- Order test recommendations by their internal priority scores (highest to lowest).
+## Priority Mapping Summary
+- High priority: ${mapping.summary.highPriority.join(", ") || "none"}
+- Medium priority: ${mapping.summary.mediumPriority.join(", ") || "none"}
+- Low priority: ${mapping.summary.lowPriority.join(", ") || "none"}
 
-## Requirements
+## Your Task
 
-For each recommended test type:
-1. **Provide rationale for prioritization based on repository attributes.
-2. **Suggest 3-4 ACTUAL tests** that should be created based on individual user flows and API endpoints.
-3. **Include available artifacts** with specific file paths
-4. **Provide guidance** for creating missing artifacts
+Generate specific, actionable test recommendations for the top ${topN} test types listed above.
 
+**MANDATORY RULES**:
+1. **NO numeric scores** in output — use only: "high", "medium", "low".
+2. **DO NOT mark any test "blocked"** even if artifacts are missing.
+3. **Branch scope**: All specific test suggestions MUST target endpoints/code that changed in the branch diff.
+4. **DO NOT create or save any files** — output everything inline in your response.
 
 ## Output Structure
 
@@ -58,74 +97,41 @@ Return a JSON object with this structure:
     "totalRecommended": 3,
     "highPriorityCount": 2,
     "estimatedEffort": "4-6 hours for top 3 tests",
-    "quickWins": [
-      "Smoke tests (OpenAPI available, 30 min)",
-      "Contract tests (OpenAPI available, 1 hour)"
-    ]
+    "quickWins": ["Smoke tests (OpenAPI available, 30 min)"]
   },
   "recommendations": [
     {
       "priority": "high",
-      "testType": "integration",
-      "rationale": "Detailed explanation of why this is high priority based on repository characteristics (CRITICAL: DO NOT MENTION THE NUMERICAL SCORE HERE)",
+      "testType": "contract",
+      "rationale": "Why this is high priority (DO NOT mention numeric scores)",
       "specificTests": [
         {
-          "testName": "User Registration and Authentication Flow",
-          "description": "Test complete user lifecycle: register → verify → login → access protected resource",
-          "targetEndpoint": "/api/v1/auth/register, /api/v1/auth/login",
-          "targetFlow": "New user onboarding",
+          "testName": "Order quantity validation contract test",
+          "description": "Verify POST /api/v1/orders rejects quantity < 1",
+          "targetEndpoint": "POST /api/v1/orders",
+          "targetFlow": "Order creation validation",
           "requiredInputs": {
-            "available": [
-              {
-                "name": "openApiSpec",
-                "path": "./docs/openapi.yaml"
-              }
-            ],
-            "missing": [
-              {
-                "name": "traceFile",
-                "guidance": "Use Skyramp trace collection: Run 'skyramp_start_trace_collection'..."
-              }
-            ]
+            "available": [{"name": "openApiSpec", "path": "./openapi.json"}],
+            "missing": []
           },
-          "estimatedValue": "High - catches integration bugs between auth and user services"
+          "estimatedValue": "High - catches regression in validation rule change"
         }
       ],
       "gettingStarted": {
-        "prerequisites": [
-          "Docker and Docker Compose installed",
-          "MongoDB running (via docker-compose up)",
-          "JWT_SECRET environment variable set"
-        ],
-        "quickStartCommand": "npm install && docker-compose up -d && npm run test:integration",
-        "documentationUrl": "https://www.skyramp.dev/docs/integration-tests"
+        "prerequisites": ["Service running at localhost:8000"],
+        "quickStartCommand": "Use Skyramp MCP generate tools",
+        "documentationUrl": "https://www.skyramp.dev/docs"
       }
     }
   ],
   "nextSteps": [
-    "1. Start with Integration Tests (highest priority, fills critical gap)",
-    "2. Copy the 'User Registration and Authentication Flow' prompt above",
-    "3. Run: skyramp_integration_test_generation with the prompt",
-    "4. Execute generated tests: npm run test:integration",
-    "5. Once integration tests pass, proceed with Fuzz Tests for security"
+    "1. Start with highest priority test type",
+    "2. Use Skyramp MCP generate tools to create each test",
+    "3. Execute and validate results"
   ]
 }
 \`\`\`
 
-## Important Guidelines
-
-1. **Be Specific**: Use actual endpoint paths, file paths, and flow names from the repository
-2. **Be Actionable**: Prompts should work without modification
-3. **Highlight Quick Wins**: Highlight tests with all artifacts available
-4. **Provide Guidance**: Clear instructions for creating missing artifacts
-5. **Include Evidence**: Reference specific repository characteristics in rationale
-
-**CRITICAL INSTRUCTIONS**:
-- Return the JSON object directly in your response text.
-- DO NOT create or save any files (no test_recommendations.md, .json, or other files).
-- DO NOT use file write tools or save recommendations to disk.
-- Output the complete recommendations JSON inline in your response.
-
 Generate recommendations now. Return the JSON object directly in your response text.
 `;
 }