# docker-mcp

AI-powered Docker management: an **MCP server** exposing 32 tools for natural-language
container/image/volume/network operations, plus an **A2A multi-agent layer** where
specialized agents autonomously diagnose and remediate container failures.

## Why

Debugging a crashed container manually:

```
docker ps -a
docker inspect crashed-api
docker logs --tail 50 crashed-api
# ...squint at exit code 137, google what it means...
```

With docker-mcp you ask an LLM: *"Why did my api container crash?"* — it calls
`diagnose_container` and answers: "exit 137 = SIGKILL, OOMKilled=true → the kernel
killed it for exceeding its memory limit." Or ask *"fix it"* and `auto_heal_container`
runs the multi-agent pipeline end to end.

## Architecture

```
┌──────────┐    ┌─────────────────┐  JSON-RPC 2.0   ┌──────────────────────┐
│   LLM    │◄──►│   MCP client    │◄──(over stdio)─►│  docker-mcp server   │
│ (Claude) │    │ (Claude Desktop)│                 │  (32 MCP tools)      │
└──────────┘    └─────────────────┘                 └──────┬───────┬───────┘
                                                           │       │ auto_heal_container
                                               Docker SDK  │       │ (A2A JSON-RPC)
                                              (HTTP over   │   ┌───▼──────────────┐
                                               unix socket)│   │ diagnosis-agent  │
                                                    ┌──────▼┐  │        │artifact │
                                                    │dockerd│  │ remediation-agent│
                                                    └───────┘  └──────────────────┘
```

- **Protocol layer** — FastMCP handles the JSON-RPC handshake, advertises tool schemas
  (auto-derived from type hints + docstrings), dispatches `tools/call` requests.
- **Tool layer** — five domain modules (`containers` 11, `images` 5, `volumes` 5,
  `networks` 7, `diagnostics` 3) + the A2A bridge (1). Adding a domain = one module
  + one `register()` call.
- **Docker layer** — one lazy singleton SDK client (`client.py`); every SDK exception
  becomes a structured `{"error", "error_type"}` result so the LLM can self-correct.
- **A2A layer** — `DiagnosisAgent` (read-only evidence gathering + root-cause
  classification) and `RemediationAgent` (declarative policy table, allowlisted
  non-destructive actions, dry-run by default), chained by a transport-independent
  `Orchestrator` that discovers agents via their Agent Cards. See `docs/A2A.md`.

## Quickstart

Prerequisites: Python 3.10+, Docker running.

```bash
pip install -e .
```

Claude Desktop config (`claude_desktop_config.json`):

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

Run the A2A agents as real HTTP services (optional — the MCP bridge runs them
in-process by default):

```bash
python -m docker_mcp.a2a.serve diagnosis   --port 9001
python -m docker_mcp.a2a.serve remediation --port 9002
```

Tests (mocked daemon, no Docker needed):

```bash
python -m pytest tests/ -v   # 13 tests
```

## Tools at a glance

| Domain | Tools |
|---|---|
| Containers (11) | list, inspect, run, start, stop, restart, remove, logs, stats, exec, prune |
| Images (5) | list, pull, inspect, remove, prune |
| Volumes (5) | list, create, inspect, remove, prune |
| Networks (7) | list, inspect, create, remove, connect, disconnect, prune |
| Diagnostics (3) | diagnose_container, docker_system_info, docker_disk_usage |
| A2A bridge (1) | auto_heal_container |