@skyramp/mcp/README.md

Skyramp MCP (Model Context Protocol) Server - AI-powered test generation and execution

# 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 on MacOS](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=skyramp-mcp&config=eyJjb21tYW5kIjoibnB4IC15IEBza3lyYW1wL21jcEBsYXRlc3QifQ==)

### Note: To pull latest changes restart the MCP server

### 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 on Windows](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/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 a UI test           |
| skyramp_start_trace_collection      | Start trace collection       |
| skyramp_stop_trace_collection       | 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 |

## 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.