ruby_llm-docker 0.0.1 → 0.3.0

data/lib/ruby_llm/docker/run_container.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for running Docker containers.
+    #
+    # This tool creates and immediately starts a Docker container from a
+    # specified image in a single operation. It combines the functionality
+    # of create_container and start_container for convenience when immediate
+    # execution is desired.
+    #
+    # == Features
+    #
+    # - Creates and starts containers in one operation
+    # - Supports all container configuration options
+    # - Configures command execution and environment variables
+    # - Sets up port exposure and network configuration
+    # - Applies advanced host configurations and volume mounts
+    # - Handles container naming and labeling
+    #
+    # == Security Considerations
+    #
+    # Running containers involves significant security considerations:
+    # - **Immediate Execution**: Starts processes immediately upon creation
+    # - **Resource Consumption**: Consumes CPU, memory, and storage resources
+    # - **Network Exposure**: Creates active network endpoints
+    # - **File System Access**: Potentially accesses host directories
+    # - **Process Isolation**: Runs processes with configured privileges
+    #
+    # Implement strict access controls and resource monitoring.
+    #
+    # == 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 execution
+    #   response = RunContainer.call(
+    #     server_context: context,
+    #     image: "alpine:latest",
+    #     cmd: "echo 'Hello World'"
+    #   )
+    #
+    #   # Web server with port binding
+    #   response = RunContainer.call(
+    #     server_context: context,
+    #     image: "nginx:latest",
+    #     name: "web-server",
+    #     exposed_ports: {"80/tcp" => {}},
+    #     host_config: {
+    #       "PortBindings" => {"80/tcp" => [{"HostPort" => "8080"}]}
+    #     }
+    #   )
+    #
+    # @see ::Docker::Container.create
+    # @since 0.1.0
+    RUN_CONTAINER_DEFINITION = ToolForge.define(:run_container) do
+      description 'Run a Docker container (create and start)'
+
+      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.start
+        container_name = container.info['Names']&.first&.delete_prefix('/')
+
+        "Container started 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 running container: #{e.message}"
+      end
+    end
+
+    RunContainer = RUN_CONTAINER_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/start_container.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for starting Docker containers.
+    #
+    # This tool starts a previously created Docker container that is currently
+    # in a "created" or "stopped" state. It transitions the container to a
+    # "running" state and begins executing the configured command or entrypoint.
+    #
+    # == Features
+    #
+    # - Starts containers by ID or name
+    # - Supports both short and full container IDs
+    # - Works with custom container names
+    # - Provides clear success/failure feedback
+    # - Handles container state transitions
+    # - Preserves all container configuration
+    #
+    # == Security Considerations
+    #
+    # Starting containers involves security implications:
+    # - **Process Execution**: Begins running container processes
+    # - **Resource Activation**: Activates CPU, memory, and I/O usage
+    # - **Network Activation**: Brings network interfaces online
+    # - **Service Exposure**: Makes configured services accessible
+    #
+    # Ensure proper monitoring and access controls are in place.
+    #
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    #   - Accepts full container IDs
+    #   - Accepts short container IDs (first 12+ characters)
+    #   - Accepts custom container names
+    #
+    # == Example Usage
+    #
+    #   # Start by container name
+    #   response = StartContainer.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Start by container ID
+    #   response = StartContainer.call(
+    #     server_context: context,
+    #     id: "a1b2c3d4e5f6"
+    #   )
+    #
+    # @see ::Docker::Container#start
+    # @since 0.1.0
+    START_CONTAINER_DEFINITION = ToolForge.define(:start_container) do
+      description 'Start a Docker container'
+
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      execute do |id:|
+        container = ::Docker::Container.get(id)
+        container.start
+
+        "Container #{id} started successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error starting container: #{e.message}"
+      end
+    end
+
+    StartContainer = START_CONTAINER_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/stop_container.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for stopping Docker containers.
+    #
+    # This tool gracefully stops a running Docker container by sending a
+    # SIGTERM signal to the main process, allowing it to shut down cleanly.
+    # If the container doesn't stop within the specified timeout, it will
+    # be forcefully killed with SIGKILL.
+    #
+    # == Features
+    #
+    # - Graceful container shutdown with SIGTERM
+    # - Configurable timeout for forced termination
+    # - Supports container identification by ID or name
+    # - Handles both running and already-stopped containers
+    # - Provides clear feedback on operation status
+    # - Preserves container and data integrity
+    #
+    # == Security Considerations
+    #
+    # Stopping containers affects service availability:
+    # - **Service Disruption**: Terminates running services and processes
+    # - **Data Integrity**: May interrupt ongoing operations
+    # - **Resource Release**: Frees CPU, memory, and network resources
+    # - **State Preservation**: Maintains container state for future restart
+    #
+    # Coordinate container stops with dependent services and users.
+    #
+    # == Parameters
+    #
+    # - **id**: Container ID or name (required)
+    #   - Accepts full container IDs
+    #   - Accepts short container IDs (first 12+ characters)
+    #   - Accepts custom container names
+    # - **timeout**: Seconds to wait before killing container (optional, default: 10)
+    #
+    # == Example Usage
+    #
+    #   # Stop with default timeout
+    #   response = StopContainer.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Stop with custom timeout
+    #   response = StopContainer.call(
+    #     server_context: context,
+    #     id: "database",
+    #     timeout: 30
+    #   )
+    #
+    # @see ::Docker::Container#stop
+    # @since 0.1.0
+    STOP_CONTAINER_DEFINITION = ToolForge.define(:stop_container) do
+      description 'Stop a Docker container'
+
+      param :id,
+            type: :string,
+            description: 'Container ID or name'
+
+      param :timeout,
+            type: :integer,
+            description: 'Seconds to wait before killing the container (default: 10)',
+            required: false,
+            default: 10
+
+      execute do |id:, timeout: 10|
+        container = ::Docker::Container.get(id)
+        container.stop('timeout' => timeout)
+
+        "Container #{id} stopped successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error stopping container: #{e.message}"
+      end
+    end
+
+    StopContainer = STOP_CONTAINER_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/tag_image.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # MCP tool for tagging Docker images.
+    #
+    # This tool provides the ability to assign repository names and tags
+    # to Docker images. Tagging is essential for image organization,
+    # versioning, and distribution through Docker registries.
+    #
+    # == Features
+    #
+    # - Tag existing images with custom repository names
+    # - Support for version and environment tags
+    # - Force tagging to overwrite existing tags
+    # - Registry-compatible naming conventions
+    # - Automatic tag defaulting to "latest"
+    # - Comprehensive error handling and validation
+    #
+    # == Security Considerations
+    #
+    # Image tagging involves several security considerations:
+    # - **Registry Authentication**: Tags may trigger registry operations
+    # - **Namespace Conflicts**: Overwriting tags can affect other deployments
+    # - **Image Identity**: Improper tagging can lead to deployment confusion
+    # - **Version Management**: Incorrect tags can compromise CI/CD pipelines
+    # - **Registry Pollution**: Excessive tagging can clutter registries
+    #
+    # **Security Recommendations**:
+    # - Use consistent naming conventions
+    # - Implement tag governance policies
+    # - Verify image identity before tagging
+    # - Avoid overwriting production tags
+    # - Use semantic versioning for releases
+    # - Monitor tag usage and lifecycle
+    #
+    # == Parameters
+    #
+    # - **id**: Image ID or current name:tag to tag (required)
+    # - **repo**: Repository name (required, e.g., "username/imagename" or "registry/username/imagename")
+    # - **tag**: Tag for the image (optional, default: "latest")
+    # - **force**: Force tag even if it already exists (optional, default: true)
+    #
+    # == Example Usage
+    #
+    #   # Tag image with version
+    #   response = TagImage.call(
+    #     server_context: context,
+    #     id: "myapp:dev",
+    #     repo: "myregistry/myapp",
+    #     tag: "v1.2.3"
+    #   )
+    #
+    #   # Tag for production deployment
+    #   response = TagImage.call(
+    #     server_context: context,
+    #     id: "abc123def456",
+    #     repo: "production/webapp",
+    #     tag: "stable",
+    #     force: false
+    #   )
+    #
+    #   # Tag with registry prefix
+    #   response = TagImage.call(
+    #     server_context: context,
+    #     id: "local-build:latest",
+    #     repo: "registry.company.com/team/service",
+    #     tag: "release-candidate"
+    #   )
+    #
+    # @see ::Docker::Image#tag
+    # @since 0.1.0
+    TAG_IMAGE_DEFINITION = ToolForge.define(:tag_image) do
+      description 'Tag a Docker image'
+
+      param :id,
+            type: :string,
+            description: 'Image ID or current name:tag to tag'
+
+      param :repo,
+            type: :string,
+            description: 'Repository name (e.g., "username/imagename" or "registry/username/imagename")'
+
+      param :tag,
+            type: :string,
+            description: 'Tag for the image (default: "latest")',
+            required: false,
+            default: 'latest'
+
+      param :force,
+            type: :boolean,
+            description: 'Force tag even if it already exists (default: true)',
+            required: false,
+            default: true
+
+      execute do |id:, repo:, tag: 'latest', force: true|
+        image = ::Docker::Image.get(id)
+
+        image.tag('repo' => repo, 'tag' => tag, 'force' => force)
+
+        "Image tagged successfully as #{repo}:#{tag}"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{id} not found"
+      rescue StandardError => e
+        "Error tagging image: #{e.message}"
+      end
+    end
+
+    TagImage = TAG_IMAGE_DEFINITION.to_ruby_llm_tool
+  end
+end

