docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/exec_container.rb

@@ -1,167 +1,124 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for executing commands inside running Docker containers.
+  # MCP tool for executing commands inside Docker containers.
   #
-  # This tool provides the ability to execute arbitrary commands inside running
-  # Docker containers, with full control over execution environment including
-  # working directory, user context, environment variables, and stdin input.
+  # This tool provides the ability to execute arbitrary commands inside
+  # running Docker containers. It supports interactive and non-interactive
+  # execution, environment variable injection, working directory specification,
+  # and user context switching within the container.
   #
-  # == ⚠️ CRITICAL SECURITY WARNING ⚠️
+  # == Features
   #
-  # This tool is EXTREMELY DANGEROUS as it allows arbitrary command execution
-  # within Docker containers. This can be used to:
-  # - Execute malicious code inside containers
-  # - Access sensitive data within container filesystems
-  # - Escalate privileges if container is poorly configured
-  # - Perform lateral movement within containerized environments
-  # - Exfiltrate data from applications
+  # - Execute arbitrary commands in running containers
+  # - Support for command arguments and shell parsing
+  # - Environment variable injection
+  # - Working directory specification
+  # - User context switching (run as specific user)
+  # - Standard input, output, and error handling
+  # - Configurable execution timeouts
   #
-  # ONLY use this tool in trusted environments with proper security controls:
-  # - Ensure containers run with minimal privileges
-  # - Use read-only filesystems where possible
-  # - Implement proper network segmentation
-  # - Monitor and audit all command executions
-  # - Never expose this tool to untrusted clients
+  # == Security Considerations
   #
-  # == Features
+  # **CRITICAL WARNING**: This tool provides arbitrary command execution
+  # capabilities with significant security implications:
+  #
+  # - **Code Execution**: Can run any command available in the container
+  # - **File System Access**: Can read, write, and modify container files
+  # - **Network Access**: Can initiate network connections from container
+  # - **Process Manipulation**: Can start, stop, and signal processes
+  # - **Data Exposure**: Can access sensitive data within the container
+  # - **Privilege Escalation**: May exploit container or kernel vulnerabilities
+  # - **Resource Consumption**: Can consume container and host resources
+  #
+  # **Security Recommendations**:
+  # - Implement strict access controls and authentication
+  # - Use dedicated execution containers with minimal privileges
+  # - Monitor and log all command executions
+  # - Apply resource limits and timeouts
+  # - Validate and sanitize all command inputs
+  # - Consider using read-only file systems where possible
+  # - Implement network segmentation for container environments
   #
-  # - Execute commands with custom working directory
-  # - Run commands as specific users
-  # - Set custom environment variables
-  # - Provide stdin input to commands
-  # - Configurable timeout protection
-  # - Comprehensive error handling
-  # - Separate stdout/stderr capture
+  # == Parameters
+  #
+  # - **id**: Container ID or name (required)
+  # - **cmd**: Command to execute (shell-parsed into arguments) (required)
+  # - **working_dir**: Working directory for command execution (optional)
+  # - **user**: User to run the command as (optional, e.g., "1000" or "username")
+  # - **env**: Environment variables as comma-separated KEY=VALUE pairs (optional)
+  # - **stdin**: Input to send to command via stdin (optional)
+  # - **timeout**: Timeout in seconds (optional, default: 60)
   #
   # == Example Usage
   #
-  #   # Simple command execution
-  #   ExecContainer.call(
+  #   # Basic command execution
+  #   response = ExecContainer.call(
   #     server_context: context,
-  #     id: "my-container",
-  #     cmd: "ls -la /app"
+  #     id: "web-container",
+  #     cmd: "nginx -t"
   #   )
   #
-  #   # Advanced execution with custom environment
-  #   ExecContainer.call(
+  #   # Advanced execution with environment
+  #   response = ExecContainer.call(
   #     server_context: context,
-  #     id: "web-server",
-  #     cmd: "python manage.py migrate",
+  #     id: "app-container",
+  #     cmd: "bundle exec rails console",
   #     working_dir: "/app",
