docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/push_image.rb

@@ -1,179 +1,122 @@
 # 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.
+  # This tool provides the ability to upload Docker images to Docker
+  # registries such as Docker Hub, private registries, or cloud-based
+  # container registries. It supports various push configurations and
+  # authentication scenarios.
   #
   # == 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
+  # - Push images to any Docker registry
+  # - Support for tagged and untagged pushes
+  # - Registry authentication integration
+  # - Comprehensive error handling and validation
+  # - Multi-registry support
+  # - Progress tracking and status reporting
+  # - Registry namespace validation
   #
-  # == ⚠️ Security Considerations ⚠️
+  # == 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
+  # - **Image Integrity**: Pushed images become publicly accessible
+  # - **Supply Chain Risk**: Malicious images can be distributed
+  # - **Registry Security**: Vulnerable registries can be compromised
+  # - **Network Exposure**: Push operations traverse networks
+  # - **Access Control**: Improper permissions can lead to unauthorized access
   #
-  # Critical security measures:
-  # - Verify registry authentication and authorization
-  # - Scan images for secrets before pushing
-  # - Use private registries for sensitive applications
+  # **Security Recommendations**:
+  # - Use secure registry authentication
+  # - Scan images for vulnerabilities before pushing
   # - Implement image signing and verification
-  # - Monitor registry access and downloads
-  # - Regularly audit pushed image contents
+  # - Use private registries for sensitive images
+  # - Monitor registry access and usage
+  # - Implement proper RBAC for registry operations
+  # - Validate image content before distribution
   #
-  # == Registry Requirements
+  # == Parameters
   #
-  # 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
+  # - **name**: Image name or ID to push (required)
+  # - **tag**: Tag to push (optional, pushes all tags if not specified)
+  # - **repo_tag**: Full repo:tag to push (optional, e.g., "registry/repo:tag")
   #
   # == Example Usage
   #
   #   # Push to Docker Hub
-  #   PushImage.call(
+  #   response = PushImage.call(
   #     server_context: context,
-  #     name: "myusername/myapp",
-  #     tag: "v1.0"
+  #     name: "username/myapp",
+  #     tag: "v1.0.0"
   #   )
   #
   #   # Push to private registry
-  #   PushImage.call(
+  #   response = PushImage.call(
   #     server_context: context,
-  #     name: "registry.company.com/team/app",
-  #     tag: "latest"
+  #     name: "myapp",
+  #     repo_tag: "registry.company.com/team/myapp:latest"
   #   )
   #
-  #   # Push with full repo specification
-  #   PushImage.call(
+  #   # Push all tags
+  #   response = PushImage.call(
   #     server_context: context,
-  #     name: "myapp",
-  #     repo_tag: "myregistry.com/myuser/myapp:v2.0"
+  #     name: "username/myapp"
   #   )
   #
-  # @see PullImage
-  # @see TagImage
-  # @see BuildImage
+  # @see Docker CLI push command
   # @since 0.1.0
-  class PushImage < MCP::Tool
+  PUSH_IMAGE_DEFINITION = ToolForge.define(:push_image) do
     description 'Push a Docker image'
 
-    input_schema(
-      properties: {
-        name: {
-          type: 'string',
+    param :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)
+    param :tag,
+          type: :string,
+          description: 'Tag to push (optional, pushes all tags if not specified)',
+          required: false
+
+    param :repo_tag,
+          type: :string,
+          description: 'Full repo:tag to push (e.g., "registry/repo:tag") (optional)',
+          required: false
+
+    execute do |name:, 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
-                                       }])
+        next 'Error: Image name must include registry/username ' \
+             "(e.g., 'username/#{name}'). Local images cannot be " \
+             'pushed without a registry prefix.'
       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"
-                                       }])
+        next "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"
-                                }])
+        "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}"
-                                }])
+        "Error pushing image: #{error_msg}"
       end
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error pushing image: #{e.message}"
-                              }])
+      "Error pushing image: #{e.message}"
     end
   end
+
+  PushImage = PUSH_IMAGE_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/recreate_container.rb

@@ -1,123 +1,79 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for recreating Docker containers with the same configuration.
+  # MCP tool for recreating Docker containers.
   #
-  # 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.
+  # This tool provides a complete container recreation process that stops
+  # the existing container, removes it, and creates a new container with
+  # the same configuration. This is useful for applying image updates,
+  # clearing container state, or resolving container corruption 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
+  # - Complete container recreation with preserved configuration
+  # - Automatic stop, remove, and recreate sequence
+  # - Preserves original container configuration and settings
+  # - Configurable stop timeout for graceful shutdown
+  # - Handles both running and stopped containers
+  # - Maintains container networking and volume configurations
   #
-  # == 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)
+  # == Security Considerations
   #
-  # == ⚠️ Data Loss Warning ⚠️
+  # Container recreation involves several security considerations:
+  # - **Service Downtime**: Temporary service interruption during recreation
+  # - **Data Loss**: Container file system changes are lost (volumes preserved)
+  # - **Resource Allocation**: New container may have different resource usage
+  # - **Network Reconfiguration**: IP addresses may change
+  # - **State Reset**: Application state within container is lost
   #
-  # **DESTRUCTIVE OPERATION - DATA LOSS POSSIBLE**
+  # Plan recreations carefully and coordinate with dependent services.
   #
-  # 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
+  # == Parameters
   #
-  # == Security Considerations
+  # - **id**: Container ID or name to recreate (required)
+  # - **timeout**: Seconds to wait before killing container when stopping (optional, default: 10)
   #
