docker_mcp 0.0.1 → 0.2.5

data/lib/docker_mcp/push_image.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module DockerMCP
+  # MCP tool for pushing Docker images to registries.
+  #
+  # This tool provides the ability to upload Docker images to Docker registries
+  # such as Docker Hub, private registries, or cloud-based container registries.
+  # It uses the Docker CLI to leverage native credential handling and push
+  # capabilities.
+  #
+  # == Features
+  #
+  # - Push images to any accessible Docker registry
+  # - Flexible image and tag specification
+  # - Native Docker credential handling
+  # - Support for private registries
+  # - Comprehensive error handling
+  # - Validation of registry-compatible names
+  #
+  # == ⚠️ Security Considerations ⚠️
+  #
+  # Pushing images involves significant security risks:
+  # - **Credential Exposure**: Registry credentials may be exposed
+  # - **Data Exfiltration**: Images may contain sensitive application data
+  # - **Intellectual Property**: Source code and binaries may be exposed
+  # - **Supply Chain Risk**: Malicious actors could access pushed images
+  # - **Registry Access**: Unauthorized access to registry accounts
+  #
+  # Critical security measures:
+  # - Verify registry authentication and authorization
+  # - Scan images for secrets before pushing
+  # - Use private registries for sensitive applications
+  # - Implement image signing and verification
+  # - Monitor registry access and downloads
+  # - Regularly audit pushed image contents
+  #
+  # == Registry Requirements
+  #
+  # Images must be properly tagged for registry compatibility:
+  # - Include registry hostname for private registries
+  # - Include username/organization for Docker Hub
+  # - Examples: `username/myapp`, `registry.company.com/team/app`
+  # - Local image names (without `/`) cannot be pushed
+  #
+  # == Example Usage
+  #
+  #   # Push to Docker Hub
+  #   PushImage.call(
+  #     server_context: context,
+  #     name: "myusername/myapp",
+  #     tag: "v1.0"
+  #   )
+  #
+  #   # Push to private registry
+  #   PushImage.call(
+  #     server_context: context,
+  #     name: "registry.company.com/team/app",
+  #     tag: "latest"
+  #   )
+  #
+  #   # Push with full repo specification
+  #   PushImage.call(
+  #     server_context: context,
+  #     name: "myapp",
+  #     repo_tag: "myregistry.com/myuser/myapp:v2.0"
+  #   )
+  #
+  # @see PullImage
+  # @see TagImage
+  # @see BuildImage
+  # @since 0.1.0
+  class PushImage < MCP::Tool
+    description 'Push a Docker image'
+
+    input_schema(
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Image name or ID to push'
+        },
+        tag: {
+          type: 'string',
+          description: 'Tag to push (optional, pushes all tags if not specified)'
+        },
+        repo_tag: {
+          type: 'string',
+          description: 'Full repo:tag to push (e.g., "registry/repo:tag") (optional)'
+        }
+      },
+      required: ['name']
+    )
+
+    # Push a Docker image to a registry.
+    #
+    # This method uploads the specified image to a Docker registry using
+    # the Docker CLI for native credential handling. The image must be
+    # properly tagged for registry compatibility.
+    #
+    # @param name [String] image name or ID to push
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param tag [String, nil] specific tag to push
+    # @param repo_tag [String, nil] complete repository:tag specification
+    #
+    # @return [MCP::Tool::Response] push operation results
+    #
+    # @raise [StandardError] for push failures or authentication issues
+    #
+    # @example Push tagged image to Docker Hub
+    #   response = PushImage.call(
+    #     server_context: context,
+    #     name: "myuser/webapp",
+    #     tag: "v1.2.3"
+    #   )
+    #
+    # @example Push to private registry
+    #   response = PushImage.call(
+    #     server_context: context,
+    #     name: "internal-registry.com/team/service",
+    #     tag: "latest"
+    #   )
+    #
+    # @see Docker::Image.get
+    def self.call(name:, server_context:, tag: nil, repo_tag: nil)
+      # Construct the full image identifier
+      image_identifier = tag ? "#{name}:#{tag}" : name
+
+      # Validate that the image name includes a registry/username
+      # Images without a registry prefix will fail to push to Docker Hub
+      unless name.include?('/') || repo_tag&.include?('/')
+        error_msg = 'Error: Image name must include registry/username ' \
+                    "(e.g., 'username/#{name}'). Local images cannot be " \
+                    'pushed without a registry prefix.'
+        return MCP::Tool::Response.new([{
+                                         type: 'text',
+                                         text: error_msg
+                                       }])
+      end
+
+      # Verify the image exists
+      begin
+        Docker::Image.get(image_identifier)
+      rescue Docker::Error::NotFoundError
+        return MCP::Tool::Response.new([{
+                                         type: 'text',
+                                         text: "Image #{image_identifier} not found"
+                                       }])
+      end
+
+      # Use the Docker CLI to push the image
+      # This way we leverage Docker's native credential handling
+      push_target = repo_tag || image_identifier
+      _, stderr, status = Open3.capture3('docker', 'push', push_target)
+
+      if status.success?
+        MCP::Tool::Response.new([{
+                                  type: 'text',
+                                  text: "Image #{push_target} pushed successfully"
+                                }])
+      else
+        # Extract the error message from stderr
+        error_msg = stderr.strip
+        error_msg = 'Failed to push image' if error_msg.empty?
+
+        MCP::Tool::Response.new([{
+                                  type: 'text',
+                                  text: "Error pushing image: #{error_msg}"
+                                }])
+      end
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error pushing image: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/recreate_container.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for recreating Docker containers with the same configuration.
+  #
+  # This tool provides a convenient way to recreate containers while preserving
+  # their original configuration. It stops and removes the existing container,
+  # then creates a new one with identical settings. This is useful for applying
+  # image updates, clearing container state, or resolving container issues.
+  #
+  # == Features
+  #
+  # - Preserves complete container configuration
+  # - Maintains original name and settings
+  # - Handles running containers gracefully
+  # - Restores running state after recreation
+  # - Configurable stop timeout
+  # - Comprehensive error handling
+  #
+  # == Process Overview
+  #
+  # 1. Retrieve existing container configuration
+  # 2. Stop container gracefully (if running)
+  # 3. Remove the old container
+  # 4. Create new container with identical config
+  # 5. Start new container (if original was running)
+  #
+  # == ⚠️ Data Loss Warning ⚠️
+  #
+  # **DESTRUCTIVE OPERATION - DATA LOSS POSSIBLE**
+  #
+  # This operation can cause permanent data loss:
+  # - Container filesystem changes are lost
+  # - Temporary data and logs are deleted
+  # - Container state is reset completely
+  # - Network connections are interrupted
+  # - Anonymous volumes may be recreated empty
+  #
+  # == Security Considerations
+  #
+  # - Original configuration is preserved exactly
+  # - Sensitive environment variables are maintained
+  # - Port mappings and volume mounts are restored
+  # - Network access patterns remain the same
+  #
+  # Ensure original configuration is still secure:
+  # - Review exposed ports and volumes
+  # - Validate environment variables
+  # - Check image security updates
+  # - Verify network policies
+  #
+  # == Example Usage
+  #
+  #   # Recreate with default timeout
+  #   RecreateContainer.call(
+  #     server_context: context,
+  #     id: "web-server"
+  #   )
+  #
+  #   # Recreate with longer stop timeout
+  #   RecreateContainer.call(
+  #     server_context: context,
+  #     id: "database",
+  #     timeout: 30
+  #   )
+  #
+  # @see CreateContainer
+  # @see StopContainer
+  # @see RemoveContainer
+  # @see Docker::Container.create
+  # @since 0.1.0
+  class RecreateContainer < MCP::Tool
+    description 'Recreate a Docker container (stops, removes, and recreates with same configuration)'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Container ID or name to recreate'
+        },
+        timeout: {
+          type: 'integer',
+          description: 'Seconds to wait before killing the container when stopping (default: 10)'
+        }
+      },
+      required: ['id']
+    )
+
+    # Recreate a Docker container with identical configuration.
+    #
+    # This method performs a complete container recreation cycle while
+    # preserving all configuration settings. The new container will have
+    # the same name, environment, port mappings, volumes, and other
+    # settings as the original.
+    #
+    # @param id [String] container ID (full or short) or container name
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param timeout [Integer] seconds to wait before force killing during stop (default: 10)
+    #
+    # @return [MCP::Tool::Response] recreation results with new container ID
+    #
+    # @raise [Docker::Error::NotFoundError] if container doesn't exist
+    # @raise [StandardError] for recreation failures
+    #
+    # @example Recreate application container
+    #   response = RecreateContainer.call(
+    #     server_context: context,
+    #     id: "my-app"
+    #   )
+    #
+    # @example Recreate database with extended timeout
+    #   response = RecreateContainer.call(
+    #     server_context: context,
+    #     id: "postgres-main",
+    #     timeout: 60  # Allow time for DB shutdown
+    #   )
+    #
+    # @see Docker::Container.get
+    # @see Docker::Container.create
+    def self.call(id:, server_context:, timeout: 10)
+      # Get the existing container
+      old_container = Docker::Container.get(id)
+      config = old_container.json
+
+      # Extract configuration we need to preserve
+      image = config['Config']['Image']
+      name = config['Name']&.delete_prefix('/')
+      cmd = config['Config']['Cmd']
+      env = config['Config']['Env']
+      exposed_ports = config['Config']['ExposedPorts']
+      host_config = config['HostConfig']
+
+      # Stop and remove the old container
+      old_container.stop('timeout' => timeout) if config['State']['Running']
+      old_container.delete
+
+      # Create new container with same config
+      new_config = {
+        'Image' => image,
+        'Cmd' => cmd,
+        'Env' => env,
+        'ExposedPorts' => exposed_ports,
+        'HostConfig' => host_config
+      }
+      new_config['name'] = name if name
+
+      new_container = Docker::Container.create(new_config)
+
+      # Start if the old one was running
+      new_container.start if config['State']['Running']
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container #{id} recreated successfully. New ID: #{new_container.id}"
+                              }])
+    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 recreating container: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/remove_container.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for removing Docker containers.
+  #
+  # This tool provides the ability to permanently delete Docker containers
+  # from the system. It supports both graceful removal of stopped containers
+  # and forced removal of running containers. Optionally, it can also remove
+  # associated anonymous volumes.
+  #
+  # == Features
+  #
+  # - Remove stopped containers safely
+  # - Force removal of running containers
+  # - Optional removal of associated volumes
+  # - Comprehensive error handling
+  # - Works with containers by ID or name
+  #
+  # == Data Loss Warning
+  #
+  # ⚠️ **DESTRUCTIVE OPERATION** ⚠️
+  #
+  # This operation permanently deletes containers and potentially data:
+  # - Container filesystem changes are lost forever
+  # - Running processes are killed immediately (with force)
+  # - Associated volumes may be removed if specified
+  # - Container logs and metadata are deleted
+  # - Operation cannot be undone
+  #
+  # == Security Considerations
+  #
+  # - Forced removal can cause data corruption
+  # - Volume removal may affect other containers
+  # - Running container removal terminates services abruptly
+  # - Sensitive data in container memory is not securely wiped
+  #
+  # Best practices:
+  # - Stop containers gracefully before removal
+  # - Backup important data before removing
+  # - Verify volume dependencies before volume removal
+  # - Use force removal only when necessary
+  #
+  # == Example Usage
+  #
+  #   # Remove stopped container
+  #   RemoveContainer.call(
+  #     server_context: context,
+  #     id: "old-container"
+  #   )
+  #
+  #   # Force remove running container with volumes
+  #   RemoveContainer.call(
+  #     server_context: context,
+  #     id: "problematic-container",
+  #     force: true,
+  #     volumes: true
+  #   )
+  #
+  # @see StopContainer
+  # @see CreateContainer
+  # @see Docker::Container#delete
+  # @since 0.1.0
+  class RemoveContainer < MCP::Tool
+    description 'Remove a Docker container'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Container ID or name'
+        },
+        force: {
+          type: 'boolean',
+          description: 'Force removal of running container (default: false)'
+        },
+        volumes: {
+          type: 'boolean',
+          description: 'Remove associated volumes (default: false)'
+        }
+      },
+      required: ['id']
+    )
+
+    # Remove a Docker container permanently.
+    #
+    # This method deletes a container from the Docker system. By default,
+    # it only removes stopped containers. The force option allows removal
+    # of running containers, and the volumes option removes associated
+    # anonymous volumes.
+    #
+    # @param id [String] container ID (full or short) or container name
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param force [Boolean] whether to force remove running containers (default: false)
+    # @param volumes [Boolean] whether to remove associated volumes (default: false)
+    #
+    # @return [MCP::Tool::Response] removal operation results
+    #
+    # @raise [Docker::Error::NotFoundError] if container doesn't exist
+    # @raise [StandardError] for other removal failures
+    #
+    # @example Remove stopped container
+    #   response = RemoveContainer.call(
+    #     server_context: context,
+    #     id: "finished-job"
+    #   )
+    #
+    # @example Force remove running container
+    #   response = RemoveContainer.call(
+    #     server_context: context,
+    #     id: "stuck-container",
+    #     force: true
+    #   )
+    #
+    # @example Remove container and its volumes
+    #   response = RemoveContainer.call(
+    #     server_context: context,
+    #     id: "temp-container",
+    #     volumes: true
+    #   )
+    #
+    # @see Docker::Container#delete
+    def self.call(id:, server_context:, force: false, volumes: false)
+      container = Docker::Container.get(id)
+      container.delete(force: force, v: volumes)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container #{id} removed successfully"
+                              }])
+    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 removing container: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/remove_image.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for removing Docker images.
+  #
+  # This tool provides the ability to permanently delete Docker images from
+  # the local system to free up disk space and remove unused images. It
+  # supports both regular and forced removal with options for parent image
+  # handling.
+  #
+  # == Features
+  #
+  # - Remove images by ID, name, or name:tag
+  # - Force removal of images in use
+  # - Control parent image cleanup
+  # - Comprehensive error handling
+  # - Safe removal with dependency checking
+  #
+  # == ⚠️ Data Loss Warning ⚠️
+  #
+  # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
+  #
+  # This operation permanently deletes images and associated data:
+  # - Image layers are deleted from disk
+  # - All tags pointing to the image are removed
+  # - Operation cannot be undone
+  # - Dependent containers may become unusable
+  # - Custom modifications to images are lost
+  #
+  # == Dependency Management
+  #
+  # Docker images have complex dependency relationships:
+  # - **Child Images**: Images built FROM this image
+  # - **Parent Images**: Base images this image depends on
+  # - **Running Containers**: Containers using this image
+  # - **Stopped Containers**: Containers that could be restarted
+  #
+  # == Security Considerations
+  #
+  # Image removal affects system security posture:
+  # - Removes potentially vulnerable software
+  # - May break running applications
+  # - Could remove security patches
+  # - Affects rollback capabilities
+  #
+  # Best practices:
+  # - Verify no critical containers depend on the image
+  # - Backup important images before removal
+  # - Use force removal judiciously
+  # - Monitor disk space after removal
+  # - Maintain image inventory documentation
+  #
+  # == Removal Options
+  #
+  # - **Normal Removal**: Only removes if no containers use the image
+  # - **Force Removal**: Removes even if containers depend on it
+  # - **Prune Parents**: Automatically removes unused parent images
+  # - **No Prune**: Keeps parent images even if unused
+  #
+  # == Example Usage
+  #
+  #   # Safe removal of unused image
+  #   RemoveImage.call(
+  #     server_context: context,
+  #     id: "old-app:v1.0"
+  #   )
+  #
+  #   # Force removal of image in use
+  #   RemoveImage.call(
+  #     server_context: context,
+  #     id: "broken-image:latest",
+  #     force: true
+  #   )
+  #
+  #   # Remove image but keep parent layers
+  #   RemoveImage.call(
+  #     server_context: context,
+  #     id: "temp-build:abc123",
+  #     noprune: true
+  #   )
+  #
+  # @see ListImages
+  # @see BuildImage
+  # @see Docker::Image#remove
+  # @since 0.1.0
+  class RemoveImage < MCP::Tool
+    description 'Remove a Docker image'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Image ID, name, or name:tag'
+        },
+        force: {
+          type: 'boolean',
+          description: 'Force removal of the image (default: false)'
+        },
+        noprune: {
+          type: 'boolean',
+          description: 'Do not delete untagged parents (default: false)'
+        }
+      },
+      required: ['id']
+    )
+
+    # Remove a Docker image from the local system.
+    #
+    # This method permanently deletes the specified image from local storage.
+    # By default, it performs safety checks to prevent removal of images with
+    # dependent containers. Force removal bypasses these checks.
+    #
+    # @param id [String] image ID, name, or name:tag to remove
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param force [Boolean] whether to force removal despite dependencies (default: false)
+    # @param noprune [Boolean] whether to preserve parent images (default: false)
+    #
+    # @return [MCP::Tool::Response] removal operation results
+    #
+    # @raise [Docker::Error::NotFoundError] if image doesn't exist
+    # @raise [StandardError] for removal failures or dependency conflicts
+    #
+    # @example Remove unused image
+    #   response = RemoveImage.call(
+    #     server_context: context,
+    #     id: "old-version:1.0"
+    #   )
+    #
+    # @example Force remove problematic image
+    #   response = RemoveImage.call(
+    #     server_context: context,
+    #     id: "corrupted-image",
+    #     force: true
+    #   )
+    #
+    # @example Remove while preserving layers
+    #   response = RemoveImage.call(
+    #     server_context: context,
+    #     id: "temp-image:build-123",
+    #     noprune: true
+    #   )
+    #
+    # @see Docker::Image#remove
+    def self.call(id:, server_context:, force: false, noprune: false)
+      image = Docker::Image.get(id)
+      image.remove(force: force, noprune: noprune)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{id} removed successfully"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{id} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error removing image: #{e.message}"
+                              }])
+    end
+  end
+end