-  #     user: "appuser",
-  #     env: "DJANGO_ENV=production,DEBUG=false",
-  #     timeout: 120
+  #     user: "rails",
+  #     env: "RAILS_ENV=production,DEBUG=true",
+  #     timeout: 300
   #   )
   #
   # @see Docker::Container#exec
   # @since 0.1.0
-  class ExecContainer < MCP::Tool
+  EXEC_CONTAINER_DEFINITION = ToolForge.define(:exec_container) do
     description 'Execute a command inside a running Docker container. ' \
                 'WARNING: This provides arbitrary command execution within the container. ' \
                 'Ensure proper security measures are in place.'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :id,
+          type: :string,
           description: 'Container ID or name'
-        },
-        cmd: {
-          type: 'string',
+
+    param :cmd,
+          type: :string,
           description: 'Command to execute (e.g., "ls -la /app" or "python script.py")'
-        },
-        working_dir: {
-          type: 'string',
-          description: 'Working directory for the command (optional)'
-        },
-        user: {
-          type: 'string',
-          description: 'User to run the command as (optional, e.g., "1000" or "username")'
-        },
-        env: {
-          type: 'string',
-          description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)'
-        },
-        stdin: {
-          type: 'string',
-          description: 'Input to send to the command via stdin (optional)'
-        },
-        timeout: {
-          type: 'integer',
-          description: 'Timeout in seconds (optional, default: 60)'
-        }
-      },
-      required: %w[id cmd]
-    )
-
-    # Execute a command inside a running Docker container.
-    #
-    # This method provides comprehensive command execution capabilities within
-    # Docker containers, including advanced features like custom user context,
-    # environment variables, working directory, and stdin input.
-    #
-    # The command is parsed using shell-like syntax with support for quoted
-    # arguments. Output is captured separately for stdout and stderr, and
-    # the exit code is reported.
-    #
-    # @param id [String] container ID or name to execute command in
-    # @param cmd [String] command to execute (shell-parsed into arguments)
-    # @param server_context [Object] MCP server context (unused but required)
-    # @param working_dir [String, nil] working directory for command execution
-    # @param user [String, nil] user to run command as (username or UID)
-    # @param env [String, nil] environment variables as comma-separated KEY=VALUE pairs
-    # @param stdin [String, nil] input to send to command via stdin
-    # @param timeout [Integer] maximum execution time in seconds (default: 60)
-    #
-    # @return [MCP::Tool::Response] execution results including stdout, stderr, and exit code
-    #
-    # @raise [Docker::Error::NotFoundError] if container doesn't exist
-    # @raise [Docker::Error::TimeoutError] if execution exceeds timeout
-    # @raise [StandardError] for other execution failures
-    #
-    # @example Basic command execution
-    #   response = ExecContainer.call(
-    #     server_context: context,
-    #     id: "web-container",
-    #     cmd: "nginx -t"
-    #   )
-    #
-    # @example Advanced execution with environment
-    #   response = ExecContainer.call(
-    #     server_context: context,
-    #     id: "app-container",
-    #     cmd: "bundle exec rails console",
-    #     working_dir: "/app",
-    #     user: "rails",
-    #     env: "RAILS_ENV=production,DEBUG=true",
-    #     timeout: 300
-    #   )
-    #
-    # @see Docker::Container#exec
-    def self.call(id:, cmd:, server_context:, working_dir: nil, user: nil,
-                  env: nil, stdin: nil, timeout: 60)
+
+    param :working_dir,
+          type: :string,
+          description: 'Working directory for the command (optional)',
+          required: false
+
+    param :user,
+          type: :string,
+          description: 'User to run the command as (optional, e.g., "1000" or "username")',
+          required: false
+
+    param :env,
+          type: :string,
+          description: 'Environment variables as comma-separated KEY=VALUE pairs (optional)',
+          required: false
+
+    param :stdin,
+          type: :string,
+          description: 'Input to send to the command via stdin (optional)',
+          required: false
+
+    param :timeout,
+          type: :integer,
+          description: 'Timeout in seconds (optional, default: 60)',
+          required: false,
+          default: 60
+
+    execute do |id:, cmd:, working_dir: nil, user: nil, env: nil, stdin: nil, timeout: 60|
       container = Docker::Container.get(id)
 
       # Parse command string into array
