docker_mcp 0.0.1 → 0.2.5

data/lib/docker_mcp/fetch_container_logs.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for retrieving Docker container logs.
+  #
+  # This tool provides access to container logs with flexible filtering and
+  # formatting options. It can retrieve both stdout and stderr logs with
+  # optional timestamps and tail functionality for recent entries.
+  #
+  # == Features
+  #
+  # - Retrieve stdout and/or stderr logs
+  # - Optional timestamp inclusion
+  # - Tail functionality for recent logs
+  # - Flexible log stream selection
+  # - Comprehensive error handling
+  # - Works with any container state
+  #
+  # == Log Sources
+  #
+  # Docker containers can generate logs from multiple sources:
+  # - **stdout**: Standard output from container processes
+  # - **stderr**: Standard error from container processes
+  # - **timestamps**: Docker-generated timestamps for each log line
+  #
+  # == Security Considerations
+  #
+  # Container logs may contain sensitive information:
+  # - Application secrets and API keys
+  # - User data and personal information
+  # - Internal system information
+  # - Database connection strings
+  # - Error messages with stack traces
+  #
+  # Security recommendations:
+  # - Review log content before sharing
+  # - Limit access to container logs
+  # - Sanitize logs in production environments
+  # - Use log rotation to manage log size
+  # - Be cautious with log forwarding
+  #
+  # == Example Usage
+  #
+  #   # Get all logs
+  #   FetchContainerLogs.call(
+  #     server_context: context,
+  #     id: "web-server"
+  #   )
+  #
+  #   # Get recent logs with timestamps
+  #   FetchContainerLogs.call(
+  #     server_context: context,
+  #     id: "app-container",
+  #     tail: 100,
+  #     timestamps: true
+  #   )
+  #
+  #   # Get only error logs
+  #   FetchContainerLogs.call(
+  #     server_context: context,
+  #     id: "database",
+  #     stdout: false,
+  #     stderr: true
+  #   )
+  #
+  # @see ExecContainer
+  # @see Docker::Container#logs
+  # @since 0.1.0
+  class FetchContainerLogs < MCP::Tool
+    description 'Fetch Docker container logs'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Container ID or name'
+        },
+        stdout: {
+          type: 'boolean',
+          description: 'Include stdout (default: true)'
+        },
+        stderr: {
+          type: 'boolean',
+          description: 'Include stderr (default: true)'
+        },
+        tail: {
+          type: 'integer',
+          description: 'Number of lines to show from the end of logs (default: all)'
+        },
+        timestamps: {
+          type: 'boolean',
+          description: 'Show timestamps (default: false)'
+        }
+      },
+      required: ['id']
+    )
+
+    # Retrieve logs from a Docker container.
+    #
+    # This method fetches logs from the specified container with configurable
+    # options for log sources (stdout/stderr), formatting (timestamps), and
+    # quantity (tail). The logs are returned as a text response.
+    #
+    # @param id [String] container ID (full or short) or container name
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param stdout [Boolean] whether to include stdout logs (default: true)
+    # @param stderr [Boolean] whether to include stderr logs (default: true)
+    # @param tail [Integer, nil] number of recent lines to return (nil for all)
+    # @param timestamps [Boolean] whether to include timestamps (default: false)
+    #
+    # @return [MCP::Tool::Response] container logs as text
+    #
+    # @raise [Docker::Error::NotFoundError] if container doesn't exist
+    # @raise [StandardError] for other log retrieval failures
+    #
+    # @example Get all logs
+    #   response = FetchContainerLogs.call(
+    #     server_context: context,
+    #     id: "nginx-server"
+    #   )
+    #
+    # @example Get recent error logs with timestamps
+    #   response = FetchContainerLogs.call(
+    #     server_context: context,
+    #     id: "app-container",
+    #     stdout: false,
+    #     stderr: true,
+    #     tail: 50,
+    #     timestamps: true
+    #   )
+    #
+    # @see Docker::Container#logs
+    def self.call(id:, server_context:, stdout: true, stderr: true, tail: nil, timestamps: false)
+      container = Docker::Container.get(id)
+
+      options = {
+        stdout: stdout,
+        stderr: stderr,
+        timestamps: timestamps
+      }
+      options[:tail] = tail if tail
+
+      logs = container.logs(options)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: logs
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container #{id} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error fetching logs: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/list_containers.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for listing Docker containers.
+  #
+  # This tool provides functionality to list all Docker containers on the system,
+  # including both running and stopped containers. It returns detailed information
+  # about each container including names, images, status, ports, and other metadata.
+  #
+  # == Security Notes
+  #
+  # This is a read-only operation that provides system information about containers.
+  # While generally safe, it may reveal information about the Docker environment
+  # that could be useful for reconnaissance.
+  #
+  # == Example Usage
+  #
+  #   # List all containers (default behavior)
+  #   ListContainers.call(server_context: context)
+  #
+  #   # Explicitly request all containers
+  #   ListContainers.call(server_context: context, all: true)
+  #
+  # @see Docker::Container.all
+  # @since 0.1.0
+  class ListContainers < MCP::Tool
+    description 'List Docker containers'
+
+    input_schema(
+      properties: {
+        all: {
+          type: 'boolean',
+          description: 'Show all containers (default shows all containers including stopped ones)'
+        }
+      },
+      required: []
+    )
+
+    # List all Docker containers with detailed information.
+    #
+    # Retrieves information about all containers on the system, including:
+    # - Container names and IDs
+    # - Image information
+    # - Current state (running, stopped, etc.)
+    # - Port mappings
+    # - Network configuration
+    # - Volume mounts
+    # - Creation and status timestamps
+    #
+    # @param server_context [Object] the MCP server context (unused but required)
+    # @param all [Boolean] whether to show all containers (default: true)
+    # @return [MCP::Tool::Response] response containing container information
+    #
+    # @example List all containers
+    #   response = ListContainers.call(server_context: context)
+    #   # Returns detailed info for all containers
+    #
+    # @see Docker::Container.all
+    def self.call(server_context:, all: true)
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: Docker::Container.all(all: all).map(&:info).to_s
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/list_images.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for listing Docker images.
+  #
+  # This tool provides functionality to list all Docker images available on
+  # the local system. It returns comprehensive information about each image
+  # including IDs, tags, sizes, creation dates, and other metadata.
+  #
+  # == Features
+  #
+  # - List all local Docker images
+  # - Comprehensive image metadata
+  # - No configuration required
+  # - Read-only operation
+  # - Includes both tagged and untagged images
+  #
+  # == Image Information Included
+  #
+  # The response typically includes:
+  # - **Image ID**: Unique identifier for the image
+  # - **Repository Tags**: All tags associated with the image
+  # - **Size**: Virtual and actual size of the image
+  # - **Created**: Timestamp when image was created
+  # - **Parent ID**: Base image information
+  # - **RepoDigests**: Content-addressable identifiers
+  #
+  # == Security Considerations
+  #
+  # This is a read-only operation that reveals system information:
+  # - Exposes available images and versions
+  # - May reveal internal application details
+  # - Shows image sources and repositories
+  # - Could aid in reconnaissance activities
+  #
+  # While generally safe, consider access control:
+  # - Limit exposure of image inventory
+  # - Be cautious with sensitive image names
+  # - Monitor for unauthorized image access attempts
+  #
+  # == Example Usage
+  #
+  #   # List all images
+  #   ListImages.call(server_context: context)
+  #
+  # @example Usage in container management
+  #   # Get available images before container creation
+  #   images_response = ListImages.call(server_context: context)
+  #   # Use image information to select appropriate base images
+  #
+  # @see PullImage
+  # @see BuildImage
+  # @see Docker::Image.all
+  # @since 0.1.0
+  class ListImages < MCP::Tool
+    description 'List Docker images'
+
+    # List all Docker images available on the local system.
+    #
+    # This method retrieves information about all Docker images stored
+    # locally, including both tagged and untagged images. The information
+    # includes comprehensive metadata for each image.
+    #
+    # @param args [Array] variable arguments (unused but accepted for compatibility)
+    #
+    # @return [MCP::Tool::Response] comprehensive image information
+    #
+    # @example List all local images
+    #   response = ListImages.call
+    #   # Returns detailed info for all local Docker images
+    #
+    # @see Docker::Image.all
+    def self.call(*)
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: Docker::Image.all.map(&:info).to_s
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/list_networks.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # 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.
+  #
+  # == Features
+  #
+  # - List all Docker networks on the system
+  # - Comprehensive network metadata
+  # - No configuration required
+  # - Read-only operation
+  # - Includes built-in and custom networks
+  #
+  # == Network Information Included
+  #
+  # 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
+  #
+  # == Security Considerations
+  #
+  # 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
+  #
+  # 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
+  #
+  # == Example Usage
+  #
+  #   # List all networks
+  #   ListNetworks.call(server_context: context)
+  #
+  # @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
+  # @since 0.1.0
+  class ListNetworks < MCP::Tool
+    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.
+    #
+    # @param args [Array] variable arguments (unused but accepted for compatibility)
+    #
+    # @return [MCP::Tool::Response] comprehensive network information
+    #
+    # @example List all networks
+    #   response = ListNetworks.call
+    #   # Returns detailed info for all Docker networks
+    #
+    # @see Docker::Network.all
+    def self.call(*)
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: Docker::Network.all.map(&:info).to_s
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/list_volumes.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # 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.
+  #
+  # == Features
+  #
+  # - List all Docker volumes on the system
+  # - Comprehensive volume metadata
+  # - No configuration required
+  # - Read-only operation
+  # - Includes named and anonymous volumes
+  #
+  # == 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
+  #
+  # 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)
+  #
+  # == Security Considerations
+  #
+  # 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
+  #
+  # 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
+  #
+  # == 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
+  #
+  # @see CreateVolume
+  # @see RemoveVolume
+  # @see Docker::Volume.all
+  # @since 0.1.0
+  class ListVolumes < MCP::Tool
+    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.
+    #
+    # @param args [Array] variable arguments (unused but accepted for compatibility)
+    #
+    # @return [MCP::Tool::Response] comprehensive volume information
+    #
+    # @example List all volumes
+    #   response = ListVolumes.call
+    #   # Returns detailed info for all Docker volumes
+    #
+    # @see Docker::Volume.all
+    def self.call(*)
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: Docker::Volume.all.map(&:info).to_s
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/pull_image.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # 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
+  # tag specification and handles various image naming conventions.
+  #
+  # == Features
+  #
+  # - Pull images from any accessible Docker registry
+  # - Flexible tag specification (explicit or default)
+  # - Support for official and user repositories
+  # - Automatic latest tag handling
+  # - Comprehensive error handling
+  # - Progress tracking through Docker daemon
+  #
+  # == Security Considerations
+  #
+  # Pulling images can introduce security risks:
+  # - **Malicious Images**: Images may contain malware or backdoors
+  # - **Vulnerable Software**: Images may have known security vulnerabilities
+  # - **Untrusted Sources**: Images from unknown publishers may be compromised
+  # - **Supply Chain Attacks**: Legitimate-looking images may be malicious
+  # - **Resource Consumption**: Large images can consume significant disk space
+  #
+  # Security recommendations:
+  # - Only pull images from trusted registries and publishers
+  # - Verify image signatures when available
+  # - Scan pulled images for vulnerabilities
+  # - Use specific tags rather than 'latest'
+  # - Monitor registry access and authentication
+  # - Regularly update and patch images
+  #
+  # == Tag Handling
+  #
+  # The tool handles tags intelligently:
+  # - If image includes tag (e.g., "nginx:1.21"), use as specified
+  # - If separate tag provided, append to image name
+  # - If no tag specified, default to "latest"
+  # - Supports all Docker tag conventions
+  #
+  # == Example Usage
+  #
+  #   # Pull latest version
+  #   PullImage.call(
+  #     server_context: context,
+  #     from_image: "nginx"
+  #   )
+  #
+  #   # Pull specific version
+  #   PullImage.call(
+  #     server_context: context,
+  #     from_image: "postgres:13"
+  #   )
+  #
+  #   # Pull with separate tag parameter
+  #   PullImage.call(
+  #     server_context: context,
+  #     from_image: "redis",
+  #     tag: "7-alpine"
+  #   )
+  #
+  # @see BuildImage
+  # @see ListImages
+  # @see Docker::Image.create
+  # @since 0.1.0
+  class PullImage < MCP::Tool
+    description 'Pull a Docker image'
+
+    input_schema(
+      properties: {
+        from_image: {
+          type: 'string',
+          description: 'Image name to pull (e.g., "ubuntu" or "ubuntu:22.04")'
+        },
+        tag: {
+          type: 'string',
+          description: 'Tag to pull (optional, defaults to "latest" if not specified in from_image)'
+        }
+      },
+      required: ['from_image']
+    )
+
+    # 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] MCP server context (unused but required)
+    # @param tag [String, nil] specific tag to pull (overrides tag in from_image)
+    #
+    # @return [MCP::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 self.call(from_image:, server_context:, 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
+      image_with_tag = if tag
+                         "#{from_image}:#{tag}"
+                       elsif from_image.include?(':')
+                         from_image
+                       else
+                         "#{from_image}:latest"
+                       end
+
+      image = Docker::Image.create('fromImage' => image_with_tag)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{image_with_tag} pulled successfully. ID: #{image.id}"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{image_with_tag} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error pulling image: #{e.message}"
+                              }])
+    end
+  end
+end