docker_mcp 0.0.1 → 0.2.0

data/lib/docker_mcp/stop_container.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for stopping running 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.
+  #
+  # == 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
+  #
+  # == 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
+  #
+  # Best practices:
+  # - Ensure data persistence before stopping
+  # - Consider impact on dependent services
+  # - Use appropriate timeout for graceful shutdown
+  # - Monitor application logs during shutdown
+  #
+  # == Example Usage
+  #
+  #   # Stop with default timeout (10 seconds)
+  #   StopContainer.call(
+  #     server_context: context,
+  #     id: "web-server"
+  #   )
+  #
+  #   # Stop with custom timeout
+  #   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
+    description 'Stop a Docker container'
+
+    input_schema(
+      properties: {
+        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)
+      container = Docker::Container.get(id)
+      container.stop('timeout' => timeout)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Container #{id} stopped 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 stopping container: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/tag_image.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module DockerMCP
+  # MCP tool for tagging Docker images.
+  #
+  # This tool provides the ability to create new tags for existing Docker images,
+  # enabling better organization, versioning, and distribution of images. Tags
+  # are essential for image management and registry operations.
+  #
+  # == Features
+  #
+  # - Tag images by ID or existing name
+  # - Support for repository and tag specification
+  # - Force tagging to overwrite existing tags
+  # - Registry-compatible tag formatting
+  # - Comprehensive error handling
+  # - Multiple tags per image support
+  #
+  # == Tag Management Benefits
+  #
+  # Proper tagging enables:
+  # - **Version Control**: Track different image versions
+  # - **Distribution**: Prepare images for registry push
+  # - **Organization**: Group related images logically
+  # - **Deployment**: Reference specific image versions
+  # - **Rollback**: Maintain previous versions for rollback
+  #
+  # == Security Considerations
+  #
+  # Tagging affects image accessibility and distribution:
+  # - Tags determine registry push destinations
+  # - Overwriting tags can affect running containers
+  # - Registry-compatible tags expose images for distribution
+  # - Tag names may reveal application details
+  #
+  # Best practices:
+  # - Use descriptive but not sensitive tag names
+  # - Avoid overwriting production tags accidentally
+  # - Implement tag naming conventions
+  # - Regular cleanup of unused tags
+  # - Control access to critical tag operations
+  #
+  # == Tag Naming Conventions
+  #
+  # Recommended patterns:
+  # - **Semantic Versioning**: `v1.2.3`, `1.2.3-alpha`
+  # - **Environment Tags**: `prod`, `staging`, `dev`
+  # - **Feature Tags**: `feature-branch-name`
+  # - **Date Tags**: `2024-01-15`, `20240115`
+  # - **Commit Tags**: `sha-abc123def`
+  #
+  # == Example Usage
+  #
+  #   # Tag with version
+  #   TagImage.call(
+  #     server_context: context,
+  #     id: "abc123def456",
+  #     repo: "myapp",
+  #     tag: "v1.0.0"
+  #   )
+  #
+  #   # Tag for registry push
+  #   TagImage.call(
+  #     server_context: context,
+  #     id: "myapp:latest",
+  #     repo: "myusername/myapp",
+  #     tag: "production"
+  #   )
+  #
+  #   # Tag for private registry
+  #   TagImage.call(
+  #     server_context: context,
+  #     id: "webapp:dev",
+  #     repo: "registry.company.com/team/webapp",
+  #     tag: "v2.1.0"
+  #   )
+  #
+  # @see BuildImage
+  # @see PushImage
+  # @see Docker::Image#tag
+  # @since 0.1.0
+  class TagImage < MCP::Tool
+    description 'Tag a Docker image'
+
+    input_schema(
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Image ID or current name:tag'
+        },
+        repo: {
+          type: 'string',
+          description: 'Repository name (e.g., "username/imagename" or "registry/username/imagename")'
+        },
+        tag: {
+          type: 'string',
+          description: 'Tag for the image (default: "latest")'
+        },
+        force: {
+          type: 'boolean',
+          description: 'Force tag even if it already exists (default: true)'
+        }
+      },
+      required: %w[id repo]
+    )
+
+    # Tag a Docker image with a new repository and tag name.
+    #
+    # This method creates a new tag for an existing image, allowing it to
+    # be referenced by the new name. This is essential for organizing images
+    # and preparing them for registry distribution.
+    #
+    # @param id [String] image ID or current name:tag to tag
+    # @param repo [String] repository name for the new tag
+    # @param server_context [Object] MCP server context (unused but required)
+    # @param tag [String] tag name for the image (default: "latest")
+    # @param force [Boolean] whether to overwrite existing tags (default: true)
+    #
+    # @return [MCP::Tool::Response] tagging operation results
+    #
+    # @raise [Docker::Error::NotFoundError] if source image doesn't exist
+    # @raise [StandardError] for other tagging failures
+    #
+    # @example Tag for versioning
+    #   response = TagImage.call(
+    #     server_context: context,
+    #     id: "my-app:latest",
+    #     repo: "my-app",
+    #     tag: "v1.2.3"
+    #   )
+    #
+    # @example Tag for registry push
+    #   response = TagImage.call(
+    #     server_context: context,
+    #     id: "abc123def456",
+    #     repo: "myregistry.com/myuser/myapp",
+    #     tag: "production",
+    #     force: true
+    #   )
+    #
+    # @see Docker::Image#tag
+    def self.call(id:, repo:, server_context:, tag: 'latest', force: true)
+      image = Docker::Image.get(id)
+
+      image.tag('repo' => repo, 'tag' => tag, 'force' => force)
+
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image tagged successfully as #{repo}:#{tag}"
+                              }])
+    rescue Docker::Error::NotFoundError
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Image #{id} not found"
+                              }])
+    rescue StandardError => e
+      MCP::Tool::Response.new([{
+                                type: 'text',
+                                text: "Error tagging image: #{e.message}"
+                              }])
+    end
+  end
+end

