@supernova123/docker-mcp-server 0.3.3 → 0.3.5

package/src/cf-worker/mcp-agent.ts

@@ -0,0 +1,362 @@
+import { DurableObject } from "cloudflare:workers";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z } from "zod";
+import { TIER_LIMITS, type UserState, type Env } from "./types.js";
+
+/**
+ * McpAgentDO — Durable Object that hosts a per-user MCP server.
+ *
+ * Each user gets their own DO instance (deterministic ID from userId).
+ * The DO holds per-user state (rate limits, tier) and proxies tool
+ * calls to the user's Docker daemon via Cloudflare Tunnel.
+ *
+ * Architecture:
+ *   Routing Worker (auth, CORS) → McpAgentDO (tool dispatch) → User's Docker daemon
+ */
+export class McpAgentDO extends DurableObject {
+  private state: DurableObjectState;
+  private userState: UserState | null = null;
+
+  constructor(state: DurableObjectState, env: Env) {
+    super(state, env);
+    this.state = state;
+  }
+
+  async initialize(userId: string, tier: string): Promise<void> {
+    const existing = await this.state.storage.get<UserState>("userState");
+    if (!existing) {
+      const newUser: UserState = {
+        userId,
+        tier: tier as UserState["tier"],
+        toolCallsToday: 0,
+        lastReset: new Date().toISOString().split("T")[0],
+        maxToolCallsPerDay: TIER_LIMITS[tier] || TIER_LIMITS.free,
+      };
+      await this.state.storage.put("userState", newUser);
+      this.userState = newUser;
+    } else {
+      this.userState = existing;
+      // Reset daily counter if needed
+      const today = new Date().toISOString().split("T")[0];
+      if (existing.lastReset !== today) {
+        existing.toolCallsToday = 0;
+        existing.lastReset = today;
+        await this.state.storage.put("userState", existing);
+      }
+    }
+  }
+
+
+  async setTunnelUrl(url: string): Promise<{ ok: boolean; tunnelUrl: string }> {
+    // Validate URL format
+    try {
+      new URL(url);
+    } catch {
+      return { ok: false, tunnelUrl: "" };
+    }
+    await this.state.storage.put("tunnelUrl", url);
+    return { ok: true, tunnelUrl: url };
+  }
+
+  async getTunnelUrl(): Promise<string> {
+    return (await this.state.storage.get<string>("tunnelUrl")) || "";
+  }
+
+  async handleMcpRequest(request: Request): Promise<Response> {
+    if (!this.userState) {
+      return new Response("User not initialized", { status: 500 });
+    }
+
+    // Check rate limit
+    if (this.userState.toolCallsToday >= this.userState.maxToolCallsPerDay) {
+      return new Response(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: `Rate limit exceeded: ${this.userState.maxToolCallsPerDay} calls/day for ${this.userState.tier} tier`,
+          },
+          id: null,
+        }),
+        { status: 429, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Create MCP server for this request
+    const server = this.createServer();
+    const transport = new WebStandardStreamableHTTPServerTransport();
+
+    await server.connect(transport);
+    const response = await transport.handleRequest(request);
+
+    // Increment counter on successful tool call
+    this.userState.toolCallsToday++;
+    await this.state.storage.put("userState", this.userState);
+
+    return response;
+  }
+
+  private createServer(): McpServer {
+    const server = new McpServer({
+      name: "docker-mcp-hosted",
+      version: "0.4.0",
+    });
+
+    // ── Container Management ──────────────────────────────────
+    server.registerTool(
+      "list_containers",
+      { description: "List Docker containers with optional filters" },
+      async () => this.proxyToDocker("list_containers", {})
+    );
+
+    server.registerTool(
+      "inspect_container",
+      {
+        description: "Get detailed info about a Docker container",
+        inputSchema: { name: z.string() },
+      },
+      async ({ name }) => this.proxyToDocker("inspect_container", { name })
+    );
+
+    server.registerTool(
+      "start_container",
+      {
+        description: "Start a stopped Docker container",
+        inputSchema: { name: z.string() },
+      },
+      async ({ name }) => this.proxyToDocker("start_container", { name })
+    );
+
+    server.registerTool(
+      "stop_container",
+      {
+        description: "Stop a running Docker container",
+        inputSchema: { name: z.string(), timeout: z.number().optional() },
+      },
+      async ({ name, timeout }) =>
+        this.proxyToDocker("stop_container", { name, timeout })
+    );
+
+    server.registerTool(
+      "restart_container",
+      {
+        description: "Restart a Docker container",
+        inputSchema: { name: z.string() },
+      },
+      async ({ name }) => this.proxyToDocker("restart_container", { name })
+    );
+
+    server.registerTool(
+      "remove_container",
+      {
+        description: "Remove a Docker container",
+        inputSchema: { name: z.string(), force: z.boolean().optional() },
+      },
+      async ({ name, force }) =>
+        this.proxyToDocker("remove_container", { name, force })
+    );
+
+    server.registerTool(
+      "create_container",
+      {
+        description: "Create a new Docker container from an image",
+        inputSchema: {
+          image: z.string(),
+          name: z.string().optional(),
+          ports: z.record(z.string()).optional(),
+          env: z.record(z.string()).optional(),
+          volumes: z.array(z.string()).optional(),
+        },
+      },
+      async (params) => this.proxyToDocker("create_container", params)
+    );
+
+    // ── Compose Lifecycle ─────────────────────────────────────
+    server.registerTool(
+      "compose_up",
+      {
+        description: "Start services defined in a docker-compose.yml file",
+        inputSchema: {
+          project: z.string(),
+          path: z.string().optional(),
+          detach: z.boolean().optional(),
+        },
+      },
+      async (params) => this.proxyToDocker("compose_up", params)
+    );
+
+    server.registerTool(
+      "compose_down",
+      {
+        description: "Stop and remove services defined in a docker-compose.yml file",
+        inputSchema: { project: z.string(), path: z.string().optional() },
+      },
+      async (params) => this.proxyToDocker("compose_down", params)
+    );
+
+    server.registerTool(
+      "compose_ps",
+      {
+        description: "List services in a Compose project",
+        inputSchema: { project: z.string() },
+      },
+      async ({ project }) => this.proxyToDocker("compose_ps", { project })
+    );
+
+    server.registerTool(
+      "compose_logs",
+      {
+        description: "Get logs from Compose services",
+        inputSchema: {
+          project: z.string(),
+          service: z.string().optional(),
+          tail: z.number().optional(),
+        },
+      },
+      async (params) => this.proxyToDocker("compose_logs", params)
+    );
+
+    // ── Monitoring ────────────────────────────────────────────
+    server.registerTool(
+      "fleet_status",
+      {
+        description: "Get status overview of all Docker containers",
+      },
+      async () => this.proxyToDocker("fleet_status", {})
+    );
+
+    server.registerTool(
+      "search_logs",
+      {
+        description: "Search container logs by keyword",
+        inputSchema: {
+          name: z.string(),
+          query: z.string(),
+          tail: z.number().optional(),
+        },
+      },
+      async (params) => this.proxyToDocker("search_logs", params)
+    );
+
+    server.registerTool(
+      "watch_events",
+      {
+        description: "Stream Docker daemon events (containers, images, networks)",
+        inputSchema: { since: z.string().optional() },
+      },
+      async (params) => this.proxyToDocker("watch_events", params)
+    );
+
+    // ── Image Management ──────────────────────────────────────
+    server.registerTool(
+      "list_images",
+      { description: "List Docker images on the host" },
+      async () => this.proxyToDocker("list_images", {})
+    );
+
+    server.registerTool(
+      "pull_image",
+      {
+        description: "Pull a Docker image from a registry",
+        inputSchema: { image: z.string() },
+      },
+      async ({ image }) => this.proxyToDocker("pull_image", { image })
+    );
+
+    // ── Network & Volume ──────────────────────────────────────
+    server.registerTool(
+      "list_networks",
+      { description: "List Docker networks" },
+      async () => this.proxyToDocker("list_networks", {})
+    );
+
+    server.registerTool(
+      "list_volumes",
+      { description: "List Docker volumes" },
+      async () => this.proxyToDocker("list_volumes", {})
+    );
+
+    return server;
+  }
+
+  /**
+   * Proxy a tool call to the user's Docker daemon via Cloudflare Tunnel.
+   *
+   * Architecture: The user runs `docker-mcp-server` locally, exposed via
+   * `cloudflared tunnel`. This DO forwards the tool call request to that
+   * endpoint. The tunnel URL is stored per-user in KV or passed at init.
+   *
+   * For now, returns a placeholder response. Real implementation connects
+   * to the user's tunnel endpoint.
+   */
+  private async proxyToDocker(
+    tool: string,
+    args: Record<string, unknown>
+  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
+    // TODO: Connect to user's Cloudflare Tunnel endpoint
+    // The tunnel URL should be stored in KV or passed during user setup.
+    // For now, return a structured placeholder.
+    const tunnelUrl = await this.state.storage.get<string>("tunnelUrl");
+
+    if (!tunnelUrl) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: "No Docker tunnel configured. Please set up a Cloudflare Tunnel to connect your Docker daemon.",
+              tool,
+              args,
+            }),
+          },
+        ],
+      };
+    }
+
+    // Forward the tool call to the user's tunnel
+    try {
+      const response = await fetch(tunnelUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          method: "tools/call",
+          params: { name: tool, arguments: args },
+          id: crypto.randomUUID(),
+        }),
+      });
+
+      const result = (await response.json()) as {
+        result?: { content: Array<{ type: string; text: string }> };
+        error?: { message: string };
+      };
+
+      if (result.error) {
+        return {
+          content: [{ type: "text", text: `Error: ${result.error.message}` }],
+        };
+      }
+
+      if (result.result?.content) {
+        return {
+          content: result.result.content.map((c) => ({
+            type: "text" as const,
+            text: c.text || "",
+          })),
+        };
+      }
+
+      return { content: [{ type: "text", text: "No result" }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Tunnel connection failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+      };
+    }
+  }
+}