-  # - Original configuration is preserved exactly
-  # - Sensitive environment variables are maintained
-  # - Port mappings and volume mounts are restored
-  # - Network access patterns remain the same
+  # == Process Flow
   #
-  # Ensure original configuration is still secure:
-  # - Review exposed ports and volumes
-  # - Validate environment variables
-  # - Check image security updates
-  # - Verify network policies
+  # 1. Inspect existing container to capture configuration
+  # 2. Stop the running container (if running)
+  # 3. Remove the stopped container
+  # 4. Create new container with captured configuration
+  # 5. Return new container information
   #
   # == Example Usage
   #
   #   # Recreate with default timeout
-  #   RecreateContainer.call(
+  #   response = RecreateContainer.call(
   #     server_context: context,
   #     id: "web-server"
   #   )
   #
-  #   # Recreate with longer stop timeout
-  #   RecreateContainer.call(
+  #   # Recreate with extended timeout
+  #   response = RecreateContainer.call(
   #     server_context: context,
   #     id: "database",
   #     timeout: 30
   #   )
   #
-  # @see CreateContainer
-  # @see StopContainer
-  # @see RemoveContainer
+  # @see Docker::Container#stop
+  # @see Docker::Container#remove
   # @see Docker::Container.create
   # @since 0.1.0
-  class RecreateContainer < MCP::Tool
+  RECREATE_CONTAINER_DEFINITION = ToolForge.define(:recreate_container) do
     description 'Recreate a Docker container (stops, removes, and recreates with same configuration)'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :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)
+    param :timeout,
+          type: :integer,
+          description: 'Seconds to wait before killing the container when stopping (default: 10)',
+          required: false,
+          default: 10
+
+    execute do |id:, timeout: 10|
       # Get the existing container
       old_container = Docker::Container.get(id)
       config = old_container.json
@@ -149,20 +105,13 @@ module DockerMCP
       # 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}"
-                              }])
+      "Container #{id} recreated successfully. New ID: #{new_container.id}"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container #{id} not found"
-                              }])
+      "Container #{id} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error recreating container: #{e.message}"
-                              }])
+      "Error recreating container: #{e.message}"
     end
   end
+
+  RecreateContainer = RECREATE_CONTAINER_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/remove_container.rb

@@ -3,140 +3,88 @@
 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.
+  # This tool permanently removes a Docker container from the system,
+  # including its file system, configuration, and metadata. This is a
+  # destructive operation that cannot be undone. The container must
+  # be stopped before removal unless force is specified.
   #
   # == Features
   #
-  # - Remove stopped containers safely
-  # - Force removal of running containers
+  # - Permanent container removal from system
+  # - Supports forced removal of running containers
   # - Optional removal of associated volumes
-  # - Comprehensive error handling
-  # - Works with containers by ID or name
+  # - Handles container identification by ID or name
+  # - Provides comprehensive error handling
+  # - Frees all associated system resources
   #
-  # == Data Loss Warning
-  #
-  # ⚠️ **DESTRUCTIVE OPERATION** ⚠️
+  # == Security Considerations
   #
-  # 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
+  # Container removal is a destructive operation with implications:
+  # - **Data Loss**: Permanently destroys container file system
+  # - **Configuration Loss**: Removes container settings and metadata
+  # - **Service Disruption**: Eliminates containerized services
+  # - **Resource Recovery**: Frees storage, memory, and system resources
+  # - **Audit Trail**: May remove forensic evidence if needed
   #
-  # == Security Considerations
+  # Implement proper backup and approval workflows for production systems.
   #
-  # - 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
+  # == Parameters
   #
-  # Best practices:
-  # - Stop containers gracefully before removal
-  # - Backup important data before removing
-  # - Verify volume dependencies before volume removal
-  # - Use force removal only when necessary
+  # - **id**: Container ID or name (required)
+  #   - Accepts full container IDs
+  #   - Accepts short container IDs (first 12+ characters)
+  #   - Accepts custom container names
+  # - **force**: Force removal of running container (optional, default: false)
+  # - **volumes**: Remove associated volumes (optional, default: false)
   #
   # == Example Usage
   #
   #   # Remove stopped container
-  #   RemoveContainer.call(
+  #   response = RemoveContainer.call(
   #     server_context: context,
-  #     id: "old-container"
+  #     id: "old-web-server"
   #   )
   #
   #   # Force remove running container with volumes
-  #   RemoveContainer.call(
+  #   response = RemoveContainer.call(
   #     server_context: context,
   #     id: "problematic-container",
   #     force: true,
   #     volumes: true
   #   )
   #
-  # @see StopContainer
-  # @see CreateContainer
-  # @see Docker::Container#delete
+  # @see Docker::Container#remove
   # @since 0.1.0
-  class RemoveContainer < MCP::Tool
+  REMOVE_CONTAINER_DEFINITION = ToolForge.define(:remove_container) do
     description 'Remove a Docker container'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :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)
+    param :force,
+          type: :boolean,
+          description: 'Force removal of running container (default: false)',
+          required: false,
+          default: false
+
+    param :volumes,
+          type: :boolean,
+          description: 'Remove associated volumes (default: false)',
+          required: false,
+          default: false
+
+    execute do |id:, 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"
-                              }])
+      "Container #{id} removed successfully"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container #{id} not found"
-                              }])
+      "Container #{id} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error removing container: #{e.message}"
-                              }])
+      "Error removing container: #{e.message}"
     end
   end
+
+  RemoveContainer = REMOVE_CONTAINER_DEFINITION.to_mcp_tool
 end