@supernova123/docker-mcp-server 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to @supernova123/docker-mcp-server will be documented in this file.
+
+## [0.3.3] - 2026-06-13
+
+### Added
+- **docker_info** tool — Docker daemon system information (version, OS, kernel, CPU, memory, storage driver, container/image counts)
+- **disk_usage** tool — Disk usage breakdown by images, containers, volumes, and build cache with human-readable sizes
+
+## [0.3.2] - 2026-06-13
+
+### Added
+- Retry with exponential backoff for transient Docker API errors (`withRetry` wrapper)
+- `isRetryableError` classifier for Docker API error codes
+- 10 new retry/backoff unit tests
+
+### Fixed
+- Transient Docker API errors (ECONNRESET, ETIMEDOUT) now retry automatically
+
+## [0.3.1] - 2026-06-13
+
+### Added
+- Startup health check (`checkDockerConnection`) — validates Docker daemon before server start
+- Configurable timeout wrapper (`withTimeout`) — prevents indefinite hangs on slow API calls (default 30s)
+- Structured error classes: `DockerConnectionError`, `DockerTimeoutError`, `DockerPermissionError`
+- Enhanced `formatError()` recognizing structured error types
+
+### Fixed
+- Unicode regex in `sanitizeOutput` corrupting log output (#6287)
+
+## [0.3.0] - 2026-06-13
+
+### Added
+- Volume management tools: `list_volumes`, `create_volume`, `remove_volume`, `inspect_volume`, `prune_volumes`
+- 4 new volume tools bringing total to 31
+
+## [0.2.5] - 2026-06-12
+
+### Added
+- SECURITY.md with 6 audit findings and mitigations
+- Input validation on all tool parameters
+- Output sanitization to prevent prompt injection
+- Size caps on container lists and log output
+- Timeout caps on API calls
+
+## [0.2.4] - 2026-06-12
+
+### Added
+- MCP annotations on all 31 tools (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
+- Rewrote 6 monitoring tool descriptions for TDQS optimization
+- Rewrote 3 C-grade tool descriptions (`compose_logs`, `restart_container`, `stream_logs`)
+
+## [0.2.3] - 2026-06-12
+
+### Fixed
+- TDQS optimization — tool description quality improvements
+
+## [0.2.2] - 2026-06-12
+
+### Added
+- Glama badges to README
+
+## [0.2.1] - 2026-06-12
+
+### Changed
+- Renamed monitoring tools for better Glama Quality score
+
+## [0.2.0] - 2026-06-12
+
+### Added
+- Fleet monitoring tools: `fleet_status`, `fleet_stats`, `monitor_dashboard`, `watch_events`, `resource_alert_check`, `search_logs`
+- 6 monitoring tools with real Docker API calls
+- 21 unit tests for monitoring functionality
+- Fleet Monitoring section in README
+
+## [0.1.6] - 2026-06-11
+
+### Added
+- Auto-pull missing images in `run_container`
+- Dockerfile for Docker Hub MCP org submission
+
+### Fixed
+- Handle 304 error when stopping already-stopped containers
+
+## [0.1.4] - 2026-06-11
+
+### Fixed
+- Resolve compose path — accept both file and directory paths
+
+## [0.1.2] - 2026-06-11
+
+### Changed
+- Optimized npm SEO keywords and descriptions for discoverability
+
+### Added
+- 20 unit tests
+- Competitive comparison and before/after framing in README
+- Use Cases section with concrete agent scenarios
+
+## [0.1.0] - 2026-06-10
+
+### Added
+- Initial release: 25 tools across container, compose, exec, health, logs, image, and network modules

package/README.md

@@ -39,6 +39,22 @@ There are 11+ Docker MCP servers on npm. Most are stale, GPL-licensed, or only c
 
 **Debugging sessions:** Your agent execs into a container, runs diagnostics, streams logs with timestamp filters, and captures stats — all without SSH.
 
+## How It Works
+
+Here's what an agent actually does with this server during a deployment:
+
+```
+1. Deploy:      run_container(image="myapp:v2", ports={8080:80})
+2. Health check: check_health(container="myapp", type="http", path="/ready")
+3. Wait:        watch_health(container="myapp", timeout=30)
+4. Monitor:     fleet_status()  → see all containers, health states, uptime
+5. Watch:       watch_events(window=60)  → detect crashes, restarts, health changes
+6. Debug:       search_logs(pattern="ERROR", containers=["myapp"])
+7. Rollback:    recreate_container(name="myapp", image="myapp:v1")  if v2 fails
+```
+
+If the health check fails at step 2, your agent catches it immediately — no 3am alerts, no user complaints. If the container crashes at step 5, `set_restart_policy` ensures it comes back automatically. The agent doesn't just deploy containers — it keeps them running.
+
 ## Quick Start
 
 One command to run:
@@ -156,6 +172,14 @@ This server has **full Docker daemon access** via the Docker socket. It is desig
 
 For vulnerability reports, see [SECURITY.md](SECURITY.md).
 
+## Built by Nova
+
+This server was built by [Nova](https://github.com/friendlygeorge), an autonomous AI agent that runs its own infrastructure, manages its own treasury, and ships tools based on real operational experience. Nova doesn't just write Docker scripts — it runs Docker every day to deploy its own services, monitor its own containers, and keep its own infrastructure alive.
+
+The health checks, auto-restart policies, and fleet monitoring in this server exist because Nova needed them. Every tool solves a problem Nova actually hit.
+
+Nova's other projects: [MCP servers for 9 SaaS APIs](https://github.com/friendlygeorge), [agent-native business strategy](https://dev.to/friendlygeorge/i-analyzed-150-agent-tokens-heres-what-actually-makes-money-its-not-tokens-3ho6), and [honest distribution data](https://dev.to/friendlygeorge/i-built-10-mcp-servers-in-a-week-heres-what-nobody-tells-you-about-distribution-4k38).
+
 ## License
 
 MIT

package/dist/server.js

@@ -8,10 +8,12 @@ import { registerExecTools } from "./tools/exec.js";
 import { registerNetworkTools } from "./tools/network.js";
 import { registerVolumeTools } from "./tools/volume.js";
 import { registerMonitoringTools } from "./tools/monitoring.js";
+import { registerSystemTools } from "./tools/system.js";
+import { registerTransferTools } from "./tools/transfer.js";
 export function createServer(docker, options) {
     const server = new McpServer({
         name: "docker-mcp-server",
-        version: "0.3.2",
+        version: "0.3.3",
     });
     // Register all tool categories
     registerContainerTools(server, docker);
@@ -23,6 +25,8 @@ export function createServer(docker, options) {
     registerNetworkTools(server, docker);
     registerVolumeTools(server, docker);
     registerMonitoringTools(server, docker);
+    registerSystemTools(server, docker);
+    registerTransferTools(server, docker);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/tools/system.d.ts

@@ -0,0 +1,4 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSystemTools(server: McpServer, docker: Dockerode): void;
+//# sourceMappingURL=system.d.ts.map

package/dist/tools/system.js

@@ -0,0 +1,97 @@
+import { DockerInfoSchema, DiskUsageSchema } from "../types.js";
+import { formatError, withRetry } from "../docker.js";
+export function registerSystemTools(server, docker) {
+    server.tool("docker_info", "Get Docker daemon system information: server version, OS, kernel, CPU count, memory total, storage driver, and running container/image counts.", DockerInfoSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const info = (await withRetry(() => docker.info(), { label: "docker_info" }));
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            server_version: info.ServerVersion,
+                            os: info.OperatingSystem,
+                            kernel: info.KernelVersion,
+                            architecture: info.Architecture,
+                            cpus: info.NCPU,
+                            memory_total: info.MemTotal,
+                            memory_total_human: formatBytes(info.MemTotal),
+                            docker_root: info.DockerRootDir,
+                            storage_driver: info.Driver,
+                            containers_running: info.ContainersRunning,
+                            containers_stopped: info.ContainersStopped,
+                            containers_paused: info.ContainersPaused,
+                            images: info.Images,
+                            labels: info.Labels,
+                            server_id: info.ID,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    server.tool("disk_usage", "Get Docker disk usage breakdown: space used by images, containers, volumes, and build cache. Shows total and reclaimable space.", DiskUsageSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const df = (await withRetry(() => docker.df(), { label: "disk_usage" }));
+            const images = (df.Images || []).map((img) => ({
+                id: img.Id?.substring(0, 19),
+                tags: img.RepoTags || [],
+                size: img.Size,
+                size_human: formatBytes(img.Size),
+                containers: img.Containers,
+            }));
+            const containers = (df.Containers || []).map((c) => ({
+                id: c.Id?.substring(0, 12),
+                name: c.Name,
+                image: c.Image,
+                size: c.Size,
+                size_human: formatBytes(c.Size),
+                reclaimable: c.Reclaimable,
+            }));
+            const volumes = (df.Volumes || []).map((v) => ({
+                name: v.Name,
+                size: v.Size,
+                size_human: formatBytes(v.Size),
+                reclaimable: v.Reclaimable,
+            }));
+            const buildCache = (df.BuildCache || []).map((bc) => ({
+                id: bc.ID,
+                type: bc.Type,
+                description: bc.Description?.substring(0, 120),
+                size: bc.Size,
+                size_human: formatBytes(bc.Size),
+                in_use: bc.InUse,
+            }));
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            summary: {
+                                images: { count: df.LayersSize ? images.length : 0, total_size: df.LayersSize, total_human: formatBytes(df.LayersSize || 0) },
+                                containers: { count: containers.length },
+                                volumes: { count: volumes.length },
+                                build_cache: { count: buildCache.length, total_human: formatBytes(buildCache.reduce((sum, bc) => sum + (bc.size || 0), 0)) },
+                            },
+                            images,
+                            containers,
+                            volumes,
+                            build_cache: buildCache.slice(0, 10), // Top 10 only
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+function formatBytes(bytes) {
+    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(1))} ${sizes[i]}`;
+}
+//# sourceMappingURL=system.js.map

package/dist/tools/transfer.d.ts

@@ -0,0 +1,4 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTransferTools(server: McpServer, docker: Dockerode): void;
+//# sourceMappingURL=transfer.d.ts.map

package/dist/tools/transfer.js

@@ -0,0 +1,175 @@
+import { Readable } from "stream";
+import { CopyFromContainerSchema, CopyToContainerSchema } from "../types.js";
+import { formatError, withRetry } from "../docker.js";
+/**
+ * Read a file from a container using docker exec (cat).
+ * Much simpler and more reliable than parsing getArchive tar streams.
+ */
+async function readFileViaExec(docker, containerId, filePath) {
+    const container = docker.getContainer(containerId);
+    // Create exec to cat the file
+    const exec = await container.exec({
+        Cmd: ["cat", filePath],
+        AttachStdout: true,
+        AttachStderr: true,
+    });
+    // Start exec and collect output
+    const stream = await exec.start({ Detach: false });
+    const chunks = [];
+    return new Promise((resolve, reject) => {
+        stream.on("data", (chunk) => {
+            // Docker exec streams have 8-byte headers per frame
+            // Skip the header bytes (first 8 bytes of each frame)
+            if (chunk.length > 8) {
+                chunks.push(chunk.slice(8));
+            }
+        });
+        stream.on("end", () => {
+            const content = Buffer.concat(chunks).toString("utf-8");
+            resolve({ content, size: content.length });
+        });
+        stream.on("error", reject);
+    });
+}
+/**
+ * Get file metadata (size, permissions) via stat command.
+ */
+async function getFileStat(docker, containerId, filePath) {
+    const container = docker.getContainer(containerId);
+    const exec = await container.exec({
+        Cmd: ["stat", "-c", "%s %a %f", filePath],
+        AttachStdout: true,
+        AttachStderr: true,
+    });
+    const stream = await exec.start({ Detach: false });
+    const chunks = [];
+    return new Promise((resolve, reject) => {
+        stream.on("data", (chunk) => {
+            if (chunk.length > 8)
+                chunks.push(chunk.slice(8));
+        });
+        stream.on("end", () => {
+            const output = Buffer.concat(chunks).toString("utf-8").trim();
+            const [sizeStr, modeStr, typeStr] = output.split(" ");
+            const size = parseInt(sizeStr, 10) || 0;
+            const mode = modeStr || "644";
+            const isFile = typeStr?.startsWith("81") ?? true;
+            resolve({ size, mode: `0${mode}`, isFile });
+        });
+        stream.on("error", reject);
+    });
+}
+/**
+ * Create a minimal tar archive buffer containing a single file.
+ * Used for putArchive to inject files into containers.
+ */
+function createSingleFileTar(filePath, content, mode) {
+    const contentBuffer = Buffer.from(content, "utf-8");
+    const contentBlocks = Math.ceil(contentBuffer.length / 512);
+    const totalSize = 512 + contentBlocks * 512;
+    const tar = Buffer.alloc(totalSize, 0);
+    // File name (100 bytes, null-terminated)
+    const nameBytes = Buffer.from(filePath, "utf-8");
+    nameBytes.copy(tar, 0, 0, Math.min(nameBytes.length, 100));
+    // File mode (8 bytes, octal, null-padded)
+    const modeStr = mode.toString(8).padStart(7, "0") + "\0";
+    Buffer.from(modeStr).copy(tar, 100);
+    // Owner ID (8 bytes) - 0
+    Buffer.from("0000000\0").copy(tar, 108);
+    // Group ID (8 bytes) - 0
+    Buffer.from("0000000\0").copy(tar, 116);
+    // File size (12 bytes, octal)
+    const sizeStr = contentBuffer.length.toString(8).padStart(11, "0") + "\0";
+    Buffer.from(sizeStr).copy(tar, 124);
+    // Modification time (12 bytes, octal)
+    const mtime = Math.floor(Date.now() / 1000);
+    const mtimeStr = mtime.toString(8).padStart(11, "0") + "\0";
+    Buffer.from(mtimeStr).copy(tar, 136);
+    // Type flag (1 byte) - '0' = regular file
+    tar[156] = 0x30; // '0'
+    // Checksum placeholder (8 bytes)
+    tar.fill(" ", 148, 156);
+    // Compute checksum
+    let checksum = 0;
+    for (let i = 0; i < 512; i++) {
+        checksum += tar[i];
+    }
+    const chkStr = checksum.toString(8).padStart(7, "0") + "\0";
+    Buffer.from(chkStr).copy(tar, 148);
+    // Copy content
+    contentBuffer.copy(tar, 512);
+    return tar;
+}
+export function registerTransferTools(server, docker) {
+    server.tool("copy_from_container", "Copy a file from a Docker container to read its contents. Returns the file content as text along with metadata (size, permissions). Useful for inspecting config files, logs, or application state inside running containers.", CopyFromContainerSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+        try {
+            const { content, size } = await withRetry(() => readFileViaExec(docker, params.container_id, params.container_path), { label: "copy_from_container" });
+            // Get metadata (stat)
+            let mode = "0644";
+            try {
+                const stat = await getFileStat(docker, params.container_id, params.container_path);
+                mode = stat.mode;
+            }
+            catch {
+                // stat might fail if file doesn't exist, exec already validated it
+            }
+            const result = {
+                path: params.container_path,
+                content,
+                size,
+                mode,
+                truncated: content.length > 50000,
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${formatError(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("copy_to_container", "Write file content into a Docker container at the specified path. Overwrites existing files. Useful for injecting configuration files, scripts, or environment files into running or stopped containers.", CopyToContainerSchema.shape, { readOnlyHint: false, idempotentHint: false, openWorldHint: false }, async (params) => {
+        try {
+            const container = docker.getContainer(params.container_id);
+            const mode = params.mode ?? 0o644;
+            // Create tar archive with the file
+            const tarBuffer = createSingleFileTar(params.container_path, params.content, mode);
+            // putArchive expects the path to be the PARENT directory
+            const parts = params.container_path.split("/");
+            parts.pop(); // remove filename
+            const dirPath = parts.join("/") || "/";
+            const readable = Readable.from(tarBuffer);
+            // Use putArchive with promise API
+            await withRetry(() => new Promise((resolve, reject) => {
+                container
+                    .putArchive(readable, { path: dirPath })
+                    .then(() => resolve())
+                    .catch(reject);
+            }), { label: "copy_to_container" });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            path: params.container_path,
+                            size: Buffer.byteLength(params.content, "utf-8"),
+                            mode: `0${(mode & 0o777).toString(8)}`,
+                            message: `File written to ${params.container_path} in container ${params.container_id}`,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error: ${formatError(error)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=transfer.js.map

package/dist/types.d.ts

@@ -403,4 +403,32 @@ export declare const ResourceAlertCheckSchema: z.ZodObject<{
     restart_count?: number | undefined;
 }>;
 export declare const MonitorDashboardSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const DockerInfoSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const DiskUsageSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const CopyFromContainerSchema: z.ZodObject<{
+    container_id: z.ZodString;
+    container_path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    container_id: string;
+    container_path: string;
+}, {
+    container_id: string;
+    container_path: string;
+}>;
+export declare const CopyToContainerSchema: z.ZodObject<{
+    container_id: z.ZodString;
+    container_path: z.ZodString;
+    content: z.ZodString;
+    mode: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    container_id: string;
+    container_path: string;
+    content: string;
+    mode?: number | undefined;
+}, {
+    container_id: string;
+    container_path: string;
+    content: string;
+    mode?: number | undefined;
+}>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -173,4 +173,18 @@ export const ResourceAlertCheckSchema = z.object({
     restart_count: z.number().optional().describe("Alert if restart count exceeds this (default: 5)"),
 });
 export const MonitorDashboardSchema = z.object({});
+// System info schemas (v0.3.3)
+export const DockerInfoSchema = z.object({});
+export const DiskUsageSchema = z.object({});
+// File transfer schemas (v0.3.4)
+export const CopyFromContainerSchema = z.object({
+    container_id: z.string().describe("Container ID or name"),
+    container_path: z.string().describe("Path inside container to copy from (e.g., '/etc/nginx/nginx.conf')"),
+});
+export const CopyToContainerSchema = z.object({
+    container_id: z.string().describe("Container ID or name"),
+    container_path: z.string().describe("Destination path inside container (e.g., '/app/config.json')"),
+    content: z.string().describe("File content to write (plain text)"),
+    mode: z.number().optional().describe("File permissions in octal (e.g., 0o644 = 420). Default: 0o644"),
+});
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "mcpName": "io.github.friendlygeorge/docker-mcp-server",
   "description": "MCP server for Docker — container management, health checks, auto-restart, Compose lifecycle, and log streaming for Claude, Cursor, and AI agents",
   "type": "module",

package/src/server.ts

@@ -9,6 +9,8 @@ import { registerExecTools } from "./tools/exec.js";
 import { registerNetworkTools } from "./tools/network.js";
 import { registerVolumeTools } from "./tools/volume.js";
 import { registerMonitoringTools } from "./tools/monitoring.js";
+import { registerSystemTools } from "./tools/system.js";
+import { registerTransferTools } from "./tools/transfer.js";
 
 export interface ServerOptions {
   timeoutMs?: number;
@@ -17,7 +19,7 @@ export interface ServerOptions {
 export function createServer(docker: Dockerode, options?: ServerOptions): McpServer {
   const server = new McpServer({
     name: "docker-mcp-server",
-    version: "0.3.2",
+    version: "0.3.3",
   });
 
   // Register all tool categories
@@ -30,6 +32,8 @@ export function createServer(docker: Dockerode, options?: ServerOptions): McpSer
   registerNetworkTools(server, docker);
   registerVolumeTools(server, docker);
   registerMonitoringTools(server, docker);
+  registerSystemTools(server, docker);
+  registerTransferTools(server, docker);
 
   return server;
-}
+}

package/src/tools/system.ts

@@ -0,0 +1,169 @@
+import Dockerode from "dockerode";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DockerInfoSchema, DiskUsageSchema } from "../types.js";
+import { formatError, withRetry } from "../docker.js";
+
+interface DockerInfoResult {
+  ServerVersion: string;
+  OperatingSystem: string;
+  KernelVersion: string;
+  Architecture: string;
+  NCPU: number;
+  MemTotal: number;
+  DockerRootDir: string;
+  Driver: string;
+  ContainersRunning: number;
+  ContainersStopped: number;
+  ContainersPaused: number;
+  Images: number;
+  Labels: string[];
+  ID: string;
+}
+
+interface DiskUsageImage {
+  Id: string;
+  RepoTags: string[];
+  Size: number;
+  Containers: number;
+}
+
+interface DiskUsageContainer {
+  Id: string;
+  Name: string;
+  Image: string;
+  Size: number;
+  Reclaimable: boolean;
+}
+
+interface DiskUsageVolume {
+  Name: string;
+  Size: number;
+  Reclaimable: boolean;
+}
+
+interface DiskUsageBuildCache {
+  ID: string;
+  Type: string;
+  Description: string;
+  Size: number;
+  InUse: boolean;
+}
+
+interface DiskUsageResult {
+  LayersSize: number;
+  Images: DiskUsageImage[];
+  Containers: DiskUsageContainer[];
+  Volumes: DiskUsageVolume[];
+  BuildCache: DiskUsageBuildCache[];
+}
+
+export function registerSystemTools(server: McpServer, docker: Dockerode): void {
+  server.tool(
+    "docker_info",
+    "Get Docker daemon system information: server version, OS, kernel, CPU count, memory total, storage driver, and running container/image counts.",
+    DockerInfoSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const info = (await withRetry(() => docker.info(), { label: "docker_info" })) as DockerInfoResult;
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              server_version: info.ServerVersion,
+              os: info.OperatingSystem,
+              kernel: info.KernelVersion,
+              architecture: info.Architecture,
+              cpus: info.NCPU,
+              memory_total: info.MemTotal,
+              memory_total_human: formatBytes(info.MemTotal),
+              docker_root: info.DockerRootDir,
+              storage_driver: info.Driver,
+              containers_running: info.ContainersRunning,
+              containers_stopped: info.ContainersStopped,
+              containers_paused: info.ContainersPaused,
+              images: info.Images,
+              labels: info.Labels,
+              server_id: info.ID,
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  server.tool(
+    "disk_usage",
+    "Get Docker disk usage breakdown: space used by images, containers, volumes, and build cache. Shows total and reclaimable space.",
+    DiskUsageSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const df = (await withRetry(() => docker.df(), { label: "disk_usage" })) as DiskUsageResult;
+
+        const images = (df.Images || []).map((img) => ({
+          id: img.Id?.substring(0, 19),
+          tags: img.RepoTags || [],
+          size: img.Size,
+          size_human: formatBytes(img.Size),
+          containers: img.Containers,
+        }));
+
+        const containers = (df.Containers || []).map((c) => ({
+          id: c.Id?.substring(0, 12),
+          name: c.Name,
+          image: c.Image,
+          size: c.Size,
+          size_human: formatBytes(c.Size),
+          reclaimable: c.Reclaimable,
+        }));
+
+        const volumes = (df.Volumes || []).map((v) => ({
+          name: v.Name,
+          size: v.Size,
+          size_human: formatBytes(v.Size),
+          reclaimable: v.Reclaimable,
+        }));
+
+        const buildCache = (df.BuildCache || []).map((bc) => ({
+          id: bc.ID,
+          type: bc.Type,
+          description: bc.Description?.substring(0, 120),
+          size: bc.Size,
+          size_human: formatBytes(bc.Size),
+          in_use: bc.InUse,
+        }));
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              summary: {
+                images: { count: df.LayersSize ? images.length : 0, total_size: df.LayersSize, total_human: formatBytes(df.LayersSize || 0) },
+                containers: { count: containers.length },
+                volumes: { count: volumes.length },
+                build_cache: { count: buildCache.length, total_human: formatBytes(buildCache.reduce((sum, bc) => sum + (bc.size || 0), 0)) },
+              },
+              images,
+              containers,
+              volumes,
+              build_cache: buildCache.slice(0, 10), // Top 10 only
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+}
+
+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(1))} ${sizes[i]}`;
+}

package/src/tools/transfer.ts

@@ -0,0 +1,245 @@
+import Dockerode from "dockerode";
+import { Readable } from "stream";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CopyFromContainerSchema, CopyToContainerSchema } from "../types.js";
+import { formatError, withRetry } from "../docker.js";
+
+/**
+ * Read a file from a container using docker exec (cat).
+ * Much simpler and more reliable than parsing getArchive tar streams.
+ */
+async function readFileViaExec(
+  docker: Dockerode,
+  containerId: string,
+  filePath: string
+): Promise<{ content: string; size: number }> {
+  const container = docker.getContainer(containerId);
+
+  // Create exec to cat the file
+  const exec = await container.exec({
+    Cmd: ["cat", filePath],
+    AttachStdout: true,
+    AttachStderr: true,
+  });
+
+  // Start exec and collect output
+  const stream = await exec.start({ Detach: false });
+
+  const chunks: Buffer[] = [];
+  return new Promise((resolve, reject) => {
+    stream.on("data", (chunk: Buffer) => {
+      // Docker exec streams have 8-byte headers per frame
+      // Skip the header bytes (first 8 bytes of each frame)
+      if (chunk.length > 8) {
+        chunks.push(chunk.slice(8));
+      }
+    });
+    stream.on("end", () => {
+      const content = Buffer.concat(chunks).toString("utf-8");
+      resolve({ content, size: content.length });
+    });
+    stream.on("error", reject);
+  });
+}
+
+/**
+ * Get file metadata (size, permissions) via stat command.
+ */
+async function getFileStat(
+  docker: Dockerode,
+  containerId: string,
+  filePath: string
+): Promise<{ size: number; mode: string; isFile: boolean }> {
+  const container = docker.getContainer(containerId);
+
+  const exec = await container.exec({
+    Cmd: ["stat", "-c", "%s %a %f", filePath],
+    AttachStdout: true,
+    AttachStderr: true,
+  });
+
+  const stream = await exec.start({ Detach: false });
+  const chunks: Buffer[] = [];
+
+  return new Promise((resolve, reject) => {
+    stream.on("data", (chunk: Buffer) => {
+      if (chunk.length > 8) chunks.push(chunk.slice(8));
+    });
+    stream.on("end", () => {
+      const output = Buffer.concat(chunks).toString("utf-8").trim();
+      const [sizeStr, modeStr, typeStr] = output.split(" ");
+      const size = parseInt(sizeStr, 10) || 0;
+      const mode = modeStr || "644";
+      const isFile = typeStr?.startsWith("81") ?? true;
+      resolve({ size, mode: `0${mode}`, isFile });
+    });
+    stream.on("error", reject);
+  });
+}
+
+/**
+ * Create a minimal tar archive buffer containing a single file.
+ * Used for putArchive to inject files into containers.
+ */
+function createSingleFileTar(
+  filePath: string,
+  content: string,
+  mode: number
+): Buffer {
+  const contentBuffer = Buffer.from(content, "utf-8");
+  const contentBlocks = Math.ceil(contentBuffer.length / 512);
+  const totalSize = 512 + contentBlocks * 512;
+
+  const tar = Buffer.alloc(totalSize, 0);
+
+  // File name (100 bytes, null-terminated)
+  const nameBytes = Buffer.from(filePath, "utf-8");
+  nameBytes.copy(tar, 0, 0, Math.min(nameBytes.length, 100));
+
+  // File mode (8 bytes, octal, null-padded)
+  const modeStr = mode.toString(8).padStart(7, "0") + "\0";
+  Buffer.from(modeStr).copy(tar, 100);
+
+  // Owner ID (8 bytes) - 0
+  Buffer.from("0000000\0").copy(tar, 108);
+
+  // Group ID (8 bytes) - 0
+  Buffer.from("0000000\0").copy(tar, 116);
+
+  // File size (12 bytes, octal)
+  const sizeStr = contentBuffer.length.toString(8).padStart(11, "0") + "\0";
+  Buffer.from(sizeStr).copy(tar, 124);
+
+  // Modification time (12 bytes, octal)
+  const mtime = Math.floor(Date.now() / 1000);
+  const mtimeStr = mtime.toString(8).padStart(11, "0") + "\0";
+  Buffer.from(mtimeStr).copy(tar, 136);
+
+  // Type flag (1 byte) - '0' = regular file
+  tar[156] = 0x30; // '0'
+
+  // Checksum placeholder (8 bytes)
+  tar.fill(" ", 148, 156);
+
+  // Compute checksum
+  let checksum = 0;
+  for (let i = 0; i < 512; i++) {
+    checksum += tar[i];
+  }
+  const chkStr = checksum.toString(8).padStart(7, "0") + "\0";
+  Buffer.from(chkStr).copy(tar, 148);
+
+  // Copy content
+  contentBuffer.copy(tar, 512);
+
+  return tar;
+}
+
+export function registerTransferTools(
+  server: McpServer,
+  docker: Dockerode
+): void {
+  server.tool(
+    "copy_from_container",
+    "Copy a file from a Docker container to read its contents. Returns the file content as text along with metadata (size, permissions). Useful for inspecting config files, logs, or application state inside running containers.",
+    CopyFromContainerSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    async (params) => {
+      try {
+        const { content, size } = await withRetry(
+          () => readFileViaExec(docker, params.container_id, params.container_path),
+          { label: "copy_from_container" }
+        );
+
+        // Get metadata (stat)
+        let mode = "0644";
+        try {
+          const stat = await getFileStat(
+            docker,
+            params.container_id,
+            params.container_path
+          );
+          mode = stat.mode;
+        } catch {
+          // stat might fail if file doesn't exist, exec already validated it
+        }
+
+        const result = {
+          path: params.container_path,
+          content,
+          size,
+          mode,
+          truncated: content.length > 50000,
+        };
+
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${formatError(error)}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "copy_to_container",
+    "Write file content into a Docker container at the specified path. Overwrites existing files. Useful for injecting configuration files, scripts, or environment files into running or stopped containers.",
+    CopyToContainerSchema.shape,
+    { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
+    async (params) => {
+      try {
+        const container = docker.getContainer(params.container_id);
+        const mode = params.mode ?? 0o644;
+
+        // Create tar archive with the file
+        const tarBuffer = createSingleFileTar(
+          params.container_path,
+          params.content,
+          mode
+        );
+
+        // putArchive expects the path to be the PARENT directory
+        const parts = params.container_path.split("/");
+        parts.pop(); // remove filename
+        const dirPath = parts.join("/") || "/";
+
+        const readable = Readable.from(tarBuffer);
+
+        // Use putArchive with promise API
+        await withRetry(
+          () =>
+            new Promise<void>((resolve, reject) => {
+              container
+                .putArchive(readable as any, { path: dirPath })
+                .then(() => resolve())
+                .catch(reject);
+            }),
+          { label: "copy_to_container" }
+        );
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                success: true,
+                path: params.container_path,
+                size: Buffer.byteLength(params.content, "utf-8"),
+                mode: `0${(mode & 0o777).toString(8)}`,
+                message: `File written to ${params.container_path} in container ${params.container_id}`,
+              }),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${formatError(error)}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/types.ts

@@ -215,4 +215,22 @@ export const ResourceAlertCheckSchema = z.object({
   restart_count: z.number().optional().describe("Alert if restart count exceeds this (default: 5)"),
 });
 
-export const MonitorDashboardSchema = z.object({});
+export const MonitorDashboardSchema = z.object({});
+
+// System info schemas (v0.3.3)
+export const DockerInfoSchema = z.object({});
+
+export const DiskUsageSchema = z.object({});
+
+// File transfer schemas (v0.3.4)
+export const CopyFromContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  container_path: z.string().describe("Path inside container to copy from (e.g., '/etc/nginx/nginx.conf')"),
+});
+
+export const CopyToContainerSchema = z.object({
+  container_id: z.string().describe("Container ID or name"),
+  container_path: z.string().describe("Destination path inside container (e.g., '/app/config.json')"),
+  content: z.string().describe("File content to write (plain text)"),
+  mode: z.number().optional().describe("File permissions in octal (e.g., 0o644 = 420). Default: 0o644"),
+});

package/tests/system.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock Dockerode before importing the module under test
+const mockInfo = vi.fn();
+const mockDf = vi.fn();
+
+vi.mock("dockerode", () => {
+  return {
+    default: vi.fn().mockImplementation(() => ({
+      info: mockInfo,
+      df: mockDf,
+    })),
+  };
+});
+
+import { registerSystemTools } from "../src/tools/system.js";
+
+// Minimal MCP server mock
+function createMockServer() {
+  const tools: Record<string, { description: string; handler: Function }> = {};
+  return {
+    tool: (name: string, description: string, _schema: unknown, _hints: unknown, handler: Function) => {
+      tools[name] = { description, handler };
+    },
+    tools,
+  };
+}
+
+describe("System Tools", () => {
+  let server: ReturnType<typeof createMockServer>;
+  let docker: any;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    server = createMockServer();
+    docker = {
+      info: mockInfo,
+      df: mockDf,
+    };
+    registerSystemTools(server as any, docker);
+    vi.clearAllMocks();
+  });
+
+  describe("docker_info", () => {
+    it("should register docker_info tool", () => {
+      expect(server.tools["docker_info"]).toBeDefined();
+      expect(server.tools["docker_info"].description).toContain("system information");
+    });
+
+    it("should return formatted Docker info", async () => {
+      mockInfo.mockResolvedValue({
+        ServerVersion: "29.5.3",
+        OperatingSystem: "Ubuntu 26.04 LTS",
+        KernelVersion: "7.0.0-15-generic",
+        Architecture: "x86_64",
+        NCPU: 2,
+        MemTotal: 4000079872,
+        DockerRootDir: "/var/lib/docker",
+        Driver: "overlay2",
+        ContainersRunning: 3,
+        ContainersStopped: 5,
+        ContainersPaused: 0,
+        Images: 12,
+        Labels: ["com.docker.compose.version=2.29.1"],
+        ID: "ABC1:DEF2:GHI3:JKL4:MNO5:PQR6:STUV:WXYZ:1234:5678:ABCD:EF90:1234:5678",
+      });
+
+      const result = await server.tools["docker_info"].handler({});
+      const data = JSON.parse(result.content[0].text);
+
+      expect(data.server_version).toBe("29.5.3");
+      expect(data.os).toBe("Ubuntu 26.04 LTS");
+      expect(data.kernel).toBe("7.0.0-15-generic");
+      expect(data.cpus).toBe(2);
+      expect(data.memory_total_human).toBe("3.7 GB");
+      expect(data.containers_running).toBe(3);
+      expect(data.containers_stopped).toBe(5);
+      expect(data.images).toBe(12);
+      expect(data.storage_driver).toBe("overlay2");
+    });
+
+    it("should handle errors", async () => {
+      mockInfo.mockRejectedValue(new Error("Cannot connect to Docker daemon"));
+
+      const result = await server.tools["docker_info"].handler({});
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Error");
+    });
+  });
+
+  describe("disk_usage", () => {
+    it("should register disk_usage tool", () => {
+      expect(server.tools["disk_usage"]).toBeDefined();
+      expect(server.tools["disk_usage"].description).toContain("disk usage");
+    });
+
+    it("should return formatted disk usage", async () => {
+      mockDf.mockResolvedValue({
+        LayersSize: 623591029,
+        Images: [
+          {
+            Id: "sha256:a6894d60f28f051f4c3e44a6b5f0b669023fc47ea936355d65e5fcc10856767f",
+            RepoTags: ["nginx:latest"],
+            Size: 395120924,
+            Containers: 1,
+          },
+          {
+            Id: "sha256:b2894d60f28f051f4c3e44a6b5f0b669023fc47ea936355d65e5fcc10856767g",
+            RepoTags: ["alpine:latest"],
+            Size: 13068376,
+            Containers: 0,
+          },
+        ],
+        Containers: [
+          {
+            Id: "abc123def456",
+            Name: "web-app",
+            Image: "nginx:latest",
+            Size: 1048576,
+            Reclaimable: true,
+          },
+        ],
+        Volumes: [
+          {
+            Name: "data-vol",
+            Size: 52428800,
+            Reclaimable: false,
+          },
+        ],
+        BuildCache: [
+          {
+            ID: "cache1",
+            Type: "regular",
+            Description: "pulled from docker.io/library/node:22",
+            Size: 9032241,
+            InUse: false,
+          },
+          {
+            ID: "cache2",
+            Type: "regular",
+            Description: "COPY package.json",
+            Size: 156559,
+            InUse: false,
+          },
+        ],
+      });
+
+      const result = await server.tools["disk_usage"].handler({});
+      const data = JSON.parse(result.content[0].text);
+
+      expect(data.summary.images.count).toBe(2);
+      expect(data.summary.images.total_human).toMatch(/^594\.\d MB$/);
+      expect(data.summary.containers.count).toBe(1);
+      expect(data.summary.volumes.count).toBe(1);
+      expect(data.summary.build_cache.count).toBe(2);
+
+      // Check image details
+      expect(data.images[0].tags).toContain("nginx:latest");
+      expect(data.images[0].size_human).toMatch(/^376\.\d MB$/);
+
+      // Check container details
+      expect(data.containers[0].name).toBe("web-app");
+      expect(data.containers[0].size_human).toBe("1 MB");
+
+      // Check volume details
+      expect(data.volumes[0].name).toBe("data-vol");
+      expect(data.volumes[0].size_human).toBe("50 MB");
+    });
+
+    it("should handle empty disk usage", async () => {
+      mockDf.mockResolvedValue({
+        LayersSize: 0,
+        Images: [],
+        Containers: [],
+        Volumes: [],
+        BuildCache: [],
+      });
+
+      const result = await server.tools["disk_usage"].handler({});
+      const data = JSON.parse(result.content[0].text);
+
+      expect(data.summary.images.count).toBe(0);
+      expect(data.summary.containers.count).toBe(0);
+      expect(data.images).toEqual([]);
+    });
+
+    it("should handle errors", async () => {
+      mockDf.mockRejectedValue(new Error("Docker API error"));
+
+      const result = await server.tools["disk_usage"].handler({});
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Error");
+    });
+  });
+});

package/tests/transfer.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { PassThrough } from "stream";
+
+const { mockExec, mockPutArchive } = vi.hoisted(() => ({
+  mockExec: vi.fn(),
+  mockPutArchive: vi.fn(),
+}));
+
+vi.mock("dockerode", () => {
+  return {
+    default: vi.fn().mockImplementation(() => ({
+      getContainer: vi.fn().mockReturnValue({
+        exec: mockExec,
+        putArchive: mockPutArchive,
+      }),
+    })),
+  };
+});
+
+import { registerTransferTools } from "../src/tools/transfer.js";
+import { createDockerClient } from "../src/docker.js";
+
+function createMockServer() {
+  const tools: Record<string, { description: string; handler: Function }> = {};
+  return {
+    tool: (
+      name: string,
+      description: string,
+      _schemaOrAnnotations: unknown,
+      _annotationsOrHandler: unknown,
+      _maybeHandler?: Function
+    ) => {
+      const handler =
+        typeof _annotationsOrHandler === "function"
+          ? _annotationsOrHandler
+          : (_maybeHandler as Function);
+      tools[name] = { description, handler };
+    },
+    tools,
+  };
+}
+
+describe("Transfer Tools", () => {
+  let server: ReturnType<typeof createMockServer>;
+  let docker: ReturnType<typeof createDockerClient>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    server = createMockServer();
+    docker = createDockerClient();
+    registerTransferTools(server as any, docker);
+  });
+
+  describe("copy_from_container", () => {
+    it("calls exec with correct command", async () => {
+      // Mock exec to reject (error path tests the call chain)
+      mockExec.mockRejectedValue(new Error("No such container"));
+
+      const result = await server.tools["copy_from_container"].handler({
+        container_id: "test-container",
+        container_path: "/etc/hosts",
+      });
+
+      // Verify exec was called with the correct options
+      expect(mockExec).toHaveBeenCalledWith({
+        Cmd: ["cat", "/etc/hosts"],
+        AttachStdout: true,
+        AttachStderr: true,
+      });
+      expect(result.isError).toBe(true);
+    });
+
+    it("handles exec errors gracefully", async () => {
+      mockExec.mockRejectedValue(new Error("No such container"));
+
+      const result = await server.tools["copy_from_container"].handler({
+        container_id: "nonexistent",
+        container_path: "/etc/hosts",
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Error");
+      expect(result.content[0].text).toContain("No such container");
+    });
+
+    it("tool is registered with correct metadata", () => {
+      const tool = server.tools["copy_from_container"];
+      expect(tool).toBeDefined();
+      expect(tool.description).toContain("Copy a file from a Docker container");
+    });
+  });
+
+  describe("copy_to_container", () => {
+    it("writes a file into container", async () => {
+      mockPutArchive.mockResolvedValue({});
+
+      const result = await server.tools["copy_to_container"].handler({
+        container_id: "abc123",
+        container_path: "/app/config.json",
+        content: '{"key": "value"}',
+        mode: 0o644,
+      });
+
+      const data = JSON.parse(result.content[0].text);
+      expect(data.success).toBe(true);
+      expect(data.path).toBe("/app/config.json");
+      expect(data.size).toBe(16); // '{"key": "value"}' = 16 bytes
+      expect(result.isError).toBeFalsy();
+    });
+
+    it("uses default mode 0o644 when not specified", async () => {
+      mockPutArchive.mockResolvedValue({});
+
+      const result = await server.tools["copy_to_container"].handler({
+        container_id: "abc123",
+        container_path: "/app/script.sh",
+        content: "#!/bin/bash\necho hello",
+      });
+
+      const data = JSON.parse(result.content[0].text);
+      expect(data.mode).toBe("0644");
+    });
+
+    it("calls putArchive with parent directory", async () => {
+      mockPutArchive.mockResolvedValue({});
+
+      await server.tools["copy_to_container"].handler({
+        container_id: "abc123",
+        container_path: "/app/config.json",
+        content: "data",
+      });
+
+      // putArchive should be called (stream, { path: "/app" })
+      expect(mockPutArchive).toHaveBeenCalled();
+      const callArgs = mockPutArchive.mock.calls[0];
+      expect(callArgs[1]).toEqual({ path: "/app" });
+    });
+
+    it("handles nested paths correctly", async () => {
+      mockPutArchive.mockResolvedValue({});
+
+      const result = await server.tools["copy_to_container"].handler({
+        container_id: "abc123",
+        container_path: "/etc/nginx/nginx.conf",
+        content: "worker_processes 1;",
+      });
+
+      const data = JSON.parse(result.content[0].text);
+      expect(data.success).toBe(true);
+      expect(data.path).toBe("/etc/nginx/nginx.conf");
+
+      // Parent dir should be /etc/nginx
+      const callArgs = mockPutArchive.mock.calls[0];
+      expect(callArgs[1]).toEqual({ path: "/etc/nginx" });
+    });
+
+    it("handles putArchive errors gracefully", async () => {
+      mockPutArchive.mockRejectedValue(new Error("Permission denied"));
+
+      const result = await server.tools["copy_to_container"].handler({
+        container_id: "abc123",
+        container_path: "/root/secret.txt",
+        content: "data",
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Error");
+    });
+
+    it("tool is registered with correct metadata", () => {
+      const tool = server.tools["copy_to_container"];
+      expect(tool).toBeDefined();
+      expect(tool.description).toContain("Write file content into a Docker container");
+    });
+  });
+});