docker_mcp 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efb62c57572aa0d7838b21fb503cc82d4d29b1b7a4b67a56a73403abf95569cd
-  data.tar.gz: 659cee10a2d4bb77b2a4dabe5acf47c63415e17e67b34f3046eb5bbb149ca9a1
+  metadata.gz: 0b93e5e574efb910b42bf12e0fe976966fadf8671644d39427fc3e0c9123ddd8
+  data.tar.gz: 693331e50cf5a4232f71e6a1d4eff6ad9df4c23d7c844140e1b25029384dc80f
 SHA512:
-  metadata.gz: f24eb8a997aa33b2a4389170fd3d938d9ac0e00fec6f437074497ddfc260d81a8390b61b883caf35901d19f34af271b1d8d32f3b5ff24ca51dea9c885cb9e7c7
-  data.tar.gz: 68672e9b0c1432fa2575aea0034d4d4d74e872d83da97456d2fc0cc698249fd643d9325cfc9ed25223f3832b980926212fc98d228d135a10180c7cdd8ea8e0d5
+  metadata.gz: bc6c784c575e29641377539be524b108bb6cf36535470eed017daf5e8df06b12254d62f91c62f6e471a9060fdfb0365e08d08b1252c2d7e05287bf82a93d981d
+  data.tar.gz: c968b9d93685216e023ccfd88fe95fffb93ba64d7305d671f0e3b8e970d4775cd66593dd582c8f4ea7ed4a2f4cd7cf6383a4d49441e7468ed89ffcc81c3e9b0d

data/lib/docker_mcp/build_image.rb

@@ -1,104 +1,90 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for building Docker images from Dockerfile content.
+  # MCP tool for building Docker images.
   #
-  # This tool provides the ability to build Docker images by providing Dockerfile
-  # content as a string. It supports optional tagging of the resulting image for
-  # easy identification and reuse.
+  # This tool provides the ability to build Docker images from Dockerfile
+  # content. It creates custom images by executing Dockerfile instructions
+  # and supports comprehensive build configuration including tagging and
+  # build arguments.
+  #
+  # == Features
+  #
+  # - Build images from Dockerfile content strings
+  # - Support for custom image tagging
+  # - Comprehensive build output and error reporting
+  # - Handles all standard Dockerfile instructions
+  # - Build context management
+  # - Progress tracking and logging
   #
   # == Security Considerations
   #
-  # Building Docker images can be potentially dangerous:
-  # - Dockerfile commands execute with Docker daemon privileges
-  # - Images can contain malicious software or backdoors
-  # - Build process can access host resources (network, files)
-  # - Base images may contain vulnerabilities
-  # - Build context may expose sensitive information
+  # Image building involves significant security risks:
+  # - **Code Execution**: Dockerfile RUN commands execute arbitrary code
+  # - **Network Access**: Build process can access networks and repositories
+  # - **File System Access**: Can read local files and directories
+  # - **Credential Exposure**: May expose build-time secrets and credentials
+  # - **Supply Chain Risk**: Downloaded packages may contain malware
+  # - **Resource Consumption**: Builds can consume significant CPU, memory, and storage
   #
-  # Security recommendations:
-  # - Review Dockerfile content carefully before building
-  # - Use trusted base images from official repositories
+  # **Security Recommendations**:
+  # - Review all Dockerfile content before building
+  # - Use trusted base images only
+  # - Avoid embedding secrets in image layers
+  # - Implement build isolation and sandboxing
+  # - Monitor build resource consumption
   # - Scan built images for vulnerabilities
-  # - Limit network access during builds
-  # - Avoid including secrets in Dockerfile instructions
-  # - Use multi-stage builds to minimize final image size
+  # - Use multi-stage builds to minimize attack surface
   #
-  # == Features
+  # == Parameters
   #
-  # - Build images from Dockerfile content strings
-  # - Optional image tagging during build
-  # - Comprehensive error handling
-  # - Support for all standard Dockerfile instructions
-  # - Returns image ID and build status
+  # - **dockerfile**: Dockerfile content as a string (required)
+  # - **tag**: Tag for the built image (optional, e.g., "myimage:latest")
   #
   # == Example Usage
   #
-  #   # Simple image build
-  #   BuildImage.call(
+  #   # Build simple image
+  #   dockerfile_content = <<~DOCKERFILE
+  #     FROM alpine:latest
+  #     RUN apk add --no-cache curl
+  #     CMD ["curl", "--version"]
+  #   DOCKERFILE
+  #
+  #   response = BuildImage.call(
   #     server_context: context,
