Merge pull request QuantGeekDev#2 from QuantGeekDev/feature/modularize

Feature/modularize

Author: QuantGeekDev

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,20 +1,57 @@
-# docker-mcp MCP server
+# 🐳 docker-mcp
 
-Docker MCP server
-Supports instantiating containers, and docker compose operations
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-## Quickstart
+A powerful Model Context Protocol (MCP) server for Docker operations, enabling seamless container and compose stack management through Claude AI.
 
-### Install
+## ✨ Features
 
-#### Claude Desktop
+- 🚀 Container creation and instantiation
+- 📦 Docker Compose stack deployment
+- 🔍 Container logs retrieval
+- 📊 Container listing and status monitoring
+- 🧹 Automatic cleanup of temporary files
+- ♻️ Automatic image pulling
 
-On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
-On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+### 🎬 Demos
+#### Deploying a Docker Compose Stack
+
+<a href="https://streamable.com/0fz6kn" target="_blank">
+ <img src="https://cdn-cf-east.streamable.com/image/0fz6kn.jpg?Expires=1733623440&Signature=PIYLK6wY6HM~9kPqmmpabnjHoObDdz9MgjE4-TVD74BN~bXTZFkHKo3B9ufF8HoVqD7lA79gpngGAJ0pJTi62UgirktBx-eG2vxXEj6IbWrTkQJnmePAV6vM8Nu5j1~v6eKiS~a8bUiYnEioyFtufxSbfgTTV3sIYzXe6blabMGf-KSHg9yoAa6CwnfDRusfrUNsJxs2uNxAfhBe8~0KC0OcPujwnPZarJmYsz7CuTgsPb3TbnREdLGb2tNxNAjMFzRxjQvkSXGbxbfytsqMGhqSDqSSuFBRcOgraZoAsJmyWt1fb2VSKaD0I6Zxzzyssr7hJ82JHMVyJZAMgT1tlQ__&Key-Pair-Id=APKAIEYUVEN4EVB2OKEQ" alt="Docker Compose Demo" width="600px"/>
+</a>
+
+#### Analyzing Container Logs
+
+<a href="https://streamable.com/3fjqi3" target="_blank">
+ <img src="https://cdn-cf-east.streamable.com/image/3fjqi3.jpg?Expires=1733623500&Signature=XaG9q65aFAl8fmk1kvf9TsJj2RB8u035RDpWTLJ7eWzqClmVOPuYEklw4dox3JBQcrcHmg4SJFcyTvhwmyQLc19UKli9yEkO4AqwSlE9SEqrBrOBvCsWoDUa8CBuTU~-9R~sJd8fLVeQNQhvTnTyVFF9z0zkJ3XzDBWcXDMleXL4IbKiD5Z0IcYTsRTJCGD91qtjdO4dDqaaj5fpWNGQixa7ffgvSu5QZJHaLrcnspum7lKKI58eJQlS7T9WqZUXSW2c5vK-EMLrTmV~AXOfZHig-d6XqdBbz0Bg1gLBCdyWsY6PkMhUaR9MIVDVzPwQonVDy5fEDNsnS18zN~1Cfw__&Key-Pair-Id=APKAIEYUVEN4EVB2OKEQ" alt="Container Logs Demo" width="600px"/>
+</a>
+
+📝 Click on the images above to watch the demos
+
+## 🚀 Quickstart
+
+### Prerequisites
+
+- Python 3.12+
+- Docker Desktop or Docker Engine
+- Claude Desktop
+
+### Installation
+
+#### Claude Desktop Configuration
+
+Add the server configuration to your Claude Desktop config file:
+
+**MacOS**: `~/Library/Application\ Support/Claude/claude_desktop_config.json` 
+**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
 
 <details>
- <summary>Development/Unpublished Servers Configuration</summary>
- ```
+ <summary>💻 Development Configuration</summary>
+
+```json
+{
  "mcpServers": {
  "docker-mcp": {
  "command": "uv",
@@ -26,12 +63,15 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  ]
  }
  }
- ```
+}
+```
 </details>
 
 <details>
- <summary>Published Servers Configuration</summary>
- ```
+ <summary>🚀 Production Configuration</summary>
+
+```json
+{
  "mcpServers": {
  "docker-mcp": {
  "command": "uvx",
@@ -40,14 +80,32 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  ]
  }
  }
- ```
+}
+```
 </details>
 
-## Development
+## 🛠️ Development
 
-### Building and Publishing
+### Local Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/QuantGeekDev/docker-mcp.git
+cd docker-mcp
+```
 
-To prepare the package for distribution:
+2. Create and activate a virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
+```bash
+uv sync
+```
+
+### Building and Publishing
 
 1. Sync dependencies and update lockfile:
 ```bash
@@ -58,25 +116,94 @@ uv sync
 ```bash
 uv build
 ```
-
-This will create source and wheel distributions in the `dist/` directory.
+This creates source and wheel distributions in the `dist/` directory.
 
 3. Publish to PyPI:
 ```bash
 uv publish
 ```
 
-Note: You'll need to set PyPI credentials via environment variables or command flags:
+#### PyPI Credentials
+
+Set your credentials via:
 - Token: `--token` or `UV_PUBLISH_TOKEN`
-- Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`
+- Username/Password: 
+ - `--username`/`UV_PUBLISH_USERNAME`
+ - `--password`/`UV_PUBLISH_PASSWORD`
 
-### Inspector
+### 🔍 Debugging
 
-You can launch the MCP Inspector with this command:
+Launch the MCP Inspector for debugging:
 
 ```bash
 npx @modelcontextprotocol/inspector uv --directory <path-to-docker-mcp> run docker-mcp
 ```
 
+The Inspector will provide a URL to access the debugging interface.
+
+## 📝 Available Tools
+
+The server provides the following tools:
+
+### create-container
+Creates a standalone Docker container
+```json
+{
+ "image": "image-name",
+ "name": "container-name",
+ "ports": {"80": "80"},
+ "environment": {"ENV_VAR": "value"}
+}
+```
+
+### deploy-compose
+Deploys a Docker Compose stack
+```json
+{
+ "project_name": "example-stack",
+ "compose_yaml": "version: '3.8'\nservices:\n service1:\n image: image1:latest\n ports:\n - '8080:80'"
+}
+```
+
+### get-logs
+Retrieves logs from a specific container
+```json
+{
+ "container_name": "my-container"
+}
+```
+
+### list-containers
+Lists all Docker containers
+```json
+{}
+```
+
+## 🚧 Current Limitations
+
+- No built-in environment variable support for containers
+- No volume management
+- No network management
+- No container health checks
+- No container restart policies
+- No container resource limits
+
+## 🤝 Contributing
+
+1. Fork the repository from [docker-mcp](https://github.com/QuantGeekDev/docker-mcp)
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Open a Pull Request
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## ✨ Authors
+
+- **Alex Andru** - *Initial work | Core contributor* - [@QuantGeekDev](https://github.com/QuantGeekDev)
+- **Ali Sadykov** - *Initial work | Core contributor* - [@md-archive](https://github.com/md-archive)
 
-Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
+---
+Made with ❤️ for the Claude community

src/docker_mcp/docker_executor.py

@@ -0,0 +1,102 @@
+from typing import Tuple, Protocol, List
+import asyncio
+import os
+import platform
+import shutil
+from abc import ABC, abstractmethod
+
+
+class CommandExecutor(Protocol):
+ async def execute(self, cmd: str | List[str]) -> Tuple[int, str, str]:
+ pass
+
+
+class WindowsExecutor:
+ async def execute(self, cmd: str) -> Tuple[int, str, str]:
+ process = await asyncio.create_subprocess_shell(
+ cmd,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ shell=True
+ )
+ stdout, stderr = await process.communicate()
+ return process.returncode, stdout.decode(), stderr.decode()
+
+
+class UnixExecutor:
+ async def execute(self, cmd: List[str]) -> Tuple[int, str, str]:
+ process = await asyncio.create_subprocess_exec(
+ *cmd,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE
+ )
+ stdout, stderr = await process.communicate()
+ return process.returncode, stdout.decode(), stderr.decode()
+
+
+class DockerExecutorBase(ABC):
+ def __init__(self):
+ self.docker_cmd = self._initialize_docker_cmd()
+ self.executor = WindowsExecutor() if platform.system() == 'Windows' else UnixExecutor()
+
+ @abstractmethod
+ async def run_command(self, command: str, *args) -> Tuple[int, str, str]:
+ pass
+
+ def _initialize_docker_cmd(self) -> str:
+ if platform.system() == 'Windows':
+ docker_dir = r"C:\Program Files\Docker\Docker\resources\bin"
+ docker_paths = [
+ os.path.join(docker_dir, "docker-compose.exe"),
+ os.path.join(docker_dir, "docker.exe")
+ ]
+ for path in docker_paths:
+ if os.path.exists(path):
+ return path
+
+ docker_cmd = shutil.which('docker')
+ if not docker_cmd:
+ raise RuntimeError("Docker executable not found")
+ return docker_cmd
+
+
+class DockerComposeExecutor(DockerExecutorBase):
+ def __init__(self, compose_file: str, project_name: str):
+ super().__init__()
+ self.compose_file = os.path.abspath(compose_file)
+ self.project_name = project_name
+
+ async def run_command(self, command: str, *args) -> Tuple[int, str, str]:
+ if platform.system() == 'Windows':
+ cmd = self._build_windows_command(command, *args)
+ else:
+ cmd = self._build_unix_command(command, *args)
+ return await self.executor.execute(cmd)
+
+ def _build_windows_command(self, command: str, *args) -> str:
+ compose_file = self.compose_file.replace('\\', '/')
+ return (f'cd "{os.path.dirname(compose_file)}" && docker compose '
+ f'-f "{os.path.basename(compose_file)}" '
+ f'-p {self.project_name} {command} {" ".join(args)}')
+
+ def _build_unix_command(self, command: str, *args) -> list[str]:
+ return [
+ self.docker_cmd,
+ "compose",
+ "-f", self.compose_file,
+ "-p", self.project_name,
+ command,
+ *args
+ ]
+
+ async def down(self) -> Tuple[int, str, str]:
+ return await self.run_command("down", "--volumes")
+
+ async def pull(self) -> Tuple[int, str, str]:
+ return await self.run_command("pull")
+
+ async def up(self) -> Tuple[int, str, str]:
+ return await self.run_command("up", "-d")
+
+ async def ps(self) -> Tuple[int, str, str]:
+ return await self.run_command("ps")