ruby_llm-docker 0.0.1 → 0.3.0

data/examples/test_chat.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test script for RubyLLM Docker Tools
+# This verifies that all Docker tools load correctly and the chat system works
+# without requiring an OpenAI API key or active Docker daemon
+
+require_relative '../lib/ruby_llm/docker'
+
+puts '🧪 Testing Docker Chat functionality...'
+
+# Test 1: Check that all tools are available
+puts "\n1. Testing tool loading:"
+tools = RubyLLM::Docker.all_tools
+puts "✅ Found #{tools.size} Docker tools"
+expected_tools = 22
+if tools.size == expected_tools
+  puts "✅ Expected number of tools loaded (#{expected_tools})"
+else
+  puts "❌ Expected #{expected_tools} tools, but found #{tools.size}"
+  exit 1
+end
+
+# Test 2: Check that all tools are valid RubyLLM::Tool classes
+puts "\n2. Testing tool validity:"
+invalid_tools = tools.reject { |tool| tool < RubyLLM::Tool }
+if invalid_tools.empty?
+  puts '✅ All tools inherit from RubyLLM::Tool'
+else
+  puts "❌ Invalid tools found: #{invalid_tools.map(&:name)}"
+  exit 1
+end
+
+# Test 3: Test helper method (without actually creating a chat)
+puts "\n3. Testing helper methods:"
+begin
+  # Create a mock chat object to test the method exists
+  mock_chat = Object.new
+  def mock_chat.with_tool(_tool_class)
+    self
+  end
+
+  result = RubyLLM::Docker.add_all_tools_to_chat(mock_chat)
+  if result == mock_chat
+    puts '✅ add_all_tools_to_chat method works correctly'
+  else
+    puts '❌ add_all_tools_to_chat method failed'
+    exit 1
+  end
+rescue StandardError => e
+  puts "❌ Helper method test failed: #{e.message}"
+  exit 1
+end
+
+# Test 4: Check that docker_chat.rb file exists and is executable
+puts "\n4. Testing chat script availability:"
+chat_script = File.join(__dir__, 'docker_chat.rb')
+if File.exist?(chat_script)
+  puts '✅ docker_chat.rb exists'
+
+  if File.executable?(chat_script)
+    puts '✅ docker_chat.rb is executable'
+  else
+    puts '⚠️  docker_chat.rb is not executable (run: chmod +x examples/docker_chat.rb)'
+  end
+else
+  puts '❌ docker_chat.rb not found'
+  exit 1
+end
+
+puts "\n🎉 All tests passed!"
+puts "\n📝 Next steps:"
+puts "   1. Set your OpenAI API key: export OPENAI_API_KEY='your-key-here'"
+puts '   2. Run the chat: ruby examples/docker_chat.rb'
+puts '   3. Or run with: ./examples/docker_chat.rb'
+puts "\n💡 Example chat commands to try:"
+puts "   • 'How many containers are running?'"
+puts "   • 'Show me all Docker images'"
+puts "   • 'List Docker networks'"
+puts "   • '/help' - to see all available tools"
+puts "   • '/exit' - to quit the chat"

