<div align="center">

[🇬🇧 English](README.md) · [🇪🇸 Español](README.es.md)

</div>

<div align="center">

# 🔌 ops-mcp

**One MCP server. Your AI agent just learned forensics.**

![Python](https://img.shields.io/badge/python-3.8%2B-blue?style=flat-square&logo=python&logoColor=white)
![Dependencies](https://img.shields.io/badge/dependencies-0-00A884?style=flat-square)
![Protocol](https://img.shields.io/badge/protocol-MCP%20stdio-8A2BE2?style=flat-square)
![Docker](https://img.shields.io/badge/deployed%20with-docker-2496ED?style=flat-square&logo=docker&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)

**Zero dependencies · One file · The MCP framing is implemented by hand**

</div>

---

You already have AI agents. What they don't have is your ops tooling.

**ops-mcp** is a Model Context Protocol server that exposes the [fernedy ops suite](https://github.com/fernedy) as native tools for any MCP client — Claude Desktop, opencode, Cursor, or anything that speaks stdio JSON-RPC:

| Tool | Your agent can now ask... |
|---|---|
| `container_autopsy` | *"Why did my-api die last night? Give me evidence and the fix."* |
| `container_obituary` | *"Write the obituary for the container that just died."* |
| `git_sins` | *"How sinful is the history of this repo we're about to fix?"* |

No glue code, no copy-pasting terminal output into a chat window. The agent calls the tool, gets the markdown report, and reasons over it.

## ⚡ Quickstart

```bash
git clone https://github.com/fernedy/ops-mcp.git
git clone https://github.com/fernedy/container-autopsy.git   # sibling repos
git clone https://github.com/fernedy/death-noticer.git
git clone https://github.com/fernedy/git-sins.git

cd ops-mcp
python ops_mcp.py          # MCP stdio server, ready for any client
```

Point your MCP client at it (Claude Desktop example):

```json
{
  "mcpServers": {
    "ops-mcp": {
      "command": "python",
      "args": ["/path/to/ops-mcp/ops_mcp.py"]
    }
  }
}
```

## 🐳 Deployed with Docker

The image is self-contained: it clones the three tool repos at build time.

```bash
docker build -t ops-mcp .
# clients must keep stdin open (-i): MCP speaks stdio
docker run --rm -i -v /var/run/docker.sock:/var/run/docker.sock ops-mcp
```

Or configure the client directly:

```json
{
  "mcpServers": {
    "ops-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-v", "/var/run/docker.sock:/var/run/docker.sock",
               "ghcr.io/fernedy/ops-mcp:latest"]
    }
  }
}
```

## 🧰 The tools

- **`container_autopsy(container, tail?)`** — full forensic workup of a dead (or running) container: evidence table, cause of death, contributing findings, the fix. Powered by [container-autopsy](https://github.com/fernedy/container-autopsy).
- **`container_obituary(container)`** — a shorter, warmer goodbye: lifespan, cause of death, final words. Powered by [death-noticer](https://github.com/fernedy/death-noticer).
- **`git_sins(repo, share?)`** — a confession of any git repository: nine sins with evidence and penance, 0–100 Sin Score. Powered by [git-sins](https://github.com/fernedy/git-sins).

Everything is **read-only**: the server invokes the tool CLIs in their own repos (`OPS_MCP_TOOLS_HOME`, defaults to the parent directory). It never restarts, mutates or writes to your infrastructure.

## 🤖 AI First, by construction

This server *is* the AI-First layer: the deterministic tools stay the source of truth, and your agent becomes the interface that interprets and explains their reports. Human in the loop is unchanged — tools diagnose, humans act.

## 🛠️ How it's built

One Python file, zero dependencies. The MCP stdio framing (newline-delimited JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`, `ping`) is implemented by hand — read the source as the protocol documentation.

```bash
python -m unittest discover -v   # 14 tests: real stdio handshake, real tool calls
```

The suite spawns the actual server process and speaks MCP to it, including a real `git_sins` call against a real temp repository. CI runs on Python 3.8, 3.10 and 3.12. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).

## 🗺️ Roadmap

This is step 2 of a linear path: **tools → MCP server → guard agent**. Step 3 is an always-on agent that listens for container deaths, diagnoses them through this server and prepares the fix as a PR for human approval.

## 📜 License

MIT — see [LICENSE](LICENSE).

---

<div align="center">

Built AI-first by [Fernedy Arias](https://github.com/fernedy) · Tech Explorer

*If ops-mcp made your agent actually useful at 3 AM, drop a ⭐.*

</div>