# QA-MCP Usage Guide / Kullanım Kılavuzu
<div align="center">
**🇬🇧 English** | [🇹🇷 Türkçe](#-türkçe-kullanım-kılavuzu)
</div>
---
# 🇬🇧 English Usage Guide
## 📋 Table of Contents
- [Quick Start](#-quick-start)
- [Installation Options](#-installation-options)
- [MCP Client Integration](#-mcp-client-integration)
- [Tool Usage Examples](#-tool-usage-examples)
- [Resource Access](#-resource-access)
- [Prompt Templates](#-prompt-templates)
- [Configuration](#️-configuration)
- [Troubleshooting](#-troubleshooting)
---
## 🚀 Quick Start
### 1. Installation
```bash
git clone https://github.com/Atakan-Emre/McpTestGenerator.git
cd McpTestGenerator
pip install -e .
```
### 2. Start MCP Server
```bash
qa-mcp
```
### 3. Connect to Cursor/Claude Desktop
```json
{
"mcpServers": {
"qa-mcp": {
"command": "qa-mcp",
"args": []
}
}
}
```
---
## 📦 Installation Options
### Option 1: With pip (Recommended)
```bash
pip install qa-mcp
```
### Option 2: From Source
```bash
git clone https://github.com/Atakan-Emre/McpTestGenerator.git
cd McpTestGenerator
pip install -e .
```
### Option 3: With Docker
```bash
docker pull atakanemree/qa-mcp:1.0.0
docker run -i --rm atakanemree/qa-mcp:1.0.0
```
### Development Environment
```bash
git clone https://github.com/Atakan-Emre/McpTestGenerator.git
cd McpTestGenerator
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest tests/ -v
```
---
## 🔌 MCP Client Integration
### Cursor IDE
1. Open Cursor settings
2. Edit `mcp.json` file:
```json
{
"mcpServers": {
"qa-mcp": {
"command": "/path/to/.venv/bin/qa-mcp",
"args": []
}
}
}
```
### Claude Desktop
Add to `~/.claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"qa-mcp": {
"command": "qa-mcp",
"args": []
}
}
}
```
### MCP with Docker
```json
{
"mcpServers": {
"qa-mcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "atakanemree/qa-mcp:1.0.0"]
}
}
}
```
---
## 🔧 Tool Usage Examples
### 1. Test Case Generation (`testcase.generate`)
**Purpose:** Generates standard test cases from feature and acceptance criteria.
**Example Request:**
```json
{
"feature": "User Login",
"acceptance_criteria": [
"User can login with valid email and password",
"Account should be locked after 3 failed attempts",
"Forgot password link should work"
],
"module": "auth",
"risk_level": "high",
"include_negative": true
}
```
**Example Output:**
```json
{
"testcases": [
{
"id": "TC-A1B2C3D4",
"title": "User Login - Valid email and password login",
"description": "This test verifies that the 'User Login' feature works according to acceptance criteria...",
"risk_level": "high",
"priority": "P1",
"steps": [...]
}
],
"coverage_summary": {
"positive_scenarios": 3,
"negative_scenarios": 7,
"boundary_tests": 2
},
"total_generated": 12
}
```
### 2. Test Case Lint (`testcase.lint`)
**Purpose:** Analyzes test case quality, returns score and improvement suggestions.
**Example Request:**
```json
{
"testcase": {
"title": "Login test",
"description": "Login test",
"preconditions": [],
"steps": [
{"step_number": 1, "action": "Login", "expected_result": "OK"}
],
"expected_result": "Works"
}
}
```
**Example Output:**
```json
{
"score": 35,
"grade": "F",
"passed": false,
"issues": [
{
"severity": "error",
"field": "preconditions",
"message": "Preconditions not defined",
"suggestion": "List the initial states required for the test to run"
}
],
"improvement_plan": [
{"priority": 1, "action": "Add preconditions", "impact": "high"}
]
}
```
### 3. Format Conversion (`testcase.normalize`)
**Purpose:** Converts test cases from Gherkin, Markdown, or plain text to standard format.
**Gherkin Example:**
```json
{
"input_data": "Feature: User Login\nScenario: Valid login\nGiven user is registered\nWhen user enters credentials\nThen user is logged in",
"source_format": "gherkin"
}
```
### 4. Xray Conversion (`testcase.to_xray`)
**Purpose:** Converts standard test case to Jira/Xray import format.
**Example Request:**
```json
{
"testcase": {
"title": "Login Test",
"description": "Test login functionality",
"preconditions": ["User exists"],
"steps": [
{"step_number": 1, "action": "Navigate to login", "expected_result": "Form displayed"}
],
"expected_result": "User logged in",
"priority": "P1"
},
"project_key": "MYPROJ",
"test_type": "Manual"
}
```
### 5. Suite Composition (`suite.compose`)
**Purpose:** Creates Smoke/Regression/E2E suite from test case list.
```json
{
"testcases": [...],
"target": "smoke",
"sprint": "Sprint 15",
"max_duration_minutes": 15
}
```
---
## 📚 Resource Access
| URI | Description |
|-----|-------------|
| `qa://standards/testcase/v1` | Test case writing standard |
| `qa://checklists/lint-rules/v1` | Lint rules and scoring |
| `qa://mappings/xray/v1` | Xray field mappings |
| `qa://examples/good` | Good test case examples |
| `qa://examples/bad` | Bad test case examples (anti-patterns) |
---
## 💬 Prompt Templates
| Prompt | Description | Arguments |
|--------|-------------|-----------|
| `create-manual-test` | Manual test creation guide | feature, acceptance_criteria |
| `select-smoke-tests` | Smoke test selection guide | testcases, max_duration |
| `generate-negative-scenarios` | Negative scenario generation | feature, positive_testcases |
| `review-test-coverage` | Coverage analysis guide | testcases, requirements |
---
## ⚙️ Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | Log level: debug, info, warning, error |
| `ENABLE_WRITE_TOOLS` | `false` | Enables Jira/Xray write tools |
| `AUDIT_LOG_ENABLED` | `true` | Logs tool calls |
| `HTTP_ENABLED` | `false` | Enables HTTP transport |
| `HTTP_PORT` | `8080` | HTTP port number |
---
## 🔍 Troubleshooting
### 1. "qa-mcp command not found"
```bash
pip show qa-mcp
# or use full path
python -m qa_mcp.server
```
### 2. "Connection refused" (in MCP client)
- Make sure server is running
- Check mcp.json paths
- Restart Cursor/Claude Desktop
### Debug Mode
```bash
LOG_LEVEL=debug qa-mcp
```
---
# 🇹🇷 Türkçe Kullanım Kılavuzu
## 📋 İçindekiler
- [Hızlı Başlangıç](#-hızlı-başlangıç)
- [Kurulum Seçenekleri](#-kurulum-seçenekleri)
- [MCP İstemci Entegrasyonu](#-mcp-i̇stemci-entegrasyonu)
- [Tool Kullanım Örnekleri](#-tool-kullanım-örnekleri-1)
- [Resource Erişimi](#-resource-erişimi)
- [Prompt Şablonları](#-prompt-şablonları)
- [Yapılandırma](#️-yapılandırma-1)
- [Sorun Giderme](#-sorun-giderme)
---
## 🚀 Hızlı Başlangıç
### 1. Kurulum
```bash
git clone https://github.com/Atakan-Emre/McpTestGenerator.git
cd McpTestGenerator
pip install -e .
```
### 2. MCP Server'ı Başlat
```bash
qa-mcp
```
### 3. Cursor/Claude Desktop'a Bağla
```json
{
"mcpServers": {
"qa-mcp": {
"command": "qa-mcp",
"args": []
}
}
}
```
---
## 📦 Kurulum Seçenekleri
### Seçenek 1: pip ile (Önerilen)
```bash
pip install qa-mcp
```
### Seçenek 2: Kaynak Koddan
```bash
git clone https://github.com/Atakan-Emre/McpTestGenerator.git
cd McpTestGenerator
pip install -e .
```
### Seçenek 3: Docker ile
```bash
docker pull atakanemree/qa-mcp:1.0.0
docker run -i --rm atakanemree/qa-mcp:1.0.0
```
### Geliştirme Ortamı
```bash
git clone https://github.com/Atakan-Emre/McpTestGenerator.git
cd McpTestGenerator
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest tests/ -v
```
---
## 🔌 MCP İstemci Entegrasyonu
### Cursor IDE
1. Cursor ayarlarını açın
2. `mcp.json` dosyasını düzenleyin:
```json
{
"mcpServers": {
"qa-mcp": {
"command": "/path/to/.venv/bin/qa-mcp",
"args": []
}
}
}
```
### Claude Desktop
`~/.claude/claude_desktop_config.json` dosyasına ekleyin:
```json
{
"mcpServers": {
"qa-mcp": {
"command": "qa-mcp",
"args": []
}
}
}
```
### Docker ile MCP
```json
{
"mcpServers": {
"qa-mcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "atakanemree/qa-mcp:1.0.0"]
}
}
}
```
---
## 🔧 Tool Kullanım Örnekleri
### 1. Test Case Üretimi (`testcase.generate`)
**Amaç:** Feature ve acceptance criteria'dan standart test case üretir.
**Örnek İstek:**
```json
{
"feature": "Kullanıcı Girişi",
"acceptance_criteria": [
"Geçerli email ve şifre ile giriş yapılabilmeli",
"3 başarısız denemeden sonra hesap kilitlenmeli",
"Şifremi unuttum linki çalışmalı"
],
"module": "auth",
"risk_level": "high",
"include_negative": true
}
```
**Örnek Çıktı:**
```json
{
"testcases": [
{
"id": "TC-A1B2C3D4",
"title": "Kullanıcı Girişi - Geçerli email ve şifre ile giriş",
"description": "Bu test, 'Kullanıcı Girişi' özelliğinin kabul kriterine göre çalıştığını doğrular...",
"risk_level": "high",
"priority": "P1",
"steps": [...]
}
],
"coverage_summary": {
"positive_scenarios": 3,
"negative_scenarios": 7,
"boundary_tests": 2
},
"total_generated": 12
}
```
### 2. Test Case Lint (`testcase.lint`)
**Amaç:** Test case kalitesini analiz eder, skor ve iyileştirme önerileri döner.
**Örnek İstek:**
```json
{
"testcase": {
"title": "Login test",
"description": "Login test",
"preconditions": [],
"steps": [
{"step_number": 1, "action": "Login", "expected_result": "OK"}
],
"expected_result": "Works"
}
}
```
**Örnek Çıktı:**
```json
{
"score": 35,
"grade": "F",
"passed": false,
"issues": [
{
"severity": "error",
"field": "preconditions",
"message": "Ön koşullar tanımlanmamış",
"suggestion": "Test'in çalışması için gerekli başlangıç durumlarını listeleyin"
}
],
"improvement_plan": [
{"priority": 1, "action": "Ön koşullar ekleyin", "impact": "high"}
]
}
```
### 3. Format Dönüştürme (`testcase.normalize`)
**Amaç:** Gherkin, Markdown veya düz metin formatındaki test case'leri standart formata çevirir.
**Gherkin Örneği:**
```json
{
"input_data": "Feature: User Login\nScenario: Valid login\nGiven user is registered\nWhen user enters credentials\nThen user is logged in",
"source_format": "gherkin"
}
```
### 4. Xray Dönüşümü (`testcase.to_xray`)
**Amaç:** Standart test case'i Jira/Xray import formatına çevirir.
**Örnek İstek:**
```json
{
"testcase": {
"title": "Login Test",
"description": "Test login functionality",
"preconditions": ["User exists"],
"steps": [
{"step_number": 1, "action": "Navigate to login", "expected_result": "Form displayed"}
],
"expected_result": "User logged in",
"priority": "P1"
},
"project_key": "MYPROJ",
"test_type": "Manual"
}
```
### 5. Suite Kompozisyonu (`suite.compose`)
**Amaç:** Test case listesinden Smoke/Regression/E2E suite oluşturur.
```json
{
"testcases": [...],
"target": "smoke",
"sprint": "Sprint 15",
"max_duration_minutes": 15
}
```
---
## 📚 Resource Erişimi
| URI | Açıklama |
|-----|----------|
| `qa://standards/testcase/v1` | Test case yazım standardı |
| `qa://checklists/lint-rules/v1` | Lint kuralları ve puanlama |
| `qa://mappings/xray/v1` | Xray alan eşlemeleri |
| `qa://examples/good` | İyi test case örnekleri |
| `qa://examples/bad` | Kötü test case örnekleri (anti-patterns) |
---
## 💬 Prompt Şablonları
| Prompt | Açıklama | Argümanlar |
|--------|----------|------------|
| `create-manual-test` | Manual test oluşturma rehberi | feature, acceptance_criteria |
| `select-smoke-tests` | Smoke test seçim rehberi | testcases, max_duration |
| `generate-negative-scenarios` | Negatif senaryo üretimi | feature, positive_testcases |
| `review-test-coverage` | Kapsam analizi rehberi | testcases, requirements |
---
## ⚙️ Yapılandırma
### Environment Variables
| Değişken | Varsayılan | Açıklama |
|----------|------------|----------|
| `LOG_LEVEL` | `info` | Log seviyesi: debug, info, warning, error |
| `ENABLE_WRITE_TOOLS` | `false` | Jira/Xray yazma tool'larını etkinleştirir |
| `AUDIT_LOG_ENABLED` | `true` | Tool çağrılarını loglar |
| `HTTP_ENABLED` | `false` | HTTP transport'u etkinleştirir |
| `HTTP_PORT` | `8080` | HTTP port numarası |
---
## 🔍 Sorun Giderme
### 1. "qa-mcp command not found"
```bash
pip show qa-mcp
# veya tam yol kullanın
python -m qa_mcp.server
```
### 2. "Connection refused" (MCP istemcisinde)
- Server'ın çalıştığından emin olun
- mcp.json yollarını kontrol edin
- Cursor/Claude Desktop'ı yeniden başlatın
### Debug Modu
```bash
LOG_LEVEL=debug qa-mcp
```
---
## 📄 License / Lisans
MIT License - Copyright (c) 2024-2026 [Atakan Emre](https://github.com/Atakan-Emre)
### Support / Destek
- GitHub Issues: [https://github.com/Atakan-Emre/McpTestGenerator/issues](https://github.com/Atakan-Emre/McpTestGenerator/issues)
