JinDaGe - deployhq-mcp-server MCP Details

article

README

🚀 DeployHQ MCP 服务器

DeployHQ 的模型上下文协议（MCP）服务器，可让 Claude Desktop 和 Claude Code 等 AI 助手与你的 DeployHQ 部署进行交互。

🚀 快速开始

使用 Claude Code 轻松安装

使用 Claude Code 时，最快的安装方式如下：

claude mcp add --transport stdio deployhq --env DEPLOYHQ_EMAIL=your-email@example.com --env DEPLOYHQ_API_KEY=your-api-key --env DEPLOYHQ_ACCOUNT=your-account -- npx -y deployhq-mcp-server

请将 your-email@example.com、your-api-key 和 your-account 替换为你实际的 DeployHQ 凭证。

手动配置（适用于 Claude Desktop 和 Claude Code）

同样的配置适用于这两个客户端。从 docs/claude-config.json 复制配置并添加你的凭证。

对于 Claude Desktop：编辑你的配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json 然后重启 Claude Desktop。

对于 Claude Code：将配置添加到项目目录下的 .claude.json 文件中。

配置示例：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
        // 可选："LOG_LEVEL": "INFO"  (ERROR, INFO, or DEBUG)
      }
    }
  }
}

注意：仅需要 3 个 DeployHQ 凭证。LOG_LEVEL 是可选的，默认为 INFO。

开始使用

配置完成后，你可以让 Claude 与 DeployHQ 进行交互，例如：

"列出我所有的 DeployHQ 项目"
"显示项目 X 的服务器"
"获取项目 Y 的最新部署状态"
"为项目 Z 创建一个新的部署"
"显示最新部署的部署日志"

✨ 主要特性

全面集成 DeployHQ API：可访问项目、服务器和部署信息。
易于安装：可直接使用 npx，无需安装。
与 Claude Desktop 和 Claude Code 兼容：为两个 MCP 客户端提供标准输入输出传输。
安全可靠：通过环境变量传递凭证，不进行存储。
类型安全：使用 TypeScript 和 Zod 验证构建。
多种传输方式：标准输入输出（主要方式）、SSE 和 HTTP（托管时可选）。
生产就绪：具备全面的错误处理和日志记录功能。

📦 安装指南

此部分内容已在快速开始中详细介绍，通过 npx 可直接使用，无需额外安装。

💻 使用示例

基础用法

检查部署状态

用户：我的应用 my-app 的最新部署状态如何？
Claude：[使用 list_deployments → get_deployment → 显示状态]

调试失败的部署

用户：我的应用 my-app 的上次部署为什么失败了？
Claude：[使用 list_deployments → get_deployment_log → 分析日志]

部署最新更改

用户：将我的应用 my-app 的最新更改部署到生产环境
Claude：[使用 list_servers → list_deployments → 使用 use_latest 创建部署]

完整工作流程示例

用户：我想将我的应用 my-app 的最新更改部署到生产环境

Claude 将执行以下操作：
1. 使用 list_projects 查找 "my-app"
2. 使用 list_servers 查找生产服务器的 UUID
3. 使用 list_deployments 和 use_latest 获取上次修订版本
4. 使用 create_deployment 排队部署
5. 使用 get_deployment 显示状态
6. 如果出现问题，使用 get_deployment_log

📚 详细文档

可用工具

MCP 服务器为 AI 助手提供了 7 个工具： | 属性 | 详情 | |------|------| | list_projects | 列出所有项目 | | get_project | 获取项目详细信息，参数：permalink | | list_servers | 列出项目服务器，参数：project | | list_deployments | 分页列出部署，参数：project, page?, server_uuid? | | get_deployment | 获取特定部署的详细信息，参数：project, uuid | | get_deployment_log | 获取部署日志输出，参数：project, uuid | | create_deployment | 创建新部署，参数：project, parent_identifier, start_revision, end_revision 及其他可选参数 |

