<p align="center">
  <a href="./assets/readme/hero.svg">
    <img src="./assets/readme/hero.gif" width="100%" alt="PerfSage JMeter MCP — your LLM becomes a performance engineer: heal, script, discover, verdict">
  </a>
</p>

<p align="center">
  <strong>Self-healing JMeter for LLM agents.</strong><br/>
  Heal the runtime · auto-correlate scripts · discover capacity · ship a <code>p95</code>/<code>p99</code> verdict.
</p>

<p align="center">
  <a href="#-60-second-setup">🚀 Setup</a> ·
  <a href="#-why-teams-reach-for-this">✨ Why</a> ·
  <a href="#-how-it-works">🔁 Flow</a> ·
  <a href="#-tools">🧰 Tools</a> ·
  <a href="#-example-session">💬 Demo</a> ·
  <a href="https://perfsage.com">🌐 PerfSage</a>
</p>

---

## 🎯 What you get

Stop wrestling with Java paths, broken plugins, and hand-written extractors.

Point Cursor / Claude at this MCP server and ask for a performance test. It will:

1. **Heal** Java + Apache JMeter **5.6.3** + plugins under `~/.perfsage` (Docker fallback if needed)
2. **Import** HAR / OpenAPI / Postman traffic
3. **Auto-correlate** tokens, cookies, and IDs into JMeter variables
4. **Discover** the throughput knee when you don’t know the workload
5. **Report** a PASS / WARN / FAIL led by **p95 + p99** (never averages alone)

> Analysis, not dashboards. Every run ends in a decision.

---

## ⚡ 60-second setup

