@loadmill/mcp/README.md

Loadmill mcp library

# Loadmill MCP Server

The Loadmill MCP server exposes Loadmill’s test-management APIs to any Model Context Protocol (MCP) client. Use it to search, run, write and validate Loadmill tests without leaving your MCP-enabled IDE or agent workflow.

## Use Cases
 - Query Loadmill for information
 - Execute Loadmill tests
 - Write and maintain Loadmill tests

*Note*: When working with MCPs, make sure your client runs in `Agent` mode.

## IDE Integration

### VS Code

*Important*: You will have to generate a Loadmill API token from your [Loadmill account settings](https://app.loadmill.com/app/user/settings/security) to authenticate the MCP server.
```
{
  "servers": {
    "loadmill": {
      "type": "stdio",
      "command": "npx",
      "args": ["@loadmill/mcp"],
      "env": {
        "LOADMILL_API_TOKEN": "${input:loadmill-api-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "loadmill-api-token",
      "type": "promptString",
      "description": "Loadmill API token",
      "password": true
    }
  ]
}
```

### Cursor

```
{
  "mcpServers": {
    "loadmill": {
      "command": "npx",
      "args": ["@loadmill/mcp"],
      "env": {
        "LOADMILL_API_TOKEN": "${env:LOADMILL_API_TOKEN}"
      }
    }
  }
}
```


## MCP Capabilities

**Tools** – Supports `list_tools` and `call_tool`; each tool returns standard MCP text content:
- `search_test_suites` – Filter Loadmill test suites by text, dates, or labels.
- `search_test_suite_runs` – Search historical test-suite flow runs.
- `run_test_suite` – Trigger a test-suite execution by ID.
- `get_test_suite_run` – Retrieve run details (including flow run IDs).
- `get_test_suite_flow_run` – Inspect an individual flow run by ID.
- `search_test_plans` – Browse Loadmill test plans.
- `run_test_plans` – Start a plan with optional labels and parameter overrides.
- `get_test_plan_run` – Fetch plan-run status and metadata.
- `get_labels` – List team labels (id and description).
- `validate_test_suite` – Validate a local Loadmill test-suite JSON file against the official schema.

**Prompts** – Supports `list_prompts` and `get_prompt`:
- `investigate_failed_test` – Summarise a failed run and advise next steps.
- `create_test_suite` – Generate a Loadmill test-suite JSON that conforms to the schema resource.

**Resources** – Supports `list_resources` and `read_resource`:
- `loadmill://schemas/test-suite@v1` – JSON Schema (draft 2020-12) for Loadmill test suites. Responses are cached locally for an hour.

## Working with the Test-Suite Schema
- Use `validate_test_suite` to catch schema violations in local JSON files before uploading them to Loadmill.
- The `create_test_suite` prompt relies on the same schema resource, ensuring generated suites are schema-compliant.

Once connected, your MCP client can mix these tools, prompts, and resources to automate Loadmill QA workflows end-to-end.