# QA Studio MCP Server

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

MCP (Model Context Protocol) server for QA Studio - interact with your test management platform directly from Claude.

## Features

This MCP server exposes QA Studio's API as MCP tools, allowing you to:

- 📋 List and search projects
- 🚀 Create and manage test runs
- ✅ View test results and execution history
- 📝 Create test cases
- 📊 Submit test results (manual testing)

## Installation

### Option 1: NPM Package (Recommended)

```bash
npx @qastudio-dev/mcp-server
```

Or install globally:

```bash
npm install -g @qastudio-dev/mcp-server
```

### Option 2: Local Development

For local development or if the package isn't published yet:

```bash
git clone https://github.com/QAStudio-Dev/mcp-server.git
cd mcp-server
npm install
npm run build
```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**For published package (after publishing to npm):**

```json
{
  "mcpServers": {
    "qastudio": {
      "command": "npx",
      "args": ["-y", "@qastudio-dev/mcp-server"],
      "env": {
        "QA_STUDIO_API_URL": "https://qastudio.dev/api",
        "QA_STUDIO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**For local development (before publishing):**

```json
{
  "mcpServers": {
    "qastudio": {
      "command": "node",
      "args": ["/absolute/path/to/qastudio-mcp/dist/index.js"],
      "env": {
        "QA_STUDIO_API_URL": "https://qastudio.dev/api",
        "QA_STUDIO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

> **Note:** Replace `/absolute/path/to/qastudio-mcp` with the actual path to your local repository.

### Environment Variables

- `QA_STUDIO_API_URL` - Base URL for your QA Studio API (default: `http://localhost:3000/api`)
- `QA_STUDIO_API_KEY` - Your QA Studio API key (required)

## Usage

Once configured, you can interact with QA Studio directly from Claude:

### Examples

**List projects:**

```
Show me all projects in QA Studio
```

**Create a test run:**

```
Create a new test run for project ABC123 called "Sprint 45 Regression" in the staging environment
```

**View test results:**

```
Show me the test results for project ABC123, test run XYZ789
```

**Create a test case:**

```
Create a high priority functional test case for project ABC123:
Title: "Verify user login with valid credentials"
Steps:
1. Navigate to login page
2. Enter valid username and password
3. Click login button
Expected: User is redirected to dashboard
```

**Submit test results:**

```
Submit these manual test results for project ABC123, run XYZ789:
- "Login test" - passed
- "Registration test" - failed (Error: Email validation not working)
- "Logout test" - passed
```

## Available Tools

### `list-projects`

List all projects with optional search filtering.

**Parameters:**

- `search` (optional): Search query to filter projects by name

### `create-test-run`

Create a new test run for a project.

**Parameters:**

- `projectId` (required): Project ID
- `name` (required): Test run name
- `environment` (required): Environment (e.g., "production", "staging")
- `description` (optional): Test run description
- `milestoneId` (optional): Associated milestone ID

### `list-test-runs`

List test runs for a project.

**Parameters:**

- `projectId` (required): Project ID
- `limit` (optional): Maximum results (default: 50)
- `offset` (optional): Pagination offset (default: 0)

### `get-test-run`

Get detailed information about a specific test run.

**Parameters:**

- `projectId` (required): Project ID
- `testRunId` (required): Test run ID

### `get-test-results`

Get test results for a specific test run.

**Parameters:**

- `projectId` (required): Project ID
- `testRunId` (required): Test run ID
- `status` (optional): Filter by status (passed, failed, skipped, blocked, retest, untested)

### `create-test-case`

Create a new test case in a project.

**Parameters:**

- `projectId` (required): Project ID
- `title` (required): Test case title
- `description` (optional): Detailed description
- `priority` (optional): CRITICAL, HIGH, MEDIUM, LOW
- `type` (optional): FUNCTIONAL, REGRESSION, SMOKE, INTEGRATION, PERFORMANCE, SECURITY, UI, API, UNIT, E2E
- `automationStatus` (optional): AUTOMATED, NOT_AUTOMATED, CANDIDATE
- `steps` (optional): Array of test steps with action and expectedResult

### `submit-test-results`

Submit test results for a test run (useful for manual testing).

**Parameters:**

- `projectId` (required): Project ID
- `testRunId` (required): Test run ID
- `results` (required): Array of test results with title, status, duration, and optional error

## Development

### Local Development Setup

1. **Clone and install dependencies:**

   ```bash
   git clone https://github.com/QAStudio-Dev/mcp-server.git
   cd mcp-server
   npm install
   ```

2. **Build the project:**

   ```bash
   npm run build
   ```

3. **Configure Claude Desktop for local development:**

   Edit your Claude Desktop config file:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

   Add this configuration (replace the path with your actual project path):

   ```json
   {
     "mcpServers": {
       "qastudio": {
         "command": "node",
         "args": ["/Users/yourusername/path/to/qastudio-mcp/dist/index.js"],
         "env": {
           "QA_STUDIO_API_URL": "https://qastudio.dev/api",
           "QA_STUDIO_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop** to load the MCP server

5. **Run tests:**

   ```bash
   # Run all tests
   npm test

   # Run tests in watch mode
   npm run test:watch

   # Run tests with UI
   npm run test:ui
   ```

6. **Watch mode for development:**

   ```bash
   # Automatically rebuild on file changes
   npm run dev
   ```

   After making changes, restart Claude Desktop to reload the server.

### Testing the Server Directly

You can test the MCP server independently (without Claude):

```bash
# Set environment variables
export QA_STUDIO_API_URL="https://qastudio.dev/api"
export QA_STUDIO_API_KEY="your-api-key"

# Run the server (it will listen on stdio)
node dist/index.js
```

## API Key Setup

To create an API key in QA Studio:

1. Log in to your QA Studio instance
2. Navigate to Settings → API Keys
3. Click "Create API Key"
4. Give it a name (e.g., "Claude MCP Server")
5. Copy the generated key and add it to your MCP configuration

## Security

- Never commit your API key to version control
- Store API keys securely in environment variables or configuration files
- Use HTTPS for production QA Studio instances
- Rotate API keys regularly

## License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.

### What does AGPL-3.0 mean?

- You are free to use, modify, and distribute this software
- If you modify this software and run it on a server (including offering it as a service), you must make your modified source code available to users
- Any derivative work must also be licensed under AGPL-3.0
- This ensures that improvements to the software remain open source and benefit the community

For more information, see the [full license text](LICENSE) or visit [GNU AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).

## Links

- [QA Studio](https://github.com/QAStudio-Dev/qa-studio)
- [Playwright Reporter](https://github.com/QAStudio-Dev/playwright)
- [Model Context Protocol](https://modelcontextprotocol.io)