npm package: @smartcase/mcp
Description: SmartCase MCP server — expose AI-generated QA test suites to any MCP-compatible IDE or CI/CD pipeline
Latest version: 0.3.0

# @smartcase/mcp

> SmartCase MCP server — expose AI-generated QA test suites to Cursor, Claude Desktop, and CI/CD pipelines via the [Model Context Protocol](https://modelcontextprotocol.io).

## Quick Start

### 1. Create an API Key

Go to **Settings → API Keys** in your SmartCase account and create a new key (`sk-smrt-...`).

### 2. Configure your IDE

#### Cursor / Claude Desktop

Add to your `mcp.json` (Cursor: `~/.cursor/mcp.json`, Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "smartcase": {
      "command": "npx",
      "args": ["-y", "@smartcase/mcp"],
      "env": {
        "FLOWSPECQA_API_KEY": "sk-smrt-your-key-here",
        "FLOWSPECQA_BASE_URL": "https://www.flowspecqa.com"
      }
    }
  }
}
```

Restart Cursor/Claude and the SmartCase tools will appear automatically.

---

## Available Tools

| Tool | What it does |
|---|---|
| `list_entities` | List entities (HU-xxx) in a project with their spec review status |
| `get_test_suite` | Fetch all generated test files for a run ID |
| `generate_suite` | Trigger AI generation for an entity, returns a `run_id` |
| `setup_and_run` | Download suite + generate `playwright.config.ts` with HTML & JSON reporters |
| `push_results` | Push test execution results back to SmartCase |

### Example agent prompt (Cursor)

```
Use SmartCase to generate and run a Playwright suite for entity HU-042 in project abc-123
against https://staging.myapp.com. Push the results when done.
```

The agent will: generate_suite → setup_and_run → write files → run Playwright → push_results.

---

## CI/CD — GitHub Actions

```yaml
name: SmartCase + Playwright

on: [push]

jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch test suite from SmartCase
        env:
          FLOWSPECQA_API_KEY: ${{ secrets.FLOWSPECQA_API_KEY }}
          FLOWSPECQA_BASE_URL: https://www.flowspecqa.com
        run: |
          npx -y @smartcase/mcp get-suite \
            --run-id ${{ vars.SMARTCASE_RUN_ID }} \
            --output ./tests/generated

      - name: Install Playwright
        run: npx playwright install --with-deps

      - name: Run tests
        run: npx playwright test ./tests/generated --reporter=json > results.json

      - name: Push results to SmartCase
        env:
          FLOWSPECQA_API_KEY: ${{ secrets.FLOWSPECQA_API_KEY }}
        run: |
          npx @smartcase/mcp push-results \
            --run-id ${{ vars.SMARTCASE_RUN_ID }} \
            --results-file results.json
```

---

## Environment Variables

| Variable | Required | Default |
|---|---|---|
| `FLOWSPECQA_API_KEY` | ✅ Yes | — |
| `FLOWSPECQA_BASE_URL` | No | `https://www.flowspecqa.com` |

---

## Local Development

```bash
git clone https://github.com/pablomra/smartcase.git
cd flowspecqa-mcp
npm install
npm run build

# Test with MCP Inspector
FLOWSPECQA_API_KEY=sk-smrt-... npx @modelcontextprotocol/inspector node dist/index.js
```

---

## Score Semantics

| Score | Meaning |
|---|---|
| **Design Score** | Code quality · maintainability (0–100) |
| **Run-Ready Score** | 100 = zero BLOCKERs, safe to execute; <100 = fix issues first |

`get_test_suite` will warn you if the suite has BLOCKERs before you run it.