docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/remove_image.rb

@@ -3,162 +3,96 @@
 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.
+  # This tool provides the ability to delete Docker images from the
+  # local Docker daemon. It supports various removal options including
+  # forced removal and parent image cleanup management.
   #
   # == Features
   #
-  # - Remove images by ID, name, or name:tag
+  # - Remove images by ID, name, or tag
   # - Force removal of images in use
-  # - Control parent image cleanup
+  # - Control untagged parent image cleanup
   # - Comprehensive error handling
+  # - Validation of image existence
   # - 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
+  # Image removal involves important considerations:
+  # - **Data Loss**: Removed images cannot be recovered locally
+  # - **Service Disruption**: Removing images used by running containers
+  # - **Storage Cleanup**: Improper cleanup can leave orphaned layers
+  # - **Registry Impact**: Local removal doesn't affect registry copies
+  # - **Dependency Conflicts**: Force removal can break container dependencies
+  #
+  # **Security Recommendations**:
+  # - Verify image is not in use before removal
+  # - Use force option only when necessary
+  # - Consider impact on running containers
   # - Backup important images before removal
-  # - Use force removal judiciously
-  # - Monitor disk space after removal
-  # - Maintain image inventory documentation
+  # - Monitor disk space after removal operations
+  # - Implement image lifecycle policies
   #
-  # == Removal Options
+  # == Parameters
   #
-  # - **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
+  # - **id**: Image ID, name, or name:tag (required)
+  # - **force**: Force removal of the image (optional, default: false)
+  # - **noprune**: Do not delete untagged parents (optional, default: false)
   #
   # == Example Usage
   #
-  #   # Safe removal of unused image
-  #   RemoveImage.call(
+  #   # Remove specific image
+  #   response = RemoveImage.call(
   #     server_context: context,
-  #     id: "old-app:v1.0"
+  #     id: "myapp:old-version"
   #   )
   #
-  #   # Force removal of image in use
-  #   RemoveImage.call(
+  #   # Force remove image in use
+  #   response = RemoveImage.call(
   #     server_context: context,
-  #     id: "broken-image:latest",
+  #     id: "abc123def456",
   #     force: true
   #   )
   #
-  #   # Remove image but keep parent layers
-  #   RemoveImage.call(
+  #   # Remove without cleaning parent images
+  #   response = RemoveImage.call(
   #     server_context: context,
-  #     id: "temp-build:abc123",
+  #     id: "test-image:latest",
   #     noprune: true
   #   )
   #
-  # @see ListImages
-  # @see BuildImage
   # @see Docker::Image#remove
   # @since 0.1.0
-  class RemoveImage < MCP::Tool
+  REMOVE_IMAGE_DEFINITION = ToolForge.define(:remove_image) do
     description 'Remove a Docker image'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :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)
+    param :force,
+          type: :boolean,
+          description: 'Force removal of the image (default: false)',
+          required: false,
+          default: false
+
+    param :noprune,
+          type: :boolean,
+          description: 'Do not delete untagged parents (default: false)',
+          required: false,
+          default: false
+
+    execute do |id:, 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"
-                              }])
+      "Image #{id} removed successfully"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Image #{id} not found"
-                              }])
+      "Image #{id} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error removing image: #{e.message}"
-                              }])
+      "Error removing image: #{e.message}"
     end
   end
+
+  RemoveImage = REMOVE_IMAGE_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/remove_network.rb

@@ -3,134 +3,80 @@
 module DockerMCP
   # MCP tool for removing Docker networks.
   #
-  # This tool provides the ability to permanently delete Docker networks from
-  # the system. It safely removes custom networks while protecting built-in
-  # system networks from accidental deletion.
+  # This tool provides the ability to delete Docker networks when they
+  # are no longer needed. Network removal helps maintain clean network
+  # configurations and prevents resource leaks.
   #
   # == Features
   #
-  # - Remove custom Docker networks by ID or name
-  # - Protection against removing built-in networks
+  # - Remove networks by ID or name
+  # - Validation of network existence
   # - Comprehensive error handling
-  # - Dependency checking (prevents removal if containers are connected)
+  # - Prevention of removing networks in use
   # - Safe cleanup of network resources
-  #
-  # == ⚠️ Service Disruption Warning ⚠️
-  #
-  # **NETWORK REMOVAL CAN DISRUPT SERVICES**
-  #
-  # Removing networks can cause immediate service disruption:
-  # - Connected containers lose network connectivity
-  # - Inter-container communication is broken
-  # - Services may become unreachable
-  # - Application functionality can be severely impacted
-  # - Network-dependent processes may fail
-  #
-  # == Protected Networks
-  #
-  # Docker protects certain built-in networks from removal:
-  # - **bridge**: Default bridge network
-  # - **host**: Host networking
-  # - **none**: No networking
-  # - **System networks**: Docker-managed networks
+  # - Network dependency checking
   #
   # == Security Considerations
   #