-      # Simple shell-like parsing: split on spaces but respect quoted strings
-
       cmd_array = Shellwords.split(cmd)
 
       # Parse environment variables from comma-separated string to array
-      env_array = nil
-      env_array = env.split(',').map(&:strip) if env && !env.empty?
-
-      # Build exec options
-      exec_options = {
-        'Cmd' => cmd_array,
-        'AttachStdout' => true,
-        'AttachStderr' => true
-      }
-      exec_options['WorkingDir'] = working_dir if working_dir
-      exec_options['User'] = user if user
-      exec_options['Env'] = env_array if env_array
-      exec_options['AttachStdin'] = true if stdin
+      env.split(',').map(&:strip) if env && !env.empty?
 
       # Execute the command
       stdout_data = []
@@ -180,10 +137,7 @@ module DockerMCP
         stderr_data = result[1]
         exit_code = result[2]
       rescue Docker::Error::TimeoutError
-        return MCP::Tool::Response.new([{
-                                         type: 'text',
-                                         text: "Command execution timed out after #{timeout} seconds"
-                                       }])
+        return "Command execution timed out after #{timeout} seconds"
       end
 
       # Format response
@@ -200,20 +154,13 @@ module DockerMCP
         response_text += "\nSTDERR:\n#{stderr_str}\n" unless stderr_str.strip.empty?
       end
 
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: response_text.strip
-                              }])
+      response_text.strip
     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 executing command: #{e.message}"
-                              }])
+      "Error executing command: #{e.message}"
     end
   end
+
+  ExecContainer = EXEC_CONTAINER_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/fetch_container_logs.rb

@@ -1,136 +1,92 @@
 # frozen_string_literal: true
 
 module DockerMCP
-  # MCP tool for retrieving Docker container logs.
+  # MCP tool for fetching Docker container logs.
   #
-  # This tool provides access to container logs with flexible filtering and
-  # formatting options. It can retrieve both stdout and stderr logs with
-  # optional timestamps and tail functionality for recent entries.
+  # This tool retrieves log output from Docker containers, including both
+  # standard output and standard error streams. It supports filtering by
+  # stream type, limiting output length, timestamp inclusion, and retrieving
+  # logs from both running and stopped containers.
   #
   # == Features
   #
-  # - Retrieve stdout and/or stderr logs
-  # - Optional timestamp inclusion
-  # - Tail functionality for recent logs
-  # - Flexible log stream selection
-  # - Comprehensive error handling
-  # - Works with any container state
-  #
-  # == Log Sources
-  #
-  # Docker containers can generate logs from multiple sources:
-  # - **stdout**: Standard output from container processes
-  # - **stderr**: Standard error from container processes
-  # - **timestamps**: Docker-generated timestamps for each log line
+  # - Fetch logs from running and stopped containers
+  # - Separate or combined stdout and stderr streams
+  # - Configurable output length limiting (tail functionality)
+  # - Optional timestamp inclusion for log entries
+  # - Support for container identification by ID or name
+  # - Comprehensive error handling and status reporting
   #
   # == Security Considerations
   #
   # Container logs may contain sensitive information:
-  # - Application secrets and API keys
-  # - User data and personal information
-  # - Internal system information
-  # - Database connection strings
-  # - Error messages with stack traces
+  # - **Application Data**: Database queries, API keys, user data
+  # - **System Information**: Internal paths, configuration details
+  # - **Error Details**: Stack traces revealing application internals
+  # - **Access Patterns**: User behavior and system usage information
+  # - **Debugging Information**: Temporary credentials or session data
+  #
+  # Implement proper access controls and data sanitization for log access.
+  #
+  # == Parameters
   #
