# Docker MCP Server (`docker-mcp`)

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Architecture: Deep Module](https://img.shields.io/badge/architecture-Deep%20Module-blue.svg)](./CONTEXT.md)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)

Model Context Protocol (MCP) server providing high-leverage tools for inspecting, orchestrating, and troubleshooting Docker Engine and Docker Compose environments.

Built on [@thargy/mcp-server-core](https://github.com/thargy/mcp-server-core) following John Ousterhout’s **Deep Module** philosophy (*A Philosophy of Software Design*).

---

## 1. Architectural Vision: Deep Module vs. Tool Bloat

Traditional MCP servers map 1:1 to Docker CLI verbs, resulting in 25+ shallow tools that bloat LLM context windows (consuming 4,000+ prompt tokens per turn) and increase hallucinations.

`docker-mcp` exposes exactly **6 consolidated, high-leverage tools** with polymorphic typed action discriminators, consuming **<1,000 tokens**:

```mermaid
graph LR
    subgraph Clients ["MCP Clients"]
        Claude["Claude Desktop (Stdio)"]
        Agent["Antigravity / Coding Agents"]
        Gateway["mcp-gateway (SSE / Streamable HTTP)"]
    end

    subgraph DeepModule ["docker-mcp (Deep Module)"]
        T1["docker_containers"]
        T2["docker_compose"]
        T3["docker_images"]
        T4["docker_volumes"]
        T5["docker_networks"]
        T6["docker_system"]
        
        Seam["IDockerClient Seam"]
        Engine["DockerodeClient / InMemoryDockerClient"]
    end

    subgraph Host ["Docker Infrastructure"]
        Socket["/var/run/docker.sock"]
        RemoteTCP["tcp://remote-host:2376"]
        RemoteSSH["ssh://user@remote-host"]
    end

    Clients --> DeepModule
    DeepModule --> Seam
    Seam --> Engine
    Engine --> Host
```

---

## 2. Consolidated MCP Tool Catalog

| Tool | Actions | Capabilities & Highlights |
| :--- | :--- | :--- |
| **`docker_containers`** | `list`, `inspect`, `start`, `stop`, `restart`, `logs`, `stats`, `exec`, `remove` | Name/status regex filtering, real-time CPU/RAM calculation, multiplexed stdout/stderr log extraction, command execution, safe timeouts. |
| **`docker_compose`** | `ps`, `up`, `down`, `restart`, `logs` | Multi-container stack discovery via labels/directories, lifecycle orchestration, healthcheck readiness verification. |
| **`docker_images`** | `list`, `inspect`, `pull`, `prune`, `remove` | Image inventory, virtual size formatting, tag resolution, dangling image cleanup. |
| **`docker_volumes`** | `list`, `inspect`, `create`, `prune`, `remove` | Persistent volume catalog, driver inspection, orphan volume pruning. |
| **`docker_networks`** | `list`, `inspect`, `create`, `prune`, `remove` | Bridge, overlay, and macvlan network topology inspection and subnet resolution. |
| **`docker_system`** | `info`, `df`, `prune`, `version`, `ping` | Daemon healthcheck, engine version, disk usage breakdown, system-wide reclamation. |

---

## 3. Quickstart & Configuration

### Environment Variables

| Variable | Default | Description |
| :--- | :--- | :--- |
| `PORT` | `3008` | HTTP / SSE listen port |
| `HOST` | `0.0.0.0` | Bind address |
| `MCP_TOKEN` | *optional* | Secret token for Bearer authentication over HTTP / SSE |
| `DOCKER_SOCKET` | `/var/run/docker.sock` | Path to local Unix Docker socket |
| `DOCKER_HOST` | *optional* | Remote Docker TCP URL (e.g. `tcp://192.168.86.50:2376`) |
| `DOCKER_TLS_VERIFY` | *optional* | Enable TLS certificate verification (`1` or `0`) |
| `DOCKER_CERT_PATH` | *optional* | Path to client TLS certificates (`ca.pem`, `cert.pem`, `key.pem`) |

### Running with Stdio (Claude Desktop / Local CLI)

```json
{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/Users/craigdean/Repos/docker-mcp/dist/src/index.js"],
      "env": {
        "DOCKER_SOCKET": "/var/run/docker.sock"
      }
    }
  }
}
```

### Running with Docker Compose & `mcp-gateway`

```bash
docker compose up -d --build
```

Access HTTP SSE at `http://localhost:3008/docker/mcp` or `http://localhost:3008/docker/sse`.

---

## 4. Testing & Code Quality

100% of unit tests execute against `InMemoryDockerClient` without requiring access to a live Docker socket.

```bash
# Run unit tests
npm test

# Run test coverage (>85% required)
npm run test:coverage

# TypeScript compile check
npm run types:check
```

---

## License

MIT © 2026 Craig Dean