@supernova123/docker-mcp-server 0.2.4 → 0.3.0

package/src/types.ts

@@ -1,5 +1,11 @@
 import { z } from "zod";
 
+// Validation regexes (shared across schemas)
+const SAFE_CMD_ARG = /^[A-Za-z0-9_./:@%+=,\-]+$/;
+const SAFE_PATH = /^\/[A-Za-z0-9_./\-]+$/;
+const SAFE_ENV_KEY = /^[A-Z_][A-Z0-9_]*$/;
+const SAFE_BUILD_CONTEXT = /^\/[A-Za-z0-9_./\-]+$/;
+
 // Container lifecycle schemas
 export const ListContainersSchema = z.object({
   all: z.boolean().optional().describe("Include stopped containers (default: false)"),
@@ -59,11 +65,15 @@ export const PullImageSchema = z.object({
 });
 
 export const BuildImageSchema = z.object({
-  context: z.string().describe("Build context path or Dockerfile content"),
+  context: z.string().regex(SAFE_BUILD_CONTEXT, "Build context must be a local absolute path (no URLs, no '..')")
+    .max(4096).describe("Build context path (local absolute path only)"),
   tag: z.string().describe("Tag for the built image (e.g., 'myapp:v1')"),
-  dockerfile: z.string().optional().describe("Dockerfile name relative to context (default: 'Dockerfile')"),
-  build_args: z.record(z.string()).optional().describe("Build arguments"),
-  target: z.string().optional().describe("Target build stage"),
+  dockerfile: z.string().max(256).optional().describe("Dockerfile name relative to context (default: 'Dockerfile')"),
+  build_args: z.record(
+    z.string().regex(SAFE_ENV_KEY, "Build arg key must be POSIX-style").max(256),
+    z.string().max(4096)
+  ).optional().describe("Build arguments (keys must be POSIX-style)"),
+  target: z.string().max(256).optional().describe("Target build stage"),
 });
 
 export const RemoveImageSchema = z.object({
@@ -112,8 +122,8 @@ export const CheckHealthSchema = z.object({
 
 export const WatchHealthSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
-  timeout: z.number().optional().describe("Max seconds to wait (default: 60)"),
-  interval: z.number().optional().describe("Seconds between polls (default: 5)"),
+  timeout: z.number().max(600).optional().describe("Max seconds to wait (default: 60, max: 600)"),
+  interval: z.number().max(60).optional().describe("Seconds between polls (default: 5, max: 60)"),
 });
 
 export const SetRestartPolicySchema = z.object({
@@ -125,7 +135,7 @@ export const SetRestartPolicySchema = z.object({
 // Logs schemas
 export const StreamLogsSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
-  tail: z.number().optional().describe("Number of lines to show (default: 100)"),
+  tail: z.number().max(10000).optional().describe("Number of lines to show (default: 100, max: 10000)"),
   since: z.string().optional().describe("Show logs since timestamp (e.g., '2026-01-01T00:00:00Z')"),
   follow: z.boolean().optional().describe("Follow log output (default: false)"),
 });
@@ -134,12 +144,17 @@ export const ContainerStatsSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
 });
 
-// Exec schema
+// Exec schema (validated per Finding 8.1 — command/working_dir/env constraints)
 export const ExecInContainerSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
-  command: z.array(z.string()).describe("Command to execute"),
-  working_dir: z.string().optional().describe("Working directory inside container"),
-  env: z.record(z.string()).optional().describe("Environment variables"),
+  command: z.array(z.string().max(500).regex(SAFE_CMD_ARG, "Command arg contains disallowed characters"))
+    .min(1).max(50).describe("Command to execute (max 50 args, alphanumeric + safe chars only)"),
+  working_dir: z.string().regex(SAFE_PATH, "Working directory must be an absolute path without '..'")
+    .max(1000).optional().describe("Working directory inside container (absolute path)"),
+  env: z.record(
+    z.string().regex(SAFE_ENV_KEY, "Env key must be POSIX-style (A-Z, 0-9, _)").max(100),
+    z.string().max(1000)
+  ).optional().describe("Environment variables (keys must be POSIX-style)"),
 });
 
 // Network/Volume schemas
@@ -151,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({});
@@ -163,13 +198,13 @@ export const WatchEventsSchema = z.object({
   container: z.string().optional().describe("Filter by container name or ID"),
   event_type: z.enum(["start", "stop", "die", "restart", "health_status", "oom", "all"]).optional().describe("Filter by event type (default: all)"),
   since: z.string().optional().describe("Show events since timestamp (e.g., '2026-01-01T00:00:00Z')"),
-  duration: z.number().optional().describe("Max seconds to listen (default: 30)"),
+  duration: z.number().max(300).optional().describe("Max seconds to listen (default: 30, max: 300)"),
 });
 
 export const SearchLogsSchema = z.object({
-  pattern: z.string().describe("Regex or grep pattern to search for"),
-  containers: z.array(z.string()).optional().describe("Specific containers to search (default: all running)"),
-  tail: z.number().optional().describe("Max lines to scan per container (default: 500)"),
+  pattern: z.string().max(1000).describe("Regex or grep pattern to search for"),
+  containers: z.array(z.string()).max(50).optional().describe("Specific containers to search (default: all running, max: 50)"),
+  tail: z.number().max(10000).optional().describe("Max lines to scan per container (default: 500, max: 10000)"),
   since: z.string().optional().describe("Only search logs since timestamp"),
   ignore_case: z.boolean().optional().describe("Case-insensitive search (default: false)"),
 });

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");
+    });
+  });
+});