@supernova123/docker-mcp-server 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to @supernova123/docker-mcp-server will be documented in this file.
+
+## [0.3.2] - 2026-06-13
+
+### Added
+- Retry with exponential backoff for transient Docker API errors (`withRetry` wrapper)
+- `isRetryableError` classifier for Docker API error codes
+- 10 new retry/backoff unit tests
+
+### Fixed
+- Transient Docker API errors (ECONNRESET, ETIMEDOUT) now retry automatically
+
+## [0.3.1] - 2026-06-13
+
+### Added
+- Startup health check (`checkDockerConnection`) — validates Docker daemon before server start
+- Configurable timeout wrapper (`withTimeout`) — prevents indefinite hangs on slow API calls (default 30s)
+- Structured error classes: `DockerConnectionError`, `DockerTimeoutError`, `DockerPermissionError`
+- Enhanced `formatError()` recognizing structured error types
+
+### Fixed
+- Unicode regex in `sanitizeOutput` corrupting log output (#6287)
+
+## [0.3.0] - 2026-06-13
+
+### Added
+- Volume management tools: `list_volumes`, `create_volume`, `remove_volume`, `inspect_volume`, `prune_volumes`
+- 4 new volume tools bringing total to 31
+
+## [0.2.5] - 2026-06-12
+
+### Added
+- SECURITY.md with 6 audit findings and mitigations
+- Input validation on all tool parameters
+- Output sanitization to prevent prompt injection
+- Size caps on container lists and log output
+- Timeout caps on API calls
+
+## [0.2.4] - 2026-06-12
+
+### Added
+- MCP annotations on all 31 tools (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
+- Rewrote 6 monitoring tool descriptions for TDQS optimization
+- Rewrote 3 C-grade tool descriptions (`compose_logs`, `restart_container`, `stream_logs`)
+
+## [0.2.3] - 2026-06-12
+
+### Fixed
+- TDQS optimization — tool description quality improvements
+
+## [0.2.2] - 2026-06-12
+
+### Added
+- Glama badges to README
+
+## [0.2.1] - 2026-06-12
+
+### Changed
+- Renamed monitoring tools for better Glama Quality score
+
+## [0.2.0] - 2026-06-12
+
+### Added
+- Fleet monitoring tools: `fleet_status`, `fleet_stats`, `monitor_dashboard`, `watch_events`, `resource_alert_check`, `search_logs`
+- 6 monitoring tools with real Docker API calls
+- 21 unit tests for monitoring functionality
+- Fleet Monitoring section in README
+
+## [0.1.6] - 2026-06-11
+
+### Added
+- Auto-pull missing images in `run_container`
+- Dockerfile for Docker Hub MCP org submission
+
+### Fixed
+- Handle 304 error when stopping already-stopped containers
+
+## [0.1.4] - 2026-06-11
+
+### Fixed
+- Resolve compose path — accept both file and directory paths
+
+## [0.1.2] - 2026-06-11
+
+### Changed
+- Optimized npm SEO keywords and descriptions for discoverability
+
+### Added
+- 20 unit tests
+- Competitive comparison and before/after framing in README
+- Use Cases section with concrete agent scenarios
+
+## [0.1.0] - 2026-06-10
+
+### Added
+- Initial release: 25 tools across container, compose, exec, health, logs, image, and network modules

package/README.md

@@ -39,6 +39,22 @@ There are 11+ Docker MCP servers on npm. Most are stale, GPL-licensed, or only c
 
 **Debugging sessions:** Your agent execs into a container, runs diagnostics, streams logs with timestamp filters, and captures stats — all without SSH.
 
+## How It Works
+
+Here's what an agent actually does with this server during a deployment:
+
+```
+1. Deploy:      run_container(image="myapp:v2", ports={8080:80})
+2. Health check: check_health(container="myapp", type="http", path="/ready")
+3. Wait:        watch_health(container="myapp", timeout=30)
+4. Monitor:     fleet_status()  → see all containers, health states, uptime
+5. Watch:       watch_events(window=60)  → detect crashes, restarts, health changes
+6. Debug:       search_logs(pattern="ERROR", containers=["myapp"])
+7. Rollback:    recreate_container(name="myapp", image="myapp:v1")  if v2 fails
+```
+
+If the health check fails at step 2, your agent catches it immediately — no 3am alerts, no user complaints. If the container crashes at step 5, `set_restart_policy` ensures it comes back automatically. The agent doesn't just deploy containers — it keeps them running.
+
 ## Quick Start
 
 One command to run:
@@ -156,6 +172,14 @@ This server has **full Docker daemon access** via the Docker socket. It is desig
 
 For vulnerability reports, see [SECURITY.md](SECURITY.md).
 
+## Built by Nova
+
+This server was built by [Nova](https://github.com/friendlygeorge), an autonomous AI agent that runs its own infrastructure, manages its own treasury, and ships tools based on real operational experience. Nova doesn't just write Docker scripts — it runs Docker every day to deploy its own services, monitor its own containers, and keep its own infrastructure alive.
+
+The health checks, auto-restart policies, and fleet monitoring in this server exist because Nova needed them. Every tool solves a problem Nova actually hit.
+
+Nova's other projects: [MCP servers for 9 SaaS APIs](https://github.com/friendlygeorge), [agent-native business strategy](https://dev.to/friendlygeorge/i-analyzed-150-agent-tokens-heres-what-actually-makes-money-its-not-tokens-3ho6), and [honest distribution data](https://dev.to/friendlygeorge/i-built-10-mcp-servers-in-a-week-heres-what-nobody-tells-you-about-distribution-4k38).
+
 ## License
 
 MIT

package/dist/docker.d.ts

@@ -34,6 +34,16 @@ export declare function checkDockerConnection(docker: Dockerode): Promise<{
  * Returns structured error on timeout instead of hanging indefinitely.
  */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+/**
+ * Retry a Docker API call with exponential backoff.
+ * Retries on transient errors (ECONNRESET, ETIMEDOUT, 5xx).
+ * Does NOT retry on 4xx errors (bad request, not found, permission denied).
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    label?: string;
+}): Promise<T>;
 export declare function formatError(error: unknown): string;
 export declare function formatContainer(container: Dockerode.ContainerInfo): Record<string, unknown>;
 export declare function formatImage(image: Dockerode.ImageInfo): Record<string, unknown>;

package/dist/docker.js

@@ -73,6 +73,85 @@ export async function withTimeout(promise, ms, label) {
         new Promise((_, reject) => setTimeout(() => reject(new DockerTimeoutError(`Docker API call "${label}" timed out after ${ms}ms`)), ms)),
     ]);
 }
+/**
+ * Retry a Docker API call with exponential backoff.
+ * Retries on transient errors (ECONNRESET, ETIMEDOUT, 5xx).
+ * Does NOT retry on 4xx errors (bad request, not found, permission denied).
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries = 3, baseDelayMs = 1000, label = "Docker API call" } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry on non-transient errors
+            if (!isRetryableError(error)) {
+                throw error;
+            }
+            // Don't retry on last attempt
+            if (attempt === maxRetries) {
+                throw error;
+            }
+            // Exponential backoff: 1s, 2s, 4s
+            const delay = baseDelayMs * Math.pow(2, attempt);
+            process.stderr.write(`[retry] ${label} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms...\n`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Determine if an error is transient and worth retrying.
+ * Retries on: connection resets, timeouts, 5xx status codes.
+ * Does NOT retry on: 4xx (client errors), permission denied, not found.
+ */
+function isRetryableError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const msg = error.message.toLowerCase();
+    // Connection-level transient errors
+    if (msg.includes("econnreset") || msg.includes("econnrefused"))
+        return true;
+    if (msg.includes("etimedout") || msg.includes("socket hang up"))
+        return true;
+    if (msg.includes("epipe") || msg.includes("eai_again"))
+        return true;
+    // Docker API 5xx errors (server-side)
+    if (msg.includes("status code 5"))
+        return true;
+    if (msg.includes("internal server error"))
+        return true;
+    if (msg.includes("bad gateway"))
+        return true;
+    if (msg.includes("service unavailable"))
+        return true;
+    // Docker daemon busy (transient)
+    if (msg.includes("daemon is busy"))
+        return true;
+    if (msg.includes("too many requests"))
+        return true;
+    // 4xx errors are NOT retryable (client errors)
+    if (msg.includes("status code 4"))
+        return false;
+    if (msg.includes("not found"))
+        return false;
+    if (msg.includes("permission denied"))
+        return false;
+    if (msg.includes("bad request"))
+        return false;
+    // Permission/connection errors are NOT retryable
+    if (error.name === "DockerConnectionError")
+        return false;
+    if (error.name === "DockerPermissionError")
+        return false;
+    // Timeout errors ARE retryable (might be transient)
+    if (error.name === "DockerTimeoutError")
+        return true;
+    return false;
+}
 export function formatError(error) {
     if (error instanceof DockerConnectionError)
         return `${error.name}: ${error.message}`;

package/dist/server.js

@@ -8,10 +8,11 @@ import { registerExecTools } from "./tools/exec.js";
 import { registerNetworkTools } from "./tools/network.js";
 import { registerVolumeTools } from "./tools/volume.js";
 import { registerMonitoringTools } from "./tools/monitoring.js";
+import { registerSystemTools } from "./tools/system.js";
 export function createServer(docker, options) {
     const server = new McpServer({
         name: "docker-mcp-server",
-        version: "0.3.1",
+        version: "0.3.3",
     });
     // Register all tool categories
     registerContainerTools(server, docker);
@@ -23,6 +24,7 @@ export function createServer(docker, options) {
     registerNetworkTools(server, docker);
     registerVolumeTools(server, docker);
     registerMonitoringTools(server, docker);
+    registerSystemTools(server, docker);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/tools/container.js

@@ -1,16 +1,16 @@
 import { ListContainersSchema, InspectContainerSchema, StartContainerSchema, StopContainerSchema, RestartContainerSchema, RemoveContainerSchema, RecreateContainerSchema, RunContainerSchema, } from "../types.js";
-import { formatContainer, formatError } from "../docker.js";
+import { formatContainer, formatError, withRetry } from "../docker.js";
 export function registerContainerTools(server, docker) {
     server.tool("list_containers", "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.", ListContainersSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const containers = await docker.listContainers({
+            const containers = await withRetry(() => docker.listContainers({
                 all: params.all ?? false,
                 filters: JSON.stringify({
                     ...(params.label ? { label: params.label } : {}),
                     ...(params.name ? { name: [`/${params.name}`] } : {}),
                     ...(params.state ? { status: [params.state] } : {}),
                 }),
-            });
+            }), { label: "list_containers" });
             const results = containers.map(formatContainer);
             return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
         }
@@ -31,7 +31,7 @@ export function registerContainerTools(server, docker) {
     server.tool("start_container", "Start a stopped Docker container by ID or name.", StartContainerSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            await container.start();
+            await withRetry(() => container.start(), { label: "start_container" });
             return { content: [{ type: "text", text: `Container ${params.container_id} started.` }] };
         }
         catch (error) {
@@ -41,7 +41,7 @@ export function registerContainerTools(server, docker) {
     server.tool("stop_container", "Stop a running Docker container by ID or name with optional timeout.", StopContainerSchema.shape, { destructiveHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            await container.stop({ t: params.timeout ?? 10 });
+            await withRetry(() => container.stop({ t: params.timeout ?? 10 }), { label: "stop_container" });
             return { content: [{ type: "text", text: `Container ${params.container_id} stopped.` }] };
         }
         catch (error) {
@@ -55,7 +55,7 @@ export function registerContainerTools(server, docker) {
     server.tool("restart_container", "Restart a Docker container by ID or name with optional timeout. This tears down the running process and starts a new one — use stop_container for a graceful shutdown or remove_container to delete entirely. The timeout parameter (default 10s) controls how long to wait before force-killing. Returns a confirmation string on success. Idempotent: restarting an already-stopped container starts it again. Returns an error string if the container does not exist or is not running.", RestartContainerSchema.shape, { destructiveHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            await container.restart({ t: params.timeout ?? 10 });
+            await withRetry(() => container.restart({ t: params.timeout ?? 10 }), { label: "restart_container" });
             return { content: [{ type: "text", text: `Container ${params.container_id} restarted.` }] };
         }
         catch (error) {

package/dist/tools/image.js

@@ -1,12 +1,12 @@
 import { ListImagesSchema, PullImageSchema, BuildImageSchema, RemoveImageSchema, } from "../types.js";
-import { formatImage, formatError } from "../docker.js";
+import { formatImage, formatError, withRetry } from "../docker.js";
 export function registerImageTools(server, docker) {
     server.tool("list_images", "List Docker images with optional filters. Returns image IDs, tags, sizes, and creation dates.", ListImagesSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const images = await docker.listImages({
+            const images = await withRetry(() => docker.listImages({
                 all: params.all ?? false,
                 filters: params.filter ? JSON.stringify({ reference: [params.filter] }) : undefined,
-            });
+            }), { label: "list_images" });
             const results = images.map(formatImage);
             return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
         }

package/dist/tools/logs.js

@@ -1,16 +1,16 @@
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
-import { formatError, formatBytes, sanitizeOutput } from "../docker.js";
+import { formatError, sanitizeOutput, withRetry, formatBytes } from "../docker.js";
 export function registerLogsTools(server, docker) {
     server.tool("stream_logs", "Get logs from a single Docker container by ID or name. Use stream_logs for one container; use compose_logs for multi-service Compose stacks. Supports tail count (default 100 lines), since timestamp for filtering, and follow mode. Returns UTF-8 log text with multiplexed stream headers stripped, or 'No logs found.' when the container has no output. Read-only and safe to call repeatedly. Returns an error string if the container does not exist.", StreamLogsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            const logs = await container.logs({
+            const logs = await withRetry(() => container.logs({
                 stdout: true,
                 stderr: true,
                 tail: params.tail ?? 100,
                 since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
                 follow: false,
-            });
+            }), { label: "container_logs" });
             // Dockerode returns a Buffer with multiplexed stream headers
             // Use 100KB cap for logs to keep LLM context small
             const output = sanitizeOutput(logs.toString("utf-8"), 100_000);

package/dist/tools/network.js

@@ -1,11 +1,11 @@
 import { ListNetworksSchema, ListVolumesSchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 export function registerNetworkTools(server, docker) {
     server.tool("list_networks", "List Docker networks with optional filter. Returns network IDs, names, drivers, and scopes.", ListNetworksSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const networks = await docker.listNetworks({
+            const networks = await withRetry(() => docker.listNetworks({
                 filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
-            });
+            }), { label: "list_networks" });
             const results = networks.map((n) => ({
                 id: n.Id.substring(0, 12),
                 name: n.Name,

package/dist/tools/system.d.ts

@@ -0,0 +1,4 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSystemTools(server: McpServer, docker: Dockerode): void;
+//# sourceMappingURL=system.d.ts.map

package/dist/tools/system.js

@@ -0,0 +1,97 @@
+import { DockerInfoSchema, DiskUsageSchema } from "../types.js";
+import { formatError, withRetry } from "../docker.js";
+export function registerSystemTools(server, docker) {
+    server.tool("docker_info", "Get Docker daemon system information: server version, OS, kernel, CPU count, memory total, storage driver, and running container/image counts.", DockerInfoSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const info = (await withRetry(() => docker.info(), { label: "docker_info" }));
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            server_version: info.ServerVersion,
+                            os: info.OperatingSystem,
+                            kernel: info.KernelVersion,
+                            architecture: info.Architecture,
+                            cpus: info.NCPU,
+                            memory_total: info.MemTotal,
+                            memory_total_human: formatBytes(info.MemTotal),
+                            docker_root: info.DockerRootDir,
+                            storage_driver: info.Driver,
+                            containers_running: info.ContainersRunning,
+                            containers_stopped: info.ContainersStopped,
+                            containers_paused: info.ContainersPaused,
+                            images: info.Images,
+                            labels: info.Labels,
+                            server_id: info.ID,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("disk_usage", "Get Docker disk usage breakdown: space used by images, containers, volumes, and build cache. Shows total and reclaimable space.", DiskUsageSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const df = (await withRetry(() => docker.df(), { label: "disk_usage" }));
+            const images = (df.Images || []).map((img) => ({
+                id: img.Id?.substring(0, 19),
+                tags: img.RepoTags || [],
+                size: img.Size,
+                size_human: formatBytes(img.Size),
+                containers: img.Containers,
+            }));
+            const containers = (df.Containers || []).map((c) => ({
+                id: c.Id?.substring(0, 12),
+                name: c.Name,
+                image: c.Image,
+                size: c.Size,
+                size_human: formatBytes(c.Size),
+                reclaimable: c.Reclaimable,
+            }));
+            const volumes = (df.Volumes || []).map((v) => ({
+                name: v.Name,
+                size: v.Size,
+                size_human: formatBytes(v.Size),
+                reclaimable: v.Reclaimable,
+            }));
+            const buildCache = (df.BuildCache || []).map((bc) => ({
+                id: bc.ID,
+                type: bc.Type,
+                description: bc.Description?.substring(0, 120),
+                size: bc.Size,
+                size_human: formatBytes(bc.Size),
+                in_use: bc.InUse,
+            }));
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            summary: {
+                                images: { count: df.LayersSize ? images.length : 0, total_size: df.LayersSize, total_human: formatBytes(df.LayersSize || 0) },
+                                containers: { count: containers.length },
+                                volumes: { count: volumes.length },
+                                build_cache: { count: buildCache.length, total_human: formatBytes(buildCache.reduce((sum, bc) => sum + (bc.size || 0), 0)) },
+                            },
+                            images,
+                            containers,
+                            volumes,
+                            build_cache: buildCache.slice(0, 10), // Top 10 only
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB", "TB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+//# sourceMappingURL=system.js.map

package/dist/tools/volume.js

@@ -1,14 +1,14 @@
 import { CreateVolumeSchema, InspectVolumeSchema, RemoveVolumeSchema, PruneVolumesSchema, } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 export function registerVolumeTools(server, docker) {
     server.tool("create_volume", "Create a Docker volume with optional driver, labels, and options. Returns volume name, driver, and mountpoint.", CreateVolumeSchema.shape, { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const result = await docker.createVolume({
+            const result = await withRetry(() => docker.createVolume({
                 Name: params.name,
                 Driver: params.driver || "local",
                 Labels: params.labels,
                 DriverOpts: params.options,
-            });
+            }), { label: "create_volume" });
             return {
                 content: [{
                         type: "text",

package/dist/types.d.ts

@@ -5,15 +5,15 @@ export declare const ListContainersSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodEnum<["running", "stopped", "paused", "exited", "created", "restarting"]>>;
 }, "strip", z.ZodTypeAny, {
+    label?: string[] | undefined;
     name?: string | undefined;
     state?: "created" | "running" | "stopped" | "paused" | "exited" | "restarting" | undefined;
     all?: boolean | undefined;
-    label?: string[] | undefined;
 }, {
+    label?: string[] | undefined;
     name?: string | undefined;
     state?: "created" | "running" | "stopped" | "paused" | "exited" | "restarting" | undefined;
     all?: boolean | undefined;
-    label?: string[] | undefined;
 }>;
 export declare const InspectContainerSchema: z.ZodObject<{
     container_id: z.ZodString;
@@ -403,4 +403,6 @@ export declare const ResourceAlertCheckSchema: z.ZodObject<{
     restart_count?: number | undefined;
 }>;
 export declare const MonitorDashboardSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const DockerInfoSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const DiskUsageSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -173,4 +173,7 @@ export const ResourceAlertCheckSchema = z.object({
     restart_count: z.number().optional().describe("Alert if restart count exceeds this (default: 5)"),
 });
 export const MonitorDashboardSchema = z.object({});
+// System info schemas (v0.3.3)
+export const DockerInfoSchema = z.object({});
+export const DiskUsageSchema = z.object({});
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "mcpName": "io.github.friendlygeorge/docker-mcp-server",
   "description": "MCP server for Docker — container management, health checks, auto-restart, Compose lifecycle, and log streaming for Claude, Cursor, and AI agents",
   "type": "module",

package/src/docker.ts

@@ -96,6 +96,88 @@ export async function withTimeout<T>(
   ]);
 }
 
+
+/**
+ * Retry a Docker API call with exponential backoff.
+ * Retries on transient errors (ECONNRESET, ETIMEDOUT, 5xx).
+ * Does NOT retry on 4xx errors (bad request, not found, permission denied).
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { maxRetries?: number; baseDelayMs?: number; label?: string } = {}
+): Promise<T> {
+  const { maxRetries = 3, baseDelayMs = 1000, label = "Docker API call" } = options;
+  let lastError: unknown;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      // Don't retry on non-transient errors
+      if (!isRetryableError(error)) {
+        throw error;
+      }
+      
+      // Don't retry on last attempt
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      
+      // Exponential backoff: 1s, 2s, 4s
+      const delay = baseDelayMs * Math.pow(2, attempt);
+      process.stderr.write(
+        `[retry] ${label} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms...\n`
+      );
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Determine if an error is transient and worth retrying.
+ * Retries on: connection resets, timeouts, 5xx status codes.
+ * Does NOT retry on: 4xx (client errors), permission denied, not found.
+ */
+function isRetryableError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  
+  const msg = error.message.toLowerCase();
+  
+  // Connection-level transient errors
+  if (msg.includes("econnreset") || msg.includes("econnrefused")) return true;
+  if (msg.includes("etimedout") || msg.includes("socket hang up")) return true;
+  if (msg.includes("epipe") || msg.includes("eai_again")) return true;
+  
+  // Docker API 5xx errors (server-side)
+  if (msg.includes("status code 5")) return true;
+  if (msg.includes("internal server error")) return true;
+  if (msg.includes("bad gateway")) return true;
+  if (msg.includes("service unavailable")) return true;
+  
+  // Docker daemon busy (transient)
+  if (msg.includes("daemon is busy")) return true;
+  if (msg.includes("too many requests")) return true;
+  
+  // 4xx errors are NOT retryable (client errors)
+  if (msg.includes("status code 4")) return false;
+  if (msg.includes("not found")) return false;
+  if (msg.includes("permission denied")) return false;
+  if (msg.includes("bad request")) return false;
+  
+  // Permission/connection errors are NOT retryable
+  if (error.name === "DockerConnectionError") return false;
+  if (error.name === "DockerPermissionError") return false;
+  
+  // Timeout errors ARE retryable (might be transient)
+  if (error.name === "DockerTimeoutError") return true;
+  
+  return false;
+}
+
 export function formatError(error: unknown): string {
   if (error instanceof DockerConnectionError) return `${error.name}: ${error.message}`;
   if (error instanceof DockerTimeoutError) return `${error.name}: ${error.message}`;
@@ -164,4 +246,4 @@ export function formatBytes(bytes: number): string {
   const sizes = ["B", "KB", "MB", "GB", "TB"];
   const i = Math.floor(Math.log(bytes) / Math.log(k));
   return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
-}
+}

package/src/server.ts

@@ -9,6 +9,7 @@ import { registerExecTools } from "./tools/exec.js";
 import { registerNetworkTools } from "./tools/network.js";
 import { registerVolumeTools } from "./tools/volume.js";
 import { registerMonitoringTools } from "./tools/monitoring.js";
+import { registerSystemTools } from "./tools/system.js";
 
 export interface ServerOptions {
   timeoutMs?: number;
@@ -17,7 +18,7 @@ export interface ServerOptions {
 export function createServer(docker: Dockerode, options?: ServerOptions): McpServer {
   const server = new McpServer({
     name: "docker-mcp-server",
-    version: "0.3.1",
+    version: "0.3.3",
   });
 
   // Register all tool categories
@@ -30,6 +31,7 @@ export function createServer(docker: Dockerode, options?: ServerOptions): McpSer
   registerNetworkTools(server, docker);
   registerVolumeTools(server, docker);
   registerMonitoringTools(server, docker);
+  registerSystemTools(server, docker);
 
   return server;
 }

package/src/tools/container.ts

@@ -10,7 +10,7 @@ import {
   RecreateContainerSchema,
   RunContainerSchema,
 } from "../types.js";
-import { formatContainer, formatError } from "../docker.js";
+import { formatContainer, formatError, withRetry } from "../docker.js";
 
 export function registerContainerTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -20,14 +20,17 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const containers = await docker.listContainers({
-          all: params.all ?? false,
-          filters: JSON.stringify({
-            ...(params.label ? { label: params.label } : {}),
-            ...(params.name ? { name: [`/${params.name}`] } : {}),
-            ...(params.state ? { status: [params.state] } : {}),
+        const containers = await withRetry(
+          () => docker.listContainers({
+            all: params.all ?? false,
+            filters: JSON.stringify({
+              ...(params.label ? { label: params.label } : {}),
+              ...(params.name ? { name: [`/${params.name}`] } : {}),
+              ...(params.state ? { status: [params.state] } : {}),
+            }),
           }),
-        });
+          { label: "list_containers" }
+        );
         const results = containers.map(formatContainer);
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
       } catch (error) {
@@ -60,7 +63,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        await container.start();
+        await withRetry(() => container.start(), { label: "start_container" });
         return { content: [{ type: "text", text: `Container ${params.container_id} started.` }] };
       } catch (error) {
         return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
@@ -76,7 +79,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        await container.stop({ t: params.timeout ?? 10 });
+        await withRetry(() => container.stop({ t: params.timeout ?? 10 }), { label: "stop_container" });
         return { content: [{ type: "text", text: `Container ${params.container_id} stopped.` }] };
       } catch (error: any) {
         // 304 means container is already stopped — treat as success
@@ -96,7 +99,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        await container.restart({ t: params.timeout ?? 10 });
+        await withRetry(() => container.restart({ t: params.timeout ?? 10 }), { label: "restart_container" });
         return { content: [{ type: "text", text: `Container ${params.container_id} restarted.` }] };
       } catch (error) {
         return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };

package/src/tools/health.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CheckHealthSchema, WatchHealthSchema, SetRestartPolicySchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 
 export function registerHealthTools(server: McpServer, docker: Dockerode): void {
   server.tool(

package/src/tools/image.ts

@@ -6,7 +6,7 @@ import {
   BuildImageSchema,
   RemoveImageSchema,
 } from "../types.js";
-import { formatImage, formatError } from "../docker.js";
+import { formatImage, formatError, withRetry } from "../docker.js";
 
 export function registerImageTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -16,10 +16,10 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const images = await docker.listImages({
+        const images = await withRetry(() => docker.listImages({
           all: params.all ?? false,
           filters: params.filter ? JSON.stringify({ reference: [params.filter] }) : undefined,
-        });
+        }), { label: "list_images" });
         const results = images.map(formatImage);
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
       } catch (error) {

package/src/tools/logs.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
-import { formatError, formatBytes, sanitizeOutput } from "../docker.js";
+import { formatError, sanitizeOutput, withRetry, formatBytes } from "../docker.js";
 
 export function registerLogsTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -12,13 +12,13 @@ export function registerLogsTools(server: McpServer, docker: Dockerode): void {
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        const logs = await container.logs({
+        const logs = await withRetry(() => container.logs({
           stdout: true,
           stderr: true,
           tail: params.tail ?? 100,
           since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
           follow: false as const,
-        });
+        }), { label: "container_logs" });
         // Dockerode returns a Buffer with multiplexed stream headers
         // Use 100KB cap for logs to keep LLM context small
         const output = sanitizeOutput(logs.toString("utf-8"), 100_000);

package/src/tools/network.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ListNetworksSchema, ListVolumesSchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 
 export function registerNetworkTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -11,9 +11,9 @@ export function registerNetworkTools(server: McpServer, docker: Dockerode): void
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const networks = await docker.listNetworks({
+        const networks = await withRetry(() => docker.listNetworks({
           filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
-        });
+        }), { label: "list_networks" });
         const results = networks.map((n) => ({
           id: n.Id.substring(0, 12),
           name: n.Name,

package/src/tools/system.ts

@@ -0,0 +1,169 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DockerInfoSchema, DiskUsageSchema } from "../types.js";
+import { formatError, withRetry } from "../docker.js";
+
+interface DockerInfoResult {
+  ServerVersion: string;
+  OperatingSystem: string;
+  KernelVersion: string;
+  Architecture: string;
+  NCPU: number;
+  MemTotal: number;
+  DockerRootDir: string;
+  Driver: string;
+  ContainersRunning: number;
+  ContainersStopped: number;
+  ContainersPaused: number;
+  Images: number;
+  Labels: string[];
+  ID: string;
+}
+
+interface DiskUsageImage {
+  Id: string;
+  RepoTags: string[];
+  Size: number;
+  Containers: number;
+}
+
+interface DiskUsageContainer {
+  Id: string;
+  Name: string;
+  Image: string;
+  Size: number;
+  Reclaimable: boolean;
+}
+
+interface DiskUsageVolume {
+  Name: string;
+  Size: number;
+  Reclaimable: boolean;
+}
+
+interface DiskUsageBuildCache {
+  ID: string;
+  Type: string;
+  Description: string;
+  Size: number;
+  InUse: boolean;
+}
+
+interface DiskUsageResult {
+  LayersSize: number;
+  Images: DiskUsageImage[];
+  Containers: DiskUsageContainer[];
+  Volumes: DiskUsageVolume[];
+  BuildCache: DiskUsageBuildCache[];
+}
+
+export function registerSystemTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "docker_info",
+    "Get Docker daemon system information: server version, OS, kernel, CPU count, memory total, storage driver, and running container/image counts.",
+    DockerInfoSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const info = (await withRetry(() => docker.info(), { label: "docker_info" })) as DockerInfoResult;
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              server_version: info.ServerVersion,
+              os: info.OperatingSystem,
+              kernel: info.KernelVersion,
+              architecture: info.Architecture,
+              cpus: info.NCPU,
+              memory_total: info.MemTotal,
+              memory_total_human: formatBytes(info.MemTotal),
+              docker_root: info.DockerRootDir,
+              storage_driver: info.Driver,
+              containers_running: info.ContainersRunning,
+              containers_stopped: info.ContainersStopped,
+              containers_paused: info.ContainersPaused,
+              images: info.Images,
+              labels: info.Labels,
+              server_id: info.ID,
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "disk_usage",
+    "Get Docker disk usage breakdown: space used by images, containers, volumes, and build cache. Shows total and reclaimable space.",
+    DiskUsageSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const df = (await withRetry(() => docker.df(), { label: "disk_usage" })) as DiskUsageResult;
+
+        const images = (df.Images || []).map((img) => ({
+          id: img.Id?.substring(0, 19),
+          tags: img.RepoTags || [],
+          size: img.Size,
+          size_human: formatBytes(img.Size),
+          containers: img.Containers,
+        }));
+
+        const containers = (df.Containers || []).map((c) => ({
+          id: c.Id?.substring(0, 12),
+          name: c.Name,
+          image: c.Image,
+          size: c.Size,
+          size_human: formatBytes(c.Size),
+          reclaimable: c.Reclaimable,
+        }));
+
+        const volumes = (df.Volumes || []).map((v) => ({
+          name: v.Name,
+          size: v.Size,
+          size_human: formatBytes(v.Size),
+          reclaimable: v.Reclaimable,
+        }));
+
+        const buildCache = (df.BuildCache || []).map((bc) => ({
+          id: bc.ID,
+          type: bc.Type,
+          description: bc.Description?.substring(0, 120),
+          size: bc.Size,
+          size_human: formatBytes(bc.Size),
+          in_use: bc.InUse,
+        }));
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              summary: {
+                images: { count: df.LayersSize ? images.length : 0, total_size: df.LayersSize, total_human: formatBytes(df.LayersSize || 0) },
+                containers: { count: containers.length },
+                volumes: { count: volumes.length },
+                build_cache: { count: buildCache.length, total_human: formatBytes(buildCache.reduce((sum, bc) => sum + (bc.size || 0), 0)) },
+              },
+              images,
+              containers,
+              volumes,
+              build_cache: buildCache.slice(0, 10), // Top 10 only
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}

package/src/tools/volume.ts

@@ -6,7 +6,7 @@ import {
   RemoveVolumeSchema,
   PruneVolumesSchema,
 } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 
 export function registerVolumeTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -16,12 +16,12 @@ export function registerVolumeTools(server: McpServer, docker: Dockerode): void
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const result = await docker.createVolume({
+        const result = await withRetry(() => docker.createVolume({
           Name: params.name,
           Driver: params.driver || "local",
           Labels: params.labels,
           DriverOpts: params.options,
-        });
+        }), { label: "create_volume" });
         return {
           content: [{
             type: "text",
@@ -122,4 +122,4 @@ export function registerVolumeTools(server: McpServer, docker: Dockerode): void
       }
     }
   );
-}
+}

package/src/types.ts

@@ -215,4 +215,9 @@ export const ResourceAlertCheckSchema = z.object({
   restart_count: z.number().optional().describe("Alert if restart count exceeds this (default: 5)"),
 });
 
-export const MonitorDashboardSchema = z.object({});
+export const MonitorDashboardSchema = z.object({});
+
+// System info schemas (v0.3.3)
+export const DockerInfoSchema = z.object({});
+
+export const DiskUsageSchema = z.object({});

package/tests/retry.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi } from "vitest";
+import { withRetry, DockerTimeoutError, DockerConnectionError, DockerPermissionError } from "../src/docker.js";
+
+describe("withRetry", () => {
+  it("returns result on first attempt (no retry needed)", async () => {
+    const fn = vi.fn().mockResolvedValue("success");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("success");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries on transient ECONNRESET error", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error("read ECONNRESET"))
+      .mockResolvedValue("recovered");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10, label: "test" });
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries on timeout error", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new DockerTimeoutError("timed out"))
+      .mockResolvedValue("recovered");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("does NOT retry on 404 Not Found", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("HTTP 404: Not Found"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("HTTP 404: Not Found");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retry on permission denied", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("Permission denied"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("Permission denied");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retry on DockerConnectionError", async () => {
+    const fn = vi.fn().mockRejectedValue(new DockerConnectionError("cannot connect"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("cannot connect");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retry on DockerPermissionError", async () => {
+    const fn = vi.fn().mockRejectedValue(new DockerPermissionError("access denied"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("access denied");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries on 500 Internal Server Error", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error("HTTP 500: Internal Server Error"))
+      .mockResolvedValue("recovered");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("exhausts retries and throws last error", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("read ECONNRESET"));
+    await expect(withRetry(fn, { maxRetries: 2, baseDelayMs: 10 }))
+      .rejects.toThrow("read ECONNRESET");
+    expect(fn).toHaveBeenCalledTimes(3); // initial + 2 retries
+  });
+
+  it("retries on socket hang up", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error("socket hang up"))
+      .mockResolvedValue("ok");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});

package/tests/system.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock Dockerode before importing the module under test
+const mockInfo = vi.fn();
+const mockDf = vi.fn();
+
+vi.mock("dockerode", () => {
+  return {
+    default: vi.fn().mockImplementation(() => ({
+      info: mockInfo,
+      df: mockDf,
+    })),
+  };
+});
+
+import { registerSystemTools } from "../src/tools/system.js";
+
+// Minimal MCP server mock
+function createMockServer() {
+  const tools: Record<string, { description: string; handler: Function }> = {};
+  return {
+    tool: (name: string, description: string, _schema: unknown, _hints: unknown, handler: Function) => {
+      tools[name] = { description, handler };
+    },
+    tools,
+  };
+}
+
+describe("System Tools", () => {
+  let server: ReturnType<typeof createMockServer>;
+  let docker: any;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    server = createMockServer();
+    docker = {
+      info: mockInfo,
+      df: mockDf,
+    };
+    registerSystemTools(server as any, docker);
+    vi.clearAllMocks();
+  });
+
+  describe("docker_info", () => {
+    it("should register docker_info tool", () => {
+      expect(server.tools["docker_info"]).toBeDefined();
+      expect(server.tools["docker_info"].description).toContain("system information");
+    });
+
+    it("should return formatted Docker info", async () => {
+      mockInfo.mockResolvedValue({
+        ServerVersion: "29.5.3",
+        OperatingSystem: "Ubuntu 26.04 LTS",
+        KernelVersion: "7.0.0-15-generic",
+        Architecture: "x86_64",
+        NCPU: 2,
+        MemTotal: 4000079872,
+        DockerRootDir: "/var/lib/docker",
+        Driver: "overlay2",
+        ContainersRunning: 3,
+        ContainersStopped: 5,
+        ContainersPaused: 0,
+        Images: 12,
+        Labels: ["com.docker.compose.version=2.29.1"],
+        ID: "ABC1:DEF2:GHI3:JKL4:MNO5:PQR6:STUV:WXYZ:1234:5678:ABCD:EF90:1234:5678",
+      });
+
+      const result = await server.tools["docker_info"].handler({});
+      const data = JSON.parse(result.content[0].text);
+
+      expect(data.server_version).toBe("29.5.3");
+      expect(data.os).toBe("Ubuntu 26.04 LTS");
+      expect(data.kernel).toBe("7.0.0-15-generic");
+      expect(data.cpus).toBe(2);
+      expect(data.memory_total_human).toBe("3.7 GB");
+      expect(data.containers_running).toBe(3);
+      expect(data.containers_stopped).toBe(5);
+      expect(data.images).toBe(12);
+      expect(data.storage_driver).toBe("overlay2");
+    });
+
+    it("should handle errors", async () => {
+      mockInfo.mockRejectedValue(new Error("Cannot connect to Docker daemon"));
+
+      const result = await server.tools["docker_info"].handler({});
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Error");
+    });
+  });
+
+  describe("disk_usage", () => {
+    it("should register disk_usage tool", () => {
+      expect(server.tools["disk_usage"]).toBeDefined();
+      expect(server.tools["disk_usage"].description).toContain("disk usage");
+    });
+
+    it("should return formatted disk usage", async () => {
+      mockDf.mockResolvedValue({
+        LayersSize: 623591029,
+        Images: [
+          {
+            Id: "sha256:a6894d60f28f051f4c3e44a6b5f0b669023fc47ea936355d65e5fcc10856767f",
+            RepoTags: ["nginx:latest"],
+            Size: 395120924,
+            Containers: 1,
+          },
+          {
+            Id: "sha256:b2894d60f28f051f4c3e44a6b5f0b669023fc47ea936355d65e5fcc10856767g",
+            RepoTags: ["alpine:latest"],
+            Size: 13068376,
+            Containers: 0,
+          },
+        ],
+        Containers: [
+          {
+            Id: "abc123def456",
+            Name: "web-app",
+            Image: "nginx:latest",
+            Size: 1048576,
+            Reclaimable: true,
+          },
+        ],
+        Volumes: [
+          {
+            Name: "data-vol",
+            Size: 52428800,
+            Reclaimable: false,
+          },
+        ],
+        BuildCache: [
+          {
+            ID: "cache1",
+            Type: "regular",
+            Description: "pulled from docker.io/library/node:22",
+            Size: 9032241,
+            InUse: false,
+          },
+          {
+            ID: "cache2",
+            Type: "regular",
+            Description: "COPY package.json",
+            Size: 156559,
+            InUse: false,
+          },
+        ],
+      });
+
+      const result = await server.tools["disk_usage"].handler({});
+      const data = JSON.parse(result.content[0].text);
+
+      expect(data.summary.images.count).toBe(2);
+      expect(data.summary.images.total_human).toMatch(/^594\.\d MB$/);
+      expect(data.summary.containers.count).toBe(1);
+      expect(data.summary.volumes.count).toBe(1);
+      expect(data.summary.build_cache.count).toBe(2);
+
+      // Check image details
+      expect(data.images[0].tags).toContain("nginx:latest");
+      expect(data.images[0].size_human).toMatch(/^376\.\d MB$/);
+
+      // Check container details
+      expect(data.containers[0].name).toBe("web-app");
+      expect(data.containers[0].size_human).toBe("1 MB");
+
+      // Check volume details
+      expect(data.volumes[0].name).toBe("data-vol");
+      expect(data.volumes[0].size_human).toBe("50 MB");
+    });
+
+    it("should handle empty disk usage", async () => {
+      mockDf.mockResolvedValue({
+        LayersSize: 0,
+        Images: [],
+        Containers: [],
+        Volumes: [],
+        BuildCache: [],
+      });
+
+      const result = await server.tools["disk_usage"].handler({});
+      const data = JSON.parse(result.content[0].text);
+
+      expect(data.summary.images.count).toBe(0);
+      expect(data.summary.containers.count).toBe(0);
+      expect(data.images).toEqual([]);
+    });
+
+    it("should handle errors", async () => {
+      mockDf.mockRejectedValue(new Error("Docker API error"));
+
+      const result = await server.tools["disk_usage"].handler({});
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Error");
+    });
+  });
+});