-  #     dockerfile: "FROM alpine:latest\nRUN apk add --no-cache curl"
+  #     dockerfile: dockerfile_content,
+  #     tag: "my-curl:latest"
   #   )
   #
-  #   # Build with custom tag
-  #   BuildImage.call(
+  #   # Build web server image
+  #   dockerfile_content = <<~DOCKERFILE
+  #     FROM nginx:alpine
+  #     COPY nginx.conf /etc/nginx/nginx.conf
+  #     EXPOSE 80
+  #     CMD ["nginx", "-g", "daemon off;"]
+  #   DOCKERFILE
+  #
+  #   response = BuildImage.call(
   #     server_context: context,
   #     dockerfile: dockerfile_content,
-  #     tag: "myapp:v1.0"
+  #     tag: "custom-nginx:v1.0"
   #   )
   #
-  # @see Docker::Image.build
-  # @see TagImage
+  # @see Docker::Image.build_from_dir
   # @since 0.1.0
-  class BuildImage < MCP::Tool
+  BUILD_IMAGE_DEFINITION = ToolForge.define(:build_image) do
     description 'Build a Docker image'
 
-    input_schema(
-      properties: {
-        dockerfile: {
-          type: 'string',
+    param :dockerfile,
+          type: :string,
           description: 'Dockerfile content as a string'
-        },
-        tag: {
-          type: 'string',
-          description: 'Tag for the built image (e.g., "myimage:latest")'
-        }
-      },
-      required: ['dockerfile']
-    )
 
-    # Build a Docker image from Dockerfile content.
-    #
-    # This method creates a Docker image by building from the provided Dockerfile
-    # content string. The Dockerfile is processed by the Docker daemon and can
-    # include any valid Dockerfile instructions. Optionally, the resulting image
-    # can be tagged with a custom name for easy reference.
-    #
-    # @param dockerfile [String] the complete Dockerfile content as a string
-    # @param server_context [Object] MCP server context (unused but required)
-    # @param tag [String, nil] optional tag to apply to the built image
-    #
-    # @return [MCP::Tool::Response] build results including image ID and tag info
-    #
-    # @raise [Docker::Error] for Docker daemon communication errors
-    # @raise [StandardError] for build failures or other errors
-    #
-    # @example Build simple image
-    #   dockerfile = <<~DOCKERFILE
-    #     FROM alpine:latest
-    #     RUN apk add --no-cache nginx
-    #     EXPOSE 80
-    #     CMD ["nginx", "-g", "daemon off;"]
-    #   DOCKERFILE
-    #
-    #   response = BuildImage.call(
-    #     server_context: context,
-    #     dockerfile: dockerfile,
-    #     tag: "my-nginx:latest"
-    #   )
-    #
-    # @see Docker::Image.build
-    def self.call(dockerfile:, server_context:, tag: nil)
+    param :tag,
+          type: :string,
+          description: 'Tag for the built image (e.g., "myimage:latest")',
+          required: false
+
+    execute do |dockerfile:, tag: nil|
       # Build the image
       image = Docker::Image.build(dockerfile)
 
@@ -112,16 +98,11 @@ module DockerMCP
 
       response_text = "Image built successfully. ID: #{image.id}"
       response_text += ", Tag: #{tag}" if tag
-
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: response_text
-                              }])
+      response_text
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error building image: #{e.message}"
-                              }])
+      "Error building image: #{e.message}"
     end
   end
+
+  BuildImage = BUILD_IMAGE_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/copy_to_container.rb

@@ -1,135 +1,117 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for copying files and directories from host to Docker containers.
+  # MCP tool for copying files and directories to Docker containers.
   #
-  # This tool provides the ability to copy files or entire directory trees from
-  # the host filesystem into running Docker containers. It uses Docker's archive
-  # streaming API to efficiently transfer files while preserving permissions and
-  # directory structure.
+  # This tool provides the ability to copy files and directories from the
+  # local host filesystem into running Docker containers. It supports both
+  # individual files and entire directory trees, with optional ownership
+  # modification within the container.
   #
-  # == ⚠️ SECURITY WARNING ⚠️
+  # == Features
   #
-  # This tool can be dangerous as it allows:
-  # - Reading arbitrary files from the host filesystem
-  # - Writing files into container filesystems
-  # - Potentially overwriting critical container files
-  # - Escalating privileges if used with setuid/setgid files
-  # - Exposing sensitive host data to containers
+  # - Copy files and directories from host to container
+  # - Supports recursive directory copying
+  # - Preserves file permissions and metadata
+  # - Optional ownership modification after copy
+  # - Works with running containers
+  # - Comprehensive error handling and validation
   #
