@rog0x/mcp-docker-tools 1.0.0

package/src/tools/container-logs.ts

@@ -0,0 +1,131 @@
+import { execSync } from "node:child_process";
+
+export const containerLogsTool = {
+  name: "docker_container_logs",
+  description:
+    "Get logs from a Docker container. Supports retrieving the last N lines, " +
+    "filtering by keyword, and including timestamps. Can target a container by name or ID.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      container: {
+        type: "string",
+        description: "Container name or ID to get logs from.",
+      },
+      tail: {
+        type: "number",
+        description: "Number of lines to retrieve from the end of logs. Defaults to 100.",
+        default: 100,
+      },
+      since: {
+        type: "string",
+        description: "Show logs since a timestamp (e.g., '2024-01-01T00:00:00') or relative duration (e.g., '1h', '30m').",
+      },
+      until: {
+        type: "string",
+        description: "Show logs until a timestamp or relative duration.",
+      },
+      filter: {
+        type: "string",
+        description: "Filter log lines to only include those containing this keyword (case-insensitive).",
+      },
+      timestamps: {
+        type: "boolean",
+        description: "Include timestamps in log output. Defaults to true.",
+        default: true,
+      },
+    },
+    required: ["container"],
+  },
+};
+
+export async function handleContainerLogs(args: Record<string, unknown>): Promise<string> {
+  const container = args.container as string;
+  const tail = typeof args.tail === "number" ? args.tail : 100;
+  const since = args.since as string | undefined;
+  const until = args.until as string | undefined;
+  const filter = args.filter as string | undefined;
+  const timestamps = args.timestamps !== false;
+
+  if (!container || !container.trim()) {
+    return "Error: 'container' parameter is required. Provide a container name or ID.";
+  }
+
+  try {
+    // Verify container exists
+    try {
+      execSync(`docker inspect --type=container ${container}`, {
+        encoding: "utf-8",
+        timeout: 10000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch {
+      return `Error: Container '${container}' not found. Use docker_container_list to see available containers.`;
+    }
+
+    // Build the logs command
+    const parts = ["docker", "logs"];
+    if (timestamps) parts.push("--timestamps");
+    parts.push(`--tail=${tail}`);
+    if (since) parts.push(`--since=${since}`);
+    if (until) parts.push(`--until=${until}`);
+    parts.push(container);
+
+    // docker logs outputs to stderr for some containers, capture both
+    const raw = execSync(parts.join(" "), {
+      encoding: "utf-8",
+      timeout: 30000,
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    // Also capture stderr since docker logs sends some output there
+    let combined: string;
+    try {
+      combined = execSync(parts.join(" ") + " 2>&1", {
+        encoding: "utf-8",
+        timeout: 30000,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    } catch {
+      combined = raw;
+    }
+
+    if (!combined.trim()) {
+      return `No logs found for container '${container}' with the specified parameters.`;
+    }
+
+    let lines = combined.split("\n");
+
+    // Apply keyword filter
+    if (filter) {
+      const lowerFilter = filter.toLowerCase();
+      lines = lines.filter((line) => line.toLowerCase().includes(lowerFilter));
+
+      if (lines.length === 0) {
+        return `No log lines matching '${filter}' found in the last ${tail} lines of container '${container}'.`;
+      }
+    }
+
+    const header = `Logs for container '${container}' (${lines.length} lines)`;
+    const separator = "=".repeat(Math.min(header.length, 60));
+
+    const result = [header, separator, ...lines].join("\n");
+
+    // Truncate if extremely long
+    if (result.length > 50000) {
+      return result.substring(0, 50000) + "\n\n... [output truncated at 50KB]";
+    }
+
+    return result;
+  } 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("Is the docker daemon running")) {
+      return "Error: Cannot connect to the Docker daemon. Is Docker running?";
+    }
+    return `Error fetching logs for '${container}': ${message}`;
+  }
+}

package/src/tools/dockerfile-analyzer.ts

@@ -0,0 +1,314 @@
+export const dockerfileAnalyzerTool = {
+  name: "docker_dockerfile_analyze",
+  description:
+    "Analyze a Dockerfile for best practices including multi-stage builds, non-root user, " +
+    ".dockerignore usage, layer caching order, image size optimization, and security. " +
+    "Provide the Dockerfile content as input and receive a detailed report with suggestions.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      content: {
+        type: "string",
+        description: "The full content of the Dockerfile to analyze.",
+      },
+      checkDockerignore: {
+        type: "boolean",
+        description: "If true, also checks for common .dockerignore recommendations. Defaults to true.",
+        default: true,
+      },
+    },
+    required: ["content"],
+  },
+};
+
+interface Finding {
+  category: string;
+  severity: "info" | "warning" | "error";
+  message: string;
+  suggestion?: string;
+  line?: number;
+}
+
+function analyzeDockerfile(content: string, checkDockerignore: boolean): { findings: Finding[]; summary: Record<string, unknown> } {
+  const lines = content.split("\n");
+  const findings: Finding[] = [];
+
+  const fromStatements: { line: number; image: string; alias?: string }[] = [];
+  let hasUser = false;
+  let hasCopy = false;
+  let hasAdd = false;
+  let hasHealthcheck = false;
+  let hasExpose = false;
+  let hasWorkdir = false;
+  let runCount = 0;
+  let hasAptGetCleanup = false;
+  let usesLatestTag = false;
+  let hasEnvForVersions = false;
+  let copiesBeforeRun = false;
+  let lastCopyLine = -1;
+  let lastRunLine = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    const lineNum = i + 1;
+
+    // Skip comments and empty
+    if (trimmed.startsWith("#") || !trimmed) continue;
+
+    const instruction = trimmed.split(/\s+/)[0].toUpperCase();
+
+    if (instruction === "FROM") {
+      const rest = trimmed.substring(4).trim();
+      const parts = rest.split(/\s+/);
+      const image = parts[0];
+      const alias = parts.find((_, idx) => idx > 0 && parts[idx - 1]?.toUpperCase() === "AS");
+      fromStatements.push({ line: lineNum, image, alias });
+
+      if (image.endsWith(":latest") || (!image.includes(":") && !image.includes("@"))) {
+        usesLatestTag = true;
+        findings.push({
+          category: "Versioning",
+          severity: "warning",
+          message: `Line ${lineNum}: Base image '${image}' uses implicit or explicit :latest tag.`,
+          suggestion: "Pin to a specific version tag (e.g., node:20-alpine) for reproducible builds.",
+          line: lineNum,
+        });
+      }
+
+      if (!image.includes("alpine") && !image.includes("slim") && !image.includes("distroless") && !image.includes("scratch")) {
+        findings.push({
+          category: "Image Size",
+          severity: "info",
+          message: `Line ${lineNum}: Base image '${image}' is not a minimal variant.`,
+          suggestion: "Consider using an alpine, slim, or distroless variant to reduce image size.",
+          line: lineNum,
+        });
+      }
+    }
+
+    if (instruction === "RUN") {
+      runCount++;
+      lastRunLine = lineNum;
+
+      if (trimmed.includes("apt-get") || trimmed.includes("apk add")) {
+        if (trimmed.includes("rm -rf /var/lib/apt/lists") || trimmed.includes("--no-cache")) {
+          hasAptGetCleanup = true;
+        } else {
+          findings.push({
+            category: "Layer Caching",
+            severity: "warning",
+            message: `Line ${lineNum}: Package install without cache cleanup.`,
+            suggestion: "Add 'rm -rf /var/lib/apt/lists/*' in the same RUN layer, or use 'apk add --no-cache'.",
+            line: lineNum,
+          });
+        }
+      }
+
+      if (trimmed.includes("curl") && !trimmed.includes("--fail")) {
+        findings.push({
+          category: "Reliability",
+          severity: "info",
+          message: `Line ${lineNum}: curl used without --fail flag.`,
+          suggestion: "Use 'curl --fail' so the build fails on HTTP errors.",
+          line: lineNum,
+        });
+      }
+    }
+
+    if (instruction === "COPY") {
+      hasCopy = true;
+      lastCopyLine = lineNum;
+      if (lastRunLine > 0 && lastCopyLine > lastRunLine) {
+        // This is normal — but copying app code before dependency install is not
+      }
+    }
+
+    if (instruction === "ADD") {
+      hasAdd = true;
+      if (!trimmed.includes(".tar") && !trimmed.includes("http")) {
+        findings.push({
+          category: "Best Practice",
+          severity: "warning",
+          message: `Line ${lineNum}: ADD instruction used instead of COPY.`,
+          suggestion: "Use COPY unless you specifically need ADD's tar extraction or URL features.",
+          line: lineNum,
+        });
+      }
+    }
+
+    if (instruction === "USER") {
+      hasUser = true;
+    }
+
+    if (instruction === "HEALTHCHECK") {
+      hasHealthcheck = true;
+    }
+
+    if (instruction === "EXPOSE") {
+      hasExpose = true;
+    }
+
+    if (instruction === "WORKDIR") {
+      hasWorkdir = true;
+    }
+
+    if (instruction === "ENV") {
+      hasEnvForVersions = true;
+    }
+  }
+
+  // Multi-stage build check
+  const isMultiStage = fromStatements.length > 1;
+  if (!isMultiStage) {
+    findings.push({
+      category: "Multi-stage Build",
+      severity: "info",
+      message: "Dockerfile does not use multi-stage builds.",
+      suggestion:
+        "Multi-stage builds reduce final image size by separating build dependencies from runtime. " +
+        "Consider adding a build stage and copying only needed artifacts to the final stage.",
+    });
+  } else {
+    findings.push({
+      category: "Multi-stage Build",
+      severity: "info",
+      message: `Good: Uses multi-stage build with ${fromStatements.length} stages.`,
+    });
+  }
+
+  // Non-root user
+  if (!hasUser) {
+    findings.push({
+      category: "Security",
+      severity: "warning",
+      message: "No USER instruction found. Container will run as root by default.",
+      suggestion: "Add a USER instruction to run as a non-root user (e.g., USER 1001 or USER appuser).",
+    });
+  }
+
+  // HEALTHCHECK
+  if (!hasHealthcheck) {
+    findings.push({
+      category: "Reliability",
+      severity: "info",
+      message: "No HEALTHCHECK instruction found.",
+      suggestion: "Add a HEALTHCHECK to enable Docker to monitor container health.",
+    });
+  }
+
+  // RUN consolidation
+  if (runCount > 5) {
+    findings.push({
+      category: "Layer Caching",
+      severity: "warning",
+      message: `Found ${runCount} separate RUN instructions.`,
+      suggestion:
+        "Consolidate related RUN commands using && to reduce the number of image layers.",
+    });
+  }
+
+  // WORKDIR
+  if (!hasWorkdir && hasCopy) {
+    findings.push({
+      category: "Best Practice",
+      severity: "info",
+      message: "No WORKDIR instruction found.",
+      suggestion: "Use WORKDIR to set a working directory instead of relying on the default or using 'cd' in RUN.",
+    });
+  }
+
+  // Layer caching order hint
+  if (hasCopy && runCount > 0) {
+    findings.push({
+      category: "Layer Caching",
+      severity: "info",
+      message: "Tip: Copy dependency manifests (package.json, requirements.txt) before source code.",
+      suggestion:
+        "COPY package*.json ./ then RUN npm install, then COPY the rest. " +
+        "This leverages Docker layer caching so dependencies are only reinstalled when manifests change.",
+    });
+  }
+
+  // .dockerignore
+  if (checkDockerignore) {
+    findings.push({
+      category: ".dockerignore",
+      severity: "info",
+      message: "Ensure a .dockerignore file exists alongside the Dockerfile.",
+      suggestion:
+        "Common entries: node_modules, .git, .env, dist, *.log, .DS_Store, __pycache__, .venv",
+    });
+  }
+
+  const score = calculateScore(findings);
+
+  return {
+    findings,
+    summary: {
+      totalFindings: findings.length,
+      errors: findings.filter((f) => f.severity === "error").length,
+      warnings: findings.filter((f) => f.severity === "warning").length,
+      info: findings.filter((f) => f.severity === "info").length,
+      stages: fromStatements.length,
+      isMultiStage,
+      hasNonRootUser: hasUser,
+      hasHealthcheck,
+      runInstructions: runCount,
+      usesLatestTag,
+      score,
+    },
+  };
+}
+
+function calculateScore(findings: Finding[]): string {
+  let score = 100;
+  for (const f of findings) {
+    if (f.severity === "error") score -= 15;
+    if (f.severity === "warning") score -= 7;
+  }
+  score = Math.max(0, score);
+  if (score >= 80) return `${score}/100 (Good)`;
+  if (score >= 50) return `${score}/100 (Needs improvement)`;
+  return `${score}/100 (Poor)`;
+}
+
+export async function handleDockerfileAnalyzer(args: Record<string, unknown>): Promise<string> {
+  const content = args.content as string;
+  const checkDockerignore = args.checkDockerignore !== false;
+
+  if (!content || !content.trim()) {
+    return "Error: Dockerfile content is empty. Please provide the Dockerfile content to analyze.";
+  }
+
+  const { findings, summary } = analyzeDockerfile(content, checkDockerignore);
+
+  const sections: string[] = [];
+
+  sections.push("# Dockerfile Analysis Report\n");
+  sections.push(`Score: ${summary.score}`);
+  sections.push(`Stages: ${summary.stages} | Multi-stage: ${summary.isMultiStage ? "Yes" : "No"}`);
+  sections.push(`Non-root user: ${summary.hasNonRootUser ? "Yes" : "No"} | Healthcheck: ${summary.hasHealthcheck ? "Yes" : "No"}`);
+  sections.push(`Findings: ${summary.errors} errors, ${summary.warnings} warnings, ${summary.info} info\n`);
+
+  const grouped: Record<string, Finding[]> = {};
+  for (const f of findings) {
+    if (!grouped[f.category]) grouped[f.category] = [];
+    grouped[f.category].push(f);
+  }
+
+  for (const [category, items] of Object.entries(grouped)) {
+    sections.push(`## ${category}`);
+    for (const item of items) {
+      const icon = item.severity === "error" ? "[ERROR]" : item.severity === "warning" ? "[WARN]" : "[INFO]";
+      const lineRef = item.line ? ` (line ${item.line})` : "";
+      sections.push(`${icon}${lineRef} ${item.message}`);
+      if (item.suggestion) {
+        sections.push(`  -> ${item.suggestion}`);
+      }
+    }
+    sections.push("");
+  }
+
+  return sections.join("\n");
+}

package/src/tools/image-list.ts

@@ -0,0 +1,134 @@
+import { execSync } from "node:child_process";
+
+export const imageListTool = {
+  name: "docker_image_list",
+  description:
+    "List Docker images with size, tags, created date, and layer count. " +
+    "Optionally filter by repository name.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      filter: {
+        type: "string",
+        description: "Filter images by repository name (partial match). Leave empty to list all.",
+      },
+      showDangling: {
+        type: "boolean",
+        description: "Include dangling (untagged) images. Defaults to false.",
+        default: false,
+      },
+      format: {
+        type: "string",
+        enum: ["table", "json"],
+        description: "Output format: 'table' or 'json'. Defaults to 'json'.",
+        default: "json",
+      },
+    },
+    required: [],
+  },
+};
+
+interface ImageInfo {
+  id: string;
+  repository: string;
+  tag: string;
+  size: string;
+  created: string;
+  layers: number;
+}
+
+function getLayerCount(imageId: string): number {
+  try {
+    const raw = execSync(`docker inspect --format="{{len .RootFS.Layers}}" ${imageId}`, {
+      encoding: "utf-8",
+      timeout: 10000,
+    }).trim();
+    return parseInt(raw, 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export async function handleImageList(args: Record<string, unknown>): Promise<string> {
+  const filter = (args.filter as string) || "";
+  const showDangling = args.showDangling === true;
+  const format = (args.format as string) || "json";
+
+  try {
+    let cmd = `docker images --format "{{.ID}}|||{{.Repository}}|||{{.Tag}}|||{{.Size}}|||{{.CreatedAt}}"`;
+    if (!showDangling) {
+      cmd += ` --filter "dangling=false"`;
+    }
+    if (filter) {
+      cmd += ` ${filter}`;
+    }
+
+    const raw = execSync(cmd, { encoding: "utf-8", timeout: 15000 }).trim();
+
+    if (!raw) {
+      return filter
+        ? `No images found matching '${filter}'.`
+        : "No Docker images found on this system.";
+    }
+
+    const lines = raw.split("\n").filter((l) => l.trim());
+    const images: ImageInfo[] = [];
+
+    for (const line of lines) {
+      const parts = line.split("|||");
+      if (parts.length < 5) continue;
+
+      const id = parts[0];
+      images.push({
+        id,
+        repository: parts[1],
+        tag: parts[2],
+        size: parts[3],
+        created: parts[4],
+        layers: getLayerCount(id),
+      });
+    }
+
+    const totalSize = images
+      .map((img) => {
+        const s = img.size.toUpperCase();
+        if (s.includes("GB")) return parseFloat(s) * 1024;
+        if (s.includes("MB")) return parseFloat(s);
+        if (s.includes("KB")) return parseFloat(s) / 1024;
+        return 0;
+      })
+      .reduce((a, b) => a + b, 0);
+
+    const totalSizeStr =
+      totalSize >= 1024
+        ? `${(totalSize / 1024).toFixed(2)} GB`
+        : `${totalSize.toFixed(1)} MB`;
+
+    if (format === "json") {
+      return JSON.stringify(
+        { count: images.length, totalSize: totalSizeStr, images },
+        null,
+        2
+      );
+    }
+
+    let table = `Found ${images.length} image(s) | Total size: ${totalSizeStr}\n\n`;
+    for (const img of images) {
+      table += `${img.repository}:${img.tag}\n`;
+      table += `  ID:      ${img.id}\n`;
+      table += `  Size:    ${img.size}\n`;
+      table += `  Layers:  ${img.layers}\n`;
+      table += `  Created: ${img.created}\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("Is the docker daemon running")) {
+      return "Error: Cannot connect to the Docker daemon. Is Docker running?";
+    }
+    return `Error listing images: ${message}`;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}