Metadata-Version: 2.4
Name: mcp-lava
Version: 0.1.1
Summary: MCP server that wraps lavacli (Linaro LAVA CLI)
Author-email: Larry Shen <larry.shen@nxp.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Systems Administration
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2.0
Requires-Dist: lavacli
Requires-Dist: python-certifi-win32; platform_system == "Windows"

# mcp-lava

`mcp-lava` is an **MCP (Model Context Protocol) server** that lets an LLM interact with a
[Linaro LAVA](https://gitlab.com/lava/lava) by **wrapping** the official
`lavacli` command-line tool.

Instead of re-implementing LAVA's XML-RPC API, this server executes `lavacli` locally and returns
results to the LLM in a tool-friendly way.

## Why an MCP server for LAVA?

LAVA is powerful, but day-to-day workflows often involve many repetitive CLI steps:

- checking device availability and health
- locating the right job definition
- submitting jobs and monitoring states
- pulling logs and artifacts for failed jobs
- correlating failures across multiple runs
- re-running jobs to reproduce or to confirm a fix

An LLM can help with these workflows **if** it can reliably call the right commands and parse the
outputs. `mcp-lava` provides that bridge:

- **Reuses `lavacli` subcommands and output formats** (many support `--json` / `--yaml`).
- **Keeps server logic minimal** (no duplicated API client).
- **Makes automation conversational**: "find the last failed run for this device type and summarize
  the failure", "show me the first kernel panic in the logs", etc.

## Example scenarios

A few practical things you can do with an LLM + `mcp-lava`:

1. **Triage a failure quickly**
   - List recent jobs for a project
   - Detect failures, fetch logs, and summarize the suspected root cause
   - Extract the first occurrence of an error pattern (e.g. *kernel panic*, *timeout*, *SSH failed*)

2. **Lab status overview**
   - List devices and filter to offline/retired/busy
   - Show which workers are overloaded
   - Identify the most flaky device type based on recent job outcomes

3. **Job submission assistance**
   - Validate that a device type exists
   - Submit a job definition
   - Track the job until completion and then download artifacts

4. **Re-run / reproduce / confirm a fix ("rerun" workflow)**
   - Re-run the same job definition to reproduce a failure on demand
   - Re-run on a different device (or a different device type) to separate lab flakiness from real
     regressions
   - Re-run after changing one variable (new kernel, new rootfs, different test plan) and compare
     outcomes
   - Compare logs/artifacts between the original run and the rerun to spot what changed

5. **Routine reporting**
   - "Summarize all failed jobs in the last 24h, grouped by device type"
   - "Show the top 3 failure signatures and link to the relevant logs"

## Installation

Create/activate a virtual environment, then install:

```
python -m venv .venv
# Activate the venv (command depends on your shell)
python -m pip install -U pip
pip install mcp-lava
```

Alternatively, you can also use `uvx mcp-lava` to run it directly without installing to your system Python.

## Configuration (required)

`mcp-lava` authenticates to LAVA by creating/refreshing a **lavacli identity** at startup and then
running all subsequent commands using that identity.

Set these environment variables:

- `LAVA_URL` - Base URL or RPC endpoint. If it doesn't end with `/RPC2`, the server appends it.
- `LAVA_USERNAME` - LAVA username.
- `LAVA_AUTHENTICATION_TOKEN` - LAVA token.

Optional:

- `LAVA_IDENTITY` - Identity name to use (default: `mcp`).
- `LAVA_SSL_VERIFY` - `true`/`false` (default: `true`).

A minimal way to represent variables (set them using your preferred method):

```text
LAVA_URL=https://lava.example.com
LAVA_USERNAME=your.user
LAVA_AUTHENTICATION_TOKEN=<your-token>
```

## Running the MCP server

This server uses the **stdio transport** (typical for MCP servers).

```
mcp-lava
```

Equivalent:

```
python -m mcp_lava.server
```

## Tools

### `lava_run`

Run *any* `lavacli` command.

- `args` must be an **argv token list** (a list of strings): exactly what you would type after
  `lavacli`.

Examples:

- `lavacli devices list` -> `args=["devices", "list"]`
- `lavacli devices show qemu0` -> `args=["devices", "show", "qemu0"]`
- `lavacli devices list --json` -> `args=["devices", "list", "--json"]`

Do **not** pass a single space-separated string like `args=["devices list"]`.

### `lava_help`

Get `lavacli --help`, or help for a specific command group.

### `lava_command_tree`

Introspect the installed `lavacli` Python package and return its command/subcommand tree.
