@skyramp/mcp 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# mcp
+
+## Overview
+
+This project implements an MCP (Model Context Protocol) server for Skyramp, providing prompt-driven guidance and automated test generation for REST APIs. The server is modular and extensible, supporting multiple test types and custom prompts.
+
+## Features
+
+- **Prompt-driven user guidance** for Skyramp test generation, following best practices.
+- **Automated test generation tools** for:
+  - Smoke tests
+  - Fuzz tests
+  - Contract tests
+  - Load tests
+  - Integration tests
+  - UI tests (with Playwright support for browser automation)
+  - E2E tests (combining backend Skyramp trace collection and frontend UI automation using Playwright)
+- **OpenAPI awareness**: Prompts can reference OpenAPI files found in your workspace.
+
+## Development
+
+1. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+2. **Build the project:**
+
+   ```bash
+   npm run build
+   ```
+
+3. **Start the MCP server:**
+
+   ```bash
+   node build/index.js
+   ```
+
+4. **Debug and inspect using Model Context Inspector:**
+
+   ```bash
+   npx @modelcontextprotocol/inspector node build/index.js
+   ```
+
+5. **Configure MCP server for cursor/vscode for local testing**
+
+```
+{
+  "mcpServers": {
+    "skyramp": {
+      "command": "node",
+      "args": [
+        "<absolute_path_of_project>/mcp/build/index.js"
+      ]
+    }
+  }
+}
+```
+
+Note:- this is just for local testing
+
+## Setup
+
+To run the MCP server using npx, use the following command:
+
+```bash
+npx -y @skyramp/mcp@latest
+```
+
+## Usage with Cursor, VScode or Claude Desktop
+
+Add the following configuration. For more information, read the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) or the [Claude Desktop MCP guide](https://modelcontextprotocol.io/quickstart/user).
+
+```json
+{
+  "mcpServers": {
+    "skyramp-mcp": {
+      "command": "npx",
+      "args": ["-y", "@skyramp/mcp@latest"]
+    }
+  }
+}
+```
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=skyramp-mcp&config=eyJjb21tYW5kIjoibnB4IC15IEBza3lyYW1wL21jcEBsYXRlc3QifQ==)
+
+**For Claude Desktop, you must set the `HOME` environment variable in your MCP server configuration.**
+
+This is required because some tools expect a valid home directory for file operations. Set `HOME` to the path where you want Skyramp to generate and execute tests. For example:
+
+```json
+{
+  "mcpServers": {
+    "skyramp-mcp": {
+      "command": "npx",
+      "args": ["-y", "@skyramp/mcp@latest"],
+      "env": {
+        "HOME": "/path/to/your/home"
+      }
+    }
+  }
+}
+```
+
+Replace `/path/to/your/home` with the actual directory you want to use. This ensures the MCP server can properly generate and execute tests in the desired location.
+
+On Windows, you might need to use this alternative configuration:
+
+```json
+{
+  "mcpServers": {
+    "skyramp-mcp": {
+      "command": "cmd",
+      "args": ["/k", "npx", "-y", "@skyramp/mcp@latest"]
+    }
+  }
+}
+```
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=skyramp-mcp&config=eyJjb21tYW5kIjoiY21kIC9rIG5weCAteSBAc2t5cmFtcC9tY3BAbGF0ZXN0In0=)
+
+## Available tools
+
+This MCP server provides the following tools:
+
+| Tool Name                           | Description                  |
+| ----------------------------------- | ---------------------------- |
+| skyramp_smoke_test_generation       | Generate a smoke test        |
+| skyramp_fuzz_test_generation        | Generate a fuzz test         |
+| skyramp_contract_test_generation    | Generate a contract test     |
+| skyramp_load_test_generation        | Generate a load test         |
+| skyramp_integration_test_generation | Generate an integration test |
+| skyramp_e2e_test_generation         | Generate an E2E test         |
+| skyramp_ui_test_generation          | Generate an UI test          |
+| skyramp_start_trace_generation      | Start trace collection       |
+| skyramp_stop_trace_generation       | Stop trace collection        |
+| skyramp_execute_test                | Execute a Skyramp test       |
+
+## Available prompts
+
+This MCP server provides the following prompts:
+
+| Prompt Name                          | Description                            |
+| ------------------------------------ | -------------------------------------- |
+| skyramp_test_generation_prompt       | Guidance for generating Skyramp tests  |
+| skyramp_trace_prompt                 | Guidance for starting trace collection |
+| skyramp_stop_trace_collection_prompt | Guidance for stopping trace collection |
+
+## How it Works
+
+- The server registers a Skyramp prompt (see `src/prompts/skyrampPrompts.ts`) that guides users through test generation and answers questions about Skyramp.
+- Test generation tools for smoke, fuzz, contract, load, and integration tests are registered and available for use.
+- The server communicates over stdio, making it suitable for CLI or integration with other tools.
+
+## Documentation
+
+- Skyramp documentation: [https://skyramp.dev/docs](https://skyramp.dev/docs)
+- Model Context Protocol: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
+
+---
+
+For questions or contributions, please open an issue or pull request.

package/build/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerStartTraceCollectionPrompt } from "./prompts/startTraceCollectionPrompts.js";
+import { registerTraceTool } from "./tools/startTraceCollectionTool.js";
+import { registerTraceStopTool } from "./tools/stopTraceCollectionTool.js";
+import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
+import { registerStopTraceCollectionPrompt } from "./prompts/stopTraceCollectionPrompts.js";
+import { registerTestGenerationPrompt } from "./prompts/testGenerationPrompt.js";
+import { logger } from "./utils/logger.js";
+import { registerUITestTool } from "./tools/generateUIRestTool.js";
+import { registerSmokeTestTool } from "./tools/generateSmokeRestTool.js";
+import { registerFuzzTestTool } from "./tools/generateFuzzRestTool.js";
+import { registerContractTestTool } from "./tools/generateContractRestTool.js";
+import { registerLoadTestTool } from "./tools/generateLoadRestTool.js";
+import { registerIntegrationTestTool } from "./tools/generateIntegrationRestTool.js";
+import { registerEndtoEndTestTool } from "./tools/generateE2ERestTool.js";
+const server = new McpServer({
+    name: "Skyramp MCP Server",
+    version: "1.0.0",
+    capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+// Register prompts
+registerTestGenerationPrompt(server);
+registerStartTraceCollectionPrompt(server);
+registerStopTraceCollectionPrompt(server);
+// Register test generation tools
+registerSmokeTestTool(server);
+registerFuzzTestTool(server);
+registerContractTestTool(server);
+registerLoadTestTool(server);
+registerIntegrationTestTool(server);
+registerEndtoEndTestTool(server);
+registerUITestTool(server);
+// Register other Skyramp tools
+registerExecuteSkyrampTestTool(server);
+registerTraceTool(server);
+registerTraceStopTool(server);
+// Start MCP server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP Server started successfully");
+}
+main().catch((error) => {
+    logger.critical("Fatal error in main()", {
+        error: error.message,
+        stack: error.stack,
+    });
+    process.exit(1);
+});

package/build/prompts/startTraceCollectionPrompts.js

@@ -0,0 +1,54 @@
+// src/prompts/skyrampPrompt.ts
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+// read env variable and use it to set custom prompt
+const isDockerEnv = process.env.MCP_SERVER_RUNTIME === "docker";
+logger.info("MCP server runtime environment", { isDockerEnv });
+export function registerStartTraceCollectionPrompt(mcpServer) {
+    mcpServer.prompt("skyramp_trace_prompt", "Skyramp trace collection prompt", {
+        include: z
+            .string()
+            .describe("Comma-separated list of URLs to include in the trace."),
+        exclude: z
+            .string()
+            .optional()
+            .describe("Comma-separated list of URLs to exclude."),
+        noProxy: z
+            .string()
+            .optional()
+            .describe("Comma-separated list of noProxy values."),
+        runtime: z
+            .string()
+            .describe("Runtime environment for trace collection. Docker is supported for trace collection."),
+        dockerNetwork: z.string().optional(),
+        dockerWorkerPort: z.string().optional(),
+        playwright: z.string(),
+    }, ({ include, exclude, noProxy, runtime, dockerNetwork, dockerWorkerPort, playwright, }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Information about trace generation:
+
+**General information about Skyramp's trace generation:**
+* 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.
+* DO NOT assume the runtime environment for trace collection.
+* Spawn a new terminal shell to start a trace collection in the same IDE window.
+* Once you have all the data call the start trace generation tool to start the trace collection.
+*Always ask user if they want to enable playwright for trace collection.
+
+**Example usage prompt for trace collection:**
+* To start a trace collection session using agent, run the following command:
+  Generate trace with default settings and include realworld.demo.com:8080
+
+**Example usage prompt for trace collection for playwright trace:**
+* To start a playwright trace collection session using agent, run the following command:
+  Start playwright trace collection with default settings.`,
+                },
+            },
+        ],
+    }));
+}

package/build/prompts/stopTraceCollectionPrompts.js

@@ -0,0 +1,113 @@
+import path from "path";
+import { z } from "zod";
+// Utility function to resolve paths to absolute
+function resolveToAbsolutePath(filePath, cwd) {
+    if (path.isAbsolute(filePath)) {
+        return filePath;
+    }
+    return path.resolve(cwd, filePath);
+}
+export function registerStopTraceCollectionPrompt(mcpServer) {
+    mcpServer.prompt("skyramp_stop_trace_collection_prompt", "Skyramp stop trace collection prompt", {
+        traceOutputFile: z
+            .string()
+            .describe("Path to the trace collection output file (relative or absolute). If relative, it will be resolved relative to the current IDE/project directory."),
+        currentWorkingDirectory: z
+            .string()
+            .describe("The current working directory from the IDE/client context. This is REQUIRED for resolving relative paths to absolute paths."),
+        playwright: z
+            .string()
+            .optional()
+            .describe("Whether to use playwright for trace collection. If not provided, it will be set to false."),
+        playwrightOutput: z
+            .string()
+            .optional()
+            .describe("Path to the playwright output file (relative or absolute). If relative, it will be resolved relative to the current IDE/project directory. If playwright is enabled, this will be the path to the playwright output file. If playwright is disabled, this will be empty."),
+    }, ({ traceOutputFile, currentWorkingDirectory, playwright, playwrightOutput, }) => {
+        // Validate currentWorkingDirectory is provided
+        if (!currentWorkingDirectory || currentWorkingDirectory.trim() === "") {
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `**ERROR: Current working directory is required**
+
+The currentWorkingDirectory parameter is required to resolve relative paths to absolute paths. Please ensure your IDE/client provides the current working directory context.
+
+**Expected Parameters:**
+- traceOutputFile: "${traceOutputFile}"
+- currentWorkingDirectory: [REQUIRED - NOT PROVIDED]
+- playwright: ${playwright || "false"}
+- playwrightOutput: "${playwrightOutput || ""}"
+
+**Resolution:** The IDE/client must provide the currentWorkingDirectory parameter to resolve relative paths properly.`,
+                        },
+                    },
+                ],
+            };
+        }
+        // Resolve paths to absolute
+        const absoluteTraceOutputFile = resolveToAbsolutePath(traceOutputFile, currentWorkingDirectory);
+        const absolutePlaywrightOutput = playwrightOutput
+            ? resolveToAbsolutePath(playwrightOutput, currentWorkingDirectory)
+            : "";
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Information about trace generation:
+**General information about Skyramp's trace collection:**
+* 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.
+
+**CRITICAL: You MUST use the following absolute paths for all tool calls:**
+
+**Path Resolution Summary:**
+- Original traceOutputFile: "${traceOutputFile}"
+- Current working directory: "${currentWorkingDirectory}"
+- Resolved absolute traceOutputFile: "${absoluteTraceOutputFile}"
+${playwrightOutput ? `- Original playwrightOutput: "${playwrightOutput}"` : ""}
+${playwrightOutput
+                            ? `- Resolved absolute playwrightOutput: "${absolutePlaywrightOutput}"`
+                            : ""}
+
+**Required Absolute Paths for Tool Calls:**
+1. **traceOutputFile parameter**: MUST use exactly this absolute path: "${absoluteTraceOutputFile}"
+2. **playwrightOutput parameter**: ${playwrightOutput
+                            ? `MUST use exactly this absolute path: "${absolutePlaywrightOutput}"`
+                            : "Not applicable (playwright disabled)"}
+3. **playwright parameter**: ${playwright === "true" ? "true" : "false"}
+
+**IMPORTANT: Path Resolution Instructions:**
+- The paths above have been automatically resolved from relative to absolute paths
+- You MUST use these exact absolute paths in all tool calls - do not modify them
+- DO NOT attempt to resolve paths yourself - use the provided absolute paths exactly as shown
+- DO NOT use the original relative paths provided by the user
+
+**Tool Call Requirements:**
+When calling skyramp_stop_trace_generation, you MUST use:
+- traceOutputFile: "${absoluteTraceOutputFile}" (this exact absolute path)
+- playwright: ${playwright === "true" ? "true" : "false"}
+- playwrightOutput: "${absolutePlaywrightOutput}" ${!playwrightOutput
+                            ? "(empty string if playwright is false)"
+                            : "(this exact absolute path)"}
+
+**Example Tool Call:**
+\`\`\`
+skyramp_stop_trace_generation({
+  traceOutputFile: "${absoluteTraceOutputFile}",
+  playwright: ${playwright === "true" ? "true" : "false"},
+  playwrightOutput: "${absolutePlaywrightOutput}"
+})
+\`\`\``,
+                    },
+                },
+            ],
+        };
+    });
+}