# sre-toolkit-mcp

An [MCP](https://modelcontextprotocol.io) server that gives LLM agents **correct SRE reliability math** instead of letting them eyeball it.

Language models are confident but bad at arithmetic, and reliability decisions are exactly where a confident wrong number is expensive. This server exposes deterministic, unit-tested tools for the calculations that actually gate a deploy — error budgets, burn rate, blast radius, and composite SLOs — so an agent asks a tool and gets an auditable verdict.

The design bias throughout is **verification over autonomy**: any change with real blast radius returns a confirmation gate rather than a green light.

## Tools

| Tool | What it answers |
| --- | --- |
| `error_budget` | Given an SLO and traffic, how much budget is left and is it safe to ship? |
| `burn_rate` | How fast is the current error rate spending the budget, and does it warrant paging? |
| `blast_radius` | Does this change touch too much of the fleet to run without human approval? |
| `composite_slo` | What end-to-end availability do these dependent services actually deliver? |
| `prometheus_query` | Run a PromQL query and get the real numbers instead of typing them in. |
| `loki_query` | Search logs with LogQL over a time window. |
| `alertmanager_alerts` | What's already firing, before proposing a change or paging. |
| `slo_recording_rules` | Emit Prometheus recording rules for an SLI error ratio, ready to commit. |
| `generate_burn_alerts` | Emit the standard multiwindow multi-burn-rate Prometheus alerts, ready to commit. |

`burn_rate` severities follow the multiwindow burn-rate guidance from the Google SRE Workbook: pass a `short_window_error_rate` alongside the primary rate and it only pages when both windows agree, which suppresses false pages from a short-lived spike. `blast_radius` applies a stricter fraction ceiling in `prod` than in lower environments and flips to a confirmation gate above it.

The observability tools turn the math from "type in your error count" into "compute the budget from the actual SLI" — an agent can call `prometheus_query` for a live error rate and feed it straight into `error_budget` or `burn_rate`. Each backend's URL is configurable via an env var, defaulting to a home-lab setup:

| Tool | Env var | Default |
| --- | --- | --- |
| `prometheus_query` | `PROMETHEUS_URL` | `http://localhost:9090` |
| `loki_query` | `LOKI_URL` | `http://localhost:3100` |
| `alertmanager_alerts` | `ALERTMANAGER_URL` | `http://localhost:9093` |

Beyond verdicts, the server also generates policy: `slo_recording_rules` and `generate_burn_alerts` turn an SLO target into the actual Prometheus rule YAML a team commits — the standard four-tier fast/slow burn page+ticket alerts from the Google SRE Workbook, wired to the recording rules by metric name so the pair stays consistent. Run `slo_recording_rules` first, then `generate_burn_alerts` with the same `service` name.

## Install

```bash
git clone https://github.com/arpothireddy/sre-toolkit-mcp.git
cd sre-toolkit-mcp
pip install -e .
```

## Run

```bash
sre-toolkit-mcp          # starts the MCP server over stdio
```

## Use it from Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sre-toolkit": {
      "command": "sre-toolkit-mcp"
    }
  }
}
```

Then ask things like *"We're at 99.9% on the checkout service with 3M requests this month and 4,200 errors — are we clear to ship?"* and the agent will call `error_budget` and reason from the real number.

## Example

```python
from sre_toolkit_mcp import blast_radius

verdict = blast_radius(targeted=30, fleet_total=100, environment="prod")
print(verdict.severity)               # "blocked"
print(verdict.requires_confirmation)  # True
```

## Develop

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT