docker_mcp 0.0.1 → 0.2.0

data/lib/docker_mcp/remove_network.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for removing Docker networks.
+  #
+  # This tool provides the ability to permanently delete Docker networks from
+  # the system. It safely removes custom networks while protecting built-in
+  # system networks from accidental deletion.
+  #
+  # == Features
+  #
+  # - Remove custom Docker networks by ID or name
+  # - Protection against removing built-in networks
+  # - Comprehensive error handling
+  # - Dependency checking (prevents removal if containers are connected)
+  # - Safe cleanup of network resources
+  #
+  # == ⚠️ Service Disruption Warning ⚠️
+  #
+  # **NETWORK REMOVAL CAN DISRUPT SERVICES**
+  #
+  # Removing networks can cause immediate service disruption:
+  # - Connected containers lose network connectivity
+  # - Inter-container communication is broken
+  # - Services may become unreachable
+  # - Application functionality can be severely impacted
+  # - Network-dependent processes may fail
+  #
+  # == Protected Networks
+  #
+  # Docker protects certain built-in networks from removal:
+  # - **bridge**: Default bridge network
+  # - **host**: Host networking
+  # - **none**: No networking
+  # - **System networks**: Docker-managed networks
+  #
+  # == Security Considerations
+  #
+  # Network removal affects security boundaries:
+  # - Removes network isolation between containers
+  # - May expose containers to unintended networks
+  # - Could impact security segmentation strategies
+  # - Affects network-based access controls
+  #
+  # Security implications:
+  # - Ensure no critical containers depend on the network
+  # - Verify alternative connectivity exists if needed
+  # - Consider impact on security boundaries
+  # - Monitor for unauthorized network modifications
+  #
+  # Best practices:
+  # - Stop containers before removing their networks
+  # - Verify network dependencies before removal
+  # - Have rollback plans for critical networks
+  # - Document network removal procedures
+  # - Monitor network connectivity after removal
+  #
+  # == Example Usage
+  #
+  #   # Remove custom network
+  #   RemoveNetwork.call(
+  #     server_context: context,
+  #     id: "app-network"
+  #   )
+  #
+  #   # Remove by network ID
+  #   RemoveNetwork.call(
+  #     server_context: context,
+  #     id: "abc123def456"
+  #   )
+  #
+  # @see CreateNetwork
+  # @see ListNetworks
+  # @see Docker::Network#delete
+  # @since 0.1.0
+  class RemoveNetwork < MCP::Tool
+    description 'Remove a Docker network'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Network ID or name'
+        }
+      },
+      required: ['id']
+    )
+
+    # Remove a Docker network from the system.
+    #
+    # This method permanently deletes the specified network. The network
+    # must not have any containers connected to it, and built-in system
+    # networks cannot be removed.
+    #
+    # @param id [String] network ID or name to remove
+    # @param server_context [Object] MCP server context (unused but required)
+    #
+    # @return [MCP::Tool::Response] removal operation results
+    #
+    # @raise [Docker::Error::NotFoundError] if network doesn't exist
+    # @raise [StandardError] for removal failures or dependency conflicts
+    #
+    # @example Remove custom network
+    #   response = RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "frontend-network"
+    #   )
+    #
+    # @example Remove by ID
+    #   response = RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "1a2b3c4d5e6f"
+    #   )
+    #
+    # @see Docker::Network#delete
+    def self.call(id:, server_context:)
+      network = Docker::Network.get(id)
+      network.delete
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Network #{id} removed successfully"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Network #{id} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error removing network: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/remove_volume.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for removing Docker volumes.
+  #
+  # This tool provides the ability to permanently delete Docker volumes from
+  # the system. This is a destructive operation that will permanently delete
+  # all data stored in the volume.
+  #
+  # == Features
+  #
+  # - Remove Docker volumes by name
+  # - Force removal option for volumes in use
+  # - Comprehensive error handling
+  # - Dependency checking (prevents removal if containers are using the volume)
+  # - Safe cleanup of storage resources
+  #
+  # == ⚠️ CRITICAL DATA LOSS WARNING ⚠️
+  #
+  # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
+  #
+  # This operation permanently and irreversibly deletes data:
+  # - **ALL DATA** in the volume is deleted forever
+  # - No recovery possible after deletion
+  # - Applications may lose critical data
+  # - Databases and persistent state are destroyed
+  # - Configuration files and user data are lost
+  # - Operation cannot be undone
+  #
+  # == Volume Dependencies
+  #
+  # Volumes may have active dependencies:
+  # - **Running Containers**: Containers currently using the volume
+  # - **Stopped Containers**: Containers that could be restarted
+  # - **Application Data**: Critical application state and databases
+  # - **User Data**: User-generated content and files
+  #
+  # == Security Considerations
+  #
+  # Volume removal has security implications:
+  # - Sensitive data is not securely wiped
+  # - Data may be recoverable from disk sectors
+  # - Shared volumes may affect multiple applications
+  # - Removal logs may reveal data existence
+  #
+  # Critical security measures:
+  # - **Backup critical data** before removal
+  # - Verify no containers depend on the volume
+  # - Consider secure data wiping for sensitive volumes
+  # - Audit volume removal operations
+  # - Monitor for unauthorized volume deletions
+  #
+  # == Force Removal Risks
+  #
+  # Force removal bypasses safety checks:
+  # - Removes volumes even if containers are using them
+  # - Can cause immediate application failures
+  # - May corrupt running applications
+  # - Data loss occurs immediately
+  #
+  # == Example Usage
+  #
+  #   # Safe removal of unused volume
+  #   RemoveVolume.call(
+  #     server_context: context,
+  #     name: "temp-data"
+  #   )
+  #
+  #   # Force removal of volume in use (DANGEROUS)
+  #   RemoveVolume.call(
+  #     server_context: context,
+  #     name: "stuck-volume",
+  #     force: true
+  #   )
+  #
+  # @see CreateVolume
+  # @see ListVolumes
+  # @see Docker::Volume#remove
+  # @since 0.1.0
+  class RemoveVolume < MCP::Tool
+    description 'Remove a Docker volume'
+
+    input_schema(
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Volume name'
+        },
+        force: {
+          type: 'boolean',
+          description: 'Force removal of the volume (default: false)'
+        }
+      },
+      required: ['name']
+    )
+
+    # Remove a Docker volume permanently from the system.
+    #
+    # This method permanently deletes the specified volume and all data
+    # contained within it. By default, it performs safety checks to prevent
+    # removal of volumes with active container dependencies.
+    #
+    # @param name [String] name of the volume to remove
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param force [Boolean] whether to force removal despite dependencies (default: false)
+    #
+    # @return [MCP::Tool::Response] removal operation results
+    #
+    # @raise [Docker::Error::NotFoundError] if volume doesn't exist
+    # @raise [StandardError] for removal failures or dependency conflicts
+    #
+    # @example Remove unused volume
+    #   response = RemoveVolume.call(
+    #     server_context: context,
+    #     name: "old-cache-data"
+    #   )
+    #
+    # @example Force remove problematic volume
+    #   response = RemoveVolume.call(
+    #     server_context: context,
+    #     name: "corrupted-volume",
+    #     force: true
+    #   )
+    #
+    # @see Docker::Volume#remove
+    def self.call(name:, server_context:, force: false)
+      volume = Docker::Volume.get(name)
+      volume.remove(force: force)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Volume #{name} removed successfully"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Volume #{name} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error removing volume: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/run_container.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for running Docker containers (create and start in one operation).
+  #
+  # This tool provides a convenient way to create and immediately start Docker
+  # containers from images. It combines the functionality of container creation
+  # and startup into a single operation, which is the most common use case for
+  # Docker containers.
+  #
+  # == Features
+  #
+  # - Create and start containers in one operation
+  # - Full support for container configuration options
+  # - Port mapping and network configuration
+  # - Volume mounting capabilities
+  # - Environment variable configuration
+  # - Custom command execution
+  # - Comprehensive error handling
+  #
+  # == Security Considerations
+  #
+  # - Containers inherit Docker daemon privileges
+  # - Port mappings expose services to host network
+  # - Volume mounts provide filesystem access
+  # - Environment variables may contain sensitive data
+  # - Custom commands can execute arbitrary code
+  #
+  # Use appropriate security measures:
+  # - Run containers with minimal required privileges
+  # - Limit port exposure to necessary services only
+  # - Use read-only volumes where possible
+  # - Avoid mounting sensitive host directories
+  # - Validate environment variables for secrets
+  #
+  # == Example Usage
+  #
+  #   # Simple container run
+  #   RunContainer.call(
+  #     server_context: context,
+  #     image: "nginx:latest",
+  #     name: "web-server"
+  #   )
+  #
+  #   # Advanced configuration with ports and volumes
+  #   RunContainer.call(
+  #     server_context: context,
+  #     image: "postgres:13",
+  #     name: "database",
+  #     env: ["POSTGRES_PASSWORD=secret"],
+  #     host_config: {
+  #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
+  #       "Binds" => ["/host/data:/var/lib/postgresql/data"]
+  #     }
+  #   )
+  #
+  # @see CreateContainer
+  # @see StartContainer
+  # @see Docker::Container.create
+  # @since 0.1.0
+  class RunContainer < MCP::Tool
+    description 'Run a Docker container (create and start)'
+
+    input_schema(
+      properties: {
+        image: {
+          type: 'string',
+          description: 'Image name to use (e.g., "ubuntu:22.04")'
+        },
+        name: {
+          type: 'string',
+          description: 'Container name (optional)'
+        },
+        cmd: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Command to run (optional)'
+        },
+        env: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Environment variables as KEY=VALUE (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']
+    )
+
+    def self.call(image:, server_context:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil)
+      config = { 'Image' => image }
+      config['name'] = name if name
+      config['Cmd'] = cmd if cmd
+      config['Env'] = env if env
+      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('/')
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container started successfully. ID: #{container.id}, Name: #{container_name}"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{image} not found"
+                              }])
+    rescue Docker::Error::ConflictError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container with name #{name} already exists"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error running container: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/server.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP Server implementation for Docker management tools.
+  #
+  # The Server class initializes and configures a Model Context Protocol server
+  # with all available Docker management tools. It serves as the main entry point
+  # for Docker operations through the MCP interface.
+  #
+  # The server provides 22 comprehensive tools organized into four categories:
+  # - Container Management: 10 tools for container lifecycle operations
+  # - Image Management: 6 tools for Docker image operations
+  # - Network Management: 3 tools for Docker network operations
+  # - Volume Management: 3 tools for Docker volume operations
+  #
+  # == Security Considerations
+  #
+  # This server includes potentially dangerous tools that can:
+  # - Execute arbitrary commands in containers (ExecContainer)
+  # - Copy files between host and containers (CopyToContainer)
+  # - Create, modify, and delete Docker resources
+  #
+  # Ensure proper security measures when exposing this server to external clients.
+  #
+  # == Example Usage
+  #
+  #   # Initialize the server
+  #   server = DockerMCP::Server.new
+  #
+  #   # Access the underlying MCP server
+  #   mcp_server = server.server
+  #
+  #   # The server automatically registers all available tools
+  #
+  # @see MCP::Server
+  # @since 0.1.0
+  class Server
+    # The underlying MCP::Server instance.
+    #
+    # @return [MCP::Server] the configured MCP server with all Docker tools
+    attr_reader :server
+
+    # Initialize a new DockerMCP server with all available tools.
+    #
+    # Creates and configures an MCP::Server instance with all 22 Docker
+    # management tools. The tools are automatically loaded and registered
+    # with the server.
+    #
+    # Tools are registered in alphabetical order for consistency:
+    # - BuildImage: Build Docker images from Dockerfiles
+    # - CopyToContainer: Copy files/directories from host to container
+    # - CreateContainer: Create new containers from images
+    # - CreateNetwork: Create Docker networks
+    # - CreateVolume: Create Docker volumes
+    # - ExecContainer: Execute commands inside containers
+    # - FetchContainerLogs: Retrieve container logs
+    # - ListContainers: List all containers
+    # - ListImages: List all images
+    # - ListNetworks: List all networks
+    # - ListVolumes: List all volumes
+    # - PullImage: Pull images from registries
+    # - PushImage: Push images to registries
+    # - RecreateContainer: Recreate containers with same config
+    # - RemoveContainer: Delete containers
+    # - RemoveImage: Delete images
+    # - RemoveNetwork: Delete networks
+    # - RemoveVolume: Delete volumes
+    # - RunContainer: Create and start containers
+    # - StartContainer: Start existing containers
+    # - StopContainer: Stop running containers
+    # - TagImage: Tag images with new names
+    #
+    # @example Initialize server
+    #   server = DockerMCP::Server.new
+    #   puts server.server.tools.length # => 22
+    #
+    # @see MCP::Server#new
+    def initialize
+      @server = MCP::Server.new(
+        name: 'docker_mcp',
+        tools: [
+          BuildImage,
+          CopyToContainer,
+          CreateContainer,
+          CreateNetwork,
+          CreateVolume,
+          ExecContainer,
+          FetchContainerLogs,
+          ListContainers,
+          ListImages,
+          ListNetworks,
+          ListVolumes,
+          PullImage,
+          PushImage,
+          RecreateContainer,
+          RemoveContainer,
+          RemoveImage,
+          RemoveNetwork,
+          RemoveVolume,
+          RunContainer,
+          StartContainer,
+          StopContainer,
+          TagImage
+        ]
+      )
+    end
+  end
+end