-  # Security recommendations:
-  # - Validate source paths to prevent directory traversal
-  # - Ensure containers run with minimal privileges
-  # - Monitor file copy operations for sensitive paths
-  # - Use read-only filesystems where possible
-  # - Implement proper access controls on source files
+  # == Security Considerations
   #
-  # == Features
+  # File copying operations have significant security implications:
+  # - **File System Access**: Reads local host file system content
+  # - **Container Modification**: Alters container file system state
+  # - **Data Injection**: Can introduce malicious files into containers
+  # - **Permission Escalation**: May affect container security context
+  # - **Resource Consumption**: Large copies can consume storage and I/O
+  # - **Path Traversal**: Improper paths could access unintended locations
+  #
+  # **Security Recommendations**:
+  # - Validate and sanitize all file paths
+  # - Implement access controls for source file locations
+  # - Monitor file copy operations and sizes
+  # - Use read-only mounts where possible
+  # - Apply resource limits to prevent abuse
+  #
+  # == Parameters
   #
-  # - Copy individual files or entire directories
-  # - Preserve file permissions and directory structure
-  # - Optional ownership changes after copy
-  # - Comprehensive error handling
-  # - Support for both absolute and relative paths
+  # - **id**: Container ID or name (required)
+  # - **source_path**: Path to file/directory on local filesystem (required)
+  # - **destination_path**: Path inside container for copied content (required)
+  # - **owner**: Owner for copied files (optional, e.g., "1000:1000" or "username:group")
   #
   # == Example Usage
   #
-  #   # Copy a configuration file
-  #   CopyToContainer.call(
+  #   # Copy single file
+  #   response = CopyToContainer.call(
   #     server_context: context,
   #     id: "web-server",
-  #     source_path: "/host/config/nginx.conf",
-  #     destination_path: "/etc/nginx/"
+  #     source_path: "/local/config.conf",
+  #     destination_path: "/etc/nginx/nginx.conf"
   #   )
   #
   #   # Copy directory with ownership change
-  #   CopyToContainer.call(
+  #   response = CopyToContainer.call(
   #     server_context: context,
   #     id: "app-container",
-  #     source_path: "/host/app/src",
-  #     destination_path: "/app/",
-  #     owner: "appuser:appgroup"
+  #     source_path: "/local/app-data",
+  #     destination_path: "/var/lib/app",
+  #     owner: "app:app"
   #   )
   #
   # @see Docker::Container#archive_in_stream
   # @since 0.1.0
-  class CopyToContainer < MCP::Tool
+  COPY_TO_CONTAINER_DEFINITION = ToolForge.define(:copy_to_container) do
     description 'Copy a file or directory from the local filesystem into a running Docker container. ' \
                 'The source path is on the local machine, and the destination path is inside the container.'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :id,
+          type: :string,
           description: 'Container ID or name'
