# QA Assistant MCP

A production-ready MCP (Model Context Protocol) server that gives Claude Desktop and Claude Code the ability to read Jira user stories, search Confluence documentation, and generate professional QA artifacts powered by GPT-4o.

---

## Features

| Tool | Description |
|------|-------------|
| `get_user_story` | Fetch a Jira issue with summary, description, acceptance criteria, labels, priority |
| `search_confluence` | Full-text search across Confluence pages |
| `get_requirement_context` | Merge Jira story + relevant Confluence pages into one context |
| `generate_test_scenarios` | AI-generated scenario table (ID, Scenario, Priority, Risk) |
| `generate_test_cases` | Comprehensive test cases — Positive, Negative, Boundary, Validation, Permission |
| `generate_rtm` | Requirements Traceability Matrix mapping ACs to test cases |
| `analyze_test_coverage` | Coverage %, missing areas, risk areas, recommendations |
| `generate_test_summary` | Executive report with coverage, risks, and release readiness |

---

## Prerequisites

- Python 3.12+
- Jira Cloud account with API token
- Confluence Cloud account with API token
- OpenAI API key (GPT-4o access recommended)
- Claude Desktop or Claude Code

---

## Installation

### 1. Clone the repository

```bash
git clone <your-repo-url>
cd qa-mcp
```

### 2. Create a virtual environment

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate
```

### 3. Install dependencies

```bash
pip install -r requirements.txt
```

### 4. Configure environment variables

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```env
JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token

CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-api-token

OPENAI_API_KEY=sk-your-openai-api-key
```

**How to get API tokens:**
- Jira/Confluence: https://id.atlassian.com/manage-profile/security/api-tokens
- OpenAI: https://platform.openai.com/api-keys

---

## Running the Server

### Standalone test (stdio mode)

```bash
python server.py
```

### Development with MCP Inspector

```bash
mcp dev server.py
```

---

## Claude Desktop Configuration

Add to your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "qa-assistant": {
      "command": "E:\\Testing\\MCP\\MCP_QA1\\.venv\\Scripts\\python.exe",
      "args": ["C:\\full\\path\\to\\qa-mcp\\server.py"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token",
        "OPENAI_API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}
```

> **Tip:** Use the full absolute path to `server.py`. On Windows use double backslashes or forward slashes.

After saving, restart Claude Desktop.

---

## Claude Code Configuration

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "qa-assistant": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "C:\\full\\path\\to\\qa-mcp"
    }
  }
}
```

Or run directly:

```bash
claude mcp add qa-assistant python server.py
```

---

## Usage Examples

Once connected to Claude, use natural language:

```
Get the user story for US-123
```

```
Search Confluence for "payment gateway BRD"
```

```
Get the full requirement context for PROJ-456
```

```
Generate test scenarios for US-123
```

```
Generate test cases for US-123
```

```
Generate RTM for US-123
```

```
Analyze test coverage for US-123
```

```
Create a test summary report for US-123
```

---

## Project Structure

```
qa-mcp/
├── server.py                  # MCP server entry point
├── tools/
│   ├── __init__.py
│   ├── jira_tools.py          # get_user_story, get_requirement_context
│   ├── confluence_tools.py    # search_confluence
│   ├── testcase_tools.py      # generate_test_scenarios, generate_test_cases,
│   │                          #   generate_rtm, analyze_test_coverage
│   └── report_tools.py        # generate_test_summary
├── services/
│   ├── __init__.py
│   ├── jira_service.py        # Jira API wrapper (atlassian-python-api)
│   ├── confluence_service.py  # Confluence API wrapper
│   └── ai_service.py          # OpenAI GPT-4o integration
├── models/
│   ├── __init__.py
│   ├── story.py               # UserStory Pydantic model
│   └── testcase.py            # TestCase, Scenario, RTM, Coverage models
├── .env                       # Your credentials (not committed)
├── .env.example               # Template
├── requirements.txt
└── README.md
```

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `EnvironmentError: Missing Jira credentials` | Check that `.env` is in the `qa-mcp/` directory and all three Jira vars are set |
| `AuthError` from Jira/Confluence | Verify email + API token; the token is NOT your password |
| `openai.AuthenticationError` | Check `OPENAI_API_KEY` starts with `sk-` |
| Tool not appearing in Claude | Restart Claude Desktop after editing `claude_desktop_config.json` |
| `ModuleNotFoundError` | Ensure virtual environment is activated when running `server.py` |

---

## Notes

- All AI generation uses **GPT-4o** by default. Override with `OPENAI_MODEL=gpt-4o-mini` for lower cost.
- Jira and Confluence use the same Atlassian API token — same credentials work for both.
- The server reads `.env` from its own directory regardless of where you invoke it.