docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/list_images.rb

@@ -3,78 +3,54 @@
 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.
+  # This tool provides comprehensive information about all Docker images
+  # stored on the local system. It returns detailed metadata including
+  # image sizes, creation dates, tags, and usage statistics.
   #
   # == Features
   #
-  # - List all local Docker images
-  # - Comprehensive image metadata
-  # - No configuration required
-  # - Read-only operation
-  # - Includes both tagged and untagged images
+  # - Lists all locally stored Docker images
+  # - Provides detailed image metadata and statistics
+  # - Shows image sizes and storage usage
+  # - Displays repository tags and digests
+  # - Includes creation timestamps and labels
+  # - Reports container usage counts
   #
-  # == Image Information Included
+  # == Security Considerations
   #
-  # 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
+  # This tool provides information that could be useful for:
+  # - **System Analysis**: Reveals installed software and versions
+  # - **Vulnerability Assessment**: Shows potential attack surfaces
+  # - **Resource Planning**: Exposes storage usage patterns
   #
-  # == Security Considerations
+  # Monitor access to this tool in production environments.
   #
-  # 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
+  # == Return Format
   #
-  # While generally safe, consider access control:
-  # - Limit exposure of image inventory
-  # - Be cautious with sensitive image names
-  # - Monitor for unauthorized image access attempts
+  # Returns an array of image objects with comprehensive metadata:
+  # - Repository tags and digests
+  # - Image sizes and virtual sizes
+  # - Creation timestamps
+  # - Container usage counts
+  # - Labels and annotations
+  # - Parent-child relationships
   #
   # == Example Usage
   #
-  #   # List all images
-  #   ListImages.call(server_context: context)
+  #   images = ListImages.call(server_context: context)
+  #   images.each do |image|
+  #     puts "#{image['RepoTags']}: #{image['Size']} bytes"
+  #   end
   #
-  # @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
+  LIST_IMAGES_DEFINITION = ToolForge.define(:list_images) do
     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
-                              }])
+    execute do
+      Docker::Image.all.map(&:info)
     end
   end
+
+  ListImages = LIST_IMAGES_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/list_networks.rb

@@ -3,82 +3,55 @@
 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.
+  # 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
   # @since 0.1.0
-  class ListNetworks < MCP::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.
-    #
-    # @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
-                              }])
+    execute do
+      Docker::Network.all.map(&:info)
     end
   end
+
+  ListNetworks = LIST_NETWORKS_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/list_volumes.rb

@@ -3,89 +3,55 @@
 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.
+  # 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
   # @since 0.1.0
-  class ListVolumes < MCP::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.
-    #
-    # @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
-                              }])
+    execute do
+      Docker::Volume.all.map(&:info)
     end
   end
+
+  ListVolumes = LIST_VOLUMES_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/pull_image.rb

@@ -25,7 +25,7 @@ module DockerMCP
   # - **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
@@ -41,78 +41,41 @@ module DockerMCP
   # - 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
   # @since 0.1.0
-  class PullImage < MCP::Tool
+  PULL_IMAGE_DEFINITION = ToolForge.define(:pull_image) do
     description 'Pull a Docker image'
 
-    input_schema(
-      properties: {
-        from_image: {
-          type: 'string',
+    param :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)
+    param :tag,
+          type: :string,
+          description: 'Tag to pull (optional, defaults to "latest" if not specified in from_image)',
+          required: false
+
+    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
@@ -126,20 +89,13 @@ module DockerMCP
 
       image = Docker::Image.create('fromImage' => image_with_tag)
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Image #{image_with_tag} pulled successfully. ID: #{image.id}"
-                              }])
+      "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"
-                              }])
+      "Image #{image_with_tag} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error pulling image: #{e.message}"
-                              }])
+      "Error pulling image: #{e.message}"
     end
   end
+
+  PullImage = PULL_IMAGE_DEFINITION.to_mcp_tool
 end