@rog0x/mcp-docker-tools 1.0.0

package/src/index.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { handleContainerList } from "./tools/container-list.js";
+import { handleImageList } from "./tools/image-list.js";
+import { handleDockerfileAnalyzer } from "./tools/dockerfile-analyzer.js";
+import { handleComposeAnalyzer } from "./tools/compose-analyzer.js";
+import { handleContainerLogs } from "./tools/container-logs.js";
+
+const server = new McpServer({
+  name: "mcp-docker-tools",
+  version: "1.0.0",
+});
+
+// Register: docker_container_list
+server.tool(
+  "docker_container_list",
+  "List Docker containers with status, ports, image, created time, and resource usage. Can show only running containers or all containers including stopped ones.",
+  {
+    all: z.boolean().optional().default(false).describe("If true, show all containers including stopped ones. Defaults to false (running only)."),
+    format: z.enum(["table", "json"]).optional().default("json").describe("Output format: 'table' for readable text, 'json' for structured data. Defaults to 'json'."),
+  },
+  async (args) => {
+    const text = await handleContainerList(args);
+    return { content: [{ type: "text" as const, text }] };
+  }
+);
+
+// Register: docker_image_list
+server.tool(
+  "docker_image_list",
+  "List Docker images with size, tags, created date, and layer count. Optionally filter by repository name.",
+  {
+    filter: z.string().optional().describe("Filter images by repository name (partial match). Leave empty to list all."),
+    showDangling: z.boolean().optional().default(false).describe("Include dangling (untagged) images. Defaults to false."),
+    format: z.enum(["table", "json"]).optional().default("json").describe("Output format: 'table' or 'json'. Defaults to 'json'."),
+  },
+  async (args) => {
+    const text = await handleImageList(args);
+    return { content: [{ type: "text" as const, text }] };
+  }
+);
+
+// Register: docker_dockerfile_analyze
+server.tool(
+  "docker_dockerfile_analyze",
+  "Analyze a Dockerfile for best practices including multi-stage builds, non-root user, .dockerignore usage, layer caching order, image size optimization, and security.",
+  {
+    content: z.string().describe("The full content of the Dockerfile to analyze."),
+    checkDockerignore: z.boolean().optional().default(true).describe("If true, also checks for common .dockerignore recommendations. Defaults to true."),
+  },
+  async (args) => {
+    const text = await handleDockerfileAnalyzer(args);
+    return { content: [{ type: "text" as const, text }] };
+  }
+);
+
+// Register: docker_compose_analyze
+server.tool(
+  "docker_compose_analyze",
+  "Analyze docker-compose.yml: list services, ports, volumes, networks, health checks, dependencies. Suggest improvements.",
+  {
+    content: z.string().describe("The full content of the docker-compose.yml to analyze."),
+  },
+  async (args) => {
+    const text = await handleComposeAnalyzer(args);
+    return { content: [{ type: "text" as const, text }] };
+  }
+);
+
+// Register: docker_container_logs
+server.tool(
+  "docker_container_logs",
+  "Get logs from a Docker container. Supports retrieving the last N lines, filtering by keyword, and including timestamps.",
+  {
+    container: z.string().describe("Container name or ID to get logs from."),
+    tail: z.number().optional().default(100).describe("Number of lines to retrieve from the end of logs. Defaults to 100."),
+    since: z.string().optional().describe("Show logs since a timestamp (e.g., '2024-01-01T00:00:00') or relative duration (e.g., '1h', '30m')."),
+    until: z.string().optional().describe("Show logs until a timestamp or relative duration."),
+    filter: z.string().optional().describe("Filter log lines to only include those containing this keyword (case-insensitive)."),
+    timestamps: z.boolean().optional().default(true).describe("Include timestamps in log output. Defaults to true."),
+  },
+  async (args) => {
+    const text = await handleContainerLogs(args);
+    return { content: [{ type: "text" as const, text }] };
+  }
+);
+
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("mcp-docker-tools server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/tools/compose-analyzer.ts

@@ -0,0 +1,316 @@
+export const composeAnalyzerTool = {
+  name: "docker_compose_analyze",
+  description:
+    "Analyze a docker-compose.yml file: list services, ports, volumes, networks, " +
+    "health checks, dependencies, and environment variables. Suggests improvements " +
+    "for production readiness, security, and best practices.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      content: {
+        type: "string",
+        description: "The full content of the docker-compose.yml to analyze.",
+      },
+    },
+    required: ["content"],
+  },
+};
+
+interface ServiceInfo {
+  name: string;
+  image?: string;
+  build?: string;
+  ports: string[];
+  volumes: string[];
+  networks: string[];
+  dependsOn: string[];
+  environment: string[];
+  hasHealthcheck: boolean;
+  restart?: string;
+  hasResourceLimits: boolean;
+  hasReadonlyRootfs: boolean;
+  hasSecurityOpt: boolean;
+}
+
+interface ComposeAnalysis {
+  version?: string;
+  services: ServiceInfo[];
+  topLevelNetworks: string[];
+  topLevelVolumes: string[];
+  findings: { severity: string; message: string; suggestion?: string }[];
+}
+
+function parseSimpleYaml(content: string): ComposeAnalysis {
+  const lines = content.split("\n");
+  const analysis: ComposeAnalysis = {
+    services: [],
+    topLevelNetworks: [],
+    topLevelVolumes: [],
+    findings: [],
+  };
+
+  let currentTopLevel = "";
+  let currentService = "";
+  let currentServiceKey = "";
+  let inServiceBlock = false;
+  const serviceMap = new Map<string, ServiceInfo>();
+
+  for (const raw of lines) {
+    // Skip comments and empty
+    if (raw.trim().startsWith("#") || !raw.trim()) continue;
+
+    const indent = raw.length - raw.trimStart().length;
+    const trimmed = raw.trim();
+
+    // Top-level keys (no indent)
+    if (indent === 0 && trimmed.endsWith(":")) {
+      currentTopLevel = trimmed.replace(":", "").trim();
+      currentService = "";
+      currentServiceKey = "";
+      inServiceBlock = currentTopLevel === "services";
+      continue;
+    }
+
+    if (indent === 0 && trimmed.includes(":")) {
+      const key = trimmed.split(":")[0].trim();
+      const value = trimmed.substring(trimmed.indexOf(":") + 1).trim();
+      if (key === "version") {
+        analysis.version = value.replace(/['"]/g, "");
+      }
+      currentTopLevel = key;
+      inServiceBlock = key === "services";
+      currentService = "";
+      continue;
+    }
+
+    // Service-level (indent 2)
+    if (inServiceBlock && indent === 2 && trimmed.endsWith(":") && !trimmed.startsWith("-")) {
+      currentService = trimmed.replace(":", "").trim();
+      currentServiceKey = "";
+      if (!serviceMap.has(currentService)) {
+        serviceMap.set(currentService, {
+          name: currentService,
+          ports: [],
+          volumes: [],
+          networks: [],
+          dependsOn: [],
+          environment: [],
+          hasHealthcheck: false,
+          hasResourceLimits: false,
+          hasReadonlyRootfs: false,
+          hasSecurityOpt: false,
+        });
+      }
+      continue;
+    }
+
+    const svc = serviceMap.get(currentService);
+
+    // Service properties (indent 4)
+    if (inServiceBlock && currentService && indent >= 4) {
+      if (indent === 4 && trimmed.includes(":")) {
+        const key = trimmed.split(":")[0].trim();
+        const value = trimmed.substring(trimmed.indexOf(":") + 1).trim();
+        currentServiceKey = key;
+
+        if (svc) {
+          if (key === "image") svc.image = value.replace(/['"]/g, "");
+          if (key === "build") svc.build = value || "(context)";
+          if (key === "restart") svc.restart = value.replace(/['"]/g, "");
+          if (key === "healthcheck") svc.hasHealthcheck = true;
+          if (key === "read_only" && value === "true") svc.hasReadonlyRootfs = true;
+          if (key === "security_opt") svc.hasSecurityOpt = true;
+          if (key === "deploy") svc.hasResourceLimits = true;
+
+          // Inline port or volume
+          if (key === "ports" && value && !value.startsWith("[")) {
+            // Not a list, skip
+          }
+          if (key === "environment" && value) {
+            // Inline map style
+          }
+        }
+        continue;
+      }
+
+      // List items (indent 6 with -)
+      if (trimmed.startsWith("-") && svc) {
+        const item = trimmed.substring(1).trim().replace(/['"]/g, "");
+        if (currentServiceKey === "ports") svc.ports.push(item);
+        if (currentServiceKey === "volumes") svc.volumes.push(item);
+        if (currentServiceKey === "networks") svc.networks.push(item);
+        if (currentServiceKey === "depends_on") svc.dependsOn.push(item);
+        if (currentServiceKey === "environment") svc.environment.push(item);
+      }
+    }
+
+    // Top-level networks/volumes
+    if (currentTopLevel === "networks" && indent === 2 && trimmed.endsWith(":")) {
+      analysis.topLevelNetworks.push(trimmed.replace(":", "").trim());
+    }
+    if (currentTopLevel === "volumes" && indent === 2 && trimmed.endsWith(":")) {
+      analysis.topLevelVolumes.push(trimmed.replace(":", "").trim());
+    }
+  }
+
+  analysis.services = Array.from(serviceMap.values());
+  return analysis;
+}
+
+function generateFindings(analysis: ComposeAnalysis): void {
+  const findings = analysis.findings;
+
+  if (analysis.version) {
+    findings.push({
+      severity: "info",
+      message: `Compose version: ${analysis.version}. Note: 'version' is obsolete in Compose V2.`,
+      suggestion: "The 'version' key can be removed when using Docker Compose V2.",
+    });
+  }
+
+  for (const svc of analysis.services) {
+    // Image tag
+    if (svc.image && (svc.image.endsWith(":latest") || (!svc.image.includes(":") && !svc.image.includes("@")))) {
+      findings.push({
+        severity: "warning",
+        message: `Service '${svc.name}': image '${svc.image}' uses :latest or no tag.`,
+        suggestion: "Pin to a specific version for reproducible deployments.",
+      });
+    }
+
+    // Restart policy
+    if (!svc.restart) {
+      findings.push({
+        severity: "warning",
+        message: `Service '${svc.name}': no restart policy defined.`,
+        suggestion: "Add 'restart: unless-stopped' or 'restart: on-failure' for production.",
+      });
+    }
+
+    // Health check
+    if (!svc.hasHealthcheck) {
+      findings.push({
+        severity: "info",
+        message: `Service '${svc.name}': no healthcheck defined.`,
+        suggestion: "Add a healthcheck for better orchestration and monitoring.",
+      });
+    }
+
+    // Resource limits
+    if (!svc.hasResourceLimits) {
+      findings.push({
+        severity: "info",
+        message: `Service '${svc.name}': no resource limits (deploy.resources) configured.`,
+        suggestion: "Set memory and CPU limits to prevent a single container from consuming all host resources.",
+      });
+    }
+
+    // Privileged ports
+    for (const port of svc.ports) {
+      const hostPort = port.split(":")[0];
+      const portNum = parseInt(hostPort, 10);
+      if (portNum > 0 && portNum < 1024) {
+        findings.push({
+          severity: "info",
+          message: `Service '${svc.name}': uses privileged port ${portNum}.`,
+          suggestion: "Privileged ports (<1024) may require elevated permissions.",
+        });
+      }
+      if (port.startsWith("0.0.0.0:") || (!port.includes("127.0.0.1") && port.includes(":"))) {
+        // Bound to all interfaces by default
+      }
+    }
+
+    // Host volumes
+    for (const vol of svc.volumes) {
+      if (vol.includes("/var/run/docker.sock")) {
+        findings.push({
+          severity: "warning",
+          message: `Service '${svc.name}': mounts Docker socket.`,
+          suggestion: "Mounting the Docker socket gives full control over the Docker daemon. Use with extreme caution.",
+        });
+      }
+    }
+
+    // Environment secrets
+    for (const env of svc.environment) {
+      const lower = env.toLowerCase();
+      if (lower.includes("password") || lower.includes("secret") || lower.includes("api_key") || lower.includes("token")) {
+        findings.push({
+          severity: "warning",
+          message: `Service '${svc.name}': environment variable '${env.split("=")[0]}' may contain a secret.`,
+          suggestion: "Use Docker secrets or an .env file (not committed to VCS) instead of inline values.",
+        });
+      }
+    }
+  }
+
+  // Dependencies without healthcheck
+  for (const svc of analysis.services) {
+    for (const dep of svc.dependsOn) {
+      const depSvc = analysis.services.find((s) => s.name === dep);
+      if (depSvc && !depSvc.hasHealthcheck) {
+        findings.push({
+          severity: "info",
+          message: `Service '${svc.name}' depends on '${dep}', but '${dep}' has no healthcheck.`,
+          suggestion: "Add a healthcheck to the dependency and use 'condition: service_healthy' for reliable startup order.",
+        });
+      }
+    }
+  }
+}
+
+export async function handleComposeAnalyzer(args: Record<string, unknown>): Promise<string> {
+  const content = args.content as string;
+
+  if (!content || !content.trim()) {
+    return "Error: docker-compose.yml content is empty. Please provide the file content to analyze.";
+  }
+
+  const analysis = parseSimpleYaml(content);
+  generateFindings(analysis);
+
+  const sections: string[] = [];
+
+  sections.push("# Docker Compose Analysis Report\n");
+
+  // Services overview
+  sections.push(`## Services (${analysis.services.length})\n`);
+  for (const svc of analysis.services) {
+    sections.push(`### ${svc.name}`);
+    if (svc.image) sections.push(`  Image: ${svc.image}`);
+    if (svc.build) sections.push(`  Build: ${svc.build}`);
+    if (svc.ports.length > 0) sections.push(`  Ports: ${svc.ports.join(", ")}`);
+    if (svc.volumes.length > 0) sections.push(`  Volumes: ${svc.volumes.join(", ")}`);
+    if (svc.networks.length > 0) sections.push(`  Networks: ${svc.networks.join(", ")}`);
+    if (svc.dependsOn.length > 0) sections.push(`  Depends on: ${svc.dependsOn.join(", ")}`);
+    if (svc.environment.length > 0) sections.push(`  Environment: ${svc.environment.length} variable(s)`);
+    sections.push(`  Restart: ${svc.restart || "not set"}`);
+    sections.push(`  Healthcheck: ${svc.hasHealthcheck ? "Yes" : "No"}`);
+    sections.push("");
+  }
+
+  // Networks & Volumes
+  if (analysis.topLevelNetworks.length > 0) {
+    sections.push(`## Networks: ${analysis.topLevelNetworks.join(", ")}\n`);
+  }
+  if (analysis.topLevelVolumes.length > 0) {
+    sections.push(`## Volumes: ${analysis.topLevelVolumes.join(", ")}\n`);
+  }
+
+  // Findings
+  const warnings = analysis.findings.filter((f) => f.severity === "warning");
+  const infos = analysis.findings.filter((f) => f.severity === "info");
+
+  sections.push(`## Findings (${warnings.length} warnings, ${infos.length} info)\n`);
+  for (const f of warnings) {
+    sections.push(`[WARN] ${f.message}`);
+    if (f.suggestion) sections.push(`  -> ${f.suggestion}`);
+  }
+  for (const f of infos) {
+    sections.push(`[INFO] ${f.message}`);
+    if (f.suggestion) sections.push(`  -> ${f.suggestion}`);
+  }
+
+  return sections.join("\n");
+}

package/src/tools/container-list.ts

@@ -0,0 +1,158 @@
+import { execSync } from "node:child_process";
+
+export const containerListTool = {
+  name: "docker_container_list",
+  description:
+    "List Docker containers with status, ports, image, created time, and resource usage. " +
+    "Can show only running containers or all containers including stopped ones.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      all: {
+        type: "boolean",
+        description:
+          "If true, show all containers including stopped ones. Defaults to false (running only).",
+        default: false,
+      },
+      format: {
+        type: "string",
+        enum: ["table", "json"],
+        description: "Output format: 'table' for readable text, 'json' for structured data. Defaults to 'json'.",
+        default: "json",
+      },
+    },
+    required: [],
+  },
+};
+
+interface ContainerInfo {
+  id: string;
+  name: string;
+  image: string;
+  status: string;
+  state: string;
+  ports: string;
+  created: string;
+  cpu: string;
+  memory: string;
+  memoryLimit: string;
+  memoryPercent: string;
+  networkIO: string;
+  blockIO: string;
+}
+
+function getContainerStats(containerIds: string[]): Map<string, { cpu: string; memory: string; memoryLimit: string; memoryPercent: string; networkIO: string; blockIO: string }> {
+  const statsMap = new Map<string, { cpu: string; memory: string; memoryLimit: string; memoryPercent: string; networkIO: string; blockIO: string }>();
+  if (containerIds.length === 0) return statsMap;
+
+  try {
+    const raw = execSync(
+      `docker stats --no-stream --format "{{.ID}}|||{{.CPUPerc}}|||{{.MemUsage}}|||{{.MemPerc}}|||{{.NetIO}}|||{{.BlockIO}}"`,
+      { encoding: "utf-8", timeout: 30000 }
+    ).trim();
+
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      const parts = line.split("|||");
+      if (parts.length >= 6) {
+        const memParts = parts[2].split(" / ");
+        statsMap.set(parts[0], {
+          cpu: parts[1],
+          memory: memParts[0]?.trim() ?? "N/A",
+          memoryLimit: memParts[1]?.trim() ?? "N/A",
+          memoryPercent: parts[3],
+          networkIO: parts[4],
+          blockIO: parts[5],
+        });
+      }
+    }
+  } catch {
+    // Stats unavailable for stopped containers — that's fine
+  }
+  return statsMap;
+}
+
+export async function handleContainerList(args: Record<string, unknown>): Promise<string> {
+  const showAll = args.all === true;
+  const format = (args.format as string) || "json";
+
+  try {
+    const allFlag = showAll ? " -a" : "";
+    const raw = execSync(
+      `docker ps${allFlag} --format "{{.ID}}|||{{.Names}}|||{{.Image}}|||{{.Status}}|||{{.State}}|||{{.Ports}}|||{{.CreatedAt}}" --no-trunc`,
+      { encoding: "utf-8", timeout: 15000 }
+    ).trim();
+
+    if (!raw) {
+      return showAll
+        ? "No containers found."
+        : "No running containers. Use { \"all\": true } to see stopped containers.";
+    }
+
+    const lines = raw.split("\n").filter((l) => l.trim());
+    const containerIds: string[] = [];
+    const containers: ContainerInfo[] = [];
+
+    for (const line of lines) {
+      const parts = line.split("|||");
+      if (parts.length < 7) continue;
+      const id = parts[0].substring(0, 12);
+      containerIds.push(id);
+      containers.push({
+        id,
+        name: parts[1],
+        image: parts[2],
+        status: parts[3],
+        state: parts[4],
+        ports: parts[5] || "none",
+        created: parts[6],
+        cpu: "N/A",
+        memory: "N/A",
+        memoryLimit: "N/A",
+        memoryPercent: "N/A",
+        networkIO: "N/A",
+        blockIO: "N/A",
+      });
+    }
+
+    const stats = getContainerStats(containerIds);
+    for (const c of containers) {
+      const s = stats.get(c.id);
+      if (s) {
+        c.cpu = s.cpu;
+        c.memory = s.memory;
+        c.memoryLimit = s.memoryLimit;
+        c.memoryPercent = s.memoryPercent;
+        c.networkIO = s.networkIO;
+        c.blockIO = s.blockIO;
+      }
+    }
+
+    if (format === "json") {
+      return JSON.stringify({ count: containers.length, containers }, null, 2);
+    }
+
+    let table = `Found ${containers.length} container(s):\n\n`;
+    for (const c of containers) {
+      table += `--- ${c.name} (${c.id}) ---\n`;
+      table += `  Image:    ${c.image}\n`;
+      table += `  State:    ${c.state} | ${c.status}\n`;
+      table += `  Ports:    ${c.ports}\n`;
+      table += `  Created:  ${c.created}\n`;
+      table += `  CPU:      ${c.cpu}\n`;
+      table += `  Memory:   ${c.memory} / ${c.memoryLimit} (${c.memoryPercent})\n`;
+      table += `  Net I/O:  ${c.networkIO}\n`;
+      table += `  Block IO: ${c.blockIO}\n\n`;
+    }
+    return table.trim();
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("not found") || message.includes("not recognized") || message.includes("ENOENT")) {
+      return "Error: Docker is not installed or not available in PATH. Please install Docker and ensure the 'docker' command is accessible.";
+    }
+    if (message.includes("Cannot connect") || message.includes("permission denied") || message.includes("Is the docker daemon running")) {
+      return "Error: Cannot connect to the Docker daemon. Is Docker running? You may also need appropriate permissions.";
+    }
+    return `Error listing containers: ${message}`;
+  }
+}