Requires **Python 3.10+**. Prefer [uv](https://docs.astral.sh/uv/) (macOS system `python3` is often 3.9; uv-managed Pythons also block bare `pip` via PEP 668).

```bash
# try it (no install)
uvx perfsage-jmeter-mcp --version
uvx perfsage-jmeter-mcp
```

```bash
# install as a user tool (recommended)
uv tool install perfsage-jmeter-mcp
perfsage-jmeter-mcp --version
```

```bash
# or inside a project venv
uv venv --python 3.12
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install perfsage-jmeter-mcp
```

> **Do not** run `python3.12 -m pip install …` against a uv-managed interpreter — you’ll get `externally-managed-environment`. Use `uv tool install` / `uv pip install` / a venv instead. Apple’s `/usr/bin/python3` (3.9) cannot see this package at all (`requires-python >=3.10`).

### 🔌 Connect Cursor / Claude Desktop

Drop this into your MCP config (`examples/cursor-mcp.json`):

```json
{
  "mcpServers": {
    "perfsage-jmeter": {
      "command": "uvx",
      "args": ["perfsage-jmeter-mcp"]
    }
  }
}
```

Then say:

> **“Set up the performance environment, then import `login_flow.har` and give me a capacity recommendation.”**

That’s the whole onboarding.

> **Fixture note:** `tests/recorder/fixtures/login_flow.har` targets `shop.perfsage.test`, which is **offline**. Use it to demo **correlation / JMX generation** only — not live `run_test` smoke. For runnable demos, import a HAR against a real host (for example JSONPlaceholder or your own staging URL).

---

## ✨ Why teams reach for this

| Pain today | With PerfSage JMeter MCP |
|---|---|
| ❌ “Wrong Java / missing JMeter / plugin chaos” | ✅ `ensure_environment` self-heals under `~/.perfsage` — **no sudo**, no shell-profile edits |
| ❌ Manual regex correlation for every token | ✅ `correlate_flow` detects CSRF / JWT / session IDs and wires extractors |
| ❌ Guessing thread counts | ✅ `discover_workload` finds the knee, recommends **80%** sustained load |
| ❌ Average latency gates that lie | ✅ Reports always include **p95 + p99** + SLO verdict |
| ❌ Client metrics disconnected from K8s | ✅ Optional [SignalPilot](https://github.com/perfsage/signalpilot) RCA + [Reveal](https://github.com/perfsage/reveal) charts |

---

## 🔁 How it works

<p align="center">
  <img src="./assets/readme/workflow.svg" width="100%" alt="Workflow: Heal → Import → Correlate → Discover → Verdict">
</p>

| Step | Tool | Outcome |
|:----:|---|---|
| 1️⃣ | `ensure_environment` | Ready runtime (native or Docker) |
| 2️⃣ | `import_traffic` | Clean application Flow (static noise filtered) |
| 3️⃣ | `correlate_flow` + `generate_jmx` | Replayable JMeter 5.6.3 plan |
| 4️⃣ | `edit_jmx` (optional) | Workload / structure tweaks (burst, loops, JSR223, …) |
| 5️⃣ | `run_test` / `discover_workload` | Guarded execution + capacity profile |
| 6️⃣ | `compile_report` | Markdown + HTML + JSON, verdict first |

---

## 💬 Example session

```text
You:  Set up the performance environment.
Agent: ensure_environment → ready=true, Java 21 + JMeter 5.6.3 under ~/.perfsage

You:  Import tests/recorder/fixtures/login_flow.har (correlation demo; host is offline) and correlate it.
Agent: import_traffic → 4 app requests
       correlate_flow → csrf_token, token, cart_id, SESSION (cookie-managed)

You:  Generate a fixed plan at 20 threads / 120s, then run a 5-minute burst inside 20 minutes.
Agent: generate_jmx → ${__P(perfsage.threads,20)} / ${__P(perfsage.duration,120)}
       edit_jmx → set_workload burst (Ultimate Thread Group)
       run_test / discover_workload → guarded execution + capacity

You:  Compile the report with examples/slo.properties.
Agent: compile_report → PASS/WARN/FAIL leading with p95 + p99
       artifacts → ~/.perfsage/runs/<id>/report/
```

---

## 🧰 Tools

| Tool | What it does |
|---|---|
| 🩺 `ensure_environment` | Diagnose + heal Java / JMeter / plugins / Docker |
| 🔍 `diagnose_environment` | Read-only readiness report |
| 📥 `import_traffic` | HAR / OpenAPI / Postman → Flow |
| 🔗 `correlate_flow` | Dynamic values → variables + extractors |
| 📝 `generate_jmx` | Correlated Flow → JMeter 5.6.3 plan |
| ✏️ `edit_jmx` | Structured ops on an existing plan (new file by default) |
| 🚀 `run_test` | Execute with always-on guardrails |
| 📈 `discover_workload` | Adaptive knee-point discovery |
| 📊 `analyze_results` | JTL → metrics, bottlenecks, p95/p99 |
| ✅ `evaluate_slo` | Gate against `slo.properties` |
| ☸️ `correlate_with_signalpilot` | Merge Kubernetes RCA for the test window |
| 📦 `compile_report` | Unified Markdown + HTML + JSON |

Full schemas & sample payloads: [`docs/TOOLS.md`](./docs/TOOLS.md)

---

## 🛡️ Environment gate (runs first)

Every JMeter-touching tool calls `ensure_environment` first:

| Condition | Action |
|---|---|
| Java missing / outside 17–21 | Download Temurin JDK **21** into `~/.perfsage/jdk/` |
| JMeter missing / &lt; 5.6.3 | Download Apache JMeter **5.6.3** + verify ASF SHA-512 |
| Plugins missing | Install `jpgc-casutg`, `jpgc-tst`, `jpgc-json`, `jpgc-dummy`, `perfsage-slo-reporter` |
| Host can’t be provisioned | Fall back to Docker (`justb4/jmeter`) and **say so** |
| Neither works | Structured failure: attempted · failed · values |

🔒 Nothing writes outside `~/.perfsage` (or your working directory). No `JAVA_HOME` mutations. No package-manager side effects.

---

## 🧩 Ecosystem

| Project | Role |
|---|---|
| [Reveal](https://github.com/perfsage/reveal) | JTL analysis + chart pack |
| [SLO Reporter](https://github.com/perfsage/perfsage-slo-reporter) | SLO gate format + Backend Listener |
| [SignalPilot](https://github.com/perfsage/signalpilot) | Kubernetes RCA for the test window |
| [perfsage.com](https://perfsage.com) | Brand home · Field Notes · tools |

---

## 🛠️ Development

```bash
uv run --python 3.12 --extra dev pytest
uv run --python 3.12 --extra dev ruff check .
uv run --python 3.12 --extra dev mypy perfsage_jmeter_mcp
```

Real JMeter e2e: `tests/test_end_to_end.py` (`e2e` marker).  
Architecture notes: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)

---

## 📄 License

MIT

Apache JMeter is a trademark of the Apache Software Foundation. This project is an independent tool and is not affiliated with or endorsed by the ASF.

---

<p align="center">
  <strong>Ready when your agent is.</strong><br/>
  <code>uvx perfsage-jmeter-mcp</code> · then ask it to <code>ensure_environment</code>
</p>