ruby_llm-docker 0.2.5 → 0.3.0

data/lib/ruby_llm/docker/list_networks.rb

@@ -2,80 +2,58 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for listing Docker networks.
+    # MCP tool for listing Docker networks.
     #
-    # This tool provides functionality to list all Docker networks available on
-    # the system, including built-in networks (bridge, host, none) and custom
-    # user-defined networks. It returns comprehensive information about network
-    # configuration, drivers, and connected containers.
+    # This tool provides comprehensive information about all Docker networks
+    # configured on the system. It returns detailed network configuration
+    # including IPAM settings, connected containers, and network drivers.
     #
     # == Features
     #
-    # - List all Docker networks on the system
-    # - Comprehensive network metadata
-    # - No configuration required
-    # - Read-only operation
-    # - Includes built-in and custom networks
+    # - Lists all Docker networks (built-in and custom)
+    # - Provides detailed network configuration
+    # - Shows IPAM (IP Address Management) settings
+    # - Displays connected containers
+    # - Includes driver information and options
+    # - Reports network scope and capabilities
     #
-    # == Network Information Included
+    # == Security Considerations
     #
-    # The response typically includes:
-    # - **Network ID**: Unique identifier for the network
-    # - **Name**: Human-readable network name
-    # - **Driver**: Network driver (bridge, host, overlay, etc.)
-    # - **Scope**: Network scope (local, global, swarm)
-    # - **IPAM**: IP Address Management configuration
-    # - **Connected Containers**: Containers attached to the network
-    # - **Options**: Driver-specific configuration options
+    # Network information can be sensitive as it reveals:
+    # - **Network Topology**: Internal network architecture
+    # - **IP Addressing**: Subnet configurations and ranges
+    # - **Container Connectivity**: Service interconnections
+    # - **Network Isolation**: Security boundary configurations
     #
-    # == Security Considerations
+    # Restrict access to this tool in production environments.
     #
-    # This is a read-only operation that reveals network topology:
-    # - Exposes network architecture and segmentation
-    # - Shows container connectivity patterns
-    # - May reveal internal network design
-    # - Could aid in network reconnaissance
+    # == Return Format
     #
-    # While generally safe, consider access control:
-    # - Limit exposure of network topology information
-    # - Be cautious with sensitive network names
-    # - Monitor for unauthorized network discovery
-    # - Consider network isolation requirements
+    # Returns an array of network objects with comprehensive metadata:
+    # - Network names and IDs
+    # - Driver types and configurations
+    # - IPAM settings and subnet information
+    # - Connected container details
+    # - Network options and labels
+    # - Scope and capability flags
     #
     # == Example Usage
     #
-    #   # List all networks
-    #   ListNetworks.call(server_context: context)
+    #   networks = ListNetworks.call(server_context: context)
+    #   networks.each do |network|
+    #     puts "#{network['Name']}: #{network['Driver']}"
+    #   end
     #
-    # @example Usage in network management
-    #   # Get available networks before container creation
-    #   networks_response = ListNetworks.call(server_context: context)
-    #   # Use network information to select appropriate networks
-    #
-    # @see CreateNetwork
-    # @see RemoveNetwork
-    # @see Docker::Network.all
+    # @see ::Docker::Network.all
     # @since 0.1.0
-    class ListNetworks < RubyLLM::Tool
+    LIST_NETWORKS_DEFINITION = ToolForge.define(:list_networks) do
       description 'List Docker networks'
 
-      # List all Docker networks available on the system.
-      #
-      # This method retrieves information about all Docker networks, including
-      # both system-created networks (bridge, host, none) and user-defined
-      # custom networks. The information includes comprehensive metadata for
-      # each network.
-      #
-      # @return [String] comprehensive network information
-      #
-      # @example List all networks
-      #   response = tool.execute
-      #   # Returns detailed info for all Docker networks
-      #
-      # @see Docker::Network.all
-      def execute
-        ::Docker::Network.all.map(&:info).to_s
+      execute do
+        ::Docker::Network.all.map(&:info)
       end
     end
+
+    ListNetworks = LIST_NETWORKS_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/list_volumes.rb

@@ -2,87 +2,58 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for listing Docker volumes.
+    # MCP tool for listing Docker volumes.
     #
-    # This tool provides functionality to list all Docker volumes on the system,
-    # including both named volumes and anonymous volumes. It returns comprehensive
-    # information about volume configuration, drivers, mount points, and usage.
+    # This tool provides comprehensive information about all Docker volumes
+    # configured on the system. It returns detailed volume metadata including
+    # mount points, drivers, usage statistics, and associated containers.
     #
     # == Features
     #