-  # Network removal affects security boundaries:
-  # - Removes network isolation between containers
-  # - May expose containers to unintended networks
-  # - Could impact security segmentation strategies
-  # - Affects network-based access controls
+  # Network removal involves important considerations:
+  # - **Service Disruption**: Removing active networks disconnects containers
+  # - **Data Isolation**: Network removal can affect container communication
+  # - **Resource Cleanup**: Improper removal can leave network artifacts
+  # - **Container Dependencies**: Containers may fail without expected networks
+  # - **Network Policies**: Removal affects security and access policies
   #
-  # Security implications:
-  # - Ensure no critical containers depend on the network
-  # - Verify alternative connectivity exists if needed
-  # - Consider impact on security boundaries
-  # - Monitor for unauthorized network modifications
+  # **Security Recommendations**:
+  # - Verify no containers are connected before removal
+  # - Check for dependent services and applications
+  # - Document network removal in change logs
+  # - Implement network lifecycle management
+  # - Monitor for orphaned network resources
+  # - Use network removal as part of cleanup procedures
   #
-  # Best practices:
-  # - Stop containers before removing their networks
-  # - Verify network dependencies before removal
-  # - Have rollback plans for critical networks
-  # - Document network removal procedures
-  # - Monitor network connectivity after removal
+  # == Parameters
+  #
+  # - **id**: Network ID or name (required)
   #
   # == Example Usage
   #
-  #   # Remove custom network
-  #   RemoveNetwork.call(
+  #   # Remove network by name
+  #   response = RemoveNetwork.call(
   #     server_context: context,
   #     id: "app-network"
   #   )
   #
-  #   # Remove by network ID
-  #   RemoveNetwork.call(
+  #   # Remove network by ID
+  #   response = RemoveNetwork.call(
   #     server_context: context,
   #     id: "abc123def456"
   #   )
   #
-  # @see CreateNetwork
-  # @see ListNetworks
+  #   # Clean up test networks
+  #   response = RemoveNetwork.call(
+  #     server_context: context,
+  #     id: "test-isolated-network"
+  #   )
+  #
   # @see Docker::Network#delete
   # @since 0.1.0
-  class RemoveNetwork < MCP::Tool
+  REMOVE_NETWORK_DEFINITION = ToolForge.define(:remove_network) do
     description 'Remove a Docker network'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :id,
+          type: :string,
           description: 'Network ID or name'
-        }
-      },
-      required: ['id']
-    )
 
-    # Remove a Docker network from the system.
-    #
-    # This method permanently deletes the specified network. The network
-    # must not have any containers connected to it, and built-in system
-    # networks cannot be removed.
-    #
-    # @param id [String] network ID or name to remove
-    # @param server_context [Object] MCP server context (unused but required)
-    #
-    # @return [MCP::Tool::Response] removal operation results
-    #
-    # @raise [Docker::Error::NotFoundError] if network doesn't exist
-    # @raise [StandardError] for removal failures or dependency conflicts
-    #
-    # @example Remove custom network
-    #   response = RemoveNetwork.call(
-    #     server_context: context,
-    #     id: "frontend-network"
-    #   )
-    #
-    # @example Remove by ID
-    #   response = RemoveNetwork.call(
-    #     server_context: context,
-    #     id: "1a2b3c4d5e6f"
-    #   )
-    #
-    # @see Docker::Network#delete
-    def self.call(id:, server_context:)
+    execute do |id:|
       network = Docker::Network.get(id)
       network.delete
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Network #{id} removed successfully"
-                              }])
+      "Network #{id} removed successfully"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Network #{id} not found"
-                              }])
+      "Network #{id} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error removing network: #{e.message}"
-                              }])
+      "Error removing network: #{e.message}"
     end
   end
+
+  RemoveNetwork = REMOVE_NETWORK_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/remove_volume.rb

@@ -3,144 +3,90 @@
 module DockerMCP
   # MCP tool for removing Docker volumes.
   #
-  # This tool provides the ability to permanently delete Docker volumes from
-  # the system. This is a destructive operation that will permanently delete
-  # all data stored in the volume.
+  # This tool provides the ability to delete Docker volumes when they
+  # are no longer needed. Volume removal is critical for preventing
+  # storage leaks and maintaining clean Docker environments.
   #
   # == Features
   #
-  # - Remove Docker volumes by name
-  # - Force removal option for volumes in use
+  # - Remove volumes by name
+  # - Force removal of volumes in use
+  # - Validation of volume existence
   # - Comprehensive error handling
-  # - Dependency checking (prevents removal if containers are using the volume)
-  # - Safe cleanup of storage resources
-  #
-  # == ⚠️ CRITICAL DATA LOSS WARNING ⚠️
-  #
-  # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
-  #
-  # This operation permanently and irreversibly deletes data:
-  # - **ALL DATA** in the volume is deleted forever
-  # - No recovery possible after deletion
-  # - Applications may lose critical data
-  # - Databases and persistent state are destroyed
-  # - Configuration files and user data are lost
-  # - Operation cannot be undone
-  #
-  # == Volume Dependencies
-  #
-  # Volumes may have active dependencies:
-  # - **Running Containers**: Containers currently using the volume
-  # - **Stopped Containers**: Containers that could be restarted
-  # - **Application Data**: Critical application state and databases
-  # - **User Data**: User-generated content and files
+  # - Safe volume cleanup procedures
+  # - Prevention of accidental data loss
   #
   # == Security Considerations
   #
