Metadata-Version: 2.4
Name: greenerplatform-mcp
Version: 0.1.1
Summary: MCP server exposing the GreenerPlatform deterministic reliability tools (kubectl-sentinel, incident-triage) to any AI agent.
Author: Olawale Ogundiran
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/GreenerPlatform/greenerplatform-mcp
Project-URL: Source, https://github.com/GreenerPlatform/greenerplatform-mcp
Project-URL: Issues, https://github.com/GreenerPlatform/greenerplatform-mcp/issues
Keywords: mcp,kubernetes,sre,reliability,incident,triage,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: mcp>=1.2.0
Dynamic: license-file

<div align="center">
  <img src="https://raw.githubusercontent.com/GreenerPlatform/greenerplatform-mcp/main/docs/banner.svg" alt="greenerplatform-mcp" width="100%"/>

[![PyPI](https://img.shields.io/pypi/v/greenerplatform-mcp?color=1a9c3e)](https://pypi.org/project/greenerplatform-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/greenerplatform-mcp)](https://pypi.org/project/greenerplatform-mcp/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)

</div>

# greenerplatform-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes the GreenerPlatform
deterministic reliability tools to any MCP-capable agent — **Cursor, Claude Desktop,
VS Code, Windsurf, or your own client.** Install once; the tools work everywhere.

> **Available on PyPI:** `pipx install greenerplatform-mcp`

It wraps two CLIs:

- **`sentinel_snapshot`** — a deterministic 15-dimension cluster-health snapshot
  ([kubectl-sentinel](https://github.com/GreenerPlatform/kubectl-sentinel)).
- **`triage_incident`** — correlate an alert to cluster findings, build a causation
  chain, and return a P1/P2/P3 fix plan
  ([incident-triage](https://github.com/GreenerPlatform/incident-triage)).

Neither tool carries an LLM or any vendor coupling. This server is a thin, neutral
adapter. The agent reasons over the evidence the tools produce — it is bounded by the
evidence, it does not guess at cluster state.

## Prerequisites

- Python 3.10+
- `kubectl-sentinel` and `incident-triage` on your `PATH`
  (or set `SENTINEL_BIN` / `TRIAGE_BIN` to their locations)
- `kubectl` + `jq` for live cluster snapshots

## Install

```bash
pipx install greenerplatform-mcp
# or: pip install greenerplatform-mcp
```

## Configure your agent

**Cursor** — `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "greenerplatform": { "command": "greenerplatform-mcp" }
  }
}
```

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "greenerplatform": { "command": "greenerplatform-mcp" }
  }
}
```

Any other MCP client uses the same pattern: run `greenerplatform-mcp` over stdio.

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `sentinel_snapshot` | `namespace?`, `context?`, `resource?` | cluster-health JSON |
| `triage_incident` | `alert`, `sentinel_json?`, `namespace?`, `context?` | triage JSON (cause + fix plan) |

If `triage_incident` is called without `sentinel_json`, it collects a fresh snapshot
first (requires cluster access).

## Version guard

A stale CLI silently emits fewer checks — for example, `kubectl-sentinel` 1.1.0
returns 10 of the 15 health dimensions. To keep an agent from reasoning over an
incomplete snapshot, the server checks each CLI's `--version` and, if it is below the
expected minimum, adds a non-destructive `warnings` array to the tool's JSON output:

```json
{ "warnings": ["kubectl-sentinel 1.1.0 is older than the expected 1.2.1; output may be missing checks — update kubectl-sentinel"] }
```

The findings are still returned; the warning just flags that they may be partial. Set
`MIN_SENTINEL_VERSION` / `MIN_TRIAGE_VERSION` to change the expected minimums.

## Environment

| Variable | Default | Purpose |
|---|---|---|
| `SENTINEL_BIN` | `kubectl-sentinel` on PATH | path to the sentinel binary |
| `TRIAGE_BIN` | `incident-triage` on PATH | path to the triage binary |
| `GP_MCP_TIMEOUT` | `90` | per-command timeout (seconds) |
| `MIN_SENTINEL_VERSION` | `1.2.1` | warn if the installed sentinel is older |
| `MIN_TRIAGE_VERSION` | `1.2.1` | warn if the installed triage is older |

## Releasing

Releases publish to PyPI automatically via GitHub Actions using **Trusted Publishing**
(OIDC) — no API tokens are stored anywhere.

One-time setup (on [pypi.org](https://pypi.org)):

1. Sign in → *Your projects* → *Publishing* → *Add a pending publisher*.
2. Project name `greenerplatform-mcp`, owner `GreenerPlatform`, repo `greenerplatform-mcp`,
   workflow `publish.yml`, environment `pypi`.

To cut a release:

```bash
# bump version in pyproject.toml, commit, then:
git tag v0.1.0 && git push origin v0.1.0
gh release create v0.1.0 --generate-notes
```

The `Publish to PyPI` workflow builds, runs `twine check`, and publishes. After the first
release, `pipx install greenerplatform-mcp` works for anyone.

## License

Apache-2.0. See `LICENSE`, `NOTICE`, and the project
[trademark policy](https://github.com/GreenerPlatform/kubectl-sentinel/blob/main/TRADEMARKS.md).