-  # Security recommendations:
-  # - Review log content before sharing
-  # - Limit access to container logs
-  # - Sanitize logs in production environments
-  # - Use log rotation to manage log size
-  # - Be cautious with log forwarding
+  # - **id**: Container ID or name (required)
+  # - **stdout**: Include stdout in logs (optional, default: true)
+  # - **stderr**: Include stderr in logs (optional, default: true)
+  # - **timestamps**: Show timestamps for log entries (optional, default: false)
+  # - **tail**: Number of lines to show from end of logs (optional, default: all)
   #
   # == Example Usage
   #
-  #   # Get all logs
-  #   FetchContainerLogs.call(
+  #   # Fetch all logs
+  #   response = FetchContainerLogs.call(
   #     server_context: context,
   #     id: "web-server"
   #   )
   #
-  #   # Get recent logs with timestamps
-  #   FetchContainerLogs.call(
+  #   # Fetch recent errors with timestamps
+  #   response = FetchContainerLogs.call(
   #     server_context: context,
   #     id: "app-container",
-  #     tail: 100,
-  #     timestamps: true
-  #   )
-  #
-  #   # Get only error logs
-  #   FetchContainerLogs.call(
-  #     server_context: context,
-  #     id: "database",
   #     stdout: false,
-  #     stderr: true
+  #     stderr: true,
+  #     timestamps: true,
+  #     tail: 100
   #   )
   #
-  # @see ExecContainer
   # @see Docker::Container#logs
   # @since 0.1.0
-  class FetchContainerLogs < MCP::Tool
+  FETCH_CONTAINER_LOGS_DEFINITION = ToolForge.define(:fetch_container_logs) do
     description 'Fetch Docker container logs'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
+    param :id,
+          type: :string,
           description: 'Container ID or name'
-        },
-        stdout: {
-          type: 'boolean',
-          description: 'Include stdout (default: true)'
-        },
-        stderr: {
-          type: 'boolean',
-          description: 'Include stderr (default: true)'
-        },
-        tail: {
-          type: 'integer',
-          description: 'Number of lines to show from the end of logs (default: all)'
-        },
-        timestamps: {
-          type: 'boolean',
-          description: 'Show timestamps (default: false)'
-        }
-      },
-      required: ['id']
-    )
 
-    # Retrieve logs from a Docker container.
-    #
-    # This method fetches logs from the specified container with configurable
-    # options for log sources (stdout/stderr), formatting (timestamps), and
-    # quantity (tail). The logs are returned as a text response.
-    #
-    # @param id [String] container ID (full or short) or container name
-    # @param server_context [Object] MCP server context (unused but required)
-    # @param stdout [Boolean] whether to include stdout logs (default: true)
-    # @param stderr [Boolean] whether to include stderr logs (default: true)
-    # @param tail [Integer, nil] number of recent lines to return (nil for all)
-    # @param timestamps [Boolean] whether to include timestamps (default: false)
-    #
-    # @return [MCP::Tool::Response] container logs as text
-    #
-    # @raise [Docker::Error::NotFoundError] if container doesn't exist
-    # @raise [StandardError] for other log retrieval failures
-    #
-    # @example Get all logs
-    #   response = FetchContainerLogs.call(
-    #     server_context: context,
-    #     id: "nginx-server"
-    #   )
-    #
-    # @example Get recent error logs with timestamps
-    #   response = FetchContainerLogs.call(
-    #     server_context: context,
-    #     id: "app-container",
-    #     stdout: false,
-    #     stderr: true,
-    #     tail: 50,
-    #     timestamps: true
-    #   )
-    #
-    # @see Docker::Container#logs
-    def self.call(id:, server_context:, stdout: true, stderr: true, tail: nil, timestamps: false)
+    param :stdout,
+          type: :boolean,
+          description: 'Include stdout (default: true)',
+          required: false,
+          default: true
+
+    param :stderr,
+          type: :boolean,
+          description: 'Include stderr (default: true)',
+          required: false,
+          default: true
+
+    param :tail,
+          type: :integer,
+          description: 'Number of lines to show from the end of logs (default: all)',
+          required: false
+
+    param :timestamps,
+          type: :boolean,
+          description: 'Show timestamps (default: false)',
+          required: false,
+          default: false
+
+    execute do |id:, stdout: true, stderr: true, tail: nil, timestamps: false|
       container = Docker::Container.get(id)
 
       options = {
@@ -140,22 +96,13 @@ module DockerMCP
       }
       options[:tail] = tail if tail
 