`list_projects`

列出你的 DeployHQ 账户中的所有项目。 返回值：包含仓库信息和部署状态的项目数组。

`get_project`

获取特定项目的详细信息。参数：

permalink（字符串）：项目永久链接或标识符

`list_servers`

列出为项目配置的所有服务器。参数：

project（字符串）：项目永久链接

`list_deployments`

支持分页列出项目的部署。参数：

project（字符串）：项目永久链接
page（数字，可选）：分页页码
server_uuid（字符串，可选）：按服务器 UUID 过滤

`get_deployment`

获取特定部署的详细信息。参数：

project（字符串）：项目永久链接
uuid（字符串）：部署 UUID

`get_deployment_log`

获取特定部署的部署日志，对调试失败的部署很有用。参数：

project（字符串）：项目永久链接
uuid（字符串）：部署 UUID 返回值：完整的部署日志文本

`create_deployment`

为项目创建新的部署。参数：

project（字符串）：项目永久链接
parent_identifier（字符串）：服务器或服务器组 UUID
start_revision（字符串）：起始提交哈希
end_revision（字符串）：结束提交哈希
branch（字符串，可选）：要部署的分支
mode（字符串，可选）："queue" 或 "preview"
copy_config_files（布尔值，可选）：复制配置文件
run_build_commands（布尔值，可选）：运行构建命令
use_build_cache（布尔值，可选）：使用构建缓存
use_latest（字符串，可选）：使用最新部署的提交作为起始点

配置选项

环境变量

必需项

DEPLOYHQ_EMAIL：你的 DeployHQ 登录邮箱
DEPLOYHQ_API_KEY：你的 DeployHQ 密码/API 密钥
DEPLOYHQ_ACCOUNT：你的 DeployHQ 账户名（从 URL https://ACCOUNT.deployhq.com 中获取）

可选项

LOG_LEVEL：控制日志详细程度 - ERROR、INFO 或 DEBUG（默认：INFO）
NODE_ENV：环境模式 - production 或 development

日志级别

通过 LOG_LEVEL 环境变量控制日志详细程度：

ERROR：仅显示错误信息
INFO：显示信息和错误信息（默认）
DEBUG：显示所有日志，包括详细的 API 调用信息

示例：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

🔧 技术细节

架构

┌─────────────────┐                    ┌─────────────┐
│  Claude Desktop │    stdio/JSON-RPC  │  DeployHQ   │
│  or Claude Code │◄──────────────────►│  API        │
│                 │    (via npx)       │             │
│  Environment    │                    │             │
│  Variables ─────┼───────────────────►│ Basic Auth  │
└─────────────────┘                    └─────────────┘

Claude Desktop/Code：通过 npx 启动服务器的 MCP 客户端。
MCP 服务器：从环境变量中读取凭证，通过标准输入输出进行通信。
DeployHQ API：使用 HTTP 基本认证的 REST API。

先决条件

Node.js 18+（推荐 Node 20+）
具有 API 访问权限的 DeployHQ 账户

注意：服务器使用 node-fetch 进行 HTTP 请求。开发工具（ESLint、Vitest）需要 Node 18+。

本地开发

1. 克隆仓库

git clone https://github.com/your-username/deployhq-mcp-server.git
cd deployhq-mcp-server

2. 安装依赖

npm install

3. 运行测试

npm test              # 运行一次测试
npm run test:watch    # 开发时的监听模式
npm run test:coverage # 生成测试覆盖率报告
npm run test:ui       # 用于调试的交互式 UI

4. 构建项目

npm run build

5. 本地测试标准输入输出传输

# 先进行构建
npm run build

# 使用环境变量进行测试
DEPLOYHQ_EMAIL="your-email@example.com" \
DEPLOYHQ_API_KEY="your-api-key" \
DEPLOYHQ_ACCOUNT="your-account" \
node dist/stdio.js

服务器将以标准输入输出模式启动，并等待标准输入上的 JSON-RPC 消息。

