ruby_llm-docker 0.2.5 → 0.3.0

data/lib/ruby_llm/docker/create_container.rb

@@ -2,49 +2,52 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for creating Docker containers without starting them.
+    # MCP tool for creating Docker containers.
     #
-    # 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.
+    # This tool creates a new Docker container from a specified image without
+    # starting it. The container is created in a "created" state and can be
+    # started later using the start_container tool. This two-step process
+    # allows for container configuration before execution.
     #
     # == 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
+    # - Creates containers from any available Docker image
+    # - Supports custom container naming
+    # - Configures command execution and environment variables
+    # - Sets up port exposure and network configuration
+    # - Applies advanced host configurations
+    # - Handles container labeling and metadata
     #
     # == 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
+    # Container creation is a powerful operation that can:
+    # - **Resource Allocation**: Consume system resources and storage
+    # - **Network Access**: Create network endpoints and bindings
+    # - **File System Access**: Mount host directories and volumes
+    # - **Security Context**: Run with elevated privileges if configured
     #
-    # 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
+    # Implement proper access controls and resource limits.
+    #
+    # == Parameters
+    #
+    # - **image**: Docker image to use (required)
+    # - **name**: Custom container name (optional)
+    # - **cmd**: Command to execute as space-separated string (optional)
+    # - **env**: Environment variables as comma-separated KEY=VALUE pairs (optional)
+    # - **exposed_ports**: Port exposure configuration as JSON object (optional)
+    # - **host_config**: Advanced host configuration as JSON object (optional)
     #
     # == Example Usage
     #
     #   # Simple container creation
-    #   CreateContainer.call(
+    #   response = CreateContainer.call(
     #     server_context: context,
     #     image: "nginx:latest",
     #     name: "web-server"
     #   )
     #
     #   # Advanced container with configuration
-    #   CreateContainer.call(
+    #   response = CreateContainer.call(
     #     server_context: context,
     #     image: "postgres:13",
     #     name: "database",
@@ -56,76 +59,49 @@ module RubyLLM
     #     }
     #   )
     #
-    # @see RunContainer
-    # @see StartContainer
-    # @see Docker::Container.create
+    # @see ::Docker::Container.create
     # @since 0.1.0
-    class CreateContainer < RubyLLM::Tool
+    CREATE_CONTAINER_DEFINITION = ToolForge.define(:create_container) do
       description 'Create a Docker container'
 
-      param :image, desc: 'Image name to use (e.g., "ubuntu:22.04")'
-      param :name, desc: 'Container name (optional)', required: false
-      param :cmd, desc: 'Command to run (optional)', required: false
+      param :image,
+            type: :string,
+            description: 'Image name to use (e.g., "ubuntu:22.04")'
+
+      param :name,
+            type: :string,
+            description: 'Container name (optional)',
+            required: false
+
+      param :cmd,
+            type: :string,
+            description: 'Command to run as space-separated string (optional, e.g., "npm start" or "python app.py")',
+            required: false
+
       param :env,
-            desc: 'Environment variables as comma-separated KEY=VALUE pairs ' \
-                  '(optional, e.g., "VAR1=value1,VAR2=value2")',
+            type: :string,
+            description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)',
             required: false
-      param :exposed_ports, desc: 'Exposed ports as JSON object (optional)', required: false
-      param :host_config, desc: 'Host configuration including port bindings, volumes, etc. as JSON object (optional)',
-                          required: false
 
-      # 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] RubyLLM context (unused but required)
-      # @param name [String, nil] custom name for the container
-      # @param cmd [String, nil] command to execute in the container
-      # @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 [RubyLLM::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",
-      #     exposed_ports: {"6379/tcp" => {}},
-      #     host_config: {
-      #       "PortBindings" => {"6379/tcp" => [{"HostPort" => "6379"}]},
-      #       "RestartPolicy" => {"Name" => "unless-stopped"}
-      #     }
-      #   )
-      #
-      # @see Docker::Container.create
-      def execute(image:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil)
+      param :exposed_ports,
+            type: :object,
+            description: 'Exposed ports as {"port/protocol": {}} (optional)',
+            required: false
+
+      param :host_config,
+            type: :object,
+            description: 'Host configuration including port bindings, volumes, etc. (optional)',
+            required: false
+
+      execute do |image:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil|
         config = { 'Image' => image }
         config['name'] = name if name
-        config['Cmd'] = cmd if cmd
 
