🩺 Triage — a self-healing ops MCP for any Dockerized service

Let an AI agent (or a human) check, diagnose, and recover a service — without a host shell.

Most "give the agent ops powers" setups are bad: you either hand the model a raw shell (now it can roam the whole box and conflate unrelated subsystems), or you wire up dashboards a model can't read. Triage is the third option:

A small MCP server that exposes a handful of health/diagnose/recover tools. Each returns raw evidence AND a plain-English translation, a suggested action, and whether the fix is safe to auto-apply. The agent acts through tools — it never touches the host directly.

The policy that makes it safe

The dual raw + layman output is the differentiator: the agent gets structured data to act on, and the human gets a sentence they can actually understand ("Postiz's API engine isn't running — the known cold-boot hiccup. I'll restart it.").

Related MCP server: Docker Manager MCP

Tools

Configure (zero code changes)

Everything is env-driven — point it at any compose-managed service:

TRIAGE_COMPOSE=/path/to/docker-compose.yaml   # compose file
TRIAGE_SERVICE=app                            # the main container/service name
TRIAGE_LABEL="My App"                         # friendly name used in messages
TRIAGE_PROCS=backend,worker                   # optional: in-container processes to watch
TRIAGE_PROC_MGR=pm2                           # "pm2" | "none"
TRIAGE_DB_PING="docker exec app-db pg_isready"  # optional: rc 0 = dependency healthy
TRIAGE_RISKY_CMD=""                           # optional: a guarded recovery (clear a queue, etc.)
TRIAGE_RISKY_DESC="clear the stuck job queue"
TRIAGE_PORT=9500

See .env.example.

Run

pip install -r requirements.txt
python3 triage.py            # serves an MCP over streamable-http on TRIAGE_PORT

Register it with your agent runtime (any MCP client). For an always-on host service, use the included launchd template com.triage.ops.plist (macOS) — adapt to systemd on Linux.

Hard-won lessons baked in

• Agents in a container can't see host processes. Give them status tools, not a shell. With shell access a model conflates unrelated subsystems and reports false negatives. Tools keep it honest.

• Two reports, always. Structured raw for the agent to branch on; a one-sentence layman for the human. A health check the human can't read is half a tool.

• Encode the safe/risky boundary in the tool, not the prompt. "Don't clear the queue without asking" in a system prompt is a suggestion; a confirm=true-gated dry-run is a guarantee.

• docker compose ps --format json varies by version (NDJSON vs single array) — handle both.

• Recover ≠ restart. A dead process needs a restart; an unhealthy container needs a recreate. Separate tools so the agent escalates correctly.

Built by

Built by KodeKing · author Fazal Shah. We build local, private, multi-agent AI systems for teams who can't send their data to the cloud. Issues and PRs welcome.

License

MIT — see LICENSE.