Qualitas MCP Server

MCP (Model Context Protocol) server for the Qualitas test automation platform. Enables AI agents to create projects, generate test flows from natural language scenarios, execute tests, and manage environment variables.

Features

• 22 tools for complete Qualitas platform interaction
• Flow generation from scenarios — describe a test in natural language, get a runnable flow
• Auto-beautify layout — nodes are automatically arranged in clean topological order
• Fragment support — create reusable flow fragments for common patterns
• Full CRUD for projects, flows, variables, and runs
• API key authentication — secure, workspace-scoped access via qlt_live_* tokens
• OCR support — extract text from test screenshots
• Upload modes — local file, URL, base64, and variable reference

Quick Start

NPX (Recommended)

No installation needed! Use directly with npx:

npx @qualitas-id/mcp

Global Install

npm install -g @qualitas-id/mcp
qualitas-mcp

Local Development

git clone https://github.com/firdyfirdy/qualitas-mcp-server.git
cd qualitas-mcp-server
npm install
npm run build
npm start

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | QUALITAS_API_KEY | Yes | — | API key from Qualitas Developer Settings (qlt_live_...) | | QUALITAS_API_URL | No | https://api.getqualitas.com | Qualitas API base URL | | QUALITAS_APP_URL | No | https://getqualitas.com | Frontend URL for deep-links |

IDE Setup

OpenCode

Add to opencode.json or opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qualitas": {
      "type": "local",
      "command": ["npx", "-y", "@qualitas-id/mcp"],
      "enabled": true,
      "environment": {
        "QUALITAS_API_KEY": "qlt_live_your_api_key_here"
      }
    }
  }
}

Or use the OpenCode CLI:

opencode mcp add qualitas -- npx -y @qualitas-id/mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "qualitas": {
      "command": "npx",
      "args": ["-y", "@qualitas-id/mcp"],
      "env": {
        "QUALITAS_API_KEY": "qlt_live_your_api_key_here"
      }
    }
  }
}

Claude Code

Use the Claude Code CLI:

claude mcp add qualitas -- npx -y @qualitas-id/mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "qualitas": {
      "command": "npx",
      "args": ["-y", "@qualitas-id/mcp"],
      "env": {
        "QUALITAS_API_KEY": "qlt_live_your_api_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "qualitas": {
      "command": "npx",
      "args": ["-y", "@qualitas-id/mcp"],
      "env": {
        "QUALITAS_API_KEY": "qlt_live_your_api_key_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "qualitas": {
      "command": "npx",
      "args": ["-y", "@qualitas-id/mcp"],
      "env": {
        "QUALITAS_API_KEY": "qlt_live_your_api_key_here"
      }
    }
  }
}

Tools Reference

Projects

| Tool | Description | Annotations | |---|---|---| | list_projects | List all projects with search/filter/sort | read-only | | get_project | Get project details with stats | read-only | | create_project | Create a new project | write | | update_project | Update project settings | write, idempotent |

Flows

| Tool | Description | Annotations | |---|---|---| | list_flows | List flows in a project | read-only | | get_flow | Get flow details (nodes, edges, variables) | read-only | | create_flow | Create a flow with explicit nodes/edges | write | | update_flow | Update flow nodes/edges/variables | write, idempotent | | delete_flow | Delete a flow permanently | write, destructive | | publish_flow | Publish a flow/fragment (draft → active) | write | | generate_flow_from_scenario | Generate a flow from natural language | write |

Runs

| Tool | Description | Annotations | |---|---|---| | run_flow | Trigger flow execution | write | | get_run_status | Get run status and step results | read-only | | list_runs | List run history for a flow | read-only | | get_run_screenshot | Get screenshot URLs for failed steps | read-only |

Variables

| Tool | Description | Annotations | |---|---|---| | list_variables | List project environment variables | read-only | | create_variable | Create environment variable | write | | update_variable | Update environment variable | write, idempotent | | delete_variable | Delete environment variable | write, destructive |

Utility

| Tool | Description | Annotations | |---|---|---| | extract_screenshot_text | OCR from image URL, extract text and error messages | read-only |

Explore

| Tool | Description | Annotations | |---|---|---| | explore_page | Explore a web page — discover structure, forms, buttons, links, navigation, and network requests | write | | get_explore_results | Get results of a previously started explore session | read-only |

Flow Generation

The generate_flow_from_scenario tool is the core feature. Describe a test scenario in natural language and get a complete, runnable flow.

Example scenario:

1. Navigate to https://example.com/login
2. Fill #email with '[email protected]'
3. Fill #password with {{flow.PASSWORD}}
4. Press Enter to submit
5. Wait 3 seconds
6. Verify URL is dashboard

Supported node types: 40 types including navigation, mouse actions, input, form, wait, assertions, API calls, loops, conditions, and more.

Fragment Support

Create reusable fragments for common patterns (login, registration, etc.):

{
  "type": "fragment",
  "name": "Login Fragment",
  "nodes": [
    {"id": "nav_login", "type": "navigate", ...},
    {"id": "fill_email", "type": "fill", ...},
    {"id": "submit", "type": "press", ...}
  ]
}

Important: Fragments MUST NOT have a start node. The fragment's nodes are inlined into the calling flow.

Page Exploration

The explore_page tool discovers what's on a web page — useful for QA testers who want to understand a page before creating test scenarios.

What it returns:

• Detected page type (login, dashboard, form, list, settings, etc.)
• Page headings
• Forms with fields and submit buttons
• Buttons with selectors
• Links with hrefs
• Navigation elements
• Input fields with names, types, placeholders
• Network requests (XHR/Fetch)
• Console errors

Parameters:

| Parameter | Required | Description | |-----------|----------|-------------| | url | Yes | The URL of the page to explore | | project_id | No | UUID of a project. If not provided, auto-creates/reuses an "Explore Sessions" project so your other projects stay clean. | | credentials | No | Login credentials for authenticated pages (email, password, optional selectors) |

Usage — just give a URL:

explore_page(url="https://example.com")

That's it. The tool auto-creates a dedicated "Explore Sessions" project so explore flows don't mix with your real test flows.

How it works:

1. Creates a mini test flow (navigate + optional login steps)
2. Executes with debug mode and exploration mode enabled
3. Captures DOM snapshot, scans all interactive elements, captures network requests
4. Returns a structured summary of the page

Docker

docker pull ghcr.io/firdyfirdy/qualitas-mcp-server:latest

docker run -e QUALITAS_API_KEY=qlt_live_your_key ghcr.io/firdyfirdy/qualitas-mcp-server:latest

Tech Stack

• TypeScript (strict mode)
• MCP SDK (@modelcontextprotocol/sdk)
• Zod (input validation)
• Axios (HTTP client)
• Tesseract.js (OCR)

License

MIT