6. 使用 Claude Code 进行测试

配置本地的 .claude.json 文件以使用构建后的版本：

{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-password",
        "DEPLOYHQ_ACCOUNT": "your-account-name"
      }
    }
  }
}

测试

项目包含一个使用 Vitest 的综合测试套件：

测试覆盖范围：
- ✅ 工具模式验证：对所有 7 个 MCP 工具模式进行有效和无效输入测试。
- ✅ API 客户端方法：对所有 DeployHQ API 方法进行模拟响应测试。
- ✅ 错误处理：测试认证、验证和网络错误。
- ✅ MCP 服务器工厂：测试服务器创建和配置。
运行测试：

npm test              # 运行所有测试
npm run test:watch    # 开发时的监听模式
npm run test:coverage # 生成测试覆盖率报告
npm run test:ui       # 用于调试的交互式 UI

测试统计：
- 3 个测试套件中包含 50 多个测试。
- 覆盖工具、api-client 和 mcp-server 模块。
- 使用模拟的 fetch 进行隔离单元测试。

安全

只读模式（可选）

默认情况下，MCP 服务器允许所有操作，包括创建部署。这是大多数用户的推荐配置。

对于希望额外保护以防止意外部署的用户，服务器提供了一个可选的只读模式，可以启用该模式来阻止部署创建。

默认行为（无需配置）：

✅ 默认允许部署。
✅ 所有操作均可正常进行：列出、获取和创建部署。
✅ 开箱即用的完整功能。

何时需要启用只读模式：

你希望对通过 AI 进行的意外部署提供额外保护。
你连接到生产环境，需要额外的安全层。
你只需要只读访问来监控部署。
你仍在测试集成，希望谨慎行事。

重要提示：只读模式是完全可选的，服务器在不启用该模式的情况下也能正常工作。

如何启用只读模式：通过环境变量：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account",
        "DEPLOYHQ_READ_ONLY": "true"
      }
    }
  }
}

通过 CLI 标志：

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": [
        "-y",
        "deployhq-mcp-server",
        "--read-only"
      ],
      "env": {
        "DEPLOYHQ_EMAIL": "your-email@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "your-account"
      }
    }
  }
}

配置优先级：

CLI 标志 --read-only（优先级最高）。
环境变量 DEPLOYHQ_READ_ONLY。
默认值：false（允许部署）。

其他安全注意事项

部署日志可能包含敏感信息：部署日志可能包含环境变量、API 密钥和其他敏感信息。在使用检索日志的工具时，尤其是与第三方 AI 服务一起使用时，请谨慎操作。
使用最小权限的 API 密钥：为 MCP 访问创建具有最小所需权限的专用 API 密钥。考虑为只读和读写操作分别使用不同的密钥。
审核 MCP 活动：监控 MCP 的使用情况，尤其是在生产环境中。定期审查日志以发现异常行为。
环境变量：凭证不进行存储，仅通过环境变量传递。
HTTPS：使用 npx 时，凭证仅保留在本地机器上。
无遥测数据：除了直接发送到 DeployHQ API 外，不向任何地方发送数据。

可选：托管部署

服务器也可以作为托管服务使用 SSE/HTTP 传输进行部署。这对于 Web 集成或团队共享访问很有用。

部署到 Digital Ocean

选项 1：使用仪表盘

准备你的仓库：

git add .
git commit -m "Initial commit"
git push origin main

创建新应用：

访问 Digital Ocean Apps。
点击 "Create App"。
选择你的 GitHub 仓库。
选择分支（main）。

配置应用：

Digital Ocean 会自动检测 Dockerfile。
也可以使用 .do/app.yaml 配置。

设置环境变量：

转到应用设置 → 环境变量。
添加以下作为加密变量：
- DEPLOYHQ_EMAIL
- DEPLOYHQ_API_KEY
- DEPLOYHQ_ACCOUNT
添加以下作为普通变量：
- NODE_ENV=production
- PORT=8080
- LOG_LEVEL=info