-  # Volume removal has security implications:
-  # - Sensitive data is not securely wiped
-  # - Data may be recoverable from disk sectors
-  # - Shared volumes may affect multiple applications
-  # - Removal logs may reveal data existence
+  # Volume removal involves critical data considerations:
+  # - **Data Loss**: Removed volumes and their data are permanently deleted
+  # - **Service Disruption**: Removing volumes can break running containers
+  # - **Data Recovery**: Volume data cannot be recovered after removal
+  # - **Container Dependencies**: Applications may fail without expected volumes
+  # - **Storage Cleanup**: Improper removal can leave orphaned data
+  # - **Backup Requirements**: Critical data should be backed up before removal
   #
-  # Critical security measures:
-  # - **Backup critical data** before removal
-  # - Verify no containers depend on the volume
-  # - Consider secure data wiping for sensitive volumes
-  # - Audit volume removal operations
-  # - Monitor for unauthorized volume deletions
+  # **Security Recommendations**:
+  # - Always backup critical data before volume removal
+  # - Verify no containers are using the volume
+  # - Use force option only when absolutely necessary
+  # - Document volume removal in change management
+  # - Implement volume lifecycle and retention policies
+  # - Monitor storage usage after volume removal
+  # - Consider data migration instead of removal
   #
-  # == Force Removal Risks
+  # == Parameters
   #
-  # Force removal bypasses safety checks:
-  # - Removes volumes even if containers are using them
-  # - Can cause immediate application failures
-  # - May corrupt running applications
-  # - Data loss occurs immediately
+  # - **name**: Volume name (required)
+  # - **force**: Force removal of the volume (optional, default: false)
   #
   # == Example Usage
   #
-  #   # Safe removal of unused volume
-  #   RemoveVolume.call(
+  #   # Remove unused volume
+  #   response = RemoveVolume.call(
   #     server_context: context,
-  #     name: "temp-data"
+  #     name: "old-app-data"
   #   )
   #
-  #   # Force removal of volume in use (DANGEROUS)
-  #   RemoveVolume.call(
+  #   # Force remove volume in use
+  #   response = RemoveVolume.call(
   #     server_context: context,
   #     name: "stuck-volume",
   #     force: true
   #   )
   #
-  # @see CreateVolume
-  # @see ListVolumes
+  #   # Clean up test volumes
+  #   response = RemoveVolume.call(
+  #     server_context: context,
+  #     name: "test-data-volume"
+  #   )
+  #
   # @see Docker::Volume#remove
   # @since 0.1.0
-  class RemoveVolume < MCP::Tool
+  REMOVE_VOLUME_DEFINITION = ToolForge.define(:remove_volume) do
     description 'Remove a Docker volume'
 
-    input_schema(
-      properties: {
-        name: {
-          type: 'string',
+    param :name,
+          type: :string,
           description: 'Volume name'
-        },
-        force: {
-          type: 'boolean',
-          description: 'Force removal of the volume (default: false)'
-        }
-      },
-      required: ['name']
-    )
 
-    # Remove a Docker volume permanently from the system.
-    #
-    # This method permanently deletes the specified volume and all data
-    # contained within it. By default, it performs safety checks to prevent
-    # removal of volumes with active container dependencies.
-    #
-    # @param name [String] name of the volume to remove
-    # @param server_context [Object] MCP server context (unused but required)
-    # @param force [Boolean] whether to force removal despite dependencies (default: false)
-    #
-    # @return [MCP::Tool::Response] removal operation results
-    #
-    # @raise [Docker::Error::NotFoundError] if volume doesn't exist
-    # @raise [StandardError] for removal failures or dependency conflicts
-    #
-    # @example Remove unused volume
-    #   response = RemoveVolume.call(
-    #     server_context: context,
-    #     name: "old-cache-data"
-    #   )
-    #
-    # @example Force remove problematic volume
-    #   response = RemoveVolume.call(
-    #     server_context: context,
-    #     name: "corrupted-volume",
-    #     force: true
-    #   )
-    #
-    # @see Docker::Volume#remove
-    def self.call(name:, server_context:, force: false)
+    param :force,
+          type: :boolean,
+          description: 'Force removal of the volume (default: false)',
+          required: false,
+          default: false
+
+    execute do |name:, force: false|
       volume = Docker::Volume.get(name)
       volume.remove(force: force)
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Volume #{name} removed successfully"
-                              }])
+      "Volume #{name} removed successfully"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Volume #{name} not found"
-                              }])
+      "Volume #{name} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error removing volume: #{e.message}"
-                              }])
+      "Error removing volume: #{e.message}"
     end
   end
+
+  RemoveVolume = REMOVE_VOLUME_DEFINITION.to_mcp_tool
 end