Runner-specific prerequisites

Install

Two paths — pick the one that matches how you'll use it.

A. Run via `uvx` (zero install, recommended for end users)

Add mk-qa-master to your client config without installing anything globally; uv fetches and runs it in an ephemeral environment per session:

{
  "mcpServers": {
    "mk-qa-master": {
      "command": "uvx",
      "args": ["mk-qa-master"],
      "env": { "QA_RUNNER": "pytest", "QA_PROJECT_ROOT": "/path/to/your-test-project" }
    }
  }
}

That's the whole setup. First call downloads the package; subsequent calls are cached. Switching versions: uvx mk-qa-master@0.4.1 ....

B. Install into a project venv (for contributors / hacking)

pip install mk-qa-master       # or: pip install -e . from a clone
playwright install                # only if you use pytest-playwright
pip install pytest-rerunfailures  # optional, enables auto-retry

Then point your client config at the same Python interpreter:

"command": "/path/to/.venv/bin/python",
"args": ["-m", "mk_qa_master.server"]

Verify the install (v1.4+)

mk-qa-master doctor          # human-readable check report
mk-qa-master doctor --json   # for CI gates / host-LLM consumption

Walks Python version, ffmpeg + mediamtx on PATH, core deps, [edge] extras, runner registry, and MCP tool surface. Exits 0 when nothing critical is missing (warnings about unused features don't fail), 1 when mk-qa-master can't run cleanly. Run it after a fresh install or when an MCP tool returns missing_extras.

Quick install (Claude Code)

```text

Quick install

```bash pip install "mk-qa-master[edge]" # opencv-python + ultralytics + requests

or: sudo apt install ffmpeg + download mediamtx from https://github.com/bluenviron/mediamtx

```

One-time setup

Building tests from a URL (web)

Building tests from a mobile screen (Maestro)

Requires QA_RUNNER=maestro, Maestro CLI, and a booted simulator/emulator/device.

BlueStacks / remote Android instances: set QA_ANDROID_HOST=127.0.0.1:5555 (or whatever host:port BlueStacks exposes — see Settings → Advanced → Android Debug Bridge). The Maestro runner will adb connect before each test and analyze_screen, and bumps the hierarchy timeout to 60s to absorb the slower TCP-ADB path. Genymotion / Nox / LDPlayer / WSA work the same way; any host:port that responds to adb connect is fine.

Quick start

"env": {
  "QA_RUNNER": "pytest",
  "QA_PROJECT_ROOT": "/path/to/project",
  "QA_VISUAL_CHALLENGE_CONSENT": "true",
  "QA_VISUAL_CHALLENGE_AUTHORIZED_DOMAINS": "client-staging.example.com"
}

Then, when a run_tests call surfaces an external_dependency failure that points at a CAPTCHA, the AI client can escalate:

mk-qa-master.inspect_visual_challenge()  # screenshot + tile grid
→ AI vision picks tiles [0, 4, 7]
mk-qa-master.solve_visual_challenge(
    challenge_id="...", selected_tile_indices=[0, 4, 7], confirm=true,
)
→ status: "passed", token: "...", hint: "CAPTCHA verified. Resume your test."

Full walkthrough lives in docs/walkthrough-visual-challenge.md. PRD: docs/prd-v0.7-visual-challenge.md.

Quick start

"env": {
  "QA_RUNNER": "pytest",
  "QA_PROJECT_ROOT": "/path/to/project",
  "QA_API_SECURITY_CONSENT": "true",
  "QA_API_SECURITY_AUTHORIZED_DOMAINS": "api.staging.example.com"
}

Then ask the AI client to scan:

mk-qa-master.run_api_security_scan(
    spec_url="https://api.staging.example.com/openapi.yaml",
    auth={
        "token": "alice's bearer token",
        "alt_user_token": "bob's bearer token",
        "bola_test_ids": {"user_a": [101, 103], "user_b": [202]}
    },
    severity_threshold="medium"
)

Returns the v0.8 security report block:

{
  "scan_id": "a3f8d1c9b7e2",
  "spec_url": "...",
  "base_url": "https://api.staging.example.com",
  "categories_run": ["headers", "broken_auth", "bola", "function_authz"],
  "rules_ran": ["OWASP-API8-Headers", "OWASP-API2-BrokenAuth", ...],
  "ops_scanned": 23,
  "severity_threshold": "medium",
  "findings": [
    {
      "rule_id": "OWASP-API1-BOLA-CrossUserDataExposure",
      "severity": "critical",
      "endpoint": "GET /orders/{id}",
      "title": "user_a can read user_b's object id=202 — missing object-level authorization check",
      "evidence": {"actor": "user_a", "target_owner": "user_b", "target_id": 202, "probed_path": "/orders/202", "status_code": 200, ...},
      "remediation_hint": "Compare the caller's identity to the object's owner before returning..."
    },
    ...
  ],
  "summary": {"total": 7, "by_severity": {"critical": 2, "high": 4, "medium": 1, "low": 0, "info": 0}}
}

Sample outputs

5-line config

"env": {
  "QA_RUNNER": "schemathesis",
  "QA_OPENAPI_URL": "https://api.example.com/openapi.json"
}

Environment variables

Standard QA_TIMEOUT_SECONDS still applies (default 600s).

5-line config

"env": {
  "QA_RUNNER": "newman",
  "QA_POSTMAN_COLLECTION": "/absolute/path/to/your-collection.json"
}

Environment variables

Standard QA_TIMEOUT_SECONDS still applies (default 600s).

Composing in your client config

All five run as separate processes alongside mk-qa-master:

{
  "mcpServers": {
    "mk-qa-master": { "command": "python", "args": ["-m", "mk_qa_master.server"], "env": { "QA_RUNNER": "maestro" } },
    "atlassian":       { "command": "npx", "args": ["-y", "@atlassian/mcp"] },
    "slack":           { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-slack"] },
    "github":          { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
  }
}

Then a single prompt walks the chain:

"Run the checkout suite. For each failure, open a JIRA in project QA with the RIDER format and the screenshot attached. Post the HTML report to #qa-bots when done."

Why this matters: mk-qa-master stays focused on the test loop (analyze → generate → run → coach). JIRA / Slack / Sentry are entire domains with their own dedicated servers — bolting them into this one would dilute the scope, duplicate auth handling, and force every user to inherit dependencies they may not want.

本 repo 不打包任何第三方 SDK——維持「測試執行 + 分析」單一職責。實務上 QA 工作流是多個 MCP server 並存、由 Claude 編排跨 server 的 tool chain達成的。範例配套：JIRA / Slack / GitHub / Sentry / Filesystem 各自獨立 MCP server，配上 mk-qa-master 拼出完整測試管線。

---

OWASP API Security scanning (v0.8.0)

Schemathesis catches correctness drift. v0.8.0 adds the layer that catches the security drift hiding behind a passing schema.

v0.8.0 ships an OWASP API Security Top 10 (2023) rule-based scanner as a new MCP tool: run_api_security_scan. It loads an OpenAPI 3.x spec, walks each (path × method), and dispatches five purely-HTTP- observable rules:

API4 (rate limit DoS risk), API6 (business flow modeling), API7 (SSRF callback infra), API9 (prod recon), API10 (upstream APIs) are deferred — see docs/prd-v0.8-api-security.md §3.

Then from another shell, point run_api_security_scan at

http://127.0.0.1:5099 + the bundled openapi.yaml

```

The scanner finds all 5 categories on /vuln/* and produces zero false positives on /safe/*. That property is enforced by the Tier 1 dogfood tests on every PR.

End-to-end workflow

The intended pipeline — from a URL to "what should I improve next time":

The loop is the point: every run feeds the optimizer, the optimizer points at the weakest link, the next run hits that link first.

`generate_test` output (smart, with module)

"""
Login happy path

Auto-generated from analyze_url module: email_password_form_0 (kind=form)
"""
from playwright.sync_api import Page, expect


def test_login(page: Page):
    page.goto('https://shop.example/login')
    page.locator('#email').fill('test@example.com')
    page.locator('#password').fill('TestPass123!')
    page.locator("button[type='submit']").click()
    # TC: Email 欄位填入格式錯誤的字串（無 @），應顯示格式錯誤
    # TC: Password 欄位輸入後應預設遮蔽
    # TC: 正確 Email + 正確密碼 → 導向 dashboard
    # TODO: 補上實際斷言，例如：
    # expect(page).to_have_url(...)
    # expect(page.get_by_text("成功")).to_be_visible()

Integrations

mk-qa-master doesn't bundle third-party SDKs — it stays a pure test-execution + analysis layer. Real QA workflows are composed by running multiple MCP servers side-by-side in the same client config; Claude orchestrates the chain across servers. There's no MCP-to-MCP RPC — each server is independent, the AI client is the conductor.

The pairings below are the ones that complete the loop most often:

Honorable mention — Google Drive MCP: pairs with Google-Sheet-based TC management (read TCs from a sheet → generate_test → write status back).

When to use this — Tier 1 vs Tier 3

The built-in QA knowledge layer (get_qa_context section="CAPTCHA") codifies three tiers. Reach for them in order:

API testing (`QA_RUNNER=schemathesis`)

Point the runner at any OpenAPI 3.x / Swagger 2.0 schema and Schemathesis generates property-based test cases per operation — covering response schema conformance, status code conformance, content-type checks, and 5xx-on-fuzz. Results flow through the same report.json / history / flake / optimizer pipeline as your UI tests.

End-to-end walkthrough lives in docs/walkthrough-api.md; a self-contained 3-endpoint sample lives at examples/sample_api_project/.

API testing (`QA_RUNNER=newman`)

Point the runner at any exported Postman 2.x collection and Newman 6.x replays every request, runs the embedded pm.test(...) assertions, and returns one mk-qa-master "test" per assertion. Results flow through the same report.json / history / flake / optimizer pipeline as the Schemathesis and UI runners.

System prerequisite: Newman ships via npm, not pip. Install once:

npm install -g newman

There's no pip install 'mk-qa-master[postman]' extra — the runner just shells out to the newman binary on PATH. If it's missing, the runner raises a clear ImportError pointing at the npm install line.

The same 3-endpoint Library API that the OpenAPI sample targets ships as a Postman collection at examples/sample_api_project/postman-collection.json — pair it with prism mock examples/sample_api_project/openapi.yaml for a fully self-contained dev loop, or point at your own staging server.

Troubleshooting