docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/run_container.rb

@@ -1,97 +1,97 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for running Docker containers (create and start in one operation).
+  # MCP tool for running Docker containers.
   #
-  # 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.
+  # This tool creates and immediately starts a Docker container from a
+  # specified image in a single operation. It combines the functionality
+  # of create_container and start_container for convenience when immediate
+  # execution is desired.
   #
   # == 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
+  # - Creates and starts containers in one operation
+  # - Supports all container configuration options
+  # - Configures command execution and environment variables
+  # - Sets up port exposure and network configuration
+  # - Applies advanced host configurations and volume mounts
+  # - Handles container naming and labeling
   #
   # == 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
+  # Running containers involves significant security considerations:
+  # - **Immediate Execution**: Starts processes immediately upon creation
+  # - **Resource Consumption**: Consumes CPU, memory, and storage resources
+  # - **Network Exposure**: Creates active network endpoints
+  # - **File System Access**: Potentially accesses host directories
+  # - **Process Isolation**: Runs processes with configured privileges
   #
-  # 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
+  # Implement strict access controls and resource monitoring.
+  #
+  # == 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 run
-  #   RunContainer.call(
+  #   # Simple container execution
+  #   response = RunContainer.call(
   #     server_context: context,
-  #     image: "nginx:latest",
-  #     name: "web-server"
+  #     image: "alpine:latest",
+  #     cmd: "echo 'Hello World'"
   #   )
   #
-  #   # Advanced configuration with ports and volumes
-  #   RunContainer.call(
+  #   # Web server with port binding
+  #   response = RunContainer.call(
   #     server_context: context,
-  #     image: "postgres:13",
-  #     name: "database",
-  #     env: "POSTGRES_PASSWORD=secret,POSTGRES_DB=myapp",
+  #     image: "nginx:latest",
+  #     name: "web-server",
+  #     exposed_ports: {"80/tcp" => {}},
   #     host_config: {
-  #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
-  #       "Binds" => ["/host/data:/var/lib/postgresql/data"]
+  #       "PortBindings" => {"80/tcp" => [{"HostPort" => "8080"}]}
   #     }
   #   )
   #
-  # @see CreateContainer
-  # @see StartContainer
   # @see Docker::Container.create
   # @since 0.1.0
-  class RunContainer < MCP::Tool
+  RUN_CONTAINER_DEFINITION = ToolForge.define(:run_container) do
     description 'Run a Docker container (create and start)'
 
-    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']
-    )
 
-    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
 
@@ -108,25 +108,15 @@ module DockerMCP
       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}"
-                              }])
+      "Container started 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 running container: #{e.message}"
-                              }])
+      "Error running container: #{e.message}"
     end
   end
+
+  RunContainer = RUN_CONTAINER_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/start_container.rb

@@ -1,112 +1,72 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for starting existing Docker containers.
+  # MCP tool for starting 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.
+  # This tool starts a previously created Docker container that is currently
+  # in a "created" or "stopped" state. It transitions the container to a
+  # "running" state and begins executing the configured command or entrypoint.
   #
   # == Features
   #
-  # - Start stopped containers by ID or name
-  # - Simple and reliable container lifecycle management
-  # - Comprehensive error handling
-  # - Works with containers in any stopped state
+  # - Starts containers by ID or name
+  # - Supports both short and full container IDs
+  # - Works with custom container names
+  # - Provides clear success/failure feedback
+  # - Handles container state transitions
+  # - Preserves all container configuration
   #
   # == 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
+  # Starting containers involves security implications:
+  # - **Process Execution**: Begins running container processes
+  # - **Resource Activation**: Activates CPU, memory, and I/O usage
+  # - **Network Activation**: Brings network interfaces online
+  # - **Service Exposure**: Makes configured services accessible
   #
-  # 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
+  # Ensure proper monitoring and access controls are in place.
+  #
+  # == Parameters
+  #
+  # - **id**: Container ID or name (required)
+  #   - Accepts full container IDs
+  #   - Accepts short container IDs (first 12+ characters)
+  #   - Accepts custom container names
   #
   # == Example Usage
   #
-  #   # Start container by name
-  #   StartContainer.call(
+  #   # Start by container name
+  #   response = StartContainer.call(
   #     server_context: context,
   #     id: "web-server"
   #   )
   #
-  #   # Start container by ID
-  #   StartContainer.call(
+  #   # Start by container ID
+  #   response = 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
+  START_CONTAINER_DEFINITION = ToolForge.define(:start_container) do
     description 'Start a Docker container'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :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:)
+    execute do |id:|
       container = Docker::Container.get(id)
       container.start
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container #{id} started successfully"
-                              }])
+      "Container #{id} started successfully"
     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 starting container: #{e.message}"
-                              }])
+      "Error starting container: #{e.message}"
     end
   end
+
+  StartContainer = START_CONTAINER_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/stop_container.rb

@@ -1,126 +1,81 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for stopping running Docker containers.
+  # MCP tool for stopping Docker containers.
   #
