# qa-ai-mcp-server-gits

[![npm version](https://img.shields.io/npm/v/qa-ai-mcp-server-gits)](https://www.npmjs.com/package/qa-ai-mcp-server-gits)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

MCP server for end-to-end QA automation: test scenario generation, Playwright locator discovery, TypeScript test codegen, test execution, and automated bug filing to **GitHub**, **Jira**, or **Azure DevOps**.

- **npm:** https://www.npmjs.com/package/qa-ai-mcp-server-gits
- **GitHub:** https://github.com/gits5213/qa-ai-mcp-server-gits

---

## Features at a Glance

| Capability | Details |
|------------|---------|
| **6 MCP tools** | Scenarios → test cases → locators → Playwright codegen → test run → bug filing |
| **4 MCP prompts** | Built-in workflow templates (no copy-paste needed) |
| **3 bug trackers** | GitHub Issues · Jira · Azure DevOps |
| **2 editors** | Cursor · VS Code (GitHub Copilot Agent) |
| **npm install** | `npx -y qa-ai-mcp-server-gits` — no clone required |
| **Output** | `qa-mcp-output/` in your automation project |

---

## Quick Start

### 1. Install Playwright browser (one-time)

```bash
npx playwright install chromium
```

### 2. Add MCP config to your automation project

Create `.vscode/mcp.json` (works in **Cursor** and **VS Code**):

```json
{
  "mcpServers": {
    "qa-ai-mcp-server-gits": {
      "command": "npx",
      "args": ["-y", "qa-ai-mcp-server-gits"],
      "env": {
        "QA_MCP_PROJECT_ROOT": "${workspaceFolder}",
        "LOG_LEVEL": "info",
        "BUG_PROVIDER": "github",
        "GITHUB_OWNER": "your-org",
        "GITHUB_REPO": "your-automation-repo",
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}
```

> For Jira or Azure DevOps, set `BUG_PROVIDER` to `jira` or `azure-devops` and add the matching env vars — see [Bug Filing](#8-bug-filing-github--jira--azure-devops).

Config examples: [cursor-npx.json](./mcp-config-examples/cursor-npx.json) · [vscode-npx.json](./mcp-config-examples/vscode-npx.json)

### 3. Enable in your editor

| Editor | Steps |
|--------|--------|
| **Cursor** | Settings → **MCP** → enable `qa-ai-mcp-server-gits` → restart → **Agent mode** |
| **VS Code** | Install [Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) + [Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) → reload window → Copilot **Agent** mode |

### 4. Run your first workflow

Use MCP prompt **`qa_automation_workflow_example`** (login demo) or ask in Agent chat:

```
List the available MCP tools from qa-ai-mcp-server-gits
```

---

## MCP Tools

| Tool | Description |
|------|-------------|
| `generate_test_scenarios` | Positive, negative, boundary, validation, role-based, accessibility, security, and E2E scenarios |
| `generate_test_cases` | Detailed automation-ready test cases with IDs, steps, and test data |
| `discover_stable_locators` | Playwright browser scan — locator priority: role → label → placeholder → text → testId → CSS → XPath |
| `generate_playwright_test` | Page Object Model Playwright TypeScript framework (pages, tests, data, utils, config) |
| `run_playwright_test` | Execute tests; capture screenshots, traces, and videos |
| `create_bug` | File bugs to **GitHub**, **Jira**, or **Azure DevOps** (dry-run or live) |

---

## MCP Prompts

Invoke from the MCP **prompts** picker in Cursor or VS Code Copilot — no manual copy-paste:

| Prompt | Description |
|--------|-------------|
| `qa_automation_workflow` | Full workflow — pass `featureName`, `userStory`, `acceptanceCriteria`, `applicationUrl` |
| `qa_automation_workflow_example` | Pre-filled Applitools login demo |
| `qa_automation_workflow_short` | Compact workflow prompt |
| `qa_automation_instructions` | Setup guide for Cursor, VS Code, and bug trackers |

Prompt template file: [prompts/MCP-QA-AUTOMATION-TEMPLATE.md](./prompts/MCP-QA-AUTOMATION-TEMPLATE.md)

---

## Output Location

With `QA_MCP_PROJECT_ROOT` set to `${workspaceFolder}`, artifacts are written to **your project**:

```
qa-mcp-output/
├── test-cases/          # scenarios & test cases JSON
├── locators/            # discovered locators JSON
├── generated-tests/     # Playwright POM framework
└── reports/             # test runs & bug payloads
```

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `QA_MCP_PROJECT_ROOT` | Recommended | Automation workspace path (`${workspaceFolder}` in mcp.json) |
| `BUG_PROVIDER` | No | Default bug tracker: `github` · `jira` · `azure-devops` |
| `GITHUB_TOKEN` | GitHub bugs | Personal access token (`repo` scope) |
| `GITHUB_OWNER` | GitHub bugs | GitHub org or username |
| `GITHUB_REPO` | GitHub bugs | Target repository |
| `GITHUB_DEFAULT_LABELS` | No | Comma-separated labels (default: `bug,automated-test,qa`) |
| `JIRA_BASE_URL` | Jira bugs | e.g. `https://your-domain.atlassian.net` |
| `JIRA_EMAIL` | Jira bugs | Atlassian account email |
| `JIRA_API_TOKEN` | Jira bugs | Jira API token |
| `JIRA_PROJECT_KEY` | Jira bugs | e.g. `QA` |
| `JIRA_ISSUE_TYPE` | No | Default: `Bug` |
| `AZURE_DEVOPS_ORG` | ADO bugs | Organization name |
| `AZURE_DEVOPS_PROJECT` | ADO bugs | Project name |
| `AZURE_DEVOPS_PAT` | ADO bugs | Personal access token (Work Items write) |
| `AZURE_DEVOPS_AREA_PATH` | No | Optional area path |
| `AZURE_DEVOPS_ITERATION_PATH` | No | Optional iteration path |
| `ALLOW_PRODUCTION_URLS` | No | `true` to allow production-like URLs |
| `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` | No | `1` to skip Chromium install on `npm install` |
| `LOG_LEVEL` | No | `debug` · `info` · `warn` · `error` |

Copy [.env.example](./.env.example) for a full template.

---

## License

MIT © [gits5213](https://github.com/gits5213)

---

# 📖 Instructions

> Complete setup, workflow, prompt templates, and bug tracker configuration.

---

## 1. Installation

### Option A — npm (recommended)

No clone required. Editors run the server via `npx`:

```bash
npx playwright install chromium   # one-time per machine
```

`.vscode/mcp.json` in your automation project:

```json
{
  "mcpServers": {
    "qa-ai-mcp-server-gits": {
      "command": "npx",
      "args": ["-y", "qa-ai-mcp-server-gits"],
      "env": {
        "QA_MCP_PROJECT_ROOT": "${workspaceFolder}",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

### Option B — GitHub clone (developers / contributors)

```bash
git clone https://github.com/gits5213/qa-ai-mcp-server-gits.git
cd qa-ai-mcp-server-gits
npm install
cp .env.example .env
npm run build
```

```json
{
  "mcpServers": {
    "qa-ai-mcp-server-gits": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/server.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "qa-ai-mcp-server-gits": {
      "command": "npx",
      "args": ["-y", "qa-ai-mcp-server-gits"],
      "env": {
        "QA_MCP_PROJECT_ROOT": "/absolute/path/to/your/automation-project",
        "BUG_PROVIDER": "github",
        "GITHUB_TOKEN": "ghp_your_token",
        "GITHUB_OWNER": "your-org",
        "GITHUB_REPO": "your-repo"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

---

## 2. Enable in Cursor & VS Code

Both editors share the same `.vscode/mcp.json`.

### Cursor

1. Open your **automation project** (e.g. `qa-automation-framework-gits`)
2. Add `.vscode/mcp.json` (see [Quick Start](#quick-start))
3. **Cursor Settings → MCP** → enable `qa-ai-mcp-server-gits`
4. **Restart Cursor**
5. Open chat in **Agent mode**
6. Confirm **6 tools** and **4 prompts** are available

### VS Code (GitHub Copilot)

**Prerequisites:** VS Code 1.99+ · [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) · [Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat)

1. Open your automation project in VS Code
2. Add `.vscode/mcp.json` — see [vscode-npx.json](./mcp-config-examples/vscode-npx.json)
3. **Developer: Reload Window** (`Cmd+Shift+P` / `Ctrl+Shift+P`)
4. Open **Copilot Chat** → switch to **Agent** mode
5. Open the **tools** picker → verify all 6 tools load
6. MCP prompts appear in the prompts picker

**VS Code user-level config (optional):**

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
| Windows | `%APPDATA%\Code\User\mcp.json` |
| Linux | `~/.config/Code/User/mcp.json` |

> Prefer workspace `.vscode/mcp.json` so `${workspaceFolder}` resolves per project.

### Verify

```
List the available MCP tools from qa-ai-mcp-server-gits
```

Then try prompt **`qa_automation_workflow_example`**.

---

## 3. Built-in MCP Prompts

| Prompt | When to use |
|--------|-------------|
| `qa_automation_workflow` | Your feature — provide story, AC, URL |
| `qa_automation_workflow_example` | Quick Applitools login demo |
| `qa_automation_workflow_short` | Minimal prompt for fast runs |
| `qa_automation_instructions` | Setup help |

### `qa_automation_workflow` arguments

| Argument | Required | Example |
|----------|----------|---------|
| `featureName` | Yes | `UserLogin` |
| `userStory` | Yes | `As a user, I want to...` |
| `acceptanceCriteria` | Yes | Numbered list |
| `applicationUrl` | Yes | `https://demo.applitools.com/` |
| `priority` | No | `high` |
| `pageName` | No | `LoginPage` |
| `environment` | No | `test` |
| `module` | No | `Authentication` |
| `businessRules` | No | Optional rules |
| `featureFolder` | No | `userlogin` |

---

## 4. Full QA Workflow

Run MCP tools **in order** in Agent mode:

| Step | Tool | Purpose |
|------|------|---------|
| 1 | `generate_test_scenarios` | Scenarios from user story & acceptance criteria |
| 2 | `generate_test_cases` | Detailed test cases with IDs and steps |
| 3 | `discover_stable_locators` | Playwright scan for stable locators |
| 4 | `generate_playwright_test` | POM Playwright TypeScript framework |
| 5 | `run_playwright_test` | Execute tests; capture artifacts |
| 6 | `create_bug` | File bug to GitHub / Jira / ADO (dry-run first) |

---

## 5. Copy/Paste Prompt Template

Paste into **Cursor** or **VS Code Copilot Agent mode**:

```
You are my QA Automation Engineer. Use the qa-ai-mcp-server-gits MCP tools.

Feature Name: UserLogin
Application URL: https://demo.applitools.com/
Priority: high

User Story:
As a user, I want to login with valid credentials so that I can access my dashboard.

Acceptance Criteria:
1. User can login with valid username and password.
2. After successful login, URL should contain app.html.
3. Invalid login should show an error message.

Workflow:
1. generate_test_scenarios (featureName: UserLogin, priority: high)
2. generate_test_cases
3. discover_stable_locators (pageName: LoginPage)
4. generate_playwright_test (allureReporting, screenshotOnFailure, traceOnFailure: true)
5. run_playwright_test (headless: true)
6. If fail → create_bug (provider: github, dryRun: true)

Output: qa-mcp-output/ in this project
Begin with Step 1.
```

---

## 6. Example Tool Inputs

### `generate_test_scenarios`

```json
{
  "userStory": "As a user, I want to login with valid credentials so that I can access my dashboard.",
  "acceptanceCriteria": [
    "User can login with valid username and password.",
    "After successful login, URL should contain app.html.",
    "Invalid login should show an error message."
  ],
  "featureName": "UserLogin",
  "priority": "high"
}
```

### `discover_stable_locators`

```json
{
  "applicationUrl": "https://demo.applitools.com/",
  "pageName": "LoginPage",
  "scenarioSteps": ["Enter username", "Enter password", "Click Sign in"]
}
```

### `create_bug` — GitHub (dry-run)

```json
{
  "provider": "github",
  "dryRun": true,
  "failedTestResult": {
    "testStatus": "failed",
    "errorMessage": "Assertion failed",
    "executionSummary": "1 test failed"
  },
  "testCaseDetails": {
    "testCaseId": "TC-USERLOGIN-001",
    "testCaseTitle": "Verify valid login",
    "testType": "positive",
    "priority": "high",
    "module": "Authentication",
    "testSteps": ["1. Navigate to login", "2. Enter credentials", "3. Submit"],
    "expectedResult": "User is logged in"
  },
  "applicationUrl": "https://demo.applitools.com/",
  "environment": "demo",
  "browser": "chromium"
}
```

### `create_bug` — Jira (live)

```json
{
  "provider": "jira",
  "dryRun": false,
  "confirmed": true,
  "failedTestResult": { "testStatus": "failed", "errorMessage": "Timeout", "executionSummary": "1 failed" },
  "testCaseDetails": {
    "testCaseId": "TC-001",
    "testCaseTitle": "Login fails",
    "testType": "negative",
    "priority": "high",
    "module": "Authentication",
    "testSteps": ["1. Enter invalid credentials", "2. Submit"],
    "expectedResult": "Error message shown"
  },
  "applicationUrl": "https://demo.applitools.com/",
  "environment": "staging",
  "browser": "chromium"
}
```

### `create_bug` — Azure DevOps (live)

```json
{
  "provider": "azure-devops",
  "dryRun": false,
  "confirmed": true,
  "failedTestResult": { "testStatus": "failed", "errorMessage": "Element not found", "executionSummary": "1 failed" },
  "testCaseDetails": {
    "testCaseId": "TC-002",
    "testCaseTitle": "Dashboard not loaded",
    "testType": "positive",
    "priority": "critical",
    "module": "Dashboard",
    "testSteps": ["1. Login", "2. Verify dashboard"],
    "expectedResult": "Dashboard visible"
  },
  "applicationUrl": "https://demo.applitools.com/",
  "environment": "test",
  "browser": "chromium"
}
```

**Live bug rules (all providers):** `"dryRun": false` + `"confirmed": true` (or `autoCreateBug: true`)

---

## 7. Run Generated Playwright Tests

```bash
cd qa-mcp-output/generated-tests/userlogin
npm init -y
npm install -D @playwright/test
npx playwright install
npx playwright test
```

Update `data/userData.json` with valid credentials before expecting passes.

Sync into your framework repo (if using `qa-automation-framework-gits`):

```bash
./scripts/sync-from-mcp.sh userlogin
```

---

## 8. Bug Filing (GitHub · Jira · Azure DevOps)

The `create_bug` tool supports three providers. Set per call via `"provider"` or default with `BUG_PROVIDER` env.

| Provider | `provider` value | Creates |
|----------|------------------|---------|
| GitHub | `github` | GitHub Issue |
| Jira | `jira` | Jira Bug |
| Azure DevOps | `azure-devops` | ADO Bug work item |

### GitHub

```env
BUG_PROVIDER=github
GITHUB_TOKEN=ghp_your_personal_access_token
GITHUB_OWNER=your-github-org
GITHUB_REPO=your-automation-repo
GITHUB_DEFAULT_LABELS=bug,automated-test,qa
```

### Jira

```env
BUG_PROVIDER=jira
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your_jira_api_token
JIRA_PROJECT_KEY=QA
JIRA_ISSUE_TYPE=Bug
JIRA_DEFAULT_LABELS=automated-test,qa
```

### Azure DevOps

```env
BUG_PROVIDER=azure-devops
AZURE_DEVOPS_ORG=your-organization
AZURE_DEVOPS_PROJECT=your-project
AZURE_DEVOPS_PAT=your_personal_access_token
AZURE_DEVOPS_AREA_PATH=your-project\\Team Name
AZURE_DEVOPS_ITERATION_PATH=your-project\\Sprint 1
AZURE_DEVOPS_DEFAULT_TAGS=automated-test;qa
```

### Behavior

- **Dry-run (default):** builds payload, saves to `qa-mcp-output/reports/bug-payload-{provider}-{testCaseId}.json`
- **Live:** requires `dryRun: false` + `confirmed: true`
- **Security:** tokens masked in logs; never committed to git

---

## 9. Troubleshooting

| Problem | Solution |
|---------|----------|
| MCP tools not visible (Cursor) | Restart Cursor; enable in **Settings → MCP** |
| MCP tools not visible (VS Code) | Reload window; Copilot **Agent** mode; check `.vscode/mcp.json` |
| npm page shows no README | Hard refresh; ensure latest version published |
| Locator discovery fails | `npx playwright install chromium` |
| Output not in my project | Set `QA_MCP_PROJECT_ROOT` to `${workspaceFolder}` |
| Production URL blocked | `ALLOW_PRODUCTION_URLS=true` |
| Tests fail after codegen | Update `data/userData.json` credentials |
| GitHub bug fails | Check `GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO` |
| Jira bug fails | Verify `JIRA_BASE_URL`, email, API token, project key |
| ADO bug fails | PAT needs **Work Items (Read & Write)** scope |
| `${workspaceFolder}` not resolving | Use workspace `.vscode/mcp.json`, not user-level config |

---

## 10. Security

- Secrets loaded from `.env` / MCP env — **never logged** (masked)
- File writes restricted to project root (`QA_MCP_PROJECT_ROOT`)
- Only `npx playwright test` permitted — no arbitrary shell commands
- Production URLs blocked unless `ALLOW_PRODUCTION_URLS=true`
- Bug creation defaults to **dry-run**; live requires explicit confirmation

---

## 11. Scripts (developers)

| Command | Description |
|---------|-------------|
| `npm run build` | Compile TypeScript |
| `npm start` | Run MCP server (stdio) |
| `npm run dev` | Dev mode with tsx |
| `npm run setup` | Install Playwright Chromium |
| `npm run verify` | Full verification suite |
| `npm run test:mcp` | Verify tools & prompts register |

### Publish to npm (maintainers)

```bash
npm login
npm run build
npm publish --access public --otp=YOUR_CODE
```

---

## 12. Links & Support

| Resource | URL |
|----------|-----|
| npm package | https://www.npmjs.com/package/qa-ai-mcp-server-gits |
| GitHub repo | https://github.com/gits5213/qa-ai-mcp-server-gits |
| Issues | https://github.com/gits5213/qa-ai-mcp-server-gits/issues |
| Public install guide | [PUBLIC-INSTALL.md](./PUBLIC-INSTALL.md) |
| Deployment guide | [DEPLOYMENT.md](./DEPLOYMENT.md) |
| Prompt template | [prompts/MCP-QA-AUTOMATION-TEMPLATE.md](./prompts/MCP-QA-AUTOMATION-TEMPLATE.md) |

---

**Made with ❤️ by [gits5213](https://github.com/gits5213) for QA automation teams.**