data/lib/ruby_llm/docker/build_image.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for building Docker images.
+    #
+    # This tool provides the ability to build Docker images from Dockerfile
+    # content. It creates custom images by executing Dockerfile instructions
+    # and supports comprehensive build configuration including tagging and
+    # build arguments.
+    #
+    # == Features
+    #
+    # - Build images from Dockerfile content strings
+    # - Support for custom image tagging
+    # - Comprehensive build output and error reporting
+    # - Handles all standard Dockerfile instructions
+    # - Build context management
+    # - Progress tracking and logging
+    #
+    # == Security Considerations
+    #
+    # Image building involves significant security risks:
+    # - **Code Execution**: Dockerfile RUN commands execute arbitrary code
+    # - **Network Access**: Build process can access networks and repositories
+    # - **File System Access**: Can read local files and directories
+    # - **Credential Exposure**: May expose build-time secrets and credentials
+    # - **Supply Chain Risk**: Downloaded packages may contain malware
+    # - **Resource Consumption**: Builds can consume significant CPU, memory, and storage
+    #
+    # **Security Recommendations**:
+    # - Review all Dockerfile content before building
+    # - Use trusted base images only
+    # - Avoid embedding secrets in image layers
+    # - Implement build isolation and sandboxing
+    # - Monitor build resource consumption
+    # - Scan built images for vulnerabilities
+    # - Use multi-stage builds to minimize attack surface
+    #
+    # == Parameters
+    #
+    # - **dockerfile**: Dockerfile content as a string (required)
+    # - **tag**: Tag for the built image (optional, e.g., "myimage:latest")
+    #
+    # == Example Usage
+    #
+    #   # Build simple image
+    #   dockerfile_content = <<~DOCKERFILE
+    #     FROM alpine:latest
+    #     RUN apk add --no-cache curl
+    #     CMD ["curl", "--version"]
+    #   DOCKERFILE
+    #
+    #   response = BuildImage.call(
+    #     server_context: context,
+    #     dockerfile: dockerfile_content,
+    #     tag: "my-curl:latest"
+    #   )
+    #
+    #   # Build web server image
+    #   dockerfile_content = <<~DOCKERFILE
+    #     FROM nginx:alpine
+    #     COPY nginx.conf /etc/nginx/nginx.conf
+    #     EXPOSE 80
+    #     CMD ["nginx", "-g", "daemon off;"]
+    #   DOCKERFILE
+    #
+    #   response = BuildImage.call(
+    #     server_context: context,
+    #     dockerfile: dockerfile_content,
+    #     tag: "custom-nginx:v1.0"
+    #   )
+    #
+    # @see ::Docker::Image.build_from_dir
+    # @since 0.1.0
+    BUILD_IMAGE_DEFINITION = ToolForge.define(:build_image) do
+      description 'Build a Docker image'
+
+      param :dockerfile,
+            type: :string,
+            description: 'Dockerfile content as a string'
+
+      param :tag,
+            type: :string,
+            description: 'Tag for the built image (e.g., "myimage:latest")',
+            required: false
+
+      execute do |dockerfile:, tag: nil|
+        # Build the image
+        image = ::Docker::Image.build(dockerfile)
+
+        # If a tag was specified, tag the image
+        if tag
+          # Split tag into repo and tag parts
+          repo, image_tag = tag.split(':', 2)
+          image_tag ||= 'latest'
+          image.tag('repo' => repo, 'tag' => image_tag, 'force' => true)
+        end
+
+        response_text = "Image built successfully. ID: #{image.id}"
+        response_text += ", Tag: #{tag}" if tag
+        response_text
+      rescue StandardError => e
+        "Error building image: #{e.message}"
+      end
+    end
+
+    BuildImage = BUILD_IMAGE_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/copy_to_container.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for copying files and directories to Docker containers.
+    #
+    # This tool provides the ability to copy files and directories from the
+    # local host filesystem into running Docker containers. It supports both
+    # individual files and entire directory trees, with optional ownership
+    # modification within the container.
+    #
+    # == Features
+    #
+    # - Copy files and directories from host to container
+    # - Supports recursive directory copying
+    # - Preserves file permissions and metadata
+    # - Optional ownership modification after copy
+    # - Works with running containers
+    # - Comprehensive error handling and validation
+    #
+    # == Security Considerations
+    #
+    # File copying operations have significant security implications:
+    # - **File System Access**: Reads local host file system content
+    # - **Container Modification**: Alters container file system state
+    # - **Data Injection**: Can introduce malicious files into containers
+    # - **Permission Escalation**: May affect container security context
+    # - **Resource Consumption**: Large copies can consume storage and I/O
+    # - **Path Traversal**: Improper paths could access unintended locations
+    #
+    # **Security Recommendations**:
+    # - Validate and sanitize all file paths
+    # - Implement access controls for source file locations
+    # - Monitor file copy operations and sizes
+    # - Use read-only mounts where possible
+    # - Apply resource limits to prevent abuse
+    #
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    # - **source_path**: Path to file/directory on local filesystem (required)
+    # - **destination_path**: Path inside container for copied content (required)
+    # - **owner**: Owner for copied files (optional, e.g., "1000:1000" or "username:group")
+    #
+    # == Example Usage
+    #
+    #   # Copy single file
+    #   response = CopyToContainer.call(
+    #     server_context: context,
+    #     id: "web-server",
+    #     source_path: "/local/config.conf",
+    #     destination_path: "/etc/nginx/nginx.conf"
+    #   )
+    #
+    #   # Copy directory with ownership change
+    #   response = CopyToContainer.call(
+    #     server_context: context,
+    #     id: "app-container",
+    #     source_path: "/local/app-data",
+    #     destination_path: "/var/lib/app",
+    #     owner: "app:app"
+    #   )
+    #
+    # @see ::Docker::Container#archive_in_stream
+    # @since 0.1.0
+    COPY_TO_CONTAINER_DEFINITION = ToolForge.define(:copy_to_container) do
+      description 'Copy a file or directory from the local filesystem into a running Docker container. ' \
+                  'The source path is on the local machine, and the destination path is inside the container.'
+
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :source_path,
+            type: :string,
+            description: 'Path to the file or directory on the local filesystem to copy'
+
+      param :destination_path,
+            type: :string,
+            description: 'Path inside the container where the file/directory should be copied'
+
+      param :owner,
+            type: :string,
+            description: 'Owner for the copied files (optional, e.g., "1000:1000" or "username:group")',
+            required: false
+
+      # Helper method for adding files/directories to tar
+      class_helper :add_to_tar do |tar, path, archive_path|
+        if File.directory?(path)
+          # Add directory entry
+          tar.mkdir(archive_path, File.stat(path).mode)
+
+          # Add directory contents
+          Dir.entries(path).each do |entry|
+            next if ['.', '..'].include?(entry)
+
+            full_path = File.join(path, entry)
+            archive_entry_path = File.join(archive_path, entry)
+            add_to_tar(tar, full_path, archive_entry_path)
+          end
+        else
+          # Add file
+          File.open(path, 'rb') do |file|
+            tar.add_file_simple(archive_path, File.stat(path).mode, file.size) do |tar_file|
+              IO.copy_stream(file, tar_file)
+            end
+          end
+        end
+      end
+
+      execute do |id:, source_path:, destination_path:, owner: nil|
+        container = ::Docker::Container.get(id)
+
+        # Verify source path exists
+        next "Source path not found: #{source_path}" unless File.exist?(source_path)
+
+        # Create a tar archive of the source
+        tar_io = StringIO.new
+        tar_io.set_encoding('ASCII-8BIT')
+
+        Gem::Package::TarWriter.new(tar_io) do |tar|
+          add_to_tar(tar, source_path, File.basename(source_path))
+        end
+
+        tar_io.rewind
+
+        # Copy to container
+        container.archive_in_stream(destination_path) do
+          tar_io.read
+        end
+
+        # Optionally change ownership
+        if owner
+          chown_path = File.join(destination_path, File.basename(source_path))
+          container.exec(['chown', '-R', owner, chown_path])
+        end
+
+        file_type = File.directory?(source_path) ? 'directory' : 'file'
+        response_text = "Successfully copied #{file_type} from #{source_path} to #{id}:#{destination_path}"
+        response_text += "\nOwnership changed to #{owner}" if owner
+        response_text
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error copying to container: #{e.message}"
+      end
+    end
+
+    CopyToContainer = COPY_TO_CONTAINER_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/create_container.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for creating Docker containers.
+    #
+    # 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
+    #
+    # - 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
+    #
+    # 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
+    #
+    # 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
+    #   response = CreateContainer.call(
+    #     server_context: context,
+    #     image: "nginx:latest",
+    #     name: "web-server"
+    #   )
+    #
+    #   # Advanced container with configuration
+    #   response = CreateContainer.call(
+    #     server_context: context,
+    #     image: "postgres:13",
+    #     name: "database",
+    #     env: "POSTGRES_PASSWORD=secret,POSTGRES_DB=myapp",
+    #     exposed_ports: {"5432/tcp" => {}},
+    #     host_config: {
+    #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
+    #       "Binds" => ["/host/data:/var/lib/postgresql/data:rw"]
+    #     }
+    #   )
+    #
+    # @see ::Docker::Container.create
+    # @since 0.1.0
+    CREATE_CONTAINER_DEFINITION = ToolForge.define(:create_container) do
+      description 'Create a Docker container'
+
+      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,
+            type: :string,
+            description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)',
+            required: false
+
+      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
+
+        # 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
+
+        container = ::Docker::Container.create(config)
+        container_name = container.info['Names']&.first&.delete_prefix('/')
+
+        "Container created successfully. ID: #{container.id}, Name: #{container_name}"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{image} not found"
+      rescue ::Docker::Error::ConflictError
+        "Container with name #{name} already exists"
+      rescue StandardError => e
+        "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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for creating Docker networks.
+    #
+    # 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 multiple network drivers (bridge, overlay, host, etc.)
+    # - Duplicate name checking and validation
+    # - Network configuration and options
+    # - Comprehensive error handling
+    # - Network isolation and security controls
+    #
+    # == Security Considerations
+    #
+    # 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 Recommendations**:
+    # - Use appropriate network drivers for use case
+    # - Implement network segmentation strategies
+    # - 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
+    #   response = CreateNetwork.call(
+    #     server_context: context,
+    #     name: "app-network"
+    #   )
+    #
+    #   # Create overlay network for swarm
+    #   response = CreateNetwork.call(
+    #     server_context: context,
+    #     name: "swarm-network",
+    #     driver: "overlay"
+    #   )
+    #
+    #   # Create network allowing duplicates
+    #   response = CreateNetwork.call(
+    #     server_context: context,
+    #     name: "test-network",
+    #     driver: "bridge",
+    #     check_duplicate: false
+    #   )
+    #
+    # @see ::Docker::Network.create
+    # @since 0.1.0
+    CREATE_NETWORK_DEFINITION = ToolForge.define(:create_network) do
+      description 'Create a Docker network'
+
+      param :name,
+            type: :string,
+            description: 'Name of the network'
+
+      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,
+          'CheckDuplicate' => check_duplicate
+        }
+
+        network = ::Docker::Network.create(name, options)
+
+        "Network #{name} created successfully. ID: #{network.id}"
+      rescue ::Docker::Error::ConflictError
+        "Network #{name} already exists"
+      rescue StandardError => e
+        "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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for creating Docker volumes.
+    #
+    # 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 Docker volumes
+    # - Support for multiple volume drivers
+    # - Persistent data storage management
+    # - Volume driver configuration
+    # - Comprehensive error handling
+    # - Volume lifecycle management
+    #
+    # == Security Considerations
+    #
+    # 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
+    #
+    # **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
+    #
+    # == Parameters
+    #
+    # - **name**: Name of the volume (required)
+    # - **driver**: Driver to use (optional, default: "local")
+    #
+    # == Volume Drivers
+    #
+    # - **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
+    #   response = CreateVolume.call(
+    #     server_context: context,
+    #     name: "app-data"
+    #   )
+    #
+    #   # Create volume with specific driver
+    #   response = CreateVolume.call(
+    #     server_context: context,
+    #     name: "shared-storage",
+    #     driver: "nfs"
+    #   )
+    #
+    #   # Create database volume
+    #   response = CreateVolume.call(
+    #     server_context: context,
+    #     name: "postgres-data",
+    #     driver: "local"
+    #   )
+    #
+    # @see ::Docker::Volume.create
+    # @since 0.1.0
+    CREATE_VOLUME_DEFINITION = ToolForge.define(:create_volume) do
+      description 'Create a Docker volume'
+
+      param :name,
+            type: :string,
+            description: 'Name of the volume'
+
+      param :driver,
+            type: :string,
+            description: 'Driver to use (default: local)',
+            required: false,
+            default: 'local'
+
+      execute do |name:, driver: 'local'|
+        options = {
+          'Name' => name,
+          'Driver' => driver
+        }
+
+        ::Docker::Volume.create(name, options)
+
+        "Volume #{name} created successfully"
+      rescue ::Docker::Error::ConflictError
+        "Volume #{name} already exists"
+      rescue StandardError => e
+        "Error creating volume: #{e.message}"
+      end
+    end
+
+    CreateVolume = CREATE_VOLUME_DEFINITION.to_ruby_llm_tool
+  end
+end