@supernova123/docker-mcp-server 0.1.0

package/dist/types.js

@@ -0,0 +1,128 @@
+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"),
+});
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@supernova123/docker-mcp-server",
+  "version": "0.1.0",
+  "description": "Docker MCP server designed for agents that need their containers to stay running. Health checks, auto-restart, Compose lifecycle, log streaming.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "docker-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "docker",
+    "container",
+    "compose",
+    "health-check",
+    "devops",
+    "ai-agent",
+    "model-context-protocol"
+  ],
+  "author": "Nova",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/friendlygeorge/docker-mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "postInstallInstructions": "Run with: npx @supernova123/docker-mcp-server",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "dockerode": "^4.0.4",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.31",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  }
+}

package/src/docker.ts

@@ -0,0 +1,65 @@
+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(),
+  };
+}
+
+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/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createDockerClient } from "./docker.js";
+import { createServer } from "./server.js";
+
+async function main() {
+  const docker = createDockerClient();
+  const server = createServer(docker);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.stderr.write("Docker MCP Server running on stdio\n");
+}
+
+main().catch((error) => {
+  process.stderr.write(`Fatal error: ${error}\n`);
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import Dockerode from "dockerode";
+import { registerContainerTools } from "./tools/container.js";
+import { registerImageTools } from "./tools/image.js";
+import { registerComposeTools } from "./tools/compose.js";
+import { registerHealthTools } from "./tools/health.js";
+import { registerLogsTools } from "./tools/logs.js";
+import { registerExecTools } from "./tools/exec.js";
+import { registerNetworkTools } from "./tools/network.js";
+
+export function createServer(docker: Dockerode): McpServer {
+  const server = new McpServer({
+    name: "docker-mcp-server",
+    version: "0.1.0",
+  });
+
+  // Register all tool categories
+  registerContainerTools(server, docker);
+  registerImageTools(server, docker);
+  registerComposeTools(server);
+  registerHealthTools(server, docker);
+  registerLogsTools(server, docker);
+  registerExecTools(server, docker);
+  registerNetworkTools(server, docker);
+
+  return server;
+}

package/src/tools/compose.ts

@@ -0,0 +1,114 @@
+import { execSync, exec as execCb } from "child_process";
+import { promisify } from "util";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ComposeUpSchema,
+  ComposeDownSchema,
+  ComposePsSchema,
+  ComposeLogsSchema,
+  ComposeRestartSchema,
+} from "../types.js";
+import { formatError } from "../docker.js";
+
+const execAsync = promisify(execCb);
+
+function runCompose(path: string, args: string[]): string {
+  try {
+    const result = execSync(`docker compose -f ${path} ${args.join(" ")}`, {
+      encoding: "utf-8",
+      timeout: 30000,
+    });
+    return result.trim();
+  } catch (error: unknown) {
+    const err = error as { stderr?: string; stdout?: string };
+    throw new Error(err.stderr || err.stdout || formatError(error));
+  }
+}
+
+export function registerComposeTools(server: McpServer): void {
+  server.tool(
+    "compose_up",
+    "Bring up Docker Compose services from a docker-compose.yml file. Optionally build images first.",
+    ComposeUpSchema.shape,
+    async (params) => {
+      try {
+        const args = ["up", "-d"];
+        if (params.build) args.push("--build");
+        if (params.services?.length) args.push(...params.services);
+        const output = runCompose(params.path, args);
+        return { content: [{ type: "text", text: output || "Compose services started." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "compose_down",
+    "Tear down Docker Compose services. Optionally remove named volumes.",
+    ComposeDownSchema.shape,
+    async (params) => {
+      try {
+        const args = ["down"];
+        if (params.volumes) args.push("-v");
+        if (params.timeout) args.push(`--timeout ${params.timeout}`);
+        const output = runCompose(params.path, args);
+        return { content: [{ type: "text", text: output || "Compose services stopped." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "compose_ps",
+    "List service states across a Docker Compose stack.",
+    ComposePsSchema.shape,
+    async (params) => {
+      try {
+        const output = runCompose(params.path, ["ps", "--format", "json"]);
+        const lines = output.split("\n").filter(Boolean);
+        const services = lines.map((line) => {
+          try { return JSON.parse(line); } catch { return { raw: line }; }
+        });
+        return { content: [{ type: "text", text: JSON.stringify(services, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "compose_logs",
+    "Tail logs from Docker Compose services. Supports filtering by service and line count.",
+    ComposeLogsSchema.shape,
+    async (params) => {
+      try {
+        const args = ["logs", "--tail", String(params.tail ?? 100)];
+        if (params.follow) args.push("-f");
+        if (params.services?.length) args.push(...params.services);
+        const output = runCompose(params.path, args);
+        return { content: [{ type: "text", text: output || "No logs found." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "compose_restart",
+    "Restart Docker Compose services. Restart specific services or the entire stack.",
+    ComposeRestartSchema.shape,
+    async (params) => {
+      try {
+        const args = ["restart"];
+        if (params.timeout) args.push(`--timeout ${params.timeout}`);
+        if (params.services?.length) args.push(...params.services);
+        const output = runCompose(params.path, args);
+        return { content: [{ type: "text", text: output || "Compose services restarted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/container.ts

@@ -0,0 +1,193 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ListContainersSchema,
+  InspectContainerSchema,
+  StartContainerSchema,
+  StopContainerSchema,
+  RestartContainerSchema,
+  RemoveContainerSchema,
+  RecreateContainerSchema,
+  RunContainerSchema,
+} from "../types.js";
+import { formatContainer, formatError } from "../docker.js";
+
+export function registerContainerTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "list_containers",
+    "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.",
+    ListContainersSchema.shape,
+    async (params) => {
+      try {
+        const containers = await docker.listContainers({
+          all: params.all ?? false,
+          filters: JSON.stringify({
+            ...(params.label ? { label: params.label } : {}),
+            ...(params.name ? { name: [`/${params.name}`] } : {}),
+            ...(params.state ? { status: [params.state] } : {}),
+          }),
+        });
+        const results = containers.map(formatContainer);
+        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "inspect_container",
+    "Get detailed configuration and state of a Docker container by ID or name.",
+    InspectContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const info = await container.inspect();
+        return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "start_container",
+    "Start a stopped Docker container by ID or name.",
+    StartContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        await container.start();
+        return { content: [{ type: "text", text: `Container ${params.container_id} started.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "stop_container",
+    "Stop a running Docker container by ID or name with optional timeout.",
+    StopContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        await container.stop({ t: params.timeout ?? 10 });
+        return { content: [{ type: "text", text: `Container ${params.container_id} stopped.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "restart_container",
+    "Restart a Docker container by ID or name with optional timeout.",
+    RestartContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        await container.restart({ t: params.timeout ?? 10 });
+        return { content: [{ type: "text", text: `Container ${params.container_id} restarted.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "remove_container",
+    "Remove a Docker container by ID or name. Use force to remove running containers.",
+    RemoveContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        await container.remove({ force: params.force ?? false });
+        return { content: [{ type: "text", text: `Container ${params.container_id} removed.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "recreate_container",
+    "Recreate a container with the same configuration (stop, remove, re-create). Useful for applying config changes.",
+    RecreateContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const info = await container.inspect();
+        
+        // Stop and remove
+        try { await container.stop({ t: params.timeout ?? 10 }); } catch { /* already stopped */ }
+        await container.remove({ force: true });
+
+        // Re-create with same config
+        const createOpts: Dockerode.ContainerCreateOptions = {
+          name: info.Name.replace(/^\//, ""),
+          Image: info.Config.Image,
+          Env: info.Config.Env,
+          Cmd: info.Config.Cmd,
+          WorkingDir: info.Config.WorkingDir,
+          Labels: info.Config.Labels || {},
+          HostConfig: {
+            Binds: info.HostConfig?.Binds,
+            PortBindings: info.HostConfig?.PortBindings,
+            RestartPolicy: info.HostConfig?.RestartPolicy,
+            NetworkMode: info.HostConfig?.NetworkMode,
+          },
+        };
+
+        const newContainer = await docker.createContainer(createOpts);
+        await newContainer.start();
+        return {
+          content: [{ type: "text", text: `Container recreated and started. New ID: ${newContainer.id.substring(0, 12)}` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "run_container",
+    "Create and start a new Docker container with one command. Supports image, env, ports, volumes, restart policy, and command override.",
+    RunContainerSchema.shape,
+    async (params) => {
+      try {
+        const createOpts: Dockerode.ContainerCreateOptions = {
+          Image: params.image,
+          name: params.name,
+          Env: params.env ? Object.entries(params.env).map(([k, v]) => `${k}=${v}`) : undefined,
+          Cmd: params.command,
+          ExposedPorts: params.ports
+            ? Object.fromEntries(Object.keys(params.ports).map((k) => [k, {}]))
+            : undefined,
+          HostConfig: {
+            PortBindings: params.ports
+              ? Object.fromEntries(
+                  Object.entries(params.ports).map(([containerPort, hostBinding]) => [
+                    containerPort,
+                    [{ HostPort: hostBinding }],
+                  ])
+                )
+              : undefined,
+            Binds: params.volumes,
+            RestartPolicy: params.restart_policy
+              ? { Name: params.restart_policy, MaximumRetryCount: 0 }
+              : undefined,
+          },
+        };
+
+        const container = await docker.createContainer(createOpts);
+        await container.start();
+        return {
+          content: [{ type: "text", text: `Container created and started. ID: ${container.id.substring(0, 12)}` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}

package/src/tools/exec.ts

@@ -0,0 +1,48 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ExecInContainerSchema } from "../types.js";
+import { formatError } from "../docker.js";
+
+export function registerExecTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "exec_in_container",
+    "Execute a command inside a running Docker container. Returns stdout, stderr, and exit code.",
+    ExecInContainerSchema.shape,
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const exec = await container.exec({
+          Cmd: params.command,
+          AttachStdout: true,
+          AttachStderr: true,
+          WorkingDir: params.working_dir,
+          Env: params.env ? Object.entries(params.env).map(([k, v]) => `${k}=${v}`) : undefined,
+        });
+
+        const stream = await exec.start({});
+        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();
+        const cleanOutput = output.replace(/^[\x00-\x0f]{8}/gm, "");
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              exitCode: inspect.ExitCode,
+              stdout: cleanOutput,
+              stderr: "",
+            }, null, 2),
+          }],
+          isError: inspect.ExitCode !== 0,
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}