Ops

🇬🇧 English · 🇪🇸 Español

🔌 ops-mcp

One MCP server. Your AI agent just learned forensics.

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

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 as native tools for any MCP client — Claude Desktop, opencode, Cursor, or anything that speaks stdio JSON-RPC:

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

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):

{
  "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.

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:

{
  "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.
• container_obituary(container) — a shorter, warmer goodbye: lifespan, cause of death, final words. Powered by 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.

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.

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.

🗺️ 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.

Built AI-first by Fernedy Arias · Tech Explorer

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