-        },
-        source_path: {
-          type: 'string',
+
+    param :source_path,
+          type: :string,
           description: 'Path to the file or directory on the local filesystem to copy'
-        },
-        destination_path: {
-          type: 'string',
+
+    param :destination_path,
+          type: :string,
           description: 'Path inside the container where the file/directory should be copied'
-        },
-        owner: {
-          type: 'string',
-          description: 'Owner for the copied files (optional, e.g., "1000:1000" or "username:group")'
-        }
-      },
-      required: %w[id source_path destination_path]
-    )
-
-    # Copy files or directories from host filesystem to a Docker container.
-    #
-    # This method creates a tar archive of the source path and streams it into
-    # the specified container using Docker's archive API. The operation preserves
-    # file permissions and directory structure. Optionally, ownership can be
-    # changed after the copy operation completes.
-    #
-    # The source path must exist on the host filesystem and be readable by the
-    # process running the MCP server. The destination path must be a valid path
-    # within the container.
-    #
-    # @param id [String] container ID or name to copy files into
-    # @param source_path [String] path to file/directory on host filesystem
-    # @param destination_path [String] destination path inside container
-    # @param server_context [Object] MCP server context (unused but required)
-    # @param owner [String, nil] ownership specification (e.g., "user:group", "1000:1000")
-    #
-    # @return [MCP::Tool::Response] success/failure message with operation details
-    #
-    # @raise [Docker::Error::NotFoundError] if container doesn't exist
-    # @raise [StandardError] for file system or Docker API errors
-    #
-    # @example Copy configuration file
-    #   response = CopyToContainer.call(
-    #     server_context: context,
-    #     id: "nginx-container",
-    #     source_path: "/etc/nginx/sites-available/default",
-    #     destination_path: "/etc/nginx/sites-enabled/"
-    #   )
-    #
-    # @example Copy directory with ownership
-    #   response = CopyToContainer.call(
-    #     server_context: context,
-    #     id: "app-container",
-    #     source_path: "/local/project",
-    #     destination_path: "/app/",
-    #     owner: "www-data:www-data"
-    #   )
-    #
-    # @see Docker::Container#archive_in_stream
-    # @see #add_to_tar
-    def self.call(id:, source_path:, destination_path:, server_context:, owner: nil)
+
+    param :owner,
+          type: :string,
+          description: 'Owner for the copied files (optional, e.g., "1000:1000" or "username:group")',
+          required: false
+
+    # Helper method for adding files/directories to tar
+    class_helper :add_to_tar do |tar, path, archive_path|
+      if File.directory?(path)
+        # Add directory entry
+        tar.mkdir(archive_path, File.stat(path).mode)
+
+        # Add directory contents
+        Dir.entries(path).each do |entry|
+          next if ['.', '..'].include?(entry)
+
+          full_path = File.join(path, entry)
+          archive_entry_path = File.join(archive_path, entry)
+          add_to_tar(tar, full_path, archive_entry_path)
+        end
+      else
+        # Add file
+        File.open(path, 'rb') do |file|
+          tar.add_file_simple(archive_path, File.stat(path).mode, file.size) do |tar_file|
+            IO.copy_stream(file, tar_file)
+          end
+        end
+      end
+    end
+
+    execute do |id:, source_path:, destination_path:, owner: nil|
       container = Docker::Container.get(id)
 
       # Verify source path exists
-      unless File.exist?(source_path)
-        return MCP::Tool::Response.new([{
-                                         type: 'text',
-                                         text: "Source path not found: #{source_path}"
-                                       }])
-      end
+      next "Source path not found: #{source_path}" unless File.exist?(source_path)
 
       # Create a tar archive of the source
       tar_io = StringIO.new
@@ -155,69 +137,13 @@ module DockerMCP
       file_type = File.directory?(source_path) ? 'directory' : 'file'
       response_text = "Successfully copied #{file_type} from #{source_path} to #{id}:#{destination_path}"
       response_text += "\nOwnership changed to #{owner}" if owner
-
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: response_text
-                              }])
+      response_text
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container #{id} not found"
-                              }])
+      "Container #{id} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error copying to container: #{e.message}"
-                              }])
-    end
-
-    # Recursively add files and directories to a tar archive.
-    #
-    # This helper method builds a tar archive by recursively traversing
-    # the filesystem starting from the given path. It preserves file
-    # permissions and handles both files and directories appropriately.
-    #
-    # For directories, it creates directory entries in the tar and then
-    # recursively processes all contained files and subdirectories.
-    # For files, it reads the content and adds it to the tar with
-    # preserved permissions.
-    #
-    # @param tar [Gem::Package::TarWriter] the tar writer instance
-    # @param path [String] the filesystem path to add to the archive
-    # @param archive_path [String] the path within the tar archive
-    #
-    # @return [void]
-    #
-    # @example Add single file
-    #   add_to_tar(tar_writer, "/host/file.txt", "file.txt")
-    #
-    # @example Add directory tree
-    #   add_to_tar(tar_writer, "/host/mydir", "mydir")
-    #
-    # @see Gem::Package::TarWriter#mkdir
-    # @see Gem::Package::TarWriter#add_file_simple
-    def self.add_to_tar(tar, path, archive_path)
-      if File.directory?(path)
-        # Add directory entry
-        tar.mkdir(archive_path, File.stat(path).mode)
-
-        # Add directory contents
-        Dir.entries(path).each do |entry|
-          next if ['.', '..'].include?(entry)
-
-          full_path = File.join(path, entry)
-          archive_entry_path = File.join(archive_path, entry)
-          add_to_tar(tar, full_path, archive_entry_path)
-        end
-      else
-        # Add file
-        File.open(path, 'rb') do |file|
-          tar.add_file_simple(archive_path, File.stat(path).mode, file.size) do |tar_file|
-            IO.copy_stream(file, tar_file)
-          end
-        end
-      end
+      "Error copying to container: #{e.message}"
     end
   end
+
+  CopyToContainer = COPY_TO_CONTAINER_DEFINITION.to_mcp_tool
 end