package/src/cf-worker/types.ts

@@ -0,0 +1,38 @@
+// Types for Docker MCP Cloudflare Worker
+
+export interface Env {
+  MCP_AGENT: DurableObjectNamespace;
+  API_KEYS: KVNamespace;
+}
+
+export interface ApiKeyRecord {
+  userId: string;
+  tier: 'free' | 'standard' | 'premium';
+  createdAt: string;
+  active: boolean;
+}
+
+export interface UserState {
+  userId: string;
+  tier: 'free' | 'standard' | 'premium';
+  toolCallsToday: number;
+  lastReset: string;
+  // Per-tier limits
+  maxToolCallsPerDay: number;
+}
+
+export const TIER_LIMITS: Record<string, number> = {
+  free: 50,       // 50 tool calls/day
+  standard: 500,  // 500 tool calls/day (unlimited in practice for $19/mo)
+  premium: 5000,  // 5000 tool calls/day
+};
+
+export interface ToolRequest {
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface ToolResponse {
+  content: Array<{ type: 'text' | 'image'; text?: string; data?: string }>;
+  isError?: boolean;
+}

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;
@@ -18,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.3",
+    version: "0.3.4",
   });
 
   // Register all tool categories
@@ -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/compose.ts

@@ -50,7 +50,7 @@ function runCompose(path: string, args: string[]): string {
 export function registerComposeTools(server: McpServer): void {
   server.tool(
     "compose_up",
-    "Bring up Docker Compose services from a docker-compose.yml file. Optionally build images first.",
+    "Bring up Docker Compose services from a docker-compose.yml file at path. Use compose_ps to check service states after bringing them up; use compose_logs to inspect output. Optionally rebuild images before starting (build=true). Returns a confirmation string listing which services were started. Idempotent: already-running services are left untouched. Returns an error string if the Compose file is missing or invalid.",
     ComposeUpSchema.shape,
     { idempotentHint: true, openWorldHint: false },
     async (params) => {
@@ -86,7 +86,7 @@ export function registerComposeTools(server: McpServer): void {
 
   server.tool(
     "compose_ps",
-    "List service states across a Docker Compose stack.",
+    "List service states across a Docker Compose stack defined by docker-compose.yml at path. Returns an array of services with name, state (running, exited, etc.), health status, and port mappings. Use compose_up to start services; use compose_logs to inspect output. Read-only and safe to call repeatedly. Returns an error string if the Compose file is missing.",
     ComposePsSchema.shape,
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {

package/src/tools/container.ts

@@ -9,6 +9,8 @@ import {
   RemoveContainerSchema,
   RecreateContainerSchema,
   RunContainerSchema,
+  PruneContainersSchema,
+  UpdateContainerSchema,
 } from "../types.js";
 import { formatContainer, formatError, withRetry } from "../docker.js";
 
@@ -223,4 +225,108 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
       }
     }
   );
+
+  // prune_containers — remove stopped containers
+  server.tool(
+    "prune_containers",
+    "Remove all stopped Docker containers. Returns the number of containers removed and reclaimed disk space. This is a destructive operation — stopped containers and their non-persisted data will be deleted. Use list_containers first to see what will be removed. Useful for cleanup after deployments or when disk space is low.",
+    PruneContainersSchema.shape,
+    { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
+    async (params) => {
+      try {
+        const filterObj: Record<string, string[]> = {};
+        if (params.filter) {
+          const parts = params.filter.split('=');
+          if (parts.length === 2) {
+            filterObj[parts[0]] = [parts[1]];
+          }
+        }
+        const result = await withRetry(
+          () => docker.pruneContainers({ filters: filterObj }),
+          { label: "prune_containers" }
+        );
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              containers_deleted: (result.ContainersDeleted || []).length,
+              space_reclaimed: result.SpaceReclaimed || 0,
+              space_reclaimed_human: formatBytes(result.SpaceReclaimed || 0),
+              deleted_ids: (result.ContainersDeleted || []).map((id: string) => id.substring(0, 12)),
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+      }
+    }
+  );
+
+  // update_container — update container resource limits
+  server.tool(
+    "update_container",
+    "Update a Docker container's resource limits (CPU, memory, CPU shares). Requires the container to be stopped first. Returns the updated resource limits. Use this to right-size containers based on actual usage — set CPU limits to prevent runaway processes and memory limits to prevent OOM kills.",
+    UpdateContainerSchema.shape,
+    { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
+    async (params) => {
+      try {
+        const updateConfig: Record<string, any> = {};
+        if (params.cpu_limit !== undefined) {
+          updateConfig.NanoCpus = Math.round(params.cpu_limit * 1e9);
+        }
+        if (params.memory_limit !== undefined) {
+          updateConfig.Memory = parseMemory(params.memory_limit);
+        }
+        if (params.cpu_shares !== undefined) {
+          updateConfig.CpuShares = params.cpu_shares;
+        }
+
+        if (Object.keys(updateConfig).length === 0) {
+          return { content: [{ type: "text", text: "Error: No resource limits specified. Provide at least one of: cpu_limit, memory_limit, cpu_shares." }], isError: true };
+        }
+
+        const container = docker.getContainer(params.container_id);
+        await withRetry(() => container.update(updateConfig), { label: "update_container" });
+
+        // Inspect to return current state
+        const info = await withRetry(() => container.inspect(), { label: "update_container_inspect" });
+        const hostConfig = info.HostConfig || {};
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              container: params.container_id,
+              state: info.State?.Status,
+              resource_limits: {
+                cpu_limit_cores: hostConfig.NanoCpus ? hostConfig.NanoCpus / 1e9 : null,
+                memory_limit: hostConfig.Memory || null,
+                memory_limit_human: hostConfig.Memory ? formatBytes(hostConfig.Memory) : null,
+                cpu_shares: hostConfig.CpuShares || null,
+              },
+            }, 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]}`;
+}
+
+function parseMemory(mem: string): number {
+  const match = mem.match(/^(\d+)(b|k|m|g|t)?$/i);
+  if (!match) throw new Error(`Invalid memory format: ${mem}`);
+  const value = parseInt(match[1]);
+  const unit = (match[2] || 'b').toLowerCase();
+  const multipliers: Record<string, number> = { b: 1, k: 1024, m: 1024**2, g: 1024**3, t: 1024**4 };
+  return value * (multipliers[unit] || 1);
 }

package/src/tools/health.ts

@@ -130,7 +130,7 @@ export function registerHealthTools(server: McpServer, docker: Dockerode): void
 
   server.tool(
     "set_restart_policy",
-    "Change the restart policy of a running container without recreating it.",
+    "Change the restart policy of a running container without recreating it. Use restart_container for an immediate restart; use this tool to change the policy (always, unless-stopped, on-failure, no) for future restarts. Returns a confirmation string on success. Idempotent: setting the same policy is a no-op. Returns an error string if the container does not exist.",
     SetRestartPolicySchema.shape,
     { idempotentHint: true, openWorldHint: false },
     async (params) => {

package/src/tools/image.ts

@@ -5,6 +5,7 @@ import {
   PullImageSchema,
   BuildImageSchema,
   RemoveImageSchema,
+  PruneImagesSchema,
 } from "../types.js";
 import { formatImage, formatError, withRetry } from "../docker.js";
 
@@ -30,7 +31,7 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
 
   server.tool(
     "pull_image",
-    "Pull a Docker image from a registry. Returns pull progress events.",
+    "Pull a Docker image from a registry by image name (e.g. nginx:latest). Use list_images to see locally available images after pulling. Returns pull progress events as text. Idempotent: pulling an already-up-to-date image is a no-op. Returns an error string if the image does not exist on the registry or the pull fails.",
     PullImageSchema.shape,
     { idempotentHint: true, openWorldHint: false },
     async (params) => {
@@ -93,4 +94,56 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
       }
     }
   );
+
+  // prune_images — remove unused Docker images
+  server.tool(
+    "prune_images",
+    "Remove unused Docker images (dangling and unreferenced). Returns the number of images deleted and reclaimed disk space. Only removes images not used by any container. Use list_images first to see what will be removed. Useful for reclaiming disk space after builds or when switching base images frequently.",
+    PruneImagesSchema.shape,
+    { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
+    async (params) => {
+      try {
+        const filterObj: Record<string, string[]> = {};
+        if (params.filter) {
+          try {
+            const parsed = JSON.parse(params.filter);
+            Object.assign(filterObj, parsed);
+          } catch {
+            // If not JSON, try key=value format
+            const parts = params.filter.split('=');
+            if (parts.length === 2) {
+              filterObj[parts[0]] = [parts[1]];
+            }
+          }
+        }
+        const result = await withRetry(
+          () => docker.pruneImages({ filters: filterObj }),
+          { label: "prune_images" }
+        );
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              images_deleted: (result.ImagesDeleted || []).length,
+              space_reclaimed: result.SpaceReclaimed || 0,
+              space_reclaimed_human: formatBytes(result.SpaceReclaimed || 0),
+              deleted_ids: (result.ImagesDeleted || []).map((img: any) =>
+                typeof img === 'string' ? img.substring(0, 19) : img.Deleted?.substring(0, 19) || 'unknown'
+              ),
+            }, 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]}`;
 }