# Cursor + MCP QA Agent

[![MCP quality checks](https://github.com/Ardaka/cursor-mcp-qa-agent/actions/workflows/quality.yml/badge.svg)](https://github.com/Ardaka/cursor-mcp-qa-agent/actions/workflows/quality.yml)

A local Model Context Protocol server that gives Cursor Agent three focused QA tools, plus project rules and reusable workflows.

![Cursor](https://img.shields.io/badge/Cursor-Agent-111111)
![MCP](https://img.shields.io/badge/Model_Context_Protocol-1.30-6D5EF6)
![TypeScript](https://img.shields.io/badge/TypeScript-7-3178C6?logo=typescript&logoColor=white)

## What the agent can do

| MCP tool | Purpose |
|---|---|
| `analyze_user_story` | Extract criteria, risks, and open questions |
| `create_test_charter` | Build a timeboxed risk-based exploratory session |
| `draft_bug_report` | Format verified evidence without inventing missing details |

## Architecture

```text
Cursor Agent
  ├─ .cursor/rules/qa-agent.mdc  → behavior and safety rules
  └─ .cursor/mcp.json            → local stdio connection
                ↓
       QA MCP server (TypeScript)
          ├─ analyze story
          ├─ create charter
          └─ draft bug report
```

Cursor provides the AI reasoning. The MCP server provides small, validated, deterministic tools.

## Run and connect

```bash
npm install
npm run build
npm run smoke
```

Then open the repository in Cursor. The project-level `.cursor/mcp.json` registers the built server. Confirm `portfolio-qa-toolkit` is enabled in Cursor settings, open Agent, and paste [the feature review prompt](prompts/review-feature.md).

## Why this is safe by default

- Tools do not access the filesystem, shell, network, or issue trackers.
- Zod validates every input before execution.
- Rules prohibit invented evidence and secrets.
- Bug severity remains a human decision.
- The MCP smoke test launches the server, discovers tools, and calls one through the real protocol.

## Interview demo (3 minutes)

1. Show `.cursor/mcp.json` and the three tools in Cursor.
2. Paste the feature review prompt.
3. Let Agent call `analyze_user_story`, then create a charter.
4. Explain the boundary: Agent reasons; MCP supplies validated capabilities; a human approves conclusions.

## Project structure

```text
src/server.ts                 MCP server and schemas
src/qa-tools.ts               testable domain functions
.cursor/mcp.json              project MCP connection
.cursor/rules/qa-agent.mdc    persistent agent guidance
prompts/                      repeatable demo workflows
examples/                     sample feature description
```

## License

MIT