# DevOps Deploy Guard MCP Server (v1.7.0)

> **Production-ready, zero-knowledge AI DevOps deployment, infrastructure provisioning, self-healing execution, and persistent documentation engine for VPS servers.**

`devops-deploy-guard-mcp-server` is an advanced Model Context Protocol (MCP) server that empowers AI coding assistants (Antigravity IDE, Claude Code/Desktop, Cursor, Kimi, etc.) to safely provision servers, configure Nginx & SSL, deploy applications, debug mid-deployment failures interactively, and maintain persistent runbooks — without risking catastrophic production server crashes or database resets.

---

## 🚀 Key Features in v1.7.0

- 🤖 **Self-Healing Execution Engine**: If a deployment command fails, the server **pauses** execution in a `PAUSED_AWAITING_FIX` state instead of instantly rolling back. The LLM receives full failure outputs, applies mid-deployment fixes via `diagnose_and_fix`, and resumes execution seamlessly via `resume_execution`.
- 📘 **Auto-Runbook Generator (`generate_project_runbook`)**: Dynamically writes a physical `DEPLOYMENT_RUNBOOK.md` into the user's project root containing exact manual SSH commands, Nginx blocks, SSL status, and `.env` locations.
- 🧹 **Safe Resource Cleanup (`cleanup_server_resources`)**: Checks root partition space (`df -h /`) and safely prunes dangling Docker images (`docker image prune -f`) and stale Git branches only if disk usage exceeds 70%.
- 🎯 **Context-Aware Conditional Deployments (`plan_dynamic_deployment`)**: Inspects Git diffs against remote tracking branches to skip unnecessary `npm install` or database migrations when manifests and schemas haven't changed.
- 🛡️ **Multi-OS Infrastructure Provisioning**: Automatically detects Ubuntu, Debian, RHEL, CentOS, Fedora, and Alpine to generate idempotent provisioning plans for system packages, Node.js, PM2, Docker, UFW/Firewalld, Nginx, and Certbot SSL certificates.
- 🔒 **Two-Tier Command Sanitizer**: Hard-blocks catastrophic shell commands (`rm -rf`, `DROP DATABASE`, `prisma migrate dev`, `:dev` targets, `--watch`) while warning on risky operations (`docker system prune`, `git reset --hard`).

---

## 🔒 Security & Protection Architecture

| Security Layer | Description |
|----------------|-------------|
| **Two-Step Staged Execution** | Planning tools output a `plan_id`. Execution requires explicitly invoking `confirm_execution` with `confirm: true`. |
| **Command Sanitizer** | Statically inspects all shell strings. Blocks catastrophic commands and dev flags in production environments. |
| **Non-Fatal Pause Engine** | Pauses failed deployments without destroying Git state, enabling LLMs to run diagnostic fix commands. |
| **Secret Protection** | `.env` files are written via SSH heredocs; actual key secrets are never echoed or dumped into LLM context logs. |
| **Path Traversal Guard** | Prevents arbitrary remote file writes outside approved project paths (`/etc/shadow`, `/root/.ssh/`). |
| **Automatic Gitignore** | Automatically adds `.devops-mcp.json` and `.deployment-history.json` to `.gitignore`. |

---

## 📋 Comprehensive Tool Registry (19 Tools)

### 1. Read-Only Inspection & Analysis
| Tool Name | Description |
|-----------|-------------|
| `inspect_server` | Inspects OS, disk space, Docker containers, PM2 processes, Nginx sites, memory usage, and local runbook/history status. |
| `analyze_project_structure` | Detects package managers (npm, pnpm, yarn, bun), ecosystem files, Docker configs, build targets, and exposed ports. |
| `check_pending_migrations` | Inspects remote database migration state for Prisma, TypeORM, Sequelize, Drizzle, or custom migration scripts. |
| `verify_health` | Performs HTTP health check requests against local or domain endpoints post-deployment. |
| `view_app_logs` | Fetches tail logs from PM2 processes or Docker containers via SSH. |

### 2. Infrastructure Provisioning & Setup
| Tool Name | Description |
|-----------|-------------|
| `prepare_new_server` | Generates package update and core build utility installation plans (`curl`, `git`, `build-essential`, firewall) mapped to detected OS. |
| `install_runtimes` | Provisioning plan for dynamic Node.js versions (e.g. `20`, `22`), PM2 process manager, and Docker Engine. |
| `configure_firewall` | Generates UFW or Firewalld security rules to allow SSH (22), HTTP (80), and HTTPS (443). |
| `setup_nginx_reverse_proxy` | Generates reverse proxy blocks mapping domain names to local backend application ports. |
| `setup_ssl_certbot` | Provisions and configures Let's Encrypt SSL certificates via Certbot for secure HTTPS traffic. |

### 3. Environment & Security
| Tool Name | Description |
|-----------|-------------|
| `generate_secure_env_template` | Scans codebase and generates blank `.env` template definitions. |
| `secure_env_writer` | Writes `.env` configuration files directly to remote server paths securely via SSH. |

### 4. Planning & Execution
| Tool Name | Description |
|-----------|-------------|
| `plan_dynamic_deployment` | **(Recommended)** Context-aware deployment plan evaluating Git diffs, ORM migrations, builds, and process restarts. |
| `plan_docker_deployment` | Specialized planning tool for Docker Compose containerized applications. |
| `plan_github_pm2_deployment` | Specialized planning tool for PM2-managed Node.js applications. |
| `confirm_execution` | Executes a generated deployment plan step-by-step with non-fatal pausing on step failure. |

