docker_mcp 0.2.5 → 0.3.0

data/lib/docker_mcp/tag_image.rb

@@ -3,161 +3,107 @@
 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.
+  # This tool provides the ability to assign repository names and tags
+  # to Docker images. Tagging is essential for image organization,
+  # versioning, and distribution through Docker registries.
   #
   # == Features
   #
-  # - Tag images by ID or existing name
-  # - Support for repository and tag specification
+  # - Tag existing images with custom repository names
+  # - Support for version and environment tags
   # - 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
+  # - Registry-compatible naming conventions
+  # - Automatic tag defaulting to "latest"
+  # - Comprehensive error handling and validation
   #
   # == 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
+  # Image tagging involves several security considerations:
+  # - **Registry Authentication**: Tags may trigger registry operations
+  # - **Namespace Conflicts**: Overwriting tags can affect other deployments
+  # - **Image Identity**: Improper tagging can lead to deployment confusion
+  # - **Version Management**: Incorrect tags can compromise CI/CD pipelines
+  # - **Registry Pollution**: Excessive tagging can clutter registries
   #
-  # 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
+  # **Security Recommendations**:
+  # - Use consistent naming conventions
+  # - Implement tag governance policies
+  # - Verify image identity before tagging
+  # - Avoid overwriting production tags
+  # - Use semantic versioning for releases
+  # - Monitor tag usage and lifecycle
   #
-  # == Tag Naming Conventions
+  # == Parameters
   #
-  # 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`
+  # - **id**: Image ID or current name:tag to tag (required)
+  # - **repo**: Repository name (required, e.g., "username/imagename" or "registry/username/imagename")
+  # - **tag**: Tag for the image (optional, default: "latest")
+  # - **force**: Force tag even if it already exists (optional, default: true)
   #
   # == Example Usage
   #
-  #   # Tag with version
-  #   TagImage.call(
+  #   # Tag image with version
+  #   response = TagImage.call(
   #     server_context: context,
-  #     id: "abc123def456",
-  #     repo: "myapp",
-  #     tag: "v1.0.0"
+  #     id: "myapp:dev",
+  #     repo: "myregistry/myapp",
+  #     tag: "v1.2.3"
   #   )
   #
-  #   # Tag for registry push
-  #   TagImage.call(
+  #   # Tag for production deployment
+  #   response = TagImage.call(
   #     server_context: context,
-  #     id: "myapp:latest",
-  #     repo: "myusername/myapp",
-  #     tag: "production"
+  #     id: "abc123def456",
+  #     repo: "production/webapp",
+  #     tag: "stable",
+  #     force: false
   #   )
   #
-  #   # Tag for private registry
-  #   TagImage.call(
+  #   # Tag with registry prefix
+  #   response = TagImage.call(
   #     server_context: context,
-  #     id: "webapp:dev",
-  #     repo: "registry.company.com/team/webapp",
-  #     tag: "v2.1.0"
+  #     id: "local-build:latest",
+  #     repo: "registry.company.com/team/service",
+  #     tag: "release-candidate"
   #   )
   #
-  # @see BuildImage
-  # @see PushImage
   # @see Docker::Image#tag
   # @since 0.1.0
-  class TagImage < MCP::Tool
+  TAG_IMAGE_DEFINITION = ToolForge.define(:tag_image) do
     description 'Tag a Docker image'
 
-    input_schema(
-      properties: {
-        id: {
-          type: 'string',
-          description: 'Image ID or current name:tag'
-        },
-        repo: {
-          type: 'string',
+    param :id,
+          type: :string,
+          description: 'Image ID or current name:tag to tag'
+
+    param :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)
+    param :tag,
+          type: :string,
+          description: 'Tag for the image (default: "latest")',
+          required: false,
+          default: 'latest'
+
+    param :force,
+          type: :boolean,
+          description: 'Force tag even if it already exists (default: true)',
+          required: false,
+          default: true
+
+    execute do |id:, repo:, 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}"
-                              }])
+      "Image tagged successfully as #{repo}:#{tag}"
     rescue Docker::Error::NotFoundError
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Image #{id} not found"
-                              }])
+      "Image #{id} not found"
     rescue StandardError => e
-      MCP::Tool::Response.new([{
-                                type: 'text',
-                                text: "Error tagging image: #{e.message}"
-                              }])
+      "Error tagging image: #{e.message}"
     end
   end
+
+  TagImage = TAG_IMAGE_DEFINITION.to_mcp_tool
 end

data/lib/docker_mcp/version.rb

@@ -10,5 +10,5 @@ module DockerMCP
   #
   # @see https://semver.org/
   # @since 0.1.0
-  VERSION = '0.2.5'
+  VERSION = '0.3.0'
 end

data/lib/docker_mcp.rb

@@ -3,9 +3,11 @@
 require 'docker'
 require 'json'
 require 'mcp'
+require 'open3'
 require 'rubygems/package'
 require 'shellwords'
 require 'stringio'
+require 'tool_forge'
 require 'zeitwerk'
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker_mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Aaron F Stanton
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tool_forge
+  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: zeitwerk
   requirement: !ruby/object:Gem::Requirement