@supernova123/docker-mcp-server 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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

package/dist/server.js

@@ -9,6 +9,7 @@ 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",
@@ -25,6 +26,7 @@ export function createServer(docker, options) {
     registerVolumeTools(server, docker);
     registerMonitoringTools(server, docker);
     registerSystemTools(server, docker);
+    registerTransferTools(server, docker);
     return server;
 }
 //# sourceMappingURL=server.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

@@ -405,4 +405,30 @@ export declare const ResourceAlertCheckSchema: z.ZodObject<{
 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

@@ -176,4 +176,15 @@ 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.3",
+  "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

@@ -10,6 +10,7 @@ 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;
@@ -32,6 +33,7 @@ export function createServer(docker: Dockerode, options?: ServerOptions): McpSer
   registerVolumeTools(server, docker);
   registerMonitoringTools(server, docker);
   registerSystemTools(server, docker);
+  registerTransferTools(server, docker);
 
   return server;
-}
+}

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

@@ -220,4 +220,17 @@ export const MonitorDashboardSchema = z.object({});
 // System info schemas (v0.3.3)
 export const DockerInfoSchema = z.object({});
 
-export const DiskUsageSchema = 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/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");
+    });
+  });
+});