-        # Parse environment variables string into array if provided
-        if env && !env.empty?
-          env_array = env.split(',').map(&:strip).select { |e| e.include?('=') }
-          config['Env'] = env_array unless env_array.empty?
-        end
+        # 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
@@ -142,5 +118,7 @@ module RubyLLM
         "Error creating container: #{e.message}"
       end
     end
+
+    CreateContainer = CREATE_CONTAINER_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/create_network.rb

@@ -2,116 +2,98 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for creating Docker networks.
+    # 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.
+    # This tool provides the ability to create custom Docker networks
+    # for container communication and isolation. Networks enable secure
+    # and controlled communication between containers and external systems.
     #
     # == Features
     #
     # - Create custom Docker networks
-    # - Support for different network drivers
-    # - Duplicate name detection
+    # - Support for multiple network drivers (bridge, overlay, host, etc.)
+    # - Duplicate name checking and validation
+    # - Network configuration and options
     # - 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
+    # - Network isolation and security controls
     #
     # == 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
+    # Network creation involves important security considerations:
+    # - **Network Isolation**: Improper networks can compromise container isolation
+    # - **Traffic Control**: Networks affect inter-container communication
+    # - **External Access**: Bridge networks may expose containers externally
+    # - **Resource Usage**: Networks consume system resources
+    # - **DNS Resolution**: Custom networks affect service discovery
+    # - **Firewall Bypass**: Networks can bypass host firewall rules
     #
-    # 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
+    # **Security Recommendations**:
+    # - Use appropriate network drivers for use case
     # - Implement network segmentation strategies
-    # - Limit container access to necessary networks only
-    # - Monitor network traffic and connections
+    # - Monitor network traffic and usage
+    # - Avoid exposing internal networks externally
+    # - Use network policies for access control
     # - Regular audit of network configurations
     #
+    # == Parameters
+    #
+    # - **name**: Name of the network (required)
+    # - **driver**: Driver to use (optional, default: "bridge")
+    # - **check_duplicate**: Check for networks with duplicate names (optional, default: true)
+    #
+    # == Network Drivers
+    #
+    # - **bridge**: Default driver for single-host networking
+    # - **overlay**: Multi-host networking for Docker Swarm
+    # - **host**: Uses host's network stack directly
+    # - **none**: Disables networking for containers
+    # - **macvlan**: Assigns MAC addresses to containers
+    #
     # == Example Usage
     #
     #   # Create basic bridge network
-    #   CreateNetwork.call(
+    #   response = CreateNetwork.call(
     #     server_context: context,
     #     name: "app-network"
     #   )
     #
-    #   # Create network with specific driver
-    #   CreateNetwork.call(
+    #   # Create overlay network for swarm
+    #   response = CreateNetwork.call(
     #     server_context: context,
-    #     name: "frontend-net",
-    #     driver: "bridge"
+    #     name: "swarm-network",
+    #     driver: "overlay"
     #   )
     #
-    #   # Create without duplicate checking
-    #   CreateNetwork.call(
+    #   # Create network allowing duplicates
+    #   response = CreateNetwork.call(
     #     server_context: context,
-    #     name: "temp-network",
+    #     name: "test-network",
+    #     driver: "bridge",
     #     check_duplicate: false
     #   )
     #
-    # @see ListNetworks
-    # @see RemoveNetwork
-    # @see Docker::Network.create
+    # @see ::Docker::Network.create
     # @since 0.1.0
-    class CreateNetwork < RubyLLM::Tool
+    CREATE_NETWORK_DEFINITION = ToolForge.define(:create_network) do
       description 'Create a Docker network'
 
-      param :name, type: :string, desc: 'Name of the network'
-      param :driver, type: :string, desc: 'Driver to use (default: bridge)', required: false
-      param :check_duplicate, type: :boolean, desc: 'Check for networks with duplicate names (default: true)',
-                              required: false
+      param :name,
+            type: :string,
+            description: 'Name of the network'
 
