@supernova123/docker-mcp-server 0.2.5 → 0.3.1

package/dist/docker.d.ts

@@ -5,6 +5,35 @@ export interface DockerClientOptions {
     port?: number;
 }
 export declare function createDockerClient(options?: DockerClientOptions): Dockerode;
+/**
+ * Structured error types for programmatic error classification.
+ * Helps AI clients decide whether to retry (retryable) or report (permanent).
+ */
+export declare class DockerConnectionError extends Error {
+    retryable: boolean;
+    constructor(message: string);
+}
+export declare class DockerTimeoutError extends Error {
+    retryable: boolean;
+    constructor(message: string);
+}
+export declare class DockerPermissionError extends Error {
+    retryable: boolean;
+    constructor(message: string);
+}
+/**
+ * Check Docker daemon connectivity at startup.
+ * Returns a structured error if Docker is unreachable.
+ */
+export declare function checkDockerConnection(docker: Dockerode): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * Run a Docker API call with a configurable timeout.
+ * Returns structured error on timeout instead of hanging indefinitely.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: 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

@@ -9,7 +9,77 @@ export function createDockerClient(options) {
     // Default: local socket
     return new Dockerode({ socketPath: "/var/run/docker.sock" });
 }
+/**
+ * Structured error types for programmatic error classification.
+ * Helps AI clients decide whether to retry (retryable) or report (permanent).
+ */
+export class DockerConnectionError extends Error {
+    retryable = false;
+    constructor(message) {
+        super(message);
+        this.name = "DockerConnectionError";
+    }
+}
+export class DockerTimeoutError extends Error {
+    retryable = true;
+    constructor(message) {
+        super(message);
+        this.name = "DockerTimeoutError";
+    }
+}
+export class DockerPermissionError extends Error {
+    retryable = false;
+    constructor(message) {
+        super(message);
+        this.name = "DockerPermissionError";
+    }
+}
+/**
+ * Check Docker daemon connectivity at startup.
+ * Returns a structured error if Docker is unreachable.
+ */
+export async function checkDockerConnection(docker) {
+    try {
+        await docker.ping();
+        return { ok: true };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes("EACCES") || msg.includes("Permission denied")) {
+            return {
+                ok: false,
+                error: `DockerConnectionError: Cannot access Docker socket — ${msg}. Fix: add user to docker group (sudo usermod -aG docker $USER) or run as root.`,
+            };
+        }
+        if (msg.includes("ENOENT") || msg.includes("no such file")) {
+            return {
+                ok: false,
+                error: `DockerConnectionError: Docker socket not found at /var/run/docker.sock — ${msg}. Fix: install Docker (https://docs.docker.com/engine/install/) and ensure the daemon is running.`,
+            };
+        }
+        return {
+            ok: false,
+            error: `DockerConnectionError: Cannot connect to Docker daemon — ${msg}. Fix: ensure Docker is running (systemctl status docker).`,
+        };
+    }
+}
+/**
+ * Run a Docker API call with a configurable timeout.
+ * Returns structured error on timeout instead of hanging indefinitely.
+ */
+export async function withTimeout(promise, ms, label) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new DockerTimeoutError(`Docker API call "${label}" timed out after ${ms}ms`)), ms)),
+    ]);
+}
 export function formatError(error) {
+    if (error instanceof DockerConnectionError)
+        return `${error.name}: ${error.message}`;
+    if (error instanceof DockerTimeoutError)
+        return `${error.name}: ${error.message}`;
+    if (error instanceof DockerPermissionError)
+        return `${error.name}: ${error.message}`;
     if (error instanceof Error)
         return error.message;
     if (typeof error === "string")
@@ -57,7 +127,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/index.js

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createDockerClient } from "./docker.js";
+import { createDockerClient, checkDockerConnection } from "./docker.js";
 import { createServer } from "./server.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
 async function main() {
     const docker = createDockerClient();
-    const server = createServer(docker);
+    // Startup health check: verify Docker daemon is reachable
+    const health = await checkDockerConnection(docker);
+    if (!health.ok) {
+        process.stderr.write(`${health.error}\n`);
+        process.exit(1);
+    }
+    process.stderr.write("Docker daemon reachable\n");
+    const server = createServer(docker, { timeoutMs: DEFAULT_TIMEOUT_MS });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write("Docker MCP Server running on stdio\n");

package/dist/server.d.ts

@@ -1,4 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import Dockerode from "dockerode";
-export declare function createServer(docker: Dockerode): McpServer;
+export interface ServerOptions {
+    timeoutMs?: number;
+}
+export declare function createServer(docker: Dockerode, options?: ServerOptions): McpServer;
 //# sourceMappingURL=server.d.ts.map

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) {
+export function createServer(docker, options) {
     const server = new McpServer({
         name: "docker-mcp-server",
-        version: "0.2.0",
+        version: "0.3.1",
     });
     // 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.1",
   "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

@@ -17,7 +17,89 @@ export function createDockerClient(options?: DockerClientOptions): Dockerode {
   return new Dockerode({ socketPath: "/var/run/docker.sock" });
 }
 
+/**
+ * Structured error types for programmatic error classification.
+ * Helps AI clients decide whether to retry (retryable) or report (permanent).
+ */
+export class DockerConnectionError extends Error {
+  retryable = false;
+  constructor(message: string) {
+    super(message);
+    this.name = "DockerConnectionError";
+  }
+}
+
+export class DockerTimeoutError extends Error {
+  retryable = true;
+  constructor(message: string) {
+    super(message);
+    this.name = "DockerTimeoutError";
+  }
+}
+
+export class DockerPermissionError extends Error {
+  retryable = false;
+  constructor(message: string) {
+    super(message);
+    this.name = "DockerPermissionError";
+  }
+}
+
+/**
+ * Check Docker daemon connectivity at startup.
+ * Returns a structured error if Docker is unreachable.
+ */
+export async function checkDockerConnection(
+  docker: Dockerode
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    await docker.ping();
+    return { ok: true };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("EACCES") || msg.includes("Permission denied")) {
+      return {
+        ok: false,
+        error: `DockerConnectionError: Cannot access Docker socket — ${msg}. Fix: add user to docker group (sudo usermod -aG docker $USER) or run as root.`,
+      };
+    }
+    if (msg.includes("ENOENT") || msg.includes("no such file")) {
+      return {
+        ok: false,
+        error: `DockerConnectionError: Docker socket not found at /var/run/docker.sock — ${msg}. Fix: install Docker (https://docs.docker.com/engine/install/) and ensure the daemon is running.`,
+      };
+    }
+    return {
+      ok: false,
+      error: `DockerConnectionError: Cannot connect to Docker daemon — ${msg}. Fix: ensure Docker is running (systemctl status docker).`,
+    };
+  }
+}
+
+/**
+ * Run a Docker API call with a configurable timeout.
+ * Returns structured error on timeout instead of hanging indefinitely.
+ */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  label: string
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(
+        () => reject(new DockerTimeoutError(`Docker API call "${label}" timed out after ${ms}ms`)),
+        ms
+      )
+    ),
+  ]);
+}
+
 export function formatError(error: unknown): string {
+  if (error instanceof DockerConnectionError) return `${error.name}: ${error.message}`;
+  if (error instanceof DockerTimeoutError) return `${error.name}: ${error.message}`;
+  if (error instanceof DockerPermissionError) return `${error.name}: ${error.message}`;
   if (error instanceof Error) return error.message;
   if (typeof error === "string") return error;
   return String(error);
@@ -66,7 +148,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/index.ts

@@ -1,12 +1,23 @@
 #!/usr/bin/env node
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createDockerClient } from "./docker.js";
+import { createDockerClient, checkDockerConnection } from "./docker.js";
 import { createServer } from "./server.js";
 
+const DEFAULT_TIMEOUT_MS = 30_000;
+
 async function main() {
   const docker = createDockerClient();
-  const server = createServer(docker);
+
+  // Startup health check: verify Docker daemon is reachable
+  const health = await checkDockerConnection(docker);
+  if (!health.ok) {
+    process.stderr.write(`${health.error}\n`);
+    process.exit(1);
+  }
+  process.stderr.write("Docker daemon reachable\n");
+
+  const server = createServer(docker, { timeoutMs: DEFAULT_TIMEOUT_MS });
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/server.ts

@@ -7,12 +7,17 @@ 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 {
+export interface ServerOptions {
+  timeoutMs?: number;
+}
+
+export function createServer(docker: Dockerode, options?: ServerOptions): McpServer {
   const server = new McpServer({
     name: "docker-mcp-server",
-    version: "0.2.0",
+    version: "0.3.1",
   });
 
   // Register all tool categories
@@ -23,6 +28,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/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");
+    });
+  });
+});