# Bash MCP Server (`bash-mcp`)

A Model Context Protocol (MCP) server that provides robust Bash execution capabilities across Windows, macOS, and Linux. Built with Python 3.12+ and managed with [`uv`](https://github.com/astral-sh/uv).

---

## Key Features

- **Cross-Platform Multi-Runtime Support**:
  - **Windows**: Automatically detects and supports **Git Bash** (`C:\Program Files\Git\bin\bash.exe`), **WSL (Windows Subsystem for Linux)**, and **MSYS2**.
  - **macOS / Linux**: Native POSIX `bash`.
  - **Custom Override**: Override runtime with the `BASH_PATH` environment variable across all platforms. The target executable is expected to implement Bash semantics and accept standard `-c <command>` arguments.
- **Process Lifecycle Management & Containment Model**:
  - **Windows (Git Bash / MSYS2)**: Windows Job assignment is best-effort and occurs immediately after process creation; a short pre-assignment execution window exists. Processes assigned to the dedicated Windows Job Object (`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`) have termination attempts performed on their entire process tree on timeout, cancellation, or error.
  - **WSL (Linux VM)**: Employs PID-marker-based process-group signaling and clean group termination (`SIGTERM` -> `SIGKILL`) to terminate background Linux processes inside the VM on timeout or cancellation. (Note: commands that detach into independent sessions via `setsid` or modify supervisor markers require container-level isolation such as Docker/cgroups for full sandbox containment).
  - **POSIX (macOS / Linux)**: Creates isolated process groups (`start_new_session=True`) and performs phased shutdown (`SIGTERM` -> 0.2s grace interval -> `SIGKILL`).
  - **Cancellation-Safe**: Shielded cleanup performs bounded reader-drain and process-reap attempts, and closes pipe transports even under repeated task cancellation.
- **Exact Bash Semantics**:
  - WSL commands are passed directly as raw positional parameters without outer shell interpolation, preserving exact variable scoping, literal single-quotes, and quoted heredocs.
- **PE Binary Screening**:
  - Checks expected DOS/PE signatures (`MZ`, `PE\0\0`) for Windows binary executables, rejecting plain-text or corrupt files.
- **Bounded Stream Capture & Truncation Metadata**:
  - Streams are drained concurrently with per-stream byte limits (default 1 MB) to prevent unbounded memory consumption from noisy commands.
  - Output truncation is clearly indicated in results with byte-accurate counts.
  - Partial output emitted prior to timeouts is preserved.
- **Modern Transport Protocols**:
  - **`stdio`** (default, recommended for local clients like Antigravity, Claude Desktop, Cursor).
  - **`streamable-http`** (recommended modern network transport).
  - **`sse`** (legacy network transport).
  - Strict loopback protection: only canonical loopback addresses (`127.0.0.1`, `localhost`, `::1`) are permitted without explicit `--allow-remote` opt-in.

---

## Exposed Tools

### 1. `execute_bash`
Executes a Bash command, pipeline, or multi-line script.

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `command` | `string` | *(required)* | The Bash command or multi-line script to run. |
| `cwd` | `string` | `null` | Working directory. Accepts Windows paths or native POSIX paths (e.g. `/tmp` under WSL). |
| `timeout_seconds` | `integer` | `120` | Execution timeout in seconds (must be between 1 and 3600). |
| `env_type` | `string` | `"auto"` | Execution environment (`"auto"`, `"git_bash"`, `"wsl"`, `"msys2"`, `"native"`, `"custom"`). |

**Tool Annotations**:
- `destructive_hint=True`
- `open_world_hint=True`
- `read_only_hint=False`

### 2. `get_bash_environments`
Returns diagnostic details about all detected Bash runtimes, executable paths, and the active default environment.

---

## Installation & Setup

Ensure [`uv`](https://docs.astral.sh/uv/) is installed.

```bash
# Clone or navigate to the repository
cd bash-mcp

# Install dependencies and sync the virtual environment
uv sync
```

---

## Running the Server

### Stdio Transport (Default)

```bash
uv run bash-mcp
```

### Streamable HTTP Transport (Recommended for Network)

```bash
uv run bash-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

### Legacy SSE Transport

```bash
uv run bash-mcp --transport sse --host 127.0.0.1 --port 8000
```

> **Security Note:** Binding to non-loopback interfaces requires passing `--allow-remote`. Because command execution runs with host user privileges, network deployments should be secured with TLS, authentication proxies, or container isolation.

---

## Integrating with Antigravity / MCP Clients

### Antigravity Global Configuration (`~/.gemini/config/mcp_config.json`)

```json
{
  "mcpServers": {
    "bash": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\User\\stuff\\bash-mcp",
        "run",
        "bash-mcp"
      ]
    }
  }
}
```

---

## Running Tests

Run the test suite with `pytest`:

```bash
uv run pytest
```