data/lib/ruby_llm/docker/version.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
-module RubyLlm
+module RubyLLM
   module Docker
-    VERSION = "0.0.1"
+    # Current version of the RubyLLM::Docker gem.
+    #
+    # This constant follows semantic versioning (SemVer) principles:
+    # - MAJOR version for incompatible API changes
+    # - MINOR version for backwards-compatible functionality additions
+    # - PATCH version for backwards-compatible bug fixes
+    #
+    # @see https://semver.org/
+    # @since 0.1.0
+    VERSION = '0.3.0'
   end
 end

data/lib/ruby_llm/docker.rb

@@ -1,10 +1,73 @@
 # frozen_string_literal: true
 
-require_relative "docker/version"
+require 'ruby_llm'
+require 'docker'
+require 'shellwords'
+require 'tool_forge'
+require 'zeitwerk'
 
-module RubyLlm
+loader = Zeitwerk::Loader.for_gem_extension(RubyLLM)
+loader.setup
+
+require_relative 'docker/version'
+
+module RubyLLM
+  # Docker tools module providing comprehensive Docker management capabilities for RubyLLM.
+  #
+  # This module contains 22 Docker management tools organized into four categories:
+  # - Container Management (10 tools)
+  # - Image Management (6 tools)
+  # - Network Management (3 tools)
+  # - Volume Management (3 tools)
+  #
+  # @example Basic usage
+  #   chat = RubyLLM::Chat.new(api_key: 'your-key', model: 'gpt-4')
+  #   RubyLLM::Docker.add_all_tools_to_chat(chat)
+  #   response = chat.ask("How many containers are running?")
   module Docker
     class Error < StandardError; end
