docker_mcp 0.0.1 → 0.2.5

data/lib/docker_mcp/create_container.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for creating Docker containers without starting them.
+  #
+  # This tool provides the ability to create Docker containers from images with
+  # comprehensive configuration options. Unlike RunContainer, this tool only
+  # creates the container but does not start it, allowing for additional
+  # configuration or manual startup control.
+  #
+  # == Features
+  #
+  # - Create containers from any available Docker image
+  # - Full container configuration support
+  # - Port exposure and binding configuration
+  # - Volume mounting capabilities
+  # - Environment variable configuration
+  # - Custom command specification
+  # - Comprehensive error handling with specific error types
+  #
+  # == Security Considerations
+  #
+  # - Containers inherit Docker daemon security context
+  # - Host configuration can expose host resources
+  # - Volume mounts provide filesystem access
+  # - Port bindings expose services to networks
+  # - Environment variables may contain sensitive data
+  #
+  # Use appropriate security measures:
+  # - Validate image sources and integrity
+  # - Limit host resource exposure
+  # - Use read-only volumes where appropriate
+  # - Restrict network access through host configuration
+  # - Sanitize environment variables
+  #
+  # == Example Usage
+  #
+  #   # Simple container creation
+  #   CreateContainer.call(
+  #     server_context: context,
+  #     image: "nginx:latest",
+  #     name: "web-server"
+  #   )
+  #
+  #   # Advanced container with configuration
+  #   CreateContainer.call(
+  #     server_context: context,
+  #     image: "postgres:13",
+  #     name: "database",
+  #     env: "POSTGRES_PASSWORD=secret,POSTGRES_DB=myapp",
+  #     exposed_ports: {"5432/tcp" => {}},
+  #     host_config: {
+  #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
+  #       "Binds" => ["/host/data:/var/lib/postgresql/data:rw"]
+  #     }
+  #   )
+  #
+  # @see RunContainer
+  # @see StartContainer
+  # @see Docker::Container.create
+  # @since 0.1.0
+  class CreateContainer < MCP::Tool
+    description 'Create a Docker container'
+
+    input_schema(
+      properties: {
+        image: {
+          type: 'string',
+          description: 'Image name to use (e.g., "ubuntu:22.04")'
+        },
+        name: {
+          type: 'string',
+          description: 'Container name (optional)'
+        },
+        cmd: {
+          type: 'string',
+          description: 'Command to run as space-separated string (optional, e.g., "npm start" or "python app.py")'
+        },
+        env: {
+          type: 'string',
+          description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)'
+        },
+        exposed_ports: {
+          type: 'object',
+          description: 'Exposed ports as {"port/protocol": {}} (optional)'
+        },
+        host_config: {
+          type: 'object',
+          description: 'Host configuration including port bindings, volumes, etc. (optional)'
+        }
+      },
+      required: ['image']
+    )
+
+    # Create a new Docker container from an image.
+    #
+    # This method creates a container with the specified configuration but does
+    # not start it. The container can be started later using StartContainer or
+    # other Docker commands. All configuration parameters are optional except
+    # for the base image.
+    #
+    # @param image [String] Docker image name with optional tag (e.g., "nginx:latest")
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param name [String, nil] custom name for the container
+    # @param cmd [String, nil] command to execute as space-separated string
+    # @param env [String, nil] environment variables as comma-separated KEY=VALUE pairs
+    # @param exposed_ports [Hash, nil] ports to expose in {"port/protocol" => {}} format
+    # @param host_config [Hash, nil] Docker host configuration including bindings and volumes
+    #
+    # @return [MCP::Tool::Response] creation results with container ID and name
+    #
+    # @raise [Docker::Error::NotFoundError] if the specified image doesn't exist
+    # @raise [Docker::Error::ConflictError] if container name already exists
+    # @raise [StandardError] for other creation failures
+    #
+    # @example Create simple container
+    #   response = CreateContainer.call(
+    #     server_context: context,
+    #     image: "alpine:latest",
+    #     name: "test-container"
+    #   )
+    #
+    # @example Create container with full configuration
+    #   response = CreateContainer.call(
+    #     server_context: context,
+    #     image: "redis:7-alpine",
+    #     name: "redis-cache",
+    #     env: "REDIS_PASSWORD=secret,REDIS_PORT=6379",
+    #     exposed_ports: {"6379/tcp" => {}},
+    #     host_config: {
+    #       "PortBindings" => {"6379/tcp" => [{"HostPort" => "6379"}]},
+    #       "RestartPolicy" => {"Name" => "unless-stopped"}
+    #     }
+    #   )
+    #
+    # @see Docker::Container.create
+    def self.call(image:, server_context:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil)
+      config = { 'Image' => image }
+      config['name'] = name if name
+
+      # Parse cmd string into array if provided
+      config['Cmd'] = Shellwords.split(cmd) if cmd && !cmd.strip.empty?
+
+      # Parse env string into array if provided
+      config['Env'] = env.split(',').map(&:strip) if env && !env.strip.empty?
+
+      config['ExposedPorts'] = exposed_ports if exposed_ports
+      config['HostConfig'] = host_config if host_config
+
+      container = Docker::Container.create(config)
+      container_name = container.info['Names']&.first&.delete_prefix('/')
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container created successfully. ID: #{container.id}, Name: #{container_name}"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{image} not found"
+                              }])
+    rescue Docker::Error::ConflictError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container with name #{name} already exists"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error creating container: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/create_network.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for creating Docker networks.
+  #
+  # This tool provides the ability to create custom Docker networks for
+  # container communication and isolation. Networks enable containers to
+  # communicate securely while providing isolation from other network
+  # segments.
+  #
+  # == Features
+  #
+  # - Create custom Docker networks
+  # - Support for different network drivers
+  # - Duplicate name detection
+  # - Comprehensive error handling
+  # - Flexible network configuration
+  #
+  # == Network Drivers
+  #
+  # Docker supports various network drivers:
+  # - **bridge**: Default isolated network for single-host networking
+  # - **host**: Remove network isolation, use host networking directly
+  # - **overlay**: Multi-host networking for swarm services
+  # - **macvlan**: Assign MAC addresses to containers
+  # - **none**: Disable networking completely
+  # - **Custom**: Third-party network drivers
+  #
+  # == Security Considerations
+  #
+  # Network creation affects system security:
+  # - **Network Isolation**: Networks provide security boundaries
+  # - **Traffic Control**: Custom networks enable traffic filtering
+  # - **Access Control**: Networks control container communication
+  # - **DNS Resolution**: Networks provide internal DNS services
+  #
+  # Security implications:
+  # - Bridge networks isolate containers from host network
+  # - Host networks expose containers to all host traffic
+  # - Custom networks should follow least-privilege principles
+  # - Network names may reveal infrastructure details
+  #
+  # Best practices:
+  # - Use descriptive but not sensitive network names
+  # - Implement network segmentation strategies
+  # - Limit container access to necessary networks only
+  # - Monitor network traffic and connections
+  # - Regular audit of network configurations
+  #
+  # == Example Usage
+  #
+  #   # Create basic bridge network
+  #   CreateNetwork.call(
+  #     server_context: context,
+  #     name: "app-network"
+  #   )
+  #
+  #   # Create network with specific driver
+  #   CreateNetwork.call(
+  #     server_context: context,
+  #     name: "frontend-net",
+  #     driver: "bridge"
+  #   )
+  #
+  #   # Create without duplicate checking
+  #   CreateNetwork.call(
+  #     server_context: context,
+  #     name: "temp-network",
+  #     check_duplicate: false
+  #   )
+  #
+  # @see ListNetworks
+  # @see RemoveNetwork
+  # @see Docker::Network.create
+  # @since 0.1.0
+  class CreateNetwork < MCP::Tool
+    description 'Create a Docker network'
+
+    input_schema(
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Name of the network'
+        },
+        driver: {
+          type: 'string',
+          description: 'Driver to use (default: bridge)'
+        },
+        check_duplicate: {
+          type: 'boolean',
+          description: 'Check for networks with duplicate names (default: true)'
+        }
+      },
+      required: ['name']
+    )
+
+    # Create a new Docker network.
+    #
+    # This method creates a custom Docker network with the specified name
+    # and driver. The network can then be used by containers for isolated
+    # communication.
+    #
+    # @param name [String] name for the new network
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param driver [String] network driver to use (default: "bridge")
+    # @param check_duplicate [Boolean] whether to check for duplicate names (default: true)
+    #
+    # @return [MCP::Tool::Response] network creation results with network ID
+    #
+    # @raise [Docker::Error::ConflictError] if network name already exists
+    # @raise [StandardError] for other network creation failures
+    #
+    # @example Create application network
+    #   response = CreateNetwork.call(
+    #     server_context: context,
+    #     name: "webapp-network"
+    #   )
+    #
+    # @example Create host network
+    #   response = CreateNetwork.call(
+    #     server_context: context,
+    #     name: "high-performance-net",
+    #     driver: "host"
+    #   )
+    #
+    # @see Docker::Network.create
+    def self.call(name:, server_context:, driver: 'bridge', check_duplicate: true)
+      options = {
+        'Name' => name,
+        'Driver' => driver,
+        'CheckDuplicate' => check_duplicate
+      }
+
+      network = Docker::Network.create(name, options)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Network #{name} created successfully. ID: #{network.id}"
+                              }])
+    rescue Docker::Error::ConflictError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Network #{name} already exists"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error creating network: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/create_volume.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for creating Docker volumes.
+  #
+  # This tool provides the ability to create persistent Docker volumes for
+  # data storage that survives container lifecycle events. Volumes are the
+  # preferred mechanism for persisting data generated and used by Docker
+  # containers.
+  #
+  # == Features
+  #
+  # - Create named persistent volumes
+  # - Support for different volume drivers
+  # - Comprehensive error handling
+  # - Duplicate name detection
+  # - Flexible storage configuration
+  #
+  # == Volume Drivers
+  #
+  # Docker supports various volume drivers:
+  # - **local**: Default driver using host filesystem
+  # - **nfs**: Network File System for shared storage
+  # - **cifs**: Common Internet File System
+  # - **rexray**: External storage orchestration
+  # - **Custom**: Third-party volume drivers
+  #
+  # == Persistence Benefits
+  #
+  # Docker volumes provide several advantages:
+  # - **Data Persistence**: Survive container deletion and recreation
+  # - **Performance**: Better performance than bind mounts on Docker Desktop
+  # - **Portability**: Can be moved between containers and hosts
+  # - **Backup**: Easier to backup and restore than container filesystems
+  # - **Sharing**: Can be shared between multiple containers
+  # - **Management**: Managed by Docker daemon with proper lifecycle
+  #
+  # == Security Considerations
+  #
+  # Volume creation affects data security:
+  # - **Data Isolation**: Volumes provide isolation between containers
+  # - **Access Control**: Volume permissions affect data access
+  # - **Storage Location**: Local volumes stored on host filesystem
+  # - **Shared Access**: Multiple containers can access the same volume
+  #
+  # Security implications:
+  # - Volumes persist data beyond container lifecycle
+  # - Volume names may reveal application details
+  # - Shared volumes can leak data between containers
+  # - Storage driver choice affects security properties
+  #
+  # Best practices:
+  # - Use descriptive but not sensitive volume names
+  # - Implement proper volume access controls
+  # - Regular backup of critical volume data
+  # - Monitor volume usage and access patterns
+  # - Choose appropriate drivers for security requirements
+  #
+  # == Example Usage
+  #
+  #   # Create basic local volume
+  #   CreateVolume.call(
+  #     server_context: context,
+  #     name: "app-data"
+  #   )
+  #
+  #   # Create volume with specific driver
+  #   CreateVolume.call(
+  #     server_context: context,
+  #     name: "shared-storage",
+  #     driver: "nfs"
+  #   )
+  #
+  # @see ListVolumes
+  # @see RemoveVolume
+  # @see Docker::Volume.create
+  # @since 0.1.0
+  class CreateVolume < MCP::Tool
+    description 'Create a Docker volume'
+
+    input_schema(
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Name of the volume'
+        },
+        driver: {
+          type: 'string',
+          description: 'Driver to use (default: local)'
+        }
+      },
+      required: ['name']
+    )
+
+    # Create a new Docker volume for persistent data storage.
+    #
+    # This method creates a named Docker volume that can be used by containers
+    # for persistent data storage. The volume will survive container deletion
+    # and can be shared between multiple containers.
+    #
+    # @param name [String] name for the new volume
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param driver [String] volume driver to use (default: "local")
+    #
+    # @return [MCP::Tool::Response] volume creation results
+    #
+    # @raise [Docker::Error::ConflictError] if volume name already exists
+    # @raise [StandardError] for other volume creation failures
+    #
+    # @example Create application data volume
+    #   response = CreateVolume.call(
+    #     server_context: context,
+    #     name: "webapp-data"
+    #   )
+    #
+    # @example Create NFS volume
+    #   response = CreateVolume.call(
+    #     server_context: context,
+    #     name: "shared-files",
+    #     driver: "nfs"
+    #   )
+    #
+    # @see Docker::Volume.create
+    def self.call(name:, server_context:, driver: 'local')
+      options = {
+        'Name' => name,
+        'Driver' => driver
+      }
+
+      Docker::Volume.create(name, options)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Volume #{name} created successfully"
+                              }])
+    rescue Docker::Error::ConflictError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Volume #{name} already exists"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error creating volume: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/exec_container.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for executing commands inside running Docker containers.
+  #
+  # This tool provides the ability to execute arbitrary commands inside running
+  # Docker containers, with full control over execution environment including
+  # working directory, user context, environment variables, and stdin input.
+  #
+  # == ⚠️ CRITICAL SECURITY WARNING ⚠️
+  #
+  # This tool is EXTREMELY DANGEROUS as it allows arbitrary command execution
+  # within Docker containers. This can be used to:
+  # - Execute malicious code inside containers
+  # - Access sensitive data within container filesystems
+  # - Escalate privileges if container is poorly configured
+  # - Perform lateral movement within containerized environments
+  # - Exfiltrate data from applications
+  #
+  # ONLY use this tool in trusted environments with proper security controls:
+  # - Ensure containers run with minimal privileges
+  # - Use read-only filesystems where possible
+  # - Implement proper network segmentation
+  # - Monitor and audit all command executions
+  # - Never expose this tool to untrusted clients
+  #
+  # == Features
+  #
+  # - Execute commands with custom working directory
+  # - Run commands as specific users
+  # - Set custom environment variables
+  # - Provide stdin input to commands
+  # - Configurable timeout protection
+  # - Comprehensive error handling
+  # - Separate stdout/stderr capture
+  #
+  # == Example Usage
+  #
+  #   # Simple command execution
+  #   ExecContainer.call(
+  #     server_context: context,
+  #     id: "my-container",
+  #     cmd: "ls -la /app"
+  #   )
+  #
+  #   # Advanced execution with custom environment
+  #   ExecContainer.call(
+  #     server_context: context,
+  #     id: "web-server",
+  #     cmd: "python manage.py migrate",
+  #     working_dir: "/app",
+  #     user: "appuser",
+  #     env: "DJANGO_ENV=production,DEBUG=false",
+  #     timeout: 120
+  #   )
+  #
+  # @see Docker::Container#exec
+  # @since 0.1.0
+  class ExecContainer < MCP::Tool
+    description 'Execute a command inside a running Docker container. ' \
+                'WARNING: This provides arbitrary command execution within the container. ' \
+                'Ensure proper security measures are in place.'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Container ID or name'
+        },
+        cmd: {
+          type: 'string',
+          description: 'Command to execute (e.g., "ls -la /app" or "python script.py")'
+        },
+        working_dir: {
+          type: 'string',
+          description: 'Working directory for the command (optional)'
+        },
+        user: {
+          type: 'string',
+          description: 'User to run the command as (optional, e.g., "1000" or "username")'
+        },
+        env: {
+          type: 'string',
+          description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)'
+        },
+        stdin: {
+          type: 'string',
+          description: 'Input to send to the command via stdin (optional)'
+        },
+        timeout: {
+          type: 'integer',
+          description: 'Timeout in seconds (optional, default: 60)'
+        }
+      },
+      required: %w[id cmd]
+    )
+
+    # Execute a command inside a running Docker container.
+    #
+    # This method provides comprehensive command execution capabilities within
+    # Docker containers, including advanced features like custom user context,
+    # environment variables, working directory, and stdin input.
+    #
+    # The command is parsed using shell-like syntax with support for quoted
+    # arguments. Output is captured separately for stdout and stderr, and
+    # the exit code is reported.
+    #
+    # @param id [String] container ID or name to execute command in
+    # @param cmd [String] command to execute (shell-parsed into arguments)
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param working_dir [String, nil] working directory for command execution
+    # @param user [String, nil] user to run command as (username or UID)
+    # @param env [String, nil] environment variables as comma-separated KEY=VALUE pairs
+    # @param stdin [String, nil] input to send to command via stdin
+    # @param timeout [Integer] maximum execution time in seconds (default: 60)
+    #
+    # @return [MCP::Tool::Response] execution results including stdout, stderr, and exit code
+    #
+    # @raise [Docker::Error::NotFoundError] if container doesn't exist
+    # @raise [Docker::Error::TimeoutError] if execution exceeds timeout
+    # @raise [StandardError] for other execution failures
+    #
+    # @example Basic command execution
+    #   response = ExecContainer.call(
+    #     server_context: context,
+    #     id: "web-container",
+    #     cmd: "nginx -t"
+    #   )
+    #
+    # @example Advanced execution with environment
+    #   response = ExecContainer.call(
+    #     server_context: context,
+    #     id: "app-container",
+    #     cmd: "bundle exec rails console",
+    #     working_dir: "/app",
+    #     user: "rails",
+    #     env: "RAILS_ENV=production,DEBUG=true",
+    #     timeout: 300
+    #   )
+    #
+    # @see Docker::Container#exec
+    def self.call(id:, cmd:, server_context:, working_dir: nil, user: nil,
+                  env: nil, stdin: nil, timeout: 60)
+      container = Docker::Container.get(id)
+
+      # Parse command string into array
+      # Simple shell-like parsing: split on spaces but respect quoted strings
+
+      cmd_array = Shellwords.split(cmd)
+
+      # Parse environment variables from comma-separated string to array
+      env_array = nil
+      env_array = env.split(',').map(&:strip) if env && !env.empty?
+
+      # Build exec options
+      exec_options = {
+        'Cmd' => cmd_array,
+        'AttachStdout' => true,
+        'AttachStderr' => true
+      }
+      exec_options['WorkingDir'] = working_dir if working_dir
+      exec_options['User'] = user if user
+      exec_options['Env'] = env_array if env_array
+      exec_options['AttachStdin'] = true if stdin
+
+      # Execute the command
+      stdout_data = []
+      stderr_data = []
+      exit_code = nil
+
+      begin
+        # Use container.exec which returns [stdout, stderr, exit_code]
+        result = if stdin
+                   container.exec(cmd_array, stdin: StringIO.new(stdin), wait: timeout)
+                 else
+                   container.exec(cmd_array, wait: timeout)
+                 end
+
+        stdout_data = result[0]
+        stderr_data = result[1]
+        exit_code = result[2]
+      rescue Docker::Error::TimeoutError
+        return MCP::Tool::Response.new([{
+                                         type: 'text',
+                                         text: "Command execution timed out after #{timeout} seconds"
+                                       }])
+      end
+
+      # Format response
+      response_text = "Command executed in container #{id}\n"
+      response_text += "Exit code: #{exit_code}\n\n"
+
+      if stdout_data && !stdout_data.empty?
+        stdout_str = stdout_data.join
+        response_text += "STDOUT:\n#{stdout_str}\n" unless stdout_str.strip.empty?
+      end
+
+      if stderr_data && !stderr_data.empty?
+        stderr_str = stderr_data.join
+        response_text += "\nSTDERR:\n#{stderr_str}\n" unless stderr_str.strip.empty?
+      end
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: response_text.strip
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container #{id} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error executing command: #{e.message}"
+                              }])
+    end
+  end
+end