data/lib/docker_mcp/version.rb

@@ -1,5 +1,14 @@
 # frozen_string_literal: true
 
-module DockerMcp
-  VERSION = "0.0.1"
+module DockerMCP
+  # Current version of the DockerMCP gem.
+  #
+  # This constant follows semantic versioning (SemVer) principles:
+  # - MAJOR version for incompatible API changes
+  # - MINOR version for backwards-compatible functionality additions
+  # - PATCH version for backwards-compatible bug fixes
+  #
+  # @see https://semver.org/
+  # @since 0.1.0
+  VERSION = '0.2.0'
 end

data/lib/docker_mcp.rb

@@ -1,8 +1,69 @@
 # frozen_string_literal: true
 
-require_relative "docker_mcp/version"
+require 'docker'
+require 'json'
+require 'mcp'
+require 'rubygems/package'
+require 'shellwords'
+require 'stringio'
+require 'zeitwerk'
 
-module DockerMcp
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.inflector.inflect('docker_mcp' => 'DockerMCP')
+loader.setup # ready!
+
+require_relative 'docker_mcp/version'
+
+# DockerMCP provides a Model Context Protocol (MCP) server for comprehensive Docker management.
+#
+# This module serves as the main namespace for all Docker MCP functionality, providing tools
+# to interact with Docker containers, images, networks, and volumes through a standardized
+# MCP interface. It enables AI assistants and other MCP clients to perform Docker operations
+# programmatically.
+#
+# == Security Warning
+#
+# This tool provides powerful capabilities that can be potentially dangerous:
+# - Execute arbitrary commands inside containers
+# - Access and modify container filesystems
+# - Create, modify, and delete Docker resources
+#
+# Use with caution and ensure proper security measures are in place.
+#
+# == Example Usage
+#
+#   # Initialize the MCP server
+#   server = DockerMCP::Server.new
+#
+#   # The server provides access to 22 Docker management tools:
+#   # - Container management (create, run, start, stop, remove, etc.)
+#   # - Image management (pull, build, tag, push, remove)
+#   # - Network management (create, list, remove)
+#   # - Volume management (create, list, remove)
+#
+# == Dependencies
+#
+# Requires:
+# - Docker Engine installed and running
+# - Ruby 3.2+
+# - docker-api gem for Docker interactions
+# - mcp gem for Model Context Protocol support
+#
+# @see https://github.com/afstanton/docker_mcp
+# @since 0.1.0
+module DockerMCP
+  # Base error class for all DockerMCP-specific errors.
+  #
+  # This error class serves as the parent for any custom exceptions
+  # that may be raised by DockerMCP operations. It inherits from
+  # StandardError to maintain compatibility with standard Ruby
+  # error handling patterns.
+  #
+  # @example Rescue DockerMCP errors
+  #   begin
+  #     # DockerMCP operations
+  #   rescue DockerMCP::Error => e
+  #     puts "DockerMCP error: #{e.message}"
+  #   end
   class Error < StandardError; end
-  # Your code goes here...
 end

data/sig/docker_mcp.rbs

@@ -1,4 +1,4 @@
-module DockerMcp
+module DockerMCP
   VERSION: String
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker_mcp
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron F Stanton
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: docker-api
   requirement: !ruby/object:Gem::Requirement
@@ -37,25 +51,68 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A Model Context Protocol (MCP) server that provides Docker container
-  management and command execution capabilities for AI assistants.
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This gem provides tools to manage Docker containers and images using
+  MCP.
 email:
 - afstanton@gmail.com
-executables: []
+executables:
+- docker_mcp
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.txt
 - README.md
 - Rakefile
+- examples/.keep
+- exe/docker_mcp
 - lib/docker_mcp.rb
+- lib/docker_mcp/build_image.rb
+- lib/docker_mcp/copy_to_container.rb
+- lib/docker_mcp/create_container.rb
+- lib/docker_mcp/create_network.rb
+- lib/docker_mcp/create_volume.rb
+- lib/docker_mcp/exec_container.rb
+- lib/docker_mcp/fetch_container_logs.rb
+- lib/docker_mcp/list_containers.rb
+- lib/docker_mcp/list_images.rb
+- lib/docker_mcp/list_networks.rb
+- lib/docker_mcp/list_volumes.rb
+- lib/docker_mcp/pull_image.rb
+- lib/docker_mcp/push_image.rb
+- lib/docker_mcp/recreate_container.rb
+- lib/docker_mcp/remove_container.rb
+- lib/docker_mcp/remove_image.rb
+- lib/docker_mcp/remove_network.rb
+- lib/docker_mcp/remove_volume.rb
+- lib/docker_mcp/run_container.rb
+- lib/docker_mcp/server.rb
+- lib/docker_mcp/start_container.rb
+- lib/docker_mcp/stop_container.rb
+- lib/docker_mcp/tag_image.rb
 - lib/docker_mcp/version.rb
 - sig/docker_mcp.rbs
 homepage: https://github.com/afstanton/docker_mcp
-licenses: []
+licenses:
+- MIT
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/afstanton/docker_mcp
   source_code_uri: https://github.com/afstanton/docker_mcp
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -72,5 +129,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.2
 specification_version: 4
-summary: MCP server for Docker with command execution support
+summary: A gem to manage Docker via MCP.
 test_files: []