@rog0x/mcp-docker-tools 1.0.0

package/dist/tools/container-logs.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containerLogsTool = void 0;
+exports.handleContainerLogs = handleContainerLogs;
+const node_child_process_1 = require("node:child_process");
+exports.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",
+        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"],
+    },
+};
+async function handleContainerLogs(args) {
+    const container = args.container;
+    const tail = typeof args.tail === "number" ? args.tail : 100;
+    const since = args.since;
+    const until = args.until;
+    const filter = args.filter;
+    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 {
+            (0, node_child_process_1.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 = (0, node_child_process_1.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;
+        try {
+            combined = (0, node_child_process_1.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) {
+        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}`;
+    }
+}
+//# sourceMappingURL=container-logs.js.map

package/dist/tools/dockerfile-analyzer.d.ts

@@ -0,0 +1,21 @@
+export declare const dockerfileAnalyzerTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            content: {
+                type: string;
+                description: string;
+            };
+            checkDockerignore: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleDockerfileAnalyzer(args: Record<string, unknown>): Promise<string>;
+//# sourceMappingURL=dockerfile-analyzer.d.ts.map

package/dist/tools/dockerfile-analyzer.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dockerfileAnalyzerTool = void 0;
+exports.handleDockerfileAnalyzer = handleDockerfileAnalyzer;
+exports.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",
+        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"],
+    },
+};
+function analyzeDockerfile(content, checkDockerignore) {
+    const lines = content.split("\n");
+    const findings = [];
+    const fromStatements = [];
+    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) {
+    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)`;
+}
+async function handleDockerfileAnalyzer(args) {
+    const content = args.content;
+    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 = [];
+    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 = {};
+    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");
+}
+//# sourceMappingURL=dockerfile-analyzer.js.map

package/dist/tools/image-list.d.ts

@@ -0,0 +1,27 @@
+export declare const imageListTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            filter: {
+                type: string;
+                description: string;
+            };
+            showDangling: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+                default: string;
+            };
+        };
+        required: never[];
+    };
+};
+export declare function handleImageList(args: Record<string, unknown>): Promise<string>;
+//# sourceMappingURL=image-list.d.ts.map

package/dist/tools/image-list.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.imageListTool = void 0;
+exports.handleImageList = handleImageList;
+const node_child_process_1 = require("node:child_process");
+exports.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",
+        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: [],
+    },
+};
+function getLayerCount(imageId) {
+    try {
+        const raw = (0, node_child_process_1.execSync)(`docker inspect --format="{{len .RootFS.Layers}}" ${imageId}`, {
+            encoding: "utf-8",
+            timeout: 10000,
+        }).trim();
+        return parseInt(raw, 10) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function handleImageList(args) {
+    const filter = args.filter || "";
+    const showDangling = args.showDangling === true;
+    const format = args.format || "json";
+    try {
+        let cmd = `docker images --format "{{.ID}}|||{{.Repository}}|||{{.Tag}}|||{{.Size}}|||{{.CreatedAt}}"`;
+        if (!showDangling) {
+            cmd += ` --filter "dangling=false"`;
+        }
+        if (filter) {
+            cmd += ` ${filter}`;
+        }
+        const raw = (0, node_child_process_1.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 = [];
+        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) {
+        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}`;
+    }
+}
+//# sourceMappingURL=image-list.js.map

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@rog0x/mcp-docker-tools",
+  "version": "1.0.0",
+  "description": "Docker management tools for AI agents via MCP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-docker-tools": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "docker",
+    "containers",
+    "ai-tools",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}