# local-docker-mcp

A Python MCP (Model Context Protocol) server that provides Docker container management and test execution capabilities via FastMCP. Runs as an HTTP server on port 8000 at path `/local-docker/mcp/`.

## Features

- **Docker Image Management**: Build, pull, list, and remove Docker images
- **Container Operations**: Run, stop, remove containers; fetch logs; execute commands
- **Test Execution**: Run tests inside containers with automatic file/folder upload
- **Cross-Platform**: Works on Windows, macOS, and Linux with platform-appropriate upload strategies
- **MCP Protocol**: Exposes all functionality as MCP tools for LLM consumption

## Tech Stack

- **Python** ≥3.14
- **FastMCP** ≥3.4.2 - MCP server framework
- **docker** ≥7.1.0 - Docker SDK for Python
- **uv** - Dependency management

## Project Structure

```
local-docker-mcp/
├── main.py          # Main MCP server entry point (single file)
├── pyproject.toml   # Project config & dependencies
├── uv.lock          # Locked dependencies
├── .python-version  # Python version pin
├── .gitignore
└── README.md
```

## Quick Start

### Prerequisites

- Python ≥3.14
- Docker installed and running
- `uv` package manager

### Installation

```bash
# Clone and navigate to project
cd local-docker-mcp

# Install dependencies
uv sync

# Run the MCP server
uv run main.py
```

The server starts at `http://0.0.0.0:8000/local-docker/mcp/`

### Development

```bash
# Install in editable mode
uv pip install -e .

# Add a new dependency
uv add package-name
uv sync
```

## Available MCP Tools

All tools are decorated with `@mcp.tool()` and exposed via the MCP protocol.

### Image Management

| Tool | Description |
|------|-------------|
| `build_image` | Build Docker image from Dockerfile |
| `pull_image` | Pull Docker image from registry |
| `remove_image` | Remove Docker image |
| `list_resources` | List containers and images |

### Container Operations

| Tool | Description |
|------|-------------|
| `run_container` | Start container from image (requires `byagent_` prefix) |
| `get_container_logs` | Fetch container logs |
| `stop_and_remove_container` | Stop/remove container, optionally remove image |
| `exec_in_container` | Execute arbitrary command in container (requires `byagent_` prefix) |

### Test Execution

| Tool | Description |
|------|-------------|
| `run_tests` | Run tests inside container with optional file/folder upload |

#### `run_tests` Parameters

- `container_name` (required, must have prefix `byagent_`)
- `container_tests_folder` (required, absolute path in container)
- `test_file` (optional, specific test file)
- `test_node_ids` (optional, specific test node IDs)
- `upload_from_folder` / `upload_from_files` (mutually exclusive, for uploading test files)
- `test_runner` (default: `pytest`)
- `test_runner_args` (optional, additional test runner arguments)
- `env_vars` (optional, environment variables)
- `timeout_seconds` (optional, test timeout)

#### Upload Strategy

- `upload_from_folder`: Copies entire folder contents to `container_tests_folder`
- `upload_from_files`: Copies specific files to `container_tests_folder`
- Mutually exclusive — cannot use both

## Architecture

### Main Entry Point (`main.py`)

- **FastMCP Server**: Named "local-docker-mcp", runs on HTTP transport at `0.0.0.0:8000` with path `/local-docker/mcp/`
- **Platform Detection**: Detects OS at import time for cross-platform Docker commands

### Key Components

1. **`_run(cmd, cwd, timeout)`** — Shell command runner with structured output and timeout handling
2. **`_fmt(res, label)`** — Formats command results into readable strings with success/failure icons
3. **`_upload_files_to_container(files, container_name, dest)`** — Cross-platform file upload via `docker cp`
4. **`_upload_folder_to_container(folder, container_name, dest)`** — Cross-platform folder upload:
   - **Windows**: Uses `docker cp` exclusively
   - **macOS/Linux**: Prefers `tar` pipe for permissions/symlinks, falls back to `docker cp`

### Container Naming Convention

All container operations require the `byagent_` prefix for container names (validated in tools).

## Cross-Platform Support

| Platform | Folder Upload Method |
|----------|---------------------|
| Windows | `docker cp` |
| macOS/Linux | `tar` pipe (preferred), `docker cp` (fallback) |


## License

[Add your license here]

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests (when available)
5. Submit a pull request