部署：

点击 "Next" 和 "Create Resources"。
等待部署完成。

配置自定义域名（可选）：

转到设置 → 域名。
添加 mcp.deployhq.com。
按照指示更新你的 DNS 记录。

选项 2：使用 doctl CLI

安装 doctl：

# macOS
brew install doctl

# Linux
cd ~
wget https://github.com/digitalocean/doctl/releases/download/v1.104.0/doctl-1.104.0-linux-amd64.tar.gz
tar xf doctl-1.104.0-linux-amd64.tar.gz
sudo mv doctl /usr/local/bin

进行身份验证：

doctl auth init

更新 .do/app.yaml：

编辑 github.repo 字段为你的仓库。
根据需要审查和调整实例大小。

创建应用：

doctl apps create --spec .do/app.yaml

设置环境密钥：

# 获取你的应用 ID
doctl apps list

# 更新环境变量（替换 APP_ID）
doctl apps update APP_ID --spec .do/app.yaml

查看日志：

doctl apps logs APP_ID --follow

托管安全

切勿提交凭证：在本地开发时使用 .env 文件（被 .gitignore 排除）。
使用 Digital Ocean 密钥：将凭证存储为加密的环境变量。
仅使用 HTTPS：Digital Ocean 提供自动 HTTPS。
最小权限：使用具有最小所需权限的专用 DeployHQ 用户。

托管监控

健康检查

托管服务器在 /health 提供了一个健康检查端点：

curl https://mcp.deployhq.com/health

日志

在 Digital Ocean 中查看日志：

仪表盘：转到你的应用 → 运行时日志。
CLI：doctl apps logs <APP_ID> --follow

警报

Digital Ocean 将在以下情况下发出警报：

部署失败。
域名配置问题。
健康检查失败。

测试托管服务器

测试 SSE 端点：

curl -N http://localhost:8080/sse \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account"

测试 HTTP 传输端点：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-DeployHQ-Email: your-email@example.com" \
  -H "X-DeployHQ-API-Key: your-api-key" \
  -H "X-DeployHQ-Account: your-account" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

完整的测试示例请参阅托管部署文档。

项目结构

deployhq-mcp-server/
├── src/
│   ├── stdio.ts          # 标准输入输出传输的入口点（用于 Claude Desktop/Code）
│   ├── index.ts          # Express 服务器（用于托管部署）
│   ├── mcp-server.ts     # 核心 MCP 服务器工厂（共享）
│   ├── tools.ts          # 工具定义和模式（共享）
│   ├── api-client.ts     # DeployHQ API 客户端（共享）
│   ├── transports/       # SSE/HTTP 处理程序（用于托管）
│   └── utils/            # 日志记录和实用工具
├── docs/
│   ├── claude-config.json          # 通用配置模板（Desktop & Code）
│   ├── USER_GUIDE.md               # 用户文档
│   ├── DEPLOYMENT.md               # 托管部署指南
│   └── HTTP_TRANSPORT.md           # HTTP 传输文档
├── .do/
│   └── app.yaml          # Digital Ocean 配置（可选）
├── Dockerfile            # 容器配置（可选）
├── package.json          # 依赖项和脚本
├── tsconfig.json         # TypeScript 配置
├── STDIO_MIGRATION.md    # 标准输入输出迁移文档
└── README.md             # 本文件

🤝 贡献

欢迎贡献代码！请按以下步骤操作：

分叉仓库。
创建一个功能分支。
进行更改。
如有必要，添加测试。
提交拉取请求。

维护者说明

有关创建版本并发布到 npm 的说明，请参阅 RELEASING.md。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🆘 支持

DeployHQ API 文档：https://www.deployhq.com/support/api
MCP 文档：https://modelcontextprotocol.io
问题反馈：https://github.com/deployhq/deployhq-mcp-server/issues