@supernova123/docker-mcp-server 0.1.0

package/src/tools/health.ts

@@ -0,0 +1,150 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CheckHealthSchema, WatchHealthSchema, SetRestartPolicySchema } from "../types.js";
+import { formatError } from "../docker.js";
+
+export function registerHealthTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "check_health",
+    "Run a health probe against a container. Supports HTTP, TCP, and exec probes. Auto-detects from container HEALTHCHECK if available.",
+    CheckHealthSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const info = await container.inspect();
+        
+        // Check if container has HEALTHCHECK
+        const healthcheck = info.Config.Healthcheck;
+        let probeType = params.type;
+        let endpoint = params.endpoint;
+        let command = params.command;
+
+        if (!probeType && healthcheck?.Test?.length) {
+          const test = healthcheck.Test[0];
+          if (test.startsWith("CMD ")) {
+            probeType = "exec";
+            command = test.slice(4).split(" ");
+          } else if (test.startsWith("CMD-SHELL ")) {
+            probeType = "exec";
+            command = ["sh", "-c", test.slice(10)];
+          } else if (test === "NONE") {
+            probeType = undefined;
+          }
+        }
+
+        if (!probeType) {
+          return {
+            content: [{ type: "text", text: "No health check configured for this container and no probe type specified." }],
+          };
+        }
+
+        if (probeType === "exec" && command) {
+          const exec = await container.exec({
+            Cmd: command,
+            AttachStdout: true,
+            AttachStderr: true,
+          });
+          const stream = await exec.start({}) as unknown as import("stream").Duplex;
+          const output = await new Promise<string>((resolve) => {
+            let data = "";
+            stream.on("data", (chunk: Buffer) => { data += chunk.toString(); });
+            stream.on("end", () => resolve(data));
+          });
+          const inspect = await exec.inspect();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                healthy: inspect.ExitCode === 0,
+                exitCode: inspect.ExitCode,
+                output: output.trim(),
+              }, null, 2),
+            }],
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: `Health probe type '${probeType}' is not yet implemented in v1. Use exec probes or check container HEALTHCHECK directly.` }],
+          isError: true,
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "watch_health",
+    "Poll a container's health status until it becomes healthy or times out. Useful for waiting on service startup.",
+    WatchHealthSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const timeout = (params.timeout ?? 60) * 1000;
+        const interval = (params.interval ?? 5) * 1000;
+        const start = Date.now();
+
+        while (Date.now() - start < timeout) {
+          const info = await container.inspect();
+          const health = info.State.Health;
+          if (health?.Status === "healthy") {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ healthy: true, status: "healthy", waitTime: Date.now() - start }, null, 2) }],
+            };
+          }
+          if (health?.Status === "unhealthy") {
+            const lastLog = health.Log?.[health.Log.length - 1];
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  healthy: false,
+                  status: "unhealthy",
+                  exitCode: lastLog?.ExitCode,
+                  output: lastLog?.Output?.trim(),
+                }, null, 2),
+              }],
+            };
+          }
+          await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+
+        const info = await container.inspect();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              healthy: false,
+              status: "timeout",
+              containerHealth: info.State.Health?.Status ?? "no healthcheck",
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "set_restart_policy",
+    "Change the restart policy of a running container without recreating it.",
+    SetRestartPolicySchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        await container.update({
+          RestartPolicy: {
+            Name: params.policy,
+            MaximumRetryCount: params.max_retry_count ?? 0,
+          },
+        });
+        return {
+          content: [{ type: "text", text: `Restart policy set to '${params.policy}' for container ${params.container_id}.` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/image.ts

@@ -0,0 +1,92 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ListImagesSchema,
+  PullImageSchema,
+  BuildImageSchema,
+  RemoveImageSchema,
+} from "../types.js";
+import { formatImage, formatError } from "../docker.js";
+
+export function registerImageTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "list_images",
+    "List Docker images with optional filters. Returns image IDs, tags, sizes, and creation dates.",
+    ListImagesSchema.shape,
+    async (params) => {
+      try {
+        const images = await docker.listImages({
+          all: params.all ?? false,
+          filters: params.filter ? JSON.stringify({ reference: [params.filter] }) : undefined,
+        });
+        const results = images.map(formatImage);
+        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "pull_image",
+    "Pull a Docker image from a registry. Returns pull progress events.",
+    PullImageSchema.shape,
+    async (params) => {
+      try {
+        const imageRef = params.tag ? `${params.image}:${params.tag}` : params.image;
+        const stream = await docker.pull(imageRef);
+        // Wait for pull to complete
+        await new Promise<void>((resolve, reject) => {
+          docker.modem.followProgress(stream, (err: Error | null) => {
+            if (err) reject(err);
+            else resolve();
+          });
+        });
+        return { content: [{ type: "text", text: `Image ${imageRef} pulled successfully.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "build_image",
+    "Build a Docker image from a Dockerfile or build context path.",
+    BuildImageSchema.shape,
+    async (params) => {
+      try {
+        const stream = await docker.buildImage(
+          {
+            context: params.context,
+            src: [params.dockerfile ?? "Dockerfile"],
+          },
+          { t: params.tag, dockerfile: params.dockerfile, buildargs: params.build_args, target: params.target }
+        );
+        await new Promise<void>((resolve, reject) => {
+          docker.modem.followProgress(stream, (err: Error | null) => {
+            if (err) reject(err);
+            else resolve();
+          });
+        });
+        return { content: [{ type: "text", text: `Image ${params.tag} built successfully.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "remove_image",
+    "Remove a Docker image by name or ID. Use force to remove even if tagged.",
+    RemoveImageSchema.shape,
+    async (params) => {
+      try {
+        const image = docker.getImage(params.image);
+        await image.remove({ force: params.force ?? false });
+        return { content: [{ type: "text", text: `Image ${params.image} removed.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/logs.ts

@@ -0,0 +1,85 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
+import { formatError, formatBytes } from "../docker.js";
+
+export function registerLogsTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "stream_logs",
+    "Get logs from a Docker container. Supports tail count, timestamp filtering, and follow mode.",
+    StreamLogsSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const logs = await container.logs({
+          stdout: true,
+          stderr: true,
+          tail: params.tail ?? 100,
+          since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
+          follow: false as const,
+        });
+        // Dockerode returns a Buffer with multiplexed stream headers
+        const output = logs.toString("utf-8").replace(/^[\x00-\x0f]{8}/gm, "");
+        return { content: [{ type: "text", text: output || "No logs found." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "container_stats",
+    "Get real-time resource usage statistics for a Docker container (CPU, memory, network, I/O).",
+    ContainerStatsSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const stats = await container.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 ?? 0;
+        const memPercent = memLimit > 0 ? (memUsage / memLimit) * 100 : 0;
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              name: params.container_id,
+              cpu: {
+                percent: parseFloat(cpuPercent.toFixed(2)),
+                cores: cpuCount,
+              },
+              memory: {
+                usage: formatBytes(memUsage),
+                limit: formatBytes(memLimit),
+                percent: parseFloat(memPercent.toFixed(2)),
+              },
+              network: stats.networks
+                ? Object.fromEntries(
+                    Object.entries(stats.networks).map(([iface, data]) => [
+                      iface,
+                      {
+                        rx: formatBytes((data as { rx_bytes?: number }).rx_bytes ?? 0),
+                        tx: formatBytes((data as { tx_bytes?: number }).tx_bytes ?? 0),
+                      },
+                    ])
+                  )
+                : {},
+              blockIO: {
+                read: formatBytes((stats.blkio_stats as unknown as { io_service_bytes?: Array<{ value?: number }> })?.io_service_bytes?.[0]?.value ?? 0),
+                write: formatBytes((stats.blkio_stats as unknown as { io_service_bytes?: Array<{ value?: number }> })?.io_service_bytes?.[1]?.value ?? 0),
+              },
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/network.ts

@@ -0,0 +1,60 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListNetworksSchema, ListVolumesSchema } from "../types.js";
+import { formatError } from "../docker.js";
+
+export function registerNetworkTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "list_networks",
+    "List Docker networks with optional filter. Returns network IDs, names, drivers, and scopes.",
+    ListNetworksSchema.shape,
+    async (params) => {
+      try {
+        const networks = await docker.listNetworks({
+          filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
+        });
+        const results = networks.map((n) => ({
+          id: n.Id.substring(0, 12),
+          name: n.Name,
+          driver: n.Driver,
+          scope: n.Scope,
+          created: n.Created,
+          containers: n.Containers
+            ? Object.fromEntries(
+                Object.entries(n.Containers).map(([id, c]) => [
+                  id.substring(0, 12),
+                  { name: (c as { Name?: string }).Name, ipv4: (c as { IPv4Address?: string }).IPv4Address },
+                ])
+              )
+            : {},
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "list_volumes",
+    "List Docker volumes with optional filter. Returns volume names, drivers, mount points, and labels.",
+    ListVolumesSchema.shape,
+    async (params) => {
+      try {
+        const result = await docker.listVolumes({
+          filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
+        });
+        const volumes = (result.Volumes || []).map((v) => ({
+          name: (v as unknown as Record<string, unknown>).Name,
+          driver: (v as unknown as Record<string, unknown>).Driver,
+          mountpoint: (v as unknown as Record<string, unknown>).Mountpoint,
+          created: (v as unknown as Record<string, unknown>).CreatedAt ?? (v as unknown as Record<string, unknown>).Created,
+          labels: (v as unknown as Record<string, unknown>).Labels,
+        }));
+        return { content: [{ type: "text", text: JSON.stringify(volumes, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+
+// Container lifecycle schemas
+export const ListContainersSchema = z.object({
+  all: z.boolean().optional().describe("Include stopped containers (default: false)"),
+  label: z.array(z.string()).optional().describe("Filter by label (e.g., 'app=web')"),
+  name: z.string().optional().describe("Filter by name (partial match)"),
+  state: z.enum(["running", "stopped", "paused", "exited", "created", "restarting"]).optional().describe("Filter by state"),
+});
+
+export const InspectContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+});
+
+export const StartContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+});
+
+export const StopContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  timeout: z.number().optional().describe("Seconds to wait before killing (default: 10)"),
+});
+
+export const RestartContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  timeout: z.number().optional().describe("Seconds to wait before killing (default: 10)"),
+});
+
+export const RemoveContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  force: z.boolean().optional().describe("Force removal even if running (default: false)"),
+});
+
+export const RecreateContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  timeout: z.number().optional().describe("Seconds to wait before killing (default: 10)"),
+});
+
+export const RunContainerSchema = z.object({
+  image: z.string().describe("Image name (e.g., 'nginx:latest')"),
+  name: z.string().optional().describe("Container name"),
+  env: z.record(z.string()).optional().describe("Environment variables"),
+  ports: z.record(z.string()).optional().describe("Port mappings (e.g., {'8080/tcp': '80/tcp'})"),
+  volumes: z.array(z.string()).optional().describe("Volume mounts (e.g., ['/host/path:/container/path'])"),
+  restart_policy: z.enum(["no", "always", "unless-stopped", "on-failure"]).optional().describe("Restart policy"),
+  command: z.array(z.string()).optional().describe("Override command"),
+  detach: z.boolean().optional().describe("Run in detached mode (default: true)"),
+});
+
+// Image management schemas
+export const ListImagesSchema = z.object({
+  all: z.boolean().optional().describe("Include intermediate images (default: false)"),
+  filter: z.string().optional().describe("Filter by reference"),
+});
+
+export const PullImageSchema = z.object({
+  image: z.string().describe("Image to pull (e.g., 'nginx:latest')"),
+  tag: z.string().optional().describe("Tag to pull (default: 'latest')"),
+});
+
+export const BuildImageSchema = z.object({
+  context: z.string().describe("Build context path or Dockerfile content"),
+  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"),
+});
+
+export const RemoveImageSchema = z.object({
+  image: z.string().describe("Image name or ID"),
+  force: z.boolean().optional().describe("Force removal (default: false)"),
+});
+
+// Docker Compose schemas
+export const ComposeUpSchema = z.object({
+  path: z.string().describe("Path to docker-compose.yml directory"),
+  build: z.boolean().optional().describe("Build images before starting (default: false)"),
+  detach: z.boolean().optional().describe("Run in detached mode (default: true)"),
+  services: z.array(z.string()).optional().describe("Specific services to start"),
+});
+
+export const ComposeDownSchema = z.object({
+  path: z.string().describe("Path to docker-compose.yml directory"),
+  volumes: z.boolean().optional().describe("Remove named volumes (default: false)"),
+  timeout: z.number().optional().describe("Shutdown timeout in seconds (default: 10)"),
+});
+
+export const ComposePsSchema = z.object({
+  path: z.string().describe("Path to docker-compose.yml directory"),
+});
+
+export const ComposeLogsSchema = z.object({
+  path: z.string().describe("Path to docker-compose.yml directory"),
+  services: z.array(z.string()).optional().describe("Specific services to tail"),
+  tail: z.number().optional().describe("Number of lines to show (default: 100)"),
+  follow: z.boolean().optional().describe("Follow log output (default: false)"),
+});
+
+export const ComposeRestartSchema = z.object({
+  path: z.string().describe("Path to docker-compose.yml directory"),
+  services: z.array(z.string()).optional().describe("Specific services to restart (empty = all)"),
+  timeout: z.number().optional().describe("Shutdown timeout in seconds (default: 10)"),
+});
+
+// Health schemas
+export const CheckHealthSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  type: z.enum(["http", "tcp", "exec"]).optional().describe("Probe type (default: auto-detect from HEALTHCHECK)"),
+  endpoint: z.string().optional().describe("HTTP endpoint or TCP port"),
+  command: z.array(z.string()).optional().describe("Command for exec probe"),
+});
+
+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)"),
+});
+
+export const SetRestartPolicySchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  policy: z.enum(["no", "always", "unless-stopped", "on-failure"]).describe("Restart policy"),
+  max_retry_count: z.number().optional().describe("Max retry count for on-failure (default: 0)"),
+});
+
+// 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)"),
+  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)"),
+});
+
+export const ContainerStatsSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+});
+
+// Exec schema
+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"),
+});
+
+// Network/Volume schemas
+export const ListNetworksSchema = z.object({
+  filter: z.string().optional().describe("Filter by name or driver"),
+});
+
+export const ListVolumesSchema = z.object({
+  filter: z.string().optional().describe("Filter by name or driver"),
+});