-      # 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] RubyLLM 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 [RubyLLM::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 = tool.execute(
-      #     name: "high-performance-net",
-      #     driver: "host"
-      #   )
-      #
-      # @see Docker::Network.create
-      def execute(name:, driver: 'bridge', check_duplicate: true)
+      param :driver,
+            type: :string,
+            description: 'Driver to use (default: bridge)',
+            required: false,
+            default: 'bridge'
+
+      param :check_duplicate,
+            type: :boolean,
+            description: 'Check for networks with duplicate names (default: true)',
+            required: false,
+            default: true
+
+      execute do |name:, driver: 'bridge', check_duplicate: true|
         options = {
           'Name' => name,
           'Driver' => driver,
@@ -127,5 +109,7 @@ module RubyLLM
         "Error creating network: #{e.message}"
       end
     end
+
+    CreateNetwork = CREATE_NETWORK_DEFINITION.to_ruby_llm_tool
   end
 end

data/lib/ruby_llm/docker/create_volume.rb

@@ -2,115 +2,91 @@
 
 module RubyLLM
   module Docker
-    # RubyLLM tool for creating Docker volumes.
+    # 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.
+    # This tool provides the ability to create Docker volumes for persistent
+    # data storage. Volumes are essential for maintaining data across container
+    # lifecycles and enabling data sharing between containers.
     #
     # == Features
     #
-    # - Create named persistent volumes
-    # - Support for different volume drivers
+    # - Create named Docker volumes
+    # - Support for multiple volume drivers
+    # - Persistent data storage management
+    # - Volume driver configuration
     # - Comprehensive error handling
-    # - Duplicate name detection
-    # - Flexible storage configuration
+    # - Volume lifecycle management
     #
-    # == 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
+    # == Security Considerations
     #
-    # == Persistence Benefits
+    # Volume creation involves important security considerations:
+    # - **Data Persistence**: Volumes store data beyond container lifecycle
+    # - **Access Control**: Volume permissions affect data security
+    # - **Data Isolation**: Improper volumes can compromise data separation
+    # - **Storage Security**: Volume drivers may have security implications
+    # - **Resource Usage**: Volumes consume disk space and system resources
+    # - **Data Leakage**: Shared volumes can expose sensitive data
     #
-    # 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 Recommendations**:
+    # - Use appropriate volume drivers for security requirements
+    # - Implement proper access controls and permissions
+    # - Monitor volume usage and capacity
+    # - Regular backup of critical volume data
+    # - Audit volume access patterns
+    # - Use encryption for sensitive data volumes
+    # - Implement volume lifecycle policies
     #
-    # == Security Considerations
+    # == Parameters
     #
-    # 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
+    # - **name**: Name of the volume (required)
+    # - **driver**: Driver to use (optional, default: "local")
     #
-    # 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
+    # == Volume Drivers
     #
-    # 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
+    # - **local**: Default driver for local filesystem storage
+    # - **nfs**: Network File System driver for shared storage
+    # - **cifs**: Common Internet File System driver
+    # - **rexray**: REX-Ray driver for cloud storage integration
+    # - **convoy**: Convoy driver for snapshot management
     #
     # == Example Usage
     #
     #   # Create basic local volume
-    #   CreateVolume.call(
+    #   response = CreateVolume.call(
     #     server_context: context,
     #     name: "app-data"
     #   )
     #
     #   # Create volume with specific driver
-    #   CreateVolume.call(
+    #   response = CreateVolume.call(
     #     server_context: context,
     #     name: "shared-storage",
     #     driver: "nfs"
     #   )
     #
-    # @see ListVolumes
-    # @see RemoveVolume
-    # @see Docker::Volume.create
+    #   # Create database volume
+    #   response = CreateVolume.call(
+    #     server_context: context,
+    #     name: "postgres-data",
+    #     driver: "local"
+    #   )
+    #
+    # @see ::Docker::Volume.create
     # @since 0.1.0
-    class CreateVolume < RubyLLM::Tool
+    CREATE_VOLUME_DEFINITION = ToolForge.define(:create_volume) do
       description 'Create a Docker volume'
 
-      param :name, type: :string, desc: 'Name of the volume'
-      param :driver, type: :string, desc: 'Driver to use (default: local)', required: false
+      param :name,
+            type: :string,
+            description: 'Name of the volume'
+
+      param :driver,
+            type: :string,
+            description: 'Driver to use (default: local)',
+            required: false,
+            default: 'local'
 
-      # 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] RubyLLM context (unused but required)
-      # @param driver [String] volume driver to use (default: "local")
-      #
-      # @return [RubyLLM::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 = tool.execute(
-      #     name: "shared-files",
-      #     driver: "nfs"
-      #   )
-      #
-      # @see Docker::Volume.create
-      def execute(name:, driver: 'local')
+      execute do |name:, driver: 'local'|
         options = {
           'Name' => name,
           'Driver' => driver
@@ -125,5 +101,7 @@ module RubyLLM
         "Error creating volume: #{e.message}"
       end
     end
+
+    CreateVolume = CREATE_VOLUME_DEFINITION.to_ruby_llm_tool
   end
 end