-  # This tool provides the ability to gracefully stop running Docker containers
-  # with configurable timeout handling. It sends a SIGTERM signal to the main
-  # process and waits for the specified timeout before forcibly killing the
-  # container with SIGKILL.
+  # This tool gracefully stops a running Docker container by sending a
+  # SIGTERM signal to the main process, allowing it to shut down cleanly.
+  # If the container doesn't stop within the specified timeout, it will
+  # be forcefully killed with SIGKILL.
   #
   # == Features
   #
   # - Graceful container shutdown with SIGTERM
-  # - Configurable timeout before force kill
-  # - Works with containers by ID or name
-  # - Comprehensive error handling
-  # - Safe for already stopped containers
-  #
-  # == Shutdown Process
-  #
-  # 1. Send SIGTERM to container's main process
-  # 2. Wait for graceful shutdown up to timeout
-  # 3. Send SIGKILL if container hasn't stopped
-  # 4. Return success when container is stopped
+  # - Configurable timeout for forced termination
+  # - Supports container identification by ID or name
+  # - Handles both running and already-stopped containers
+  # - Provides clear feedback on operation status
+  # - Preserves container and data integrity
   #
   # == Security Considerations
   #
   # Stopping containers affects service availability:
-  # - Services become unavailable immediately
-  # - Network connections are terminated
-  # - Data may be lost if not properly persisted
-  # - Dependent services may be affected
+  # - **Service Disruption**: Terminates running services and processes
+  # - **Data Integrity**: May interrupt ongoing operations
+  # - **Resource Release**: Frees CPU, memory, and network resources
+  # - **State Preservation**: Maintains container state for future restart
+  #
+  # Coordinate container stops with dependent services and users.
   #
-  # Best practices:
-  # - Ensure data persistence before stopping
-  # - Consider impact on dependent services
-  # - Use appropriate timeout for graceful shutdown
-  # - Monitor application logs during shutdown
+  # == Parameters
+  #
+  # - **id**: Container ID or name (required)
+  #   - Accepts full container IDs
+  #   - Accepts short container IDs (first 12+ characters)
+  #   - Accepts custom container names
+  # - **timeout**: Seconds to wait before killing container (optional, default: 10)
   #
   # == Example Usage
   #
-  #   # Stop with default timeout (10 seconds)
-  #   StopContainer.call(
+  #   # Stop with default timeout
+  #   response = StopContainer.call(
   #     server_context: context,
   #     id: "web-server"
   #   )
   #
   #   # Stop with custom timeout
-  #   StopContainer.call(
+  #   response = StopContainer.call(
   #     server_context: context,
   #     id: "database",
   #     timeout: 30
   #   )
   #
-  # @see StartContainer
-  # @see RemoveContainer
   # @see Docker::Container#stop
   # @since 0.1.0
-  class StopContainer < MCP::Tool
+  STOP_CONTAINER_DEFINITION = ToolForge.define(:stop_container) do
     description 'Stop a Docker container'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :id,
+          type: :string,
           description: 'Container ID or name'
-        },
-        timeout: {
-          type: 'integer',
-          description: 'Seconds to wait before killing the container (default: 10)'
-        }
-      },
-      required: ['id']
-    )
 
-    # Stop a running Docker container gracefully.
-    #
-    # This method stops a container by sending SIGTERM to the main process
-    # and waiting for the specified timeout before sending SIGKILL. The
-    # operation is idempotent - stopping an already stopped container
-    # typically succeeds without error.
-    #
-    # @param id [String] container ID (full or short) or container name
-    # @param server_context [Object] MCP server context (unused but required)
-    # @param timeout [Integer] seconds to wait before force killing (default: 10)
-    #
-    # @return [MCP::Tool::Response] stop operation results
-    #
-    # @raise [Docker::Error::NotFoundError] if container doesn't exist
-    # @raise [StandardError] for other stop failures
-    #
-    # @example Stop with default timeout
-    #   response = StopContainer.call(
-    #     server_context: context,
-    #     id: "nginx-server"
-    #   )
-    #
-    # @example Stop database with longer timeout
-    #   response = StopContainer.call(
-    #     server_context: context,
-    #     id: "postgres-db",
-    #     timeout: 60  # Allow more time for DB shutdown
-    #   )
-    #
-    # @see Docker::Container#stop
-    def self.call(id:, server_context:, timeout: 10)
+    param :timeout,
+          type: :integer,
+          description: 'Seconds to wait before killing the container (default: 10)',
+          required: false,
+          default: 10
+
+    execute do |id:, timeout: 10|
       container = Docker::Container.get(id)
       container.stop('timeout' => timeout)
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Container #{id} stopped successfully"
-                              }])
+      "Container #{id} stopped successfully"
     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 stopping container: #{e.message}"
-                              }])
+      "Error stopping container: #{e.message}"
     end
   end
+
+  StopContainer = STOP_CONTAINER_DEFINITION.to_mcp_tool
 end