-      logs = container.logs(options)
-
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: logs
-                              }])
+      container.logs(options)
     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 fetching logs: #{e.message}"
-                              }])
+      "Error fetching logs: #{e.message}"
     end
   end
+
+  FetchContainerLogs = FETCH_CONTAINER_LOGS_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/list_containers.rb

@@ -3,64 +3,61 @@
 module DockerMCP
   # MCP tool for listing Docker containers.
   #
-  # This tool provides functionality to list all Docker containers on the system,
-  # including both running and stopped containers. It returns detailed information
-  # about each container including names, images, status, ports, and other metadata.
+  # This tool provides comprehensive information about all Docker containers
+  # on the system, including both running and stopped containers. It returns
+  # detailed metadata for each container including names, images, status,
+  # network configuration, and resource usage.
   #
-  # == Security Notes
+  # == Features
   #
-  # This is a read-only operation that provides system information about containers.
-  # While generally safe, it may reveal information about the Docker environment
-  # that could be useful for reconnaissance.
+  # - Lists all containers (running and stopped)
+  # - Provides detailed container metadata
+  # - Shows network configuration and port mappings
+  # - Displays resource usage and statistics
+  # - Includes mount point information
+  # - Shows container labels and annotations
   #
-  # == Example Usage
+  # == Security Considerations
+  #
+  # This tool provides system information that could be useful for:
+  # - **System Reconnaissance**: Reveals running services and configurations
+  # - **Network Discovery**: Shows internal network topology
+  # - **Resource Analysis**: Exposes system resource usage patterns
   #
-  #   # List all containers (default behavior)
-  #   ListContainers.call(server_context: context)
+  # Use with appropriate access controls in production environments.
   #
-  #   # Explicitly request all containers
-  #   ListContainers.call(server_context: context, all: true)
+  # == Return Format
+  #
+  # Returns an array of container objects with comprehensive metadata:
+  # - Container names and IDs
+  # - Image information and tags
+  # - Current state and status
+  # - Network settings and port bindings
+  # - Mount points and volumes
+  # - Labels and environment details
+  #
+  # == Example Usage
+  #
+  #   containers = ListContainers.call(server_context: context)
+  #   containers.each do |container|
+  #     puts "#{container['Names'].first}: #{container['State']}"
+  #   end
   #
   # @see Docker::Container.all
   # @since 0.1.0
-  class ListContainers < MCP::Tool
+  LIST_CONTAINERS_DEFINITION = ToolForge.define(:list_containers) do
     description 'List Docker containers'
 
-    input_schema(
-      properties: {
-        all: {
-          type: 'boolean',
-          description: 'Show all containers (default shows all containers including stopped ones)'
-        }
-      },
-      required: []
-    )
+    param :all,
+          type: :boolean,
+          description: 'Show all containers (default shows all containers including stopped ones)',
+          required: false,
+          default: true
 
-    # List all Docker containers with detailed information.
-    #
-    # Retrieves information about all containers on the system, including:
-    # - Container names and IDs
-    # - Image information
-    # - Current state (running, stopped, etc.)
-    # - Port mappings
-    # - Network configuration
-    # - Volume mounts
-    # - Creation and status timestamps
-    #
-    # @param server_context [Object] the MCP server context (unused but required)
-    # @param all [Boolean] whether to show all containers (default: true)
-    # @return [MCP::Tool::Response] response containing container information
-    #
-    # @example List all containers
-    #   response = ListContainers.call(server_context: context)
-    #   # Returns detailed info for all containers
-    #
-    # @see Docker::Container.all
-    def self.call(server_context:, all: true)
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: Docker::Container.all(all: all).map(&:info).to_s
-                              }])
+    execute do |all: true|
+      Docker::Container.all(all: all).map(&:info)
     end
   end
+
+  ListContainers = LIST_CONTAINERS_DEFINITION.to_mcp_tool
 end