内容
# DevOps 部署守护 MCP 服务器 (v1.7.0)
> **生产就绪的、零知识的 AI DevOps 部署、基础设施配置、自我修复执行和持久化文档引擎，适用于 VPS 服务器。**
`devops-deploy-guard-mcp-server` 是一个高级模型上下文协议（MCP）服务器，它赋予 AI 编码助手（Antigravity IDE、Claude Code/Desktop、Cursor、Kimi 等）安全配置服务器、配置 Nginx 和 SSL、部署应用、交互式调试部署过程中的故障以及维护持久化运行手册的能力，而不会导致生产服务器崩溃或数据库重置。
---
## 🚀 v1.7.0 主要功能
- 🤖 **自我修复执行引擎**：如果部署命令失败，服务器会将执行暂停在 `PAUSED_AWAITING_FIX` 状态，而不是立即回滚。LLM 接收完整的失败输出，通过 `diagnose_and_fix` 应用部署过程中的修复，并通过 `resume_execution` 无缝恢复执行。
- 📘 **自动运行手册生成器（`generate_project_runbook`）**：动态写入一个物理的 `DEPLOYMENT_RUNBOOK.md` 到用户项目根目录中，包含确切的手动 SSH 命令、Nginx 块、SSL 状态和 `.env` 位置。
- 🧹 **安全资源清理（`cleanup_server_resources`）**：检查根分区空间（`df -h /`）并安全地清理悬挂的 Docker 镜像（`docker image prune -f`）和陈旧的 Git 分支，仅当磁盘使用率超过 70%。
- 🎯 **上下文感知条件部署（`plan_dynamic_deployment`）**：检查 Git diffs 与远程跟踪分支，以跳过不必要的 `npm install` 或数据库迁移，当清单和模式未更改时。
- 🛡️ **多操作系统基础设施配置**：自动检测 Ubuntu、Debian、RHEL、CentOS、Fedora 和 Alpine，以生成系统包、Node.js、PM2、Docker、UFW/Firewalld、Nginx 和 Certbot SSL 证书的幂等配置计划。
- 🔒 **两层命令消毒器**：硬阻止灾难性的 shell 命令（`rm -rf`、`DROP DATABASE`、`prisma migrate dev`、`dev` 目标、`--watch`），同时警告风险操作（`docker system prune`、`git reset --hard`）。
---
## 🔒 安全与保护架构
| 安全层 | 描述 |
| --- | --- |
| **两步阶段执行** | 规划工具输出一个 `plan_id`。执行需要显式调用 `confirm_execution` 且 `confirm: true`。 |
| **命令消毒器** | 静态检查所有 shell 字符串。阻止灾难性命令和生产环境中的开发标志。 |
| **非致命暂停引擎** | 暂停失败的部署而不会销毁 Git 状态，使 LLM 能够运行诊断修复命令。 |
| **机密保护** | `.env` 文件通过 SSH heredocs 编写；实际密钥机密从未被回显或转储到 LLM 上下文日志中。 |
| **路径遍历保护** | 防止在批准的项目路径（`/etc/shadow`、`/root/.ssh/`）之外进行任意远程文件写入。 |
| **自动 Gitignore** | 自动将 `.devops-mcp.json` 和 `.deployment-history.json` 添加到 `.gitignore` 中。 |
---
## 📋 全面的工具注册表（19 个工具）
### 1. 只读检查和分析
| 工具名称 | 描述 |
| --- | --- |
| `inspect_server` | 检查操作系统、磁盘空间、Docker 容器、PM2 进程、Nginx 站点、内存使用情况和本地运行手册/历史状态。 |
| `analyze_project_structure` | 检测包管理器（npm、pnpm、yarn、bun）、生态系统文件、Docker 配置、构建目标和暴露的端口。 |
| `check_pending_migrations` | 检查 Prisma、TypeORM、Sequelize、Drizzle 或自定义迁移脚本的远程数据库迁移状态。 |
| `verify_health` | 对本地或域名端点执行 HTTP 健康检查请求，以进行部署后检查。 |
| `view_app_logs` | 通过 SSH 从 PM2 进程或 Docker 容器中获取尾部日志。 |
### 2. 基础设施配置和设置
| 工具名称 | 描述 |
| --- | --- |
| `prepare_new_server` | 生成包更新和核心构建实用程序安装计划（`curl`、`git`、`build-essential`、防火墙），映射到检测到的操作系统。 |
| `install_runtimes` | 动态 Node.js 版本（例如 `20`、`22`）、PM2 进程管理器和 Docker 引擎的配置计划。 |
| `configure_firewall` | 生成 UFW 或 Firewalld 安全规则，以允许 SSH（22）、HTTP（80）和 HTTPS（443）。 |
| `setup_nginx_reverse_proxy` | 生成将域名映射到本地后端应用程序端口的反向代理块。 |
| `setup_ssl_certbot` | 通过 Certbot 为安全 HTTPS 流量提供和配置 Let's Encrypt SSL 证书。 |
### 3. 环境和安全
| 工具名称 | 描述 |
| --- | --- |
| `generate_secure_env_template` | 扫描代码库并生成空白的 `.env` 模板定义。 |
| `secure_env_writer` | 通过 SSH 将 `.env` 配置文件安全地写入远程服务器路径。 |
### 4. 规划和执行
| 工具名称 | 描述 |
| --- | --- |
| `plan_dynamic_deployment` | **（推荐）** 上下文感知部署计划，评估 Git diffs、ORM 迁移、构建和进程重启。 |
| `plan_docker_deployment` | 适用于 Docker Compose 容器化应用程序的专用规划工具。 |
| `plan_github_pm2_deployment` | 适用于 PM2 管理的 Node.js 应用程序的专用规划工具。 |
| `confirm_execution` | 按步骤执行生成的部署计划，在步骤失败时非致命暂停。 |
### 5. 自我修复执行引擎（v1.7.0）
| 工具名称 | 描述 |
| --- | --- |
| `diagnose_and_fix` | 通过 SSH 运行消毒的诊断修复命令，以修复暂停的部署，而不会重置 Git 提交状态。 |
| `resume_execution` | 恢复暂停的部署计划，跳过已完成的步骤，并运行剩余的步骤直到完成。 |
| `rollback_execution` | 终止部署计划，并执行自动 Git 重置和服务重新加载序列。 |
### 6. 维护和持久化文档（v1.6.0）
| 工具名称 | 描述 |
| --- | --- |
| `generate_project_runbook` | 生成本地的 `DEPLOYMENT_RUNBOOK.md`，包含手动 SSH 命令、Nginx 配置、SSL 状态和 `.env` 位置。 |
| `cleanup_server_resources` | 安全地清理悬挂的 Docker 镜像（`docker image prune -f`）和陈旧的 Git 分支，如果磁盘使用率 > 70%。 |
---
## ⚡ 快速入门和配置指南
### 🤖 交互式 AI 设置向导（复制粘贴提示）
与其手动编辑配置文件，不如复制下面的提示并粘贴到您的 AI 助手（Antigravity IDE、Claude、Cursor、Kimi 等）中，以运行交互式设置向导：
```text
您是我的 AI DevOps 设置助手，用于 devops-deploy-guard-mcp-server。
请通过采访我来引导我逐步设置此 MCP 服务器。
请以干净的列表形式问我这些问题：
1. 您的 VPS IP 地址或主机域名是什么？
2. 您的 SSH 用户名（例如 root、ubuntu、deploy）是什么？
3. 您的未加密 SSH 私钥文件的本地路径是什么（例如 C:\Users\name\.ssh\id_rsa 或 ~/.ssh/id_rsa）？
4. 您的域名（例如 api.example.com）和 SSL 的管理员电子邮件地址是什么？
5. 您正在使用哪种 AI IDE / MCP 客户端（Antigravity IDE、Claude Desktop、Cursor、Kimi 等）？
在我回答后：
- 使用我的回答创建或更新我的本地 .devops-mcp.json 配置文件。
- 确保 .devops-mcp.json 和 .deployment-history.json 在我的 .gitignore 文件中列出。
- 为我的 AI IDE 生成确切的 MCP 客户端配置 JSON 代码段。
- 使用 `npm run build` 编译 TypeScript 服务器，并运行 `inspect_server` 以验证 SSH 连接性。
```
---
### 1. 手动安装
```bash
cd devops-deploy-guard-mcp-server
npm install
npm run build
```
### 2. 配置（`.devops-mcp.json`）
启动时，服务器会在工作区根目录中自动创建一个 `.devops-mcp.json` 文件（并将其追加到 `.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
}
```
---
## 🔌 连接到 MCP 客户端
### 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 客户端
命令：`node`
参数：`/absolute/path/to/devops-deploy-guard-mcp-server/dist/index.js`
---
## 🔄 自我修复部署工作流程（v1.7.0 演练）
```
开发人员 / AI 请求部署
│
▼
┌──────────────────────────┐
│ plan_dynamic_deployment │ ← 分析差异并构建计划
└────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ confirm_execution │ ← 按步骤执行
└────────────┬─────────────┘
│
┌───────────────────┴───────────────────┐
│ │
[所有步骤成功] [步骤失败（例如 npm peer dep）]
│ │
▼ ▼
┌─────────────────────┐ ┌──────────────────────────┐
│ 状态：成功 │ │ 状态：暂停等待修复 │
└─────────────────────┘ └────────────┬─────────────┘
│
▼
┌──────────────────────────┐
│ diagnose_and_fix │ ← LLM 应用修复命令
└────────────┬─────────────┘
│
┌────────────┴─────────────┐
│ │
[修复有效] [无法修复]
│ │
▼ ▼
┌────────────────────────┐ ┌────────────────────────┐
│ resume_execution │ │ rollback_execution │
└────────────────────────┘ └────────────────────────┘
```
---
## 📖 运营文档和历史
1. **自动运行手册文件（`DEPLOYMENT_RUNBOOK.md`）**：
- 运行 `generate_project_runbook` 以为人类开发人员和移交生成完整的 Markdown 运行手册。
2. **部署历史日志（`.deployment-history.json`）**：
- 每次部署尝试（成功、暂停或回滚）都会自动记录，包含时间戳、计划 ID、状态和执行的命令。
---
## 🛠️ 开发和测试
```bash
# 适用于开发的监视模式
npm run dev
# 运行 Vitest 单元测试
npm test
# 生产构建
npm run build
```
---
## 📄 许可证
MIT