### 5. Self-Healing Execution Engine (v1.7.0)
| Tool Name | Description |
|-----------|-------------|
| `diagnose_and_fix` | Runs sanitized diagnostic fix commands via SSH for a paused deployment without resetting Git commit state. |
| `resume_execution` | Resumes a paused deployment plan, skipping completed steps and running remaining steps to completion. |
| `rollback_execution` | Aborts a deployment plan and executes automated Git reset and service reload sequence. |

### 6. Maintenance & Persistent Documentation (v1.6.0)
| Tool Name | Description |
|-----------|-------------|
| `generate_project_runbook` | Generates a local `DEPLOYMENT_RUNBOOK.md` containing manual SSH commands, Nginx config, SSL status, and `.env` locations. |
| `cleanup_server_resources` | Safely prunes dangling Docker images (`docker image prune -f`) and stale Git branches if disk usage is $>70\%$. |

---

## ⚡ Quick Start & Configuration Guide

### 🤖 Interactive AI Setup Wizard (Copy-Paste Prompt)

Instead of manually editing config files, copy the prompt below and paste it into your AI assistant (Antigravity IDE, Claude, Cursor, Kimi, etc.) to run an interactive setup wizard:

```text
You are my AI DevOps Setup Assistant for devops-deploy-guard-mcp-server.

Please guide me through setting up this MCP server step-by-step by interviewing me first.

Ask me these questions in a clean list:
1. What is your VPS IP address or host domain?
2. What is your SSH username (e.g., root, ubuntu, deploy)?
3. What is the local path to your unencrypted SSH private key file (e.g., C:\Users\name\.ssh\id_rsa or ~/.ssh/id_rsa)?
4. What is your domain name (e.g., api.example.com) and admin email address for SSL?
5. Which AI IDE / MCP Client are you using (Antigravity IDE, Claude Desktop, Cursor, Kimi, etc.)?

After I answer:
- Create or update my local .devops-mcp.json config file with my responses.
- Ensure .devops-mcp.json and .deployment-history.json are listed in my .gitignore file.
- Generate the exact MCP client configuration JSON snippet formatted for my AI IDE.
- Compile the TypeScript server with `npm run build` and run `inspect_server` to verify SSH connectivity.
```

---

### 1. Manual Installation

```bash
cd devops-deploy-guard-mcp-server
npm install
npm run build
```

### 2. Configuration (`.devops-mcp.json`)

When launched, the server automatically creates a `.devops-mcp.json` file in your workspace root (and appends it to `.gitignore`):

```json
{
  "vps_host": "203.0.113.45",
  "vps_user": "root",
  "ssh_private_key_path": "/Users/yourname/.ssh/id_rsa",
  "domain_name": "api.example.com",
  "admin_email": "admin@example.com",
  "vps_port": 22
}
```

---

## 🔌 Connecting to MCP Clients

### Antigravity IDE / Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "devops-deploy-guard": {
      "command": "node",
      "args": ["/absolute/path/to/devops-deploy-guard-mcp-server/dist/index.js"]
    }
  }
}
```

### Cursor / Kimi / Stdio Clients

Command: `node`  
Arguments: `/absolute/path/to/devops-deploy-guard-mcp-server/dist/index.js`

---

## 🔄 Self-Healing Deployment Workflow (v1.7.0 Walkthrough)

```
                 Developer / AI requests deployment
                                │
                                ▼
                   ┌──────────────────────────┐
                   │ plan_dynamic_deployment  │  ← Analyzes diffs & builds plan
                   └────────────┬─────────────┘
                                │
                                ▼
                   ┌──────────────────────────┐
                   │    confirm_execution     │  ← Executes step-by-step
                   └────────────┬─────────────┘
                                │
            ┌───────────────────┴───────────────────┐
            │                                       │
     [All Steps Succeed]                    [Step Fails (e.g. npm peer dep)]
            │                                       │
            ▼                                       ▼
 ┌─────────────────────┐               ┌──────────────────────────┐
 │ Status: SUCCESS     │               │ Status: PAUSED_AWAITING_FIX│
 └─────────────────────┘               └────────────┬─────────────┘
                                                    │
                                                    ▼
                                       ┌──────────────────────────┐
                                       │    diagnose_and_fix      │  ← LLM applies fix command
                                       └────────────┬─────────────┘
                                                    │
                                       ┌────────────┴─────────────┐
                                       │                          │
                                  [Fix Works]               [Cannot Fix]
                                       │                          │
                                       ▼                          ▼
                          ┌────────────────────────┐  ┌────────────────────────┐
                          │    resume_execution    │  │   rollback_execution   │
                          └────────────────────────┘  └────────────────────────┘
```

---

## 📖 Operational Documentation & History

1. **Auto-Runbook File (`DEPLOYMENT_RUNBOOK.md`)**:
   - Run `generate_project_runbook` to generate a complete markdown runbook for human developers and handovers.
2. **Deployment History Log (`.deployment-history.json`)**:
   - Every deployment attempt (success, paused, or rolled back) is automatically logged with timestamp, plan ID, status, and executed commands.

---

## 🛠️ Development & Testing

```bash
# Watch mode for development
npm run dev

# Run Vitest unit tests
npm test

# Production build
npm run build
```

---

## 📄 License

MIT