-    # Your code goes here...
+
+    # Helper method to get all Docker tool classes
+    def self.all_tools
+      [
+        # Container Management
+        ListContainers,
+        CreateContainer,
+        RunContainer,
+        StartContainer,
+        StopContainer,
+        RemoveContainer,
+        RecreateContainer,
+        ExecContainer,
+        CopyToContainer,
+        FetchContainerLogs,
+
+        # Image Management
+        ListImages,
+        PullImage,
+        BuildImage,
+        TagImage,
+        PushImage,
+        RemoveImage,
+
+        # Network Management
+        ListNetworks,
+        CreateNetwork,
+        RemoveNetwork,
+
+        # Volume Management
+        ListVolumes,
+        CreateVolume,
+        RemoveVolume
+      ]
+    end
+
+    # Helper method to add all Docker tools to a RubyLLM chat instance
+    def self.add_all_tools_to_chat(chat)
+      all_tools.each do |tool_class|
+        chat.with_tool(tool_class)
+      end
+      chat
+    end
   end
 end

data/sig/ruby_llm/docker.rbs

@@ -1,4 +1,4 @@
-module RubyLlm
+module RubyLLM
   module Docker
     VERSION: String
     # See the writing guide of rbs: https://github.com/ruby/rbs#guides

metadata

@@ -1,16 +1,88 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-docker
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Aaron F Stanton
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: This gem provides a simple interface for managing Docker containers from
-  Ruby via RubyLLM.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: docker-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tool_forge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A comprehensive Ruby gem that provides Docker management capabilities
+  through RubyLLM tools. Enables AI assistants to interact with Docker containers,
+  images, networks, and volumes using natural language. Ported from DockerMCP to work
+  directly with RubyLLM without requiring an external MCP server.
 email:
 - afstanton@gmail.com
 executables: []
@@ -20,7 +92,32 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/docker_chat.rb
+- examples/list_containers.rb
+- examples/test_chat.rb
 - lib/ruby_llm/docker.rb
+- lib/ruby_llm/docker/build_image.rb
+- lib/ruby_llm/docker/copy_to_container.rb
+- lib/ruby_llm/docker/create_container.rb
+- lib/ruby_llm/docker/create_network.rb
+- lib/ruby_llm/docker/create_volume.rb
+- lib/ruby_llm/docker/exec_container.rb
+- lib/ruby_llm/docker/fetch_container_logs.rb
+- lib/ruby_llm/docker/list_containers.rb
+- lib/ruby_llm/docker/list_images.rb
+- lib/ruby_llm/docker/list_networks.rb
+- lib/ruby_llm/docker/list_volumes.rb
+- lib/ruby_llm/docker/pull_image.rb
+- lib/ruby_llm/docker/push_image.rb
+- lib/ruby_llm/docker/recreate_container.rb
+- lib/ruby_llm/docker/remove_container.rb
+- lib/ruby_llm/docker/remove_image.rb
+- lib/ruby_llm/docker/remove_network.rb
+- lib/ruby_llm/docker/remove_volume.rb
+- lib/ruby_llm/docker/run_container.rb
+- lib/ruby_llm/docker/start_container.rb
+- lib/ruby_llm/docker/stop_container.rb
+- lib/ruby_llm/docker/tag_image.rb
 - lib/ruby_llm/docker/version.rb
 - sig/ruby_llm/docker.rbs
 homepage: https://github.com/afstanton/ruby_llm-docker
@@ -30,6 +127,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/afstanton/ruby_llm-docker
   source_code_uri: https://github.com/afstanton/ruby_llm-docker
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -46,5 +144,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.2
 specification_version: 4
-summary: A Ruby gem for interacting with Docker containers directly with RubyLLM.
+summary: Docker management tools for RubyLLM - comprehensive container, image, network,
+  and volume operations
 test_files: []