docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/create_container.rb

@@ -1,49 +1,52 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP 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",
@@ -55,86 +58,41 @@ module DockerMCP
   #     }
   #   )
   #
-  # @see RunContainer
-  # @see StartContainer
   # @see Docker::Container.create
   # @since 0.1.0
-  class CreateContainer < MCP::Tool
+  CREATE_CONTAINER_DEFINITION = ToolForge.define(:create_container) do
     description 'Create a Docker container'
 
-    input_schema(
-      properties: {
-        image: {
-          type: 'string',
+    param :image,
+          type: :string,
           description: 'Image name to use (e.g., "ubuntu:22.04")'
-        },
-        name: {
-          type: 'string',
-          description: 'Container name (optional)'
-        },
-        cmd: {
-          type: 'string',
-          description: 'Command to run as space-separated string (optional, e.g., "npm start" or "python app.py")'
-        },
-        env: {
-          type: 'string',
-          description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)'
-        },
-        exposed_ports: {
-          type: 'object',
-          description: 'Exposed ports as {"port/protocol": {}} (optional)'
-        },
-        host_config: {
-          type: 'object',
-          description: 'Host configuration including port bindings, volumes, etc. (optional)'
-        }
-      },
-      required: ['image']
-    )
 
-    # 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] MCP server context (unused but required)
-    # @param name [String, nil] custom name for the container
-    # @param cmd [String, nil] command to execute as space-separated string
-    # @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 [MCP::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,REDIS_PORT=6379",
-    #     exposed_ports: {"6379/tcp" => {}},
-    #     host_config: {
-    #       "PortBindings" => {"6379/tcp" => [{"HostPort" => "6379"}]},
-    #       "RestartPolicy" => {"Name" => "unless-stopped"}
-    #     }
-    #   )
-    #
-    # @see Docker::Container.create
-    def self.call(image:, server_context:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil)
+    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
 
@@ -150,25 +108,15 @@ module DockerMCP
       container = Docker::Container.create(config)
       container_name = container.info['Names']&.first&.delete_prefix('/')
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container created successfully. ID: #{container.id}, Name: #{container_name}"
-                              }])
+      "Container created successfully. ID: #{container.id}, Name: #{container_name}"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Image #{image} not found"
-                              }])
+      "Image #{image} not found"
     rescue Docker::Error::ConflictError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container with name #{name} already exists"
-                              }])
+      "Container with name #{name} already exists"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error creating container: #{e.message}"
-                              }])
+      "Error creating container: #{e.message}"
     end
   end
+
+  CreateContainer = CREATE_CONTAINER_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/create_network.rb

@@ -3,128 +3,96 @@
 module DockerMCP
   # 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
   # @since 0.1.0
-  class CreateNetwork < MCP::Tool
+  CREATE_NETWORK_DEFINITION = ToolForge.define(:create_network) do
     description 'Create a Docker network'
 
-    input_schema(
-      properties: {
-        name: {
-          type: 'string',
+    param :name,
+          type: :string,
           description: 'Name of the network'
-        },
-        driver: {
-          type: 'string',
-          description: 'Driver to use (default: bridge)'
-        },
-        check_duplicate: {
-          type: 'boolean',
-          description: 'Check for networks with duplicate names (default: true)'
-        }
-      },
-      required: ['name']
-    )
 
-    # 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] MCP server 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 [MCP::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 = CreateNetwork.call(
-    #     server_context: context,
-    #     name: "high-performance-net",
-    #     driver: "host"
-    #   )
-    #
-    # @see Docker::Network.create
-    def self.call(name:, server_context:, 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,
@@ -133,20 +101,13 @@ module DockerMCP
 
       network = Docker::Network.create(name, options)
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Network #{name} created successfully. ID: #{network.id}"
-                              }])
+      "Network #{name} created successfully. ID: #{network.id}"
     rescue Docker::Error::ConflictError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Network #{name} already exists"
-                              }])
+      "Network #{name} already exists"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error creating network: #{e.message}"
-                              }])
+      "Error creating network: #{e.message}"
     end
   end
+
+  CreateNetwork = CREATE_NETWORK_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/create_volume.rb

@@ -3,125 +3,89 @@
 module DockerMCP
   # 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
+  #   # Create database volume
+  #   response = CreateVolume.call(
+  #     server_context: context,
+  #     name: "postgres-data",
+  #     driver: "local"
+  #   )
+  #
   # @see Docker::Volume.create
   # @since 0.1.0
-  class CreateVolume < MCP::Tool
+  CREATE_VOLUME_DEFINITION = ToolForge.define(:create_volume) do
     description 'Create a Docker volume'
 
-    input_schema(
-      properties: {
-        name: {
-          type: 'string',
+    param :name,
+          type: :string,
           description: 'Name of the volume'
-        },
-        driver: {
-          type: 'string',
-          description: 'Driver to use (default: local)'
-        }
-      },
-      required: ['name']
-    )
 
-    # 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] MCP server context (unused but required)
-    # @param driver [String] volume driver to use (default: "local")
-    #
-    # @return [MCP::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 = CreateVolume.call(
-    #     server_context: context,
-    #     name: "shared-files",
-    #     driver: "nfs"
-    #   )
-    #
-    # @see Docker::Volume.create
-    def self.call(name:, server_context:, driver: 'local')
+    param :driver,
+          type: :string,
+          description: 'Driver to use (default: local)',
+          required: false,
+          default: 'local'
+
+    execute do |name:, driver: 'local'|
       options = {
         'Name' => name,
         'Driver' => driver
@@ -129,20 +93,13 @@ module DockerMCP
 
       Docker::Volume.create(name, options)
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Volume #{name} created successfully"
-                              }])
+      "Volume #{name} created successfully"
     rescue Docker::Error::ConflictError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Volume #{name} already exists"
-                              }])
+      "Volume #{name} already exists"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error creating volume: #{e.message}"
-                              }])
+      "Error creating volume: #{e.message}"
     end
   end
+
+  CreateVolume = CREATE_VOLUME_DEFINITION.to_mcp_tool
 end