@supernova123/docker-mcp-server 0.3.3 → 0.3.5

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

@@ -186,6 +186,21 @@ export const PruneVolumesSchema = z.object({
   filter: z.string().optional().describe("Filter by label (e.g., 'label=key=value')"),
 });
 
+export const PruneContainersSchema = z.object({
+  filter: z.string().optional().describe("Filter by label (e.g., 'label=key=value')"),
+});
+
+export const PruneImagesSchema = z.object({
+  filter: z.string().optional().describe('Docker filters JSON (e.g. "dangling=true")'),
+});
+
+export const UpdateContainerSchema = z.object({
+  container_id: z.string().describe('Container ID or name'),
+  cpu_limit: z.number().optional().describe('CPU limit in cores (e.g. 1.5 for 1.5 CPUs)'),
+  memory_limit: z.string().optional().describe('Memory limit (e.g. "512m", "1g", "2048m")'),
+  cpu_shares: z.number().optional().describe('CPU shares (relative weight, 0-1024)'),
+});
+
 
 // Monitoring schemas (v0.2.0)
 export const ContainerHealthStatusSchema = z.object({});
@@ -220,4 +235,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");
+    });
+  });
+});

package/tsconfig.cf.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist-cf",
+    "rootDir": "src/cf-worker",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/cf-worker/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.json

@@ -15,5 +15,5 @@
     "sourceMap": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
+  "exclude": ["node_modules", "dist", "tests", "src/cf-worker"]
 }

package/wrangler.jsonc

@@ -0,0 +1,19 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "docker-mcp-worker",
+  "main": "src/cf-worker/index.ts",
+  "compatibility_date": "2026-01-28",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": { "logs": { "enabled": true } },
+  "durable_objects": {
+    "bindings": [
+      { "name": "MCP_AGENT", "class_name": "McpAgentDO" }
+    ]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["McpAgentDO"] }
+  ],
+  "kv_namespaces": [
+    { "binding": "API_KEYS", "id": "placeholder-api-keys" }
+  ]
+}