-    # - List all Docker volumes on the system
-    # - Comprehensive volume metadata
-    # - No configuration required
-    # - Read-only operation
-    # - Includes named and anonymous volumes
+    # - Lists all Docker volumes (named and anonymous)
+    # - Provides detailed volume metadata
+    # - Shows mount points and storage locations
+    # - Displays driver information and options
+    # - Includes creation timestamps and labels
+    # - Reports volume scope and capabilities
     #
-    # == Volume Information Included
-    #
-    # The response typically includes:
-    # - **Volume Name**: Unique identifier for the volume
-    # - **Driver**: Volume driver (local, nfs, etc.)
-    # - **Mountpoint**: Physical location on host filesystem
-    # - **Labels**: User-defined metadata labels
-    # - **Options**: Driver-specific configuration options
-    # - **Scope**: Volume scope (local, global)
-    # - **CreatedAt**: Volume creation timestamp
-    #
-    # == Volume Types
+    # == Security Considerations
     #
-    # Docker manages different types of volumes:
-    # - **Named Volumes**: User-created persistent volumes
-    # - **Anonymous Volumes**: Automatically created temporary volumes
-    # - **Bind Mounts**: Direct host directory mounts (not shown in volume list)
-    # - **tmpfs Mounts**: Memory-based temporary filesystems (not shown)
+    # Volume information can reveal sensitive details about:
+    # - **Data Storage**: Persistent data locations and structures
+    # - **File System Access**: Mount points and storage paths
+    # - **Container Dependencies**: Volume usage patterns
+    # - **Data Persistence**: Backup and recovery points
     #
-    # == Security Considerations
+    # Monitor access to this tool and implement appropriate controls.
     #
-    # This is a read-only operation that reveals storage information:
-    # - Exposes data storage architecture
-    # - Shows volume naming patterns
-    # - May reveal application data locations
-    # - Could aid in data discovery attacks
+    # == Return Format
     #
-    # While generally safe, consider access control:
-    # - Limit exposure of volume inventory
-    # - Be cautious with sensitive volume names
-    # - Monitor for unauthorized volume discovery
-    # - Consider data classification implications
+    # Returns an array of volume objects with comprehensive metadata:
+    # - Volume names and mount points
+    # - Driver types and configurations
+    # - Creation timestamps
+    # - Labels and options
+    # - Scope information
+    # - Storage usage details
     #
     # == Example Usage
     #
-    #   # List all volumes
-    #   ListVolumes.call(server_context: context)
-    #
-    # @example Usage in data management
-    #   # Get available volumes before container creation
-    #   volumes_response = ListVolumes.call(server_context: context)
-    #   # Use volume information to select appropriate storage
+    #   volumes = ListVolumes.call(server_context: context)
+    #   volumes.each do |volume|
+    #     puts "#{volume['Name']}: #{volume['Mountpoint']}"
+    #   end
     #
-    # @see CreateVolume
-    # @see RemoveVolume
-    # @see Docker::Volume.all
+    # @see ::Docker::Volume.all
     # @since 0.1.0
-    class ListVolumes < RubyLLM::Tool
+    LIST_VOLUMES_DEFINITION = ToolForge.define(:list_volumes) do
       description 'List Docker volumes'
 
-      # List all Docker volumes available on the system.
-      #
-      # This method retrieves information about all Docker volumes, including
-      # both named volumes created by users and anonymous volumes created
-      # automatically by containers. The information includes comprehensive
-      # metadata for each volume.
-      #
-      # @return [String] comprehensive volume information
-      #
-      # @example List all volumes
-      #   response = tool.execute
-      #   # Returns detailed info for all Docker volumes
-      #
-      # @see Docker::Volume.all
-      def execute
-        ::Docker::Volume.all.map(&:info).to_s
+      execute do
+        ::Docker::Volume.all.map(&:info)
       end
     end
+
+    ListVolumes = LIST_VOLUMES_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/pull_image.rb

@@ -2,7 +2,7 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for pulling Docker images from registries.
+    # MCP tool for pulling Docker images from registries.
     #
     # This tool provides the ability to download Docker images from Docker
     # registries (like Docker Hub) to the local system. It supports flexible
@@ -26,7 +26,7 @@ module RubyLLM
     # - **Supply Chain Attacks**: Legitimate-looking images may be malicious
     # - **Resource Consumption**: Large images can consume significant disk space
     #
-    # Security recommendations:
+    # **Security Recommendations**:
     # - Only pull images from trusted registries and publishers
     # - Verify image signatures when available
     # - Scan pulled images for vulnerabilities
@@ -42,67 +42,41 @@ module RubyLLM
     # - If no tag specified, default to "latest"
     # - Supports all Docker tag conventions
     #
