# DDQ — Domain-Driven QA

> An MCP server that turns real bug reports and QA experience into a searchable
> knowledge base, so your AI coding agent can plan QA the way an experienced QA
> engineer would — grounded in what actually breaks, not made-up checklists.

DDQ ships a curated **QA knowledge base** (real, bug-derived checkpoints tagged
by domain / feature / failure type) and exposes it over the **Model Context
Protocol**. Your agent (Claude Code, Cursor, …) calls DDQ's tools to retrieve
the right QA cases, then does the reasoning — planning tests, writing scenarios,
summarizing results — itself.

## Why DDQ

- **Grounded, not hallucinated.** Cases come from real bugs and QA experience,
  rewritten as reusable checkpoints (reproduction, expected result, how to verify).
- **Two retrieval modes**, because "QA this login screen" and "the button is
  broken on mobile" are different requests (see [Tools](#tools)).
- **Cost-zero by design.** Embeddings run on a **local, quantized multilingual
  model** — no embedding API bill. The expensive LLM reasoning stays in *your*
  agent, which you already pay for. The DDQ server only does retrieval.
- **No auth.** The knowledge base is public shared knowledge, so there's no OAuth
  or token to manage — just a URL.

## How it works

```
QA case Markdown (cases/*.md)
      → local embedding (multilingual, q8) → in-memory vector index
Your agent asks "QA this login flow"
      → DDQ returns the relevant cases (similar search OR feature coverage)
      → your agent writes the test plan / scenarios from that grounding
```

## Installation

### Remote (hosted) — nothing to download

DDQ runs at **`https://mcp.nogglee.com/mcp`** (Streamable HTTP). Add it to your
agent and you're done — the knowledge base lives on the server and is always
up to date.

**Claude Code**

```bash
claude mcp add --transport http --scope user ddq https://mcp.nogglee.com/mcp
```

**Cursor / generic MCP config**

```json
{
  "mcpServers": {
    "ddq": {
      "type": "http",
      "url": "https://mcp.nogglee.com/mcp"
    }
  }
}
```

### Local (stdio) — run it yourself

Fully offline, zero cost, private. Requires Node.js ≥ 20 and pnpm.

```bash
git clone https://github.com/nogglee-crew/domain-driven-qa.git
cd domain-driven-qa
pnpm install
pnpm build
claude mcp add ddq -- node "$(pwd)/dist/mcp/stdio.js"
```

The local server indexes `cases/` on startup (downloads the embedding model once).

## Tools

DDQ splits QA requests into two modes, plus a lookup:

### `search_qa_cases` — symptom / similar search

For bug-shaped requests. Returns the top-k QA cases most similar to a natural
language query (Korean and English both work).

```jsonc
{
  "query": "the login button doesn't respond on mobile",
  "topK": 5,
  // optional tag filters:
  "domain": "auth", "feature": "login",
  "environment": ["mobile", "safari"], "severity": "high"
}
```

### `get_coverage_context` — feature-wide QA coverage

For "QA this whole feature" requests (e.g. *"QA the login flow"*). Instead of a
few similar hits, it returns **all** cases for a `domain`/`feature`, grouped by
**risk area (`failure_type`)**, and lists which risk areas have **no cases yet**
so your agent can fill the gaps from its own knowledge.

```jsonc
{ "domain": "auth", "feature": "login" }  // feature optional → whole domain
```

Returns a coverage map (risk areas → cases), the KB gaps, and each case's full
checkpoints — enough to write a complete test plan in one call.

### `get_qa_case` — fetch one case

```jsonc
{ "id": "auth-login-rate-limit-002" }
```

## QA case format

Each case is a Markdown file with YAML frontmatter (multi-axis tags) and a body
of checkpoints / reproduction / expected result / how-to-verify:

```markdown
---
id: auth-login-rate-limit-002
title: Login allows unlimited password attempts (no rate limiting)
domain: auth            # auth | ecommerce | booking | payment | admin | content
feature: login
action: submit
environment: [desktop, chrome]
failure_type: [permission, network]   # validation | race_condition | timezone
                                       # | cache | permission | layout | input | network
severity: high          # low | medium | high | critical
source: github_issue    # github_issue | postmortem | manual_checklist | user_report
test_type: [e2e, regression]
---

## 체크포인트
- ...
## 재현 조건
- ...
## 기대 결과
- ...
## 확인 방법
- ...
```

The current knowledge base covers the **auth** domain (login / signup / logout /
password reset).

## Contributing

Add a `cases/<id>.md` file and open a PR — see **[CONTRIBUTING.md](./CONTRIBUTING.md)**
for the full guide. In short:

- Rewrite raw bug reports as **reusable QA checkpoints**, not copies of the issue.
- Always include reproduction conditions, expected result, and how to verify.
- **Never include sensitive/customer data.** Anonymize and generalize.
- Cases can also be QA methodologies (`testing_principle`) or test-generation
  rules (`scenario_rule`) — the agent reads these and applies them when planning.

## Roadmap

- **`risk_area`** as a first-class axis (e.g. security, session) above `failure_type`.
- More domains (payment, booking) and deeper auth coverage.
- **Local-mode execution tools** — `run_tests` / `save_report` via Playwright.
  These belong to the **local (stdio)** server, since a remote server cannot reach
  your `localhost` app under test.

## License

[MIT](./LICENSE) © NOGGLEE CREW