@supernova123/docker-mcp-server 0.2.5 → 0.3.0

package/dist/docker.js

@@ -57,7 +57,7 @@ export function sanitizeOutput(text, maxLength = 1_000_000) {
     text = text.replace(/\x1b\][^\x07]*\x07/g, ""); // OSC terminated by BEL
     text = text.replace(/\x1b[@-Z\\-_]/g, ""); // Single-char escapes
     // Strip invisible Unicode (Tag chars, bidi overrides, zero-width)
-    text = text.replace(/[\uE0001-\uE007F\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, "");
+    text = text.replace(/[\u{E0000}-\u{E007F}\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/gu, "");
     // Strip Docker stream-frame headers (8-byte prefix per frame)
     text = text.replace(/^[\x00-\x0f]{8}/gm, "");
     // Truncate to cap memory and LLM context cost

package/dist/server.js

@@ -6,11 +6,12 @@ import { registerHealthTools } from "./tools/health.js";
 import { registerLogsTools } from "./tools/logs.js";
 import { registerExecTools } from "./tools/exec.js";
 import { registerNetworkTools } from "./tools/network.js";
+import { registerVolumeTools } from "./tools/volume.js";
 import { registerMonitoringTools } from "./tools/monitoring.js";
 export function createServer(docker) {
     const server = new McpServer({
         name: "docker-mcp-server",
-        version: "0.2.0",
+        version: "0.3.0",
     });
     // Register all tool categories
     registerContainerTools(server, docker);
@@ -20,6 +21,7 @@ export function createServer(docker) {
     registerLogsTools(server, docker);
     registerExecTools(server, docker);
     registerNetworkTools(server, docker);
+    registerVolumeTools(server, docker);
     registerMonitoringTools(server, docker);
     return server;
 }

package/dist/tools/volume.d.ts

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

package/dist/tools/volume.js

@@ -0,0 +1,95 @@
+import { CreateVolumeSchema, InspectVolumeSchema, RemoveVolumeSchema, PruneVolumesSchema, } from "../types.js";
+import { formatError } 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({
+                Name: params.name,
+                Driver: params.driver || "local",
+                Labels: params.labels,
+                DriverOpts: params.options,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            name: result.Name,
+                            driver: result.Driver,
+                            mountpoint: result.Mountpoint,
+                            created: result.CreatedAt,
+                            labels: result.Labels,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("inspect_volume", "Inspect a Docker volume. Returns detailed info including name, driver, mountpoint, labels, scope, and usage data.", InspectVolumeSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const volume = docker.getVolume(params.name);
+            const info = await volume.inspect();
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            name: info.Name,
+                            driver: info.Driver,
+                            mountpoint: info.Mountpoint,
+                            labels: info.Labels,
+                            scope: info.Scope,
+                            options: info.Options,
+                            status: info.Status || null,
+                            usage: info.UsageData || null,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("remove_volume", "Remove a Docker volume. Use force=true to remove even if in use by containers.", RemoveVolumeSchema.shape, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const volume = docker.getVolume(params.name);
+            await volume.remove({ force: params.force || false });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ success: true, name: params.name, message: `Volume '${params.name}' removed` }),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("prune_volumes", "Remove all unused Docker volumes. Returns count of removed volumes and reclaimed space.", PruneVolumesSchema.shape, { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, async (params) => {
+        try {
+            const filters = {};
+            if (params.filter) {
+                const match = params.filter.match(/label=(.+)/);
+                if (match) {
+                    filters.label = [match[1]];
+                }
+            }
+            const result = await docker.pruneVolumes({
+                filters: Object.keys(filters).length > 0 ? filters : undefined,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            volumes_deleted: result.VolumesDeleted || [],
+                            space_reclaimed: result.SpaceReclaimed || 0,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+//# sourceMappingURL=volume.js.map

package/dist/types.d.ts

@@ -306,6 +306,46 @@ export declare const ListVolumesSchema: z.ZodObject<{
 }, {
     filter?: string | undefined;
 }>;
+export declare const CreateVolumeSchema: z.ZodObject<{
+    name: z.ZodString;
+    driver: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    labels?: Record<string, string> | undefined;
+    options?: Record<string, string> | undefined;
+    driver?: string | undefined;
+}, {
+    name: string;
+    labels?: Record<string, string> | undefined;
+    options?: Record<string, string> | undefined;
+    driver?: string | undefined;
+}>;
+export declare const InspectVolumeSchema: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+export declare const RemoveVolumeSchema: z.ZodObject<{
+    name: z.ZodString;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    force?: boolean | undefined;
+}, {
+    name: string;
+    force?: boolean | undefined;
+}>;
+export declare const PruneVolumesSchema: z.ZodObject<{
+    filter: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    filter?: string | undefined;
+}, {
+    filter?: string | undefined;
+}>;
 export declare const ContainerHealthStatusSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export declare const ContainerResourceUsageSchema: z.ZodObject<{
     sort_by: z.ZodOptional<z.ZodEnum<["cpu", "memory", "network"]>>;

package/dist/types.js

@@ -133,6 +133,22 @@ export const ListNetworksSchema = z.object({
 export const ListVolumesSchema = z.object({
     filter: z.string().optional().describe("Filter by name or driver"),
 });
+export const CreateVolumeSchema = z.object({
+    name: z.string().min(1).max(255).describe("Volume name"),
+    driver: z.string().optional().describe("Volume driver (default: 'local')"),
+    labels: z.record(z.string(), z.string()).optional().describe("Labels to apply to the volume"),
+    options: z.record(z.string(), z.string()).optional().describe("Driver-specific options"),
+});
+export const InspectVolumeSchema = z.object({
+    name: z.string().min(1).describe("Volume name or ID to inspect"),
+});
+export const RemoveVolumeSchema = z.object({
+    name: z.string().min(1).describe("Volume name or ID to remove"),
+    force: z.boolean().optional().describe("Force removal even if in use (default: false)"),
+});
+export const PruneVolumesSchema = z.object({
+    filter: z.string().optional().describe("Filter by label (e.g., 'label=key=value')"),
+});
 // Monitoring schemas (v0.2.0)
 export const ContainerHealthStatusSchema = z.object({});
 export const ContainerResourceUsageSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "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

@@ -66,7 +66,7 @@ export function sanitizeOutput(text: string, maxLength = 1_000_000): string {
   text = text.replace(/\x1b\][^\x07]*\x07/g, ""); // OSC terminated by BEL
   text = text.replace(/\x1b[@-Z\\-_]/g, "");       // Single-char escapes
   // Strip invisible Unicode (Tag chars, bidi overrides, zero-width)
-  text = text.replace(/[\uE0001-\uE007F\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, "");
+  text = text.replace(/[\u{E0000}-\u{E007F}\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/gu, "");
   // Strip Docker stream-frame headers (8-byte prefix per frame)
   text = text.replace(/^[\x00-\x0f]{8}/gm, "");
   // Truncate to cap memory and LLM context cost

package/src/docker.ts.bak

@@ -0,0 +1,85 @@
+import Dockerode from "dockerode";
+
+export interface DockerClientOptions {
+  socketPath?: string;
+  host?: string;
+  port?: number;
+}
+
+export function createDockerClient(options?: DockerClientOptions): Dockerode {
+  if (options?.socketPath) {
+    return new Dockerode({ socketPath: options.socketPath });
+  }
+  if (options?.host && options?.port) {
+    return new Dockerode({ host: options.host, port: options.port });
+  }
+  // Default: local socket
+  return new Dockerode({ socketPath: "/var/run/docker.sock" });
+}
+
+export function formatError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  return String(error);
+}
+
+export function formatContainer(container: Dockerode.ContainerInfo): Record<string, unknown> {
+  return {
+    id: container.Id.substring(0, 12),
+    name: container.Names[0]?.replace(/^\//, ""),
+    image: container.Image,
+    state: container.State,
+    status: container.Status,
+    created: new Date(container.Created * 1000).toISOString(),
+    ports: container.Ports.map((p) => ({
+      private: p.PrivatePort,
+      public: p.PublicPort,
+      type: p.Type,
+    })),
+    labels: container.Labels,
+    mounts: container.Mounts.map((m) => ({
+      type: m.Type,
+      source: m.Source,
+      destination: m.Destination,
+      mode: m.Mode,
+      rw: m.RW,
+    })),
+  };
+}
+
+export function formatImage(image: Dockerode.ImageInfo): Record<string, unknown> {
+  return {
+    id: image.Id.substring(0, 19),
+    tags: image.RepoTags || ["<none>:<none>"],
+    size: image.Size,
+    created: new Date(image.Created).toISOString(),
+  };
+}
+
+/**
+ * Sanitize tool output: strip ANSI escapes, invisible Unicode, and truncate.
+ * Prevents prompt injection via output and caps LLM context cost.
+ */
+export function sanitizeOutput(text: string, maxLength = 1_000_000): string {
+  // Strip ANSI escape codes (CSI, OSC, simple sequences)
+  text = text.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
+  text = text.replace(/\x1b\][^\x07]*\x07/g, ""); // OSC terminated by BEL
+  text = text.replace(/\x1b[@-Z\\-_]/g, "");       // Single-char escapes
+  // Strip invisible Unicode (Tag chars, bidi overrides, zero-width)
+  text = text.replace(/[\uE0001-\uE007F\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, "");
+  // Strip Docker stream-frame headers (8-byte prefix per frame)
+  text = text.replace(/^[\x00-\x0f]{8}/gm, "");
+  // Truncate to cap memory and LLM context cost
+  if (text.length > maxLength) {
+    return text.slice(0, maxLength) + `\n... [output truncated at ${maxLength} chars]`;
+  }
+  return text;
+}
+
+export 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(2)) + " " + sizes[i];
+}

package/src/server.ts

@@ -7,12 +7,13 @@ import { registerHealthTools } from "./tools/health.js";
 import { registerLogsTools } from "./tools/logs.js";
 import { registerExecTools } from "./tools/exec.js";
 import { registerNetworkTools } from "./tools/network.js";
+import { registerVolumeTools } from "./tools/volume.js";
 import { registerMonitoringTools } from "./tools/monitoring.js";
 
 export function createServer(docker: Dockerode): McpServer {
   const server = new McpServer({
     name: "docker-mcp-server",
-    version: "0.2.0",
+    version: "0.3.0",
   });
 
   // Register all tool categories
@@ -23,6 +24,7 @@ export function createServer(docker: Dockerode): McpServer {
   registerLogsTools(server, docker);
   registerExecTools(server, docker);
   registerNetworkTools(server, docker);
+  registerVolumeTools(server, docker);
   registerMonitoringTools(server, docker);
 
   return server;

package/src/tools/monitoring.ts.bak

@@ -0,0 +1,376 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ContainerHealthStatusSchema,
+  ContainerResourceUsageSchema,
+  WatchEventsSchema,
+  SearchLogsSchema,
+  ResourceAlertCheckSchema,
+  MonitorDashboardSchema,
+} from "../types.js";
+import { sanitizeOutput } from "../docker.js";
+
+export function registerMonitoringTools(server: McpServer, docker: Dockerode): void {
+  // 1. fleet_status — health status of all running containers
+  server.tool(
+    "container_health_status",
+    "Check health status, uptime, and restart count for all running Docker containers. Returns JSON with container name, state, health probe status (healthy/unhealthy/no-healthcheck), and restart count. Use this for a quick fleet health overview; for resource metrics use container_resource_usage instead. Returns an array of objects with name, id, state, status, health, uptime, restartCount, and image fields. Read-only and safe to call repeatedly.",
+    ContainerHealthStatusSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const containers = await docker.listContainers({ all: false });
+        const results = await Promise.all(
+          containers.map(async (c) => {
+            const info = await docker.getContainer(c.Id).inspect();
+            return {
+              name: c.Names[0]?.replace(/^\//, "") || c.Id.slice(0, 12),
+              id: c.Id.slice(0, 12),
+              state: c.State,
+              status: c.Status,
+              health: info.State.Health?.Status || "no-healthcheck",
+              uptime: info.State.StartedAt,
+              restartCount: info.RestartCount,
+              image: c.Image,
+            };
+          })
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // 2. fleet_stats — resource usage for all running containers
+  server.tool(
+    "container_resource_usage",
+    "Monitor CPU, memory, and network I/O across all running Docker containers. Returns sorted resource usage metrics with percentage breakdowns for each container. Use container_health_status for health probes; use resource_alert_check for threshold violations. Supports sort by cpu, memory, or network. Returns array of objects with name, id, cpu_percent, memory_usage_mb, memory_percent, network_rx_mb, network_tx_mb. Read-only and safe to call repeatedly.",
+    ContainerResourceUsageSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const containers = await docker.listContainers({ all: false });
+        const results = await Promise.all(
+          containers.map(async (c) => {
+            const stats = await docker.getContainer(c.Id).stats({ stream: false });
+            const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - (stats.precpu_stats?.cpu_usage?.total_usage ?? 0);
+            const systemDelta = stats.cpu_stats.system_cpu_usage - (stats.precpu_stats?.system_cpu_usage ?? 0);
+            const cpuCount = stats.cpu_stats.online_cpus ?? 1;
+            const cpuPercent = systemDelta > 0 ? (cpuDelta / systemDelta) * cpuCount * 100 : 0;
+            const memUsage = stats.memory_stats?.usage ?? 0;
+            const memLimit = stats.memory_stats?.limit ?? 1;
+            const memPercent = (memUsage / memLimit) * 100;
+            const netRx = Object.values(stats.networks ?? {}).reduce((sum: number, n: any) => sum + (n.rx_bytes ?? 0), 0);
+            const netTx = Object.values(stats.networks ?? {}).reduce((sum: number, n: any) => sum + (n.tx_bytes ?? 0), 0);
+
+            return {
+              name: c.Names[0]?.replace(/^\//, "") || c.Id.slice(0, 12),
+              id: c.Id.slice(0, 12),
+              cpu_percent: Math.round(cpuPercent * 100) / 100,
+              memory_usage_mb: Math.round((memUsage / 1024 / 1024) * 100) / 100,
+              memory_percent: Math.round(memPercent * 100) / 100,
+              network_rx_mb: Math.round((netRx / 1024 / 1024) * 100) / 100,
+              network_tx_mb: Math.round((netTx / 1024 / 1024) * 100) / 100,
+            };
+          })
+        );
+
+        const sortBy = params.sort_by || "cpu";
+        results.sort((a: any, b: any) => {
+          if (sortBy === "cpu") return b.cpu_percent - a.cpu_percent;
+          if (sortBy === "memory") return b.memory_percent - a.memory_percent;
+          return (b.network_rx_mb + b.network_tx_mb) - (a.network_rx_mb + a.network_tx_mb);
+        });
+
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // 3. watch_events — stream Docker events (simplified: collect events for a duration)
+  server.tool(
+    "watch_events",
+    "Stream Docker container events (start, stop, die, restart, health_status) over a configurable time window. Filter by specific container or event type. Use container_health_status for current state; use this tool to watch for changes over time. Returns array of event objects with type, action, container, and time fields. Returns 'No events captured in the time window.' when no events occur. Read-only and safe to call repeatedly.",
+    WatchEventsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const durationMs = (params.duration || 30) * 1000;
+        const filter: any = {};
+        if (params.container) filter.container = [params.container];
+        if (params.event_type && params.event_type !== "all") filter.event = [params.event_type];
+        if (params.since) filter.since = [params.since];
+
+        const events: any[] = [];
+        const stream = await docker.getEvents(filter as Dockerode.GetEventsOptions) as unknown as NodeJS.ReadableStream;
+
+        await new Promise<void>((resolve) => {
+          const timeout = setTimeout(() => {
+            resolve();
+          }, durationMs);
+
+          stream.on("data", (chunk: Buffer) => {
+            try {
+              const event = JSON.parse(chunk.toString());
+              events.push({
+                type: event.Type,
+                action: event.Action,
+                container: event.Actor?.Attributes?.name || event.Actor?.ID?.slice(0, 12),
+                time: new Date(event.time * 1000).toISOString(),
+              });
+            } catch {}
+          });
+
+          stream.on("error", () => {
+            clearTimeout(timeout);
+            resolve();
+          });
+
+          stream.on("end", () => {
+            clearTimeout(timeout);
+            resolve();
+          });
+        });
+
+        return {
+          content: [{ type: "text", text: events.length ? JSON.stringify(events, null, 2) : "No events captured in the time window." }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // 4. search_logs — search logs across multiple containers
+  server.tool(
+    "search_logs",
+    "Search Docker container logs across multiple containers using regex pattern matching. Use stream_logs for single-container log tailing; use this tool to search across multiple containers at once. Returns matching log lines with container name and line content. The pattern parameter accepts any valid regex; set ignore_case for case-insensitive matching. Returns 'No matches found.' when no lines match. Read-only and safe to call repeatedly.",
+    SearchLogsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const targetContainers = params.containers || [];
+        let containers: { id: string; name: string }[];
+
+        if (targetContainers.length > 0) {
+          containers = await Promise.all(
+            targetContainers.map(async (id) => {
+              const info = await docker.getContainer(id).inspect();
+              return { id, name: info.Name.replace(/^\//, "") };
+            })
+          );
+        } else {
+          const list = await docker.listContainers({ all: false });
+          containers = list.map((c) => ({ id: c.Id, name: c.Names[0]?.replace(/^\//, "") || c.Id.slice(0, 12) }));
+        }
+
+        const regex = new RegExp(params.pattern, params.ignore_case ? "i" : "");
+        const matches: any[] = [];
+
+        for (const container of containers) {
+          try {
+            const logStream = await docker.getContainer(container.id).logs({
+              stdout: true,
+              stderr: true,
+              tail: params.tail || 500,
+              since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
+            });
+            const output = sanitizeOutput(logStream.toString("utf-8"), 100_000);
+            const lines = output.split("\n");
+            for (const line of lines) {
+              if (regex.test(line)) {
+                matches.push({ container: container.name, line: line.trim() });
+              }
+            }
+          } catch {}
+        }
+
+        return {
+          content: [{ type: "text", text: matches.length ? JSON.stringify(matches, null, 2) : "No matches found." }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // 5. check_thresholds — check all containers against thresholds
+  server.tool(
+    "resource_alert_check",
+    "Check all running Docker containers against configurable CPU%, memory%, and restart count thresholds. Returns containers that violate thresholds with specific metrics that triggered alerts. Use container_resource_usage for raw metrics; use this tool for automated alerting. Default thresholds: 80% CPU, 80% memory, 5 restarts. Returns { violations: [...], checked: N } or { message: 'All containers within thresholds.', checked: N }. Read-only and safe to call repeatedly.",
+    ResourceAlertCheckSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const cpuThreshold = params.cpu_percent ?? 80;
+        const memThreshold = params.memory_percent ?? 80;
+        const restartThreshold = params.restart_count ?? 5;
+        const containers = await docker.listContainers({ all: false });
+        const violations: any[] = [];
+
+        for (const c of containers) {
+          const info = await docker.getContainer(c.Id).inspect();
+          const issues: string[] = [];
+
+          // Check restart count
+          if (info.RestartCount > restartThreshold) {
+            issues.push(`restarts: ${info.RestartCount} > ${restartThreshold}`);
+          }
+
+          // Check CPU and memory
+          try {
+            const stats = await docker.getContainer(c.Id).stats({ stream: false });
+            const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - (stats.precpu_stats?.cpu_usage?.total_usage ?? 0);
+            const systemDelta = stats.cpu_stats.system_cpu_usage - (stats.precpu_stats?.system_cpu_usage ?? 0);
+            const cpuCount = stats.cpu_stats.online_cpus ?? 1;
+            const cpuPercent = systemDelta > 0 ? (cpuDelta / systemDelta) * cpuCount * 100 : 0;
+            const memUsage = stats.memory_stats?.usage ?? 0;
+            const memLimit = stats.memory_stats?.limit ?? 1;
+            const memPercent = (memUsage / memLimit) * 100;
+
+            if (cpuPercent > cpuThreshold) issues.push(`cpu: ${Math.round(cpuPercent)}% > ${cpuThreshold}%`);
+            if (memPercent > memThreshold) issues.push(`memory: ${Math.round(memPercent)}% > ${memThreshold}%`);
+          } catch {}
+
+          if (issues.length > 0) {
+            violations.push({
+              container: c.Names[0]?.replace(/^\//, "") || c.Id.slice(0, 12),
+              id: c.Id.slice(0, 12),
+              issues,
+            });
+          }
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: violations.length
+              ? JSON.stringify({ violations, checked: containers.length }, null, 2)
+              : JSON.stringify({ message: "All containers within thresholds.", checked: containers.length }),
+          }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // 6. monitor_dashboard — single-call fleet summary
+  server.tool(
+    "monitor_dashboard",
+    "Comprehensive Docker fleet dashboard in a single API call. Aggregates health status of all containers, top 5 CPU consumers, recent events (last 5 minutes), and threshold violations into one response. Use individual tools (container_health_status, container_resource_usage, watch_events) for targeted queries; use this for a complete fleet overview. Returns object with summary (total, running, healthy, unhealthy), top_consumers, recent_events, and violations. Read-only and safe to call repeatedly.",
+    MonitorDashboardSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const containers = await docker.listContainers({ all: false });
+
+        // Fleet health
+        const health = await Promise.all(
+          containers.map(async (c) => {
+            const info = await docker.getContainer(c.Id).inspect();
+            return {
+              name: c.Names[0]?.replace(/^\//, "") || c.Id.slice(0, 12),
+              state: c.State,
+              health: info.State.Health?.Status || "no-healthcheck",
+              restartCount: info.RestartCount,
+            };
+          })
+        );
+
+        // Resource usage (top 5 by CPU)
+        const stats = await Promise.all(
+          containers.map(async (c) => {
+            try {
+              const s = await docker.getContainer(c.Id).stats({ stream: false });
+              const cpuDelta = s.cpu_stats.cpu_usage.total_usage - (s.precpu_stats?.cpu_usage?.total_usage ?? 0);
+              const systemDelta = s.cpu_stats.system_cpu_usage - (s.precpu_stats?.system_cpu_usage ?? 0);
+              const cpuCount = s.cpu_stats.online_cpus ?? 1;
+              const cpuPercent = systemDelta > 0 ? (cpuDelta / systemDelta) * cpuCount * 100 : 0;
+              const memUsage = s.memory_stats?.usage ?? 0;
+              const memLimit = s.memory_stats?.limit ?? 1;
+              const memPercent = (memUsage / memLimit) * 100;
+              return {
+                name: c.Names[0]?.replace(/^\//, "") || c.Id.slice(0, 12),
+                cpu_percent: Math.round(cpuPercent * 100) / 100,
+                memory_percent: Math.round(memPercent * 100) / 100,
+              };
+            } catch {
+              return null;
+            }
+          })
+        );
+
+        const topConsumers = stats.filter(Boolean).sort((a: any, b: any) => b.cpu_percent - a.cpu_percent).slice(0, 5);
+
+        // Recent events (last 5 minutes) - use simple approach
+        const recentEvents: any[] = [];
+        try {
+          const sinceTs = Math.floor((Date.now() - 5 * 60 * 1000) / 1000);
+          const eventStream = await docker.getEvents({ since: sinceTs }) as unknown as NodeJS.ReadableStream;
+          await new Promise<void>((resolve) => {
+            const timeout = setTimeout(() => { resolve(); }, 2000);
+            eventStream.on("data", (chunk: Buffer) => {
+              try {
+                const e = JSON.parse(chunk.toString());
+                recentEvents.push({
+                  action: e.Action,
+                  container: e.Actor?.Attributes?.name || e.Actor?.ID?.slice(0, 12),
+                  time: new Date(e.time * 1000).toISOString(),
+                });
+              } catch {}
+            });
+            eventStream.on("error", () => { clearTimeout(timeout); resolve(); });
+            eventStream.on("end", () => { clearTimeout(timeout); resolve(); });
+          });
+        } catch {}
+
+        // Threshold violations
+        const violations = stats.filter(Boolean).filter((s: any) => s.cpu_percent > 80 || s.memory_percent > 80);
+
+        const dashboard = {
+          summary: {
+            total_containers: containers.length,
+            running: containers.filter((c) => c.State === "running").length,
+            unhealthy: health.filter((h) => h.health === "unhealthy").length,
+          },
+          health,
+          top_cpu_consumers: topConsumers,
+          recent_events: recentEvents.slice(0, 10),
+          threshold_violations: violations,
+        };
+
+        return {
+          content: [{ type: "text", text: JSON.stringify(dashboard, null, 2) }],
+        };
+      } catch (err: any) {
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/volume.ts

@@ -0,0 +1,125 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  CreateVolumeSchema,
+  InspectVolumeSchema,
+  RemoveVolumeSchema,
+  PruneVolumesSchema,
+} from "../types.js";
+import { formatError } from "../docker.js";
+
+export function registerVolumeTools(server: McpServer, docker: Dockerode): void {
+  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({
+          Name: params.name,
+          Driver: params.driver || "local",
+          Labels: params.labels,
+          DriverOpts: params.options,
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              name: result.Name,
+              driver: result.Driver,
+              mountpoint: result.Mountpoint,
+              created: result.CreatedAt,
+              labels: result.Labels,
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "inspect_volume",
+    "Inspect a Docker volume. Returns detailed info including name, driver, mountpoint, labels, scope, and usage data.",
+    InspectVolumeSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const volume = docker.getVolume(params.name);
+        const info = await volume.inspect();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              name: info.Name,
+              driver: info.Driver,
+              mountpoint: info.Mountpoint,
+              labels: info.Labels,
+              scope: info.Scope,
+              options: info.Options,
+              status: info.Status || null,
+              usage: info.UsageData || null,
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "remove_volume",
+    "Remove a Docker volume. Use force=true to remove even if in use by containers.",
+    RemoveVolumeSchema.shape,
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const volume = docker.getVolume(params.name);
+        await volume.remove({ force: params.force || false });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ success: true, name: params.name, message: `Volume '${params.name}' removed` }),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "prune_volumes",
+    "Remove all unused Docker volumes. Returns count of removed volumes and reclaimed space.",
+    PruneVolumesSchema.shape,
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async (params) => {
+      try {
+        const filters: Record<string, string[]> = {};
+        if (params.filter) {
+          const match = params.filter.match(/label=(.+)/);
+          if (match) {
+            filters.label = [match[1]];
+          }
+        }
+        const result = await docker.pruneVolumes({
+          filters: Object.keys(filters).length > 0 ? filters : undefined,
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              volumes_deleted: result.VolumesDeleted || [],
+              space_reclaimed: result.SpaceReclaimed || 0,
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/types.ts

@@ -166,6 +166,26 @@ export const ListVolumesSchema = z.object({
   filter: z.string().optional().describe("Filter by name or driver"),
 });
 
+export const CreateVolumeSchema = z.object({
+  name: z.string().min(1).max(255).describe("Volume name"),
+  driver: z.string().optional().describe("Volume driver (default: 'local')"),
+  labels: z.record(z.string(), z.string()).optional().describe("Labels to apply to the volume"),
+  options: z.record(z.string(), z.string()).optional().describe("Driver-specific options"),
+});
+
+export const InspectVolumeSchema = z.object({
+  name: z.string().min(1).describe("Volume name or ID to inspect"),
+});
+
+export const RemoveVolumeSchema = z.object({
+  name: z.string().min(1).describe("Volume name or ID to remove"),
+  force: z.boolean().optional().describe("Force removal even if in use (default: false)"),
+});
+
+export const PruneVolumesSchema = z.object({
+  filter: z.string().optional().describe("Filter by label (e.g., 'label=key=value')"),
+});
+
 
 // Monitoring schemas (v0.2.0)
 export const ContainerHealthStatusSchema = z.object({});

package/tests/image.test.ts

@@ -28,7 +28,7 @@ import { createDockerClient } from "../src/docker.js";
 function createMockServer() {
   const tools: Record<string, { description: string; handler: Function }> = {};
   return {
-    tool: (name: string, description: string, _schema: unknown, handler: Function) => {
+    tool: (name: string, description: string, _schema: unknown, _hints: unknown, handler: Function) => {
       tools[name] = { description, handler };
     },
     tools,

package/tests/monitoring.test.ts

@@ -27,7 +27,7 @@ import { registerMonitoringTools } from "../src/tools/monitoring.js";
 function createMockServer() {
   const tools: Record<string, { description: string; handler: Function }> = {};
   return {
-    tool: (name: string, description: string, _schema: unknown, handler: Function) => {
+    tool: (name: string, description: string, _schema: unknown, _hints: unknown, handler: Function) => {
       tools[name] = { description, handler };
     },
     tools,

package/tests/volume.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock Dockerode before importing the module under test
+const mockCreateVolume = vi.fn();
+const mockListVolumes = vi.fn();
+const mockPruneVolumes = vi.fn();
+const mockGetVolume = vi.fn();
+
+vi.mock("dockerode", () => {
+  return {
+    default: vi.fn().mockImplementation(() => ({
+      createVolume: mockCreateVolume,
+      listVolumes: mockListVolumes,
+      pruneVolumes: mockPruneVolumes,
+      getVolume: mockGetVolume,
+    })),
+  };
+});
+
+import { registerVolumeTools } from "../src/tools/volume.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("Volume Tools", () => {
+  let server: ReturnType<typeof createMockServer>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    server = createMockServer();
+    // Create a fresh docker-like object with direct mock references
+    const docker = {
+      createVolume: mockCreateVolume,
+      listVolumes: mockListVolumes,
+      pruneVolumes: mockPruneVolumes,
+      getVolume: mockGetVolume,
+    } as any;
+    registerVolumeTools(server, docker);
+  });
+
+  describe("create_volume", () => {
+    it("should create a volume with default driver", async () => {
+      mockCreateVolume.mockResolvedValue({
+        Name: "test-vol",
+        Driver: "local",
+        Mountpoint: "/var/lib/docker/volumes/test-vol/_data",
+        CreatedAt: "2026-06-13T12:00:00Z",
+        Labels: {},
+      });
+
+      const handler = server.tools["create_volume"].handler;
+      const result = await handler({ name: "test-vol" });
+
+      expect(mockCreateVolume).toHaveBeenCalledWith({
+        Name: "test-vol",
+        Driver: "local",
+        Labels: undefined,
+        DriverOpts: undefined,
+      });
+      expect(result.isError).toBeFalsy();
+      const data = JSON.parse(result.content[0].text);
+      expect(data.name).toBe("test-vol");
+      expect(data.driver).toBe("local");
+    });
+
+    it("should create a volume with custom driver and labels", async () => {
+      mockCreateVolume.mockResolvedValue({
+        Name: "nfs-vol",
+        Driver: "nfs",
+        Mountpoint: "/var/lib/docker/volumes/nfs-vol/_data",
+        Labels: { env: "prod" },
+      });
+
+      const handler = server.tools["create_volume"].handler;
+      const result = await handler({
+        name: "nfs-vol",
+        driver: "nfs",
+        labels: { env: "prod" },
+      });
+
+      expect(mockCreateVolume).toHaveBeenCalledWith({
+        Name: "nfs-vol",
+        Driver: "nfs",
+        Labels: { env: "prod" },
+        DriverOpts: undefined,
+      });
+      expect(result.isError).toBeFalsy();
+    });
+
+    it("should handle creation errors", async () => {
+      mockCreateVolume.mockRejectedValue(new Error("volume name already exists"));
+
+      const handler = server.tools["create_volume"].handler;
+      const result = await handler({ name: "existing-vol" });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("volume name already exists");
+    });
+  });
+
+  describe("inspect_volume", () => {
+    it("should inspect a volume", async () => {
+      const mockInspect = vi.fn().mockResolvedValue({
+        Name: "test-vol",
+        Driver: "local",
+        Mountpoint: "/var/lib/docker/volumes/test-vol/_data",
+        Labels: {},
+        Scope: "local",
+        Options: {},
+        Status: null,
+        UsageData: null,
+      });
+      mockGetVolume.mockReturnValue({ inspect: mockInspect });
+
+      const handler = server.tools["inspect_volume"].handler;
+      const result = await handler({ name: "test-vol" });
+
+      expect(mockGetVolume).toHaveBeenCalledWith("test-vol");
+      expect(result.isError).toBeFalsy();
+      const data = JSON.parse(result.content[0].text);
+      expect(data.name).toBe("test-vol");
+      expect(data.scope).toBe("local");
+    });
+
+    it("should handle inspect errors for non-existent volumes", async () => {
+      const mockInspect = vi.fn().mockRejectedValue(new Error("No such volume"));
+      mockGetVolume.mockReturnValue({ inspect: mockInspect });
+
+      const handler = server.tools["inspect_volume"].handler;
+      const result = await handler({ name: "missing-vol" });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("No such volume");
+    });
+  });
+
+  describe("remove_volume", () => {
+    it("should remove a volume without force", async () => {
+      const mockRemove = vi.fn().mockResolvedValue(undefined);
+      mockGetVolume.mockReturnValue({ remove: mockRemove });
+
+      const handler = server.tools["remove_volume"].handler;
+      const result = await handler({ name: "old-vol" });
+
+      expect(mockRemove).toHaveBeenCalledWith({ force: false });
+      expect(result.isError).toBeFalsy();
+      const data = JSON.parse(result.content[0].text);
+      expect(data.success).toBe(true);
+    });
+
+    it("should remove a volume with force", async () => {
+      const mockRemove = vi.fn().mockResolvedValue(undefined);
+      mockGetVolume.mockReturnValue({ remove: mockRemove });
+
+      const handler = server.tools["remove_volume"].handler;
+      const result = await handler({ name: "in-use-vol", force: true });
+
+      expect(mockRemove).toHaveBeenCalledWith({ force: true });
+      expect(result.isError).toBeFalsy();
+    });
+
+    it("should handle removal errors", async () => {
+      const mockRemove = vi.fn().mockRejectedValue(new Error("volume is in use"));
+      mockGetVolume.mockReturnValue({ remove: mockRemove });
+
+      const handler = server.tools["remove_volume"].handler;
+      const result = await handler({ name: "busy-vol" });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("volume is in use");
+    });
+  });
+
+  describe("prune_volumes", () => {
+    it("should prune unused volumes", async () => {
+      mockPruneVolumes.mockResolvedValue({
+        VolumesDeleted: ["vol1", "vol2"],
+        SpaceReclaimed: 1024000,
+      });
+
+      const handler = server.tools["prune_volumes"].handler;
+      const result = await handler({});
+
+      expect(mockPruneVolumes).toHaveBeenCalledWith({ filters: undefined });
+      expect(result.isError).toBeFalsy();
+      const data = JSON.parse(result.content[0].text);
+      expect(data.volumes_deleted).toEqual(["vol1", "vol2"]);
+      expect(data.space_reclaimed).toBe(1024000);
+    });
+
+    it("should prune with label filter", async () => {
+      mockPruneVolumes.mockResolvedValue({
+        VolumesDeleted: ["old-cache"],
+        SpaceReclaimed: 500000,
+      });
+
+      const handler = server.tools["prune_volumes"].handler;
+      const result = await handler({ filter: "label=env=test" });
+
+      expect(mockPruneVolumes).toHaveBeenCalledWith({
+        filters: { label: ["env=test"] },
+      });
+      expect(result.isError).toBeFalsy();
+    });
+
+    it("should handle prune errors", async () => {
+      mockPruneVolumes.mockRejectedValue(new Error("prune failed"));
+
+      const handler = server.tools["prune_volumes"].handler;
+      const result = await handler({});
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("prune failed");
+    });
+  });
+});