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:

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

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):

{
  "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)

{
  "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

# Watch mode for development
npm run dev

# Run Vitest unit tests
npm test

# Production build
npm run build

---

📄 License

MIT