qa-ai-mcp-server-gits

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)

npx playwright install chromium

2. Add MCP config to your automation project

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

{
  "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.

Config examples: cursor-npx.json · 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 + 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

---

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 for a full template.

---

License

MIT © 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:

npx playwright install chromium   # one-time per machine

.vscode/mcp.json in your automation project:

{
  "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)

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

{
  "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):

{
  "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)
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 · Copilot Chat

1. Open your automation project in VS Code
2. Add .vscode/mcp.json — see 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

{
  "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

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

create_bug — GitHub (dry-run)

{
  "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)

{
  "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)

{
  "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

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):

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

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

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

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)

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
Deployment guide	DEPLOYMENT.md
Prompt template	prompts/MCP-QA-AUTOMATION-TEMPLATE.md

---

Made with ❤️ by gits5213 for QA automation teams.