+    # == Parameters
+    #
+    # - **from_image**: Image name to pull (required, e.g., "ubuntu" or "ubuntu:22.04")
+    # - **tag**: Tag to pull (optional, defaults to "latest" if not specified in from_image)
+    #
     # == Example Usage
     #
     #   # Pull latest version
-    #   PullImage.call(
+    #   response = PullImage.call(
     #     server_context: context,
     #     from_image: "nginx"
     #   )
     #
     #   # Pull specific version
-    #   PullImage.call(
+    #   response = PullImage.call(
     #     server_context: context,
-    #     from_image: "postgres:13"
+    #     from_image: "postgres",
+    #     tag: "13.8"
     #   )
     #
-    #   # Pull with separate tag parameter
-    #   PullImage.call(
-    #     server_context: context,
-    #     from_image: "redis",
-    #     tag: "7-alpine"
-    #   )
-    #
-    # @see BuildImage
-    # @see ListImages
-    # @see Docker::Image.create
+    # @see ::Docker::Image.create
     # @since 0.1.0
-    class PullImage < RubyLLM::Tool
+    PULL_IMAGE_DEFINITION = ToolForge.define(:pull_image) do
       description 'Pull a Docker image'
 
-      param :from_image, desc: 'Image name to pull (e.g., "ubuntu" or "ubuntu:22.04")'
-      param :tag, desc: 'Tag to pull (optional, defaults to "latest" if not specified in from_image)', required: false
+      param :from_image,
+            type: :string,
+            description: 'Image name to pull (e.g., "ubuntu" or "ubuntu:22.04")'
+
+      param :tag,
+            type: :string,
+            description: 'Tag to pull (optional, defaults to "latest" if not specified in from_image)',
+            required: false
 
-      # Pull a Docker image from a registry.
-      #
-      # This method downloads the specified image from a Docker registry to
-      # the local system. It handles tag resolution automatically and provides
-      # feedback on the pull operation status.
-      #
-      # @param from_image [String] image name (may include registry and tag)
-      # @param server_context [Object] RubyLLM context (unused but required)
-      # @param tag [String, nil] specific tag to pull (overrides tag in from_image)
-      #
-      # @return [RubyLLM::Tool::Response] pull operation results with image ID
-      #
-      # @raise [Docker::Error::NotFoundError] if image doesn't exist in registry
-      # @raise [StandardError] for network or authentication failures
-      #
-      # @example Pull official image
-      #   response = PullImage.call(
-      #     server_context: context,
-      #     from_image: "ubuntu:22.04"
-      #   )
-      #
-      # @example Pull from custom registry
-      #   response = PullImage.call(
-      #     server_context: context,
-      #     from_image: "registry.example.com/myapp",
-      #     tag: "v1.0"
-      #   )
-      #
-      # @see Docker::Image.create
-      def execute(from_image:, tag: nil)
+      execute do |from_image:, tag: nil|
         # If tag is provided separately, append it to from_image
         # If from_image already has a tag (contains :), use as-is
         # Otherwise default to :latest
@@ -123,5 +97,7 @@ module RubyLLM
         "Error pulling image: #{e.message}"
       end
     end
+
+    PullImage = PULL_IMAGE_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/push_image.rb

@@ -1,153 +1,124 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'open3'
-
 module RubyLLM
   module Docker
-    # RubyLLM tool for pushing Docker images to registries.
+    # 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 < RubyLLM::Tool
+    PUSH_IMAGE_DEFINITION = ToolForge.define(:push_image) do
       description 'Push a Docker image'
 
-      param :name, type: :string, desc: 'Image name or ID to push'
-      param :tag, type: :string, desc: 'Tag to push (optional, pushes all tags if not specified)',
-                  required: false
-      param :repo_tag, type: :string, desc: 'Full repo:tag to push (e.g., "registry/repo:tag") (optional)',
-                       required: false
+      param :name,
+            type: :string,
+            description: 'Image name or ID to push'
+
+      param :tag,
+            type: :string,
+            description: 'Tag to push (optional, pushes all tags if not specified)',
+            required: false
 
-      # 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] RubyLLM context (unused but required)
-      # @param tag [String, nil] specific tag to push
-      # @param repo_tag [String, nil] complete repository:tag specification
-      #
-      # @return [RubyLLM::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 = tool.execute(
-      #     name: "internal-registry.com/team/service",
-      #     tag: "latest"
-      #   )
-      #
-      # @see Docker::Image.get
-      def execute(name:, tag: nil, repo_tag: nil)
+      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 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 "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?
           "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?
-
           "Error pushing image: #{error_msg}"
         end
       rescue StandardError => e
         "Error pushing image: #{e.message}"
       end
     end
+
+    PushImage = PUSH_IMAGE_DEFINITION.to_ruby_llm_tool
   end
 end