data/lib/docker_mcp/start_container.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for starting existing Docker containers.
+  #
+  # This tool provides the ability to start Docker containers that have been
+  # created but are currently stopped. It's the counterpart to StopContainer
+  # and is commonly used after CreateContainer or when restarting stopped
+  # containers.
+  #
+  # == Features
+  #
+  # - Start stopped containers by ID or name
+  # - Simple and reliable container lifecycle management
+  # - Comprehensive error handling
+  # - Works with containers in any stopped state
+  #
+  # == Security Considerations
+  #
+  # Starting containers can have security implications:
+  # - Containers resume with their original configuration
+  # - Services become accessible on mapped ports
+  # - Processes resume execution with previous privileges
+  # - Network connections are re-established
+  #
+  # Ensure containers are properly configured before starting:
+  # - Review port mappings and network exposure
+  # - Verify volume mounts and file permissions
+  # - Check environment variables for sensitive data
+  # - Validate container image integrity
+  #
+  # == Example Usage
+  #
+  #   # Start container by name
+  #   StartContainer.call(
+  #     server_context: context,
+  #     id: "web-server"
+  #   )
+  #
+  #   # Start container by ID
+  #   StartContainer.call(
+  #     server_context: context,
+  #     id: "a1b2c3d4e5f6"
+  #   )
+  #
+  # @see CreateContainer
+  # @see StopContainer
+  # @see RunContainer
+  # @see Docker::Container#start
+  # @since 0.1.0
+  class StartContainer < MCP::Tool
+    description 'Start a Docker container'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Container ID or name'
+        }
+      },
+      required: ['id']
+    )
+
+    # Start an existing Docker container.
+    #
+    # This method starts a container that is currently in a stopped state.
+    # The container must already exist and be in a startable state. If the
+    # container is already running, Docker will typically ignore the start
+    # command without error.
+    #
+    # @param id [String] container ID (full or short) or container name
+    # @param server_context [Object] MCP server context (unused but required)
+    #
+    # @return [MCP::Tool::Response] start operation results
+    #
+    # @raise [Docker::Error::NotFoundError] if container doesn't exist
+    # @raise [StandardError] for other start failures
+    #
+    # @example Start by container name
+    #   response = StartContainer.call(
+    #     server_context: context,
+    #     id: "my-app-container"
+    #   )
+    #
+    # @example Start by container ID
+    #   response = StartContainer.call(
+    #     server_context: context,
+    #     id: "abc123def456"
+    #   )
+    #
+    # @see Docker::Container#start
+    def self.call(id:, server_context:)
+      container = Docker::Container.get(id)
+      container.start
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container #{id} started successfully"
+                              }])
+    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 starting container: #{e.message}"
+                              }])
+    end
+  end
+end