# JMeter MCP Server

An MCP server for generating, validating, running, and reporting Apache JMeter API performance tests from structured API sources.

The project is designed for SDETs and automation engineers who want LLM-assisted test-plan creation without letting the LLM write arbitrary JMX. The LLM supplies structured MCP tool arguments; TypeScript code validates the input, applies deterministic load policies, renders JMX, and validates the generated file.

## Features

- Generate JMeter `.jmx` plans from OpenAPI files or explicit endpoint details.
- Deterministic test profiles: `smoke`, `baseline`, `load`, `spike`, `stress`, `soak`, and `custom`.
- Zod-validated MCP tool inputs.
- Guardrails for aggressive load, documented rate limits, and profile mismatch.
- Runtime parameterization for credentials with JMeter properties such as `${__P(API_KEY,)}`.
- OS-agnostic JMeter binary resolution through `JMETER_BIN`, `JMETER_HOME`, or `jmeter` on `PATH`.
- TypeScript runner scripts for individual JMX files, suites, and JTL summary reports.
- GitHub Actions CI for strict TypeScript build and guardrail tests.

## Prerequisites

- Node.js `>=22`
- npm
- Apache JMeter `5.6.x` or compatible
- Java supported by your JMeter installation

JMeter can be discovered in one of three ways:

```bash
export JMETER_BIN=/absolute/path/to/jmeter
```

or:

```bash
export JMETER_HOME=/absolute/path/to/apache-jmeter
```

or by having `jmeter` available on `PATH`.

## Install

```bash
npm ci
npm run build:all
npm test
```

## MCP Usage

Build the server:

```bash
npm run build
```

Configure your MCP client to run:

```bash
node /absolute/path/to/jmeter-mcp-server/build/index.js
```

Or use a short command after linking the package locally:

```bash
npm link
jmeter-mcp-server
```

See [docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md) for Claude, Claude Code, VS Code/Copilot-style, Continue-style, and generic MCP client examples.

Use the high-level tool for deterministic generation:

```text
create_test_plan_from_api_source
```

Prefer this high-level tool over step-by-step JMX edits. It validates inputs, applies load-profile policy, renders a complete plan, and validates the generated JMX.

## Test Profiles

| Profile | Users | Ramp-up | Loops | Duration | Notes |
| --- | ---: | ---: | ---: | ---: | --- |
| `smoke` | 1 | 1s | 1 | none | Minimal validation |
| `baseline` | 5 | 5s | 1 | none | Safe default |
| `load` | 10 | 30s | 3 | none | Moderate load |
| `spike` | 25 | 1s | 1 | none | Requires `allowAggressiveLoad=true` |
| `stress` | 50 | 60s | 5 | none | Requires `allowAggressiveLoad=true` |
| `soak` | 5 | 60s | forever | 1800s | Requires `allowAggressiveLoad=true` |
| `custom` | required | optional | optional | optional | Fully explicit |

Deterministic profiles reject mismatched overrides. For example, `testProfile=baseline` with `users=6` fails. Use `testProfile=custom` when you need custom values.

## Guardrails

The generation path is intentionally constrained:

```text
LLM request
  -> MCP tool schema
  -> Zod validation
  -> deterministic profile policy
  -> source parsing
  -> normalized test plan model
  -> JMX renderer
  -> generated JMX validation
  -> output file
```

The MCP rejects:

- missing `users` for `custom` profiles
- deterministic profile overrides that do not match policy
- aggressive profiles without `allowAggressiveLoad=true`
- estimated request rates above a documented OpenAPI rate limit unless explicitly allowed
- malformed headers, placeholder hosts, unsupported protocols, and incomplete request body metadata

Generated JMX validation checks required JMeter components, thread settings, loop settings, duration settings, endpoint target, headers, variables, assertions, and result collectors.

## Credentials And Variables

Do not commit `.env`.

Copy the example locally:

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

Generated JMX files use JMeter properties and do not need secrets embedded:

```xml
${__P(API_KEY,)}
${__P(OAUTH_CLIENT_ID,)}
${__P(OAUTH_CLIENT_SECRET,)}
```

At runtime, pass values through JMeter properties or set `JMETER_ENV_FILE`:

```bash
JMETER_ENV_FILE=.env npm run jmeter:run -- jmeter/API_Test_Plan_4th_API.jmx results/local-run
```

## Scripts

Build:

```bash
npm run build:all
```

Run guardrail tests:

```bash
npm test
```

Generate JMX suite from OpenAPI:

```bash
npm run generate:jmeter:suite -- openapi.yaml jmeter 5
```

Run one JMX:

```bash
npm run jmeter:run -- jmeter/API_Test_Plan_1st_API.jmx results/local-run
```

Run a suite:

```bash
npm run jmeter:suite -- jmeter results/suite
```

Generate a suite report from JTL files:

```bash
npm run jmeter:report -- results/suite/<run-directory>
```

## Rate Limits And Public APIs

Do not run aggressive tests against public or third-party APIs unless the API owner explicitly allows it.

For public practice APIs, prefer `smoke` or `baseline`. Profiles such as `spike`, `stress`, and `soak` require explicit opt-in through `allowAggressiveLoad=true`.

## Repository Hygiene

Ignored by default:

- `.env`, `.env.*`
- `.continue/`, `.vscode/`
- `node_modules/`
- `build/`
- `results/`
- `*.log`
- `*.jtl`

Commit-worthy files are source, configuration, docs, workflows, OpenAPI examples, and intentional JMX examples.

## Development

```bash
npm ci
npm run build:all
npm test
```

CI runs:

```bash
npm run ci
```

which performs a strict TypeScript build and guardrail tests.

## Status

This project is suitable for early public adoption by SDETs who are comfortable with MCP, JMeter, and TypeScript. The core guardrails are deterministic and tested. Additional API source adapters such as Postman collections, HAR files, or GraphQL schemas can be added behind the existing adapter interfaces.