Deployhq MCP Server

🚀 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

列出你的 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"
      }
    }
  }
}

配置優先級：

1. CLI 標誌 --read-only（優先級最高）。
2. 環境變量 DEPLOYHQ_READ_ONLY。
3. 默認值：false（允許部署）。

其他安全注意事項

• 部署日誌可能包含敏感信息：部署日誌可能包含環境變量、API 密鑰和其他敏感信息。在使用檢索日誌的工具時，尤其是與第三方 AI 服務一起使用時，請謹慎操作。
• 使用最小權限的 API 密鑰：為 MCP 訪問創建具有最小所需權限的專用 API 密鑰。考慮為只讀和讀寫操作分別使用不同的密鑰。
• 審核 MCP 活動：監控 MCP 的使用情況，尤其是在生產環境中。定期審查日誌以發現異常行為。
• 環境變量：憑證不進行存儲，僅通過環境變量傳遞。
• HTTPS：使用 npx 時，憑證僅保留在本地機器上。
• 無遙測數據：除了直接發送到 DeployHQ API 外，不向任何地方發送數據。

可選：託管部署

服務器也可以作為託管服務使用 SSE/HTTP 傳輸進行部署。這對於 Web 集成或團隊共享訪問很有用。

部署到 Digital Ocean

選項 1：使用儀表盤

1. 準備你的倉庫：

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

2. 創建新應用：

• 訪問 Digital Ocean Apps。
• 點擊 "Create App"。
• 選擇你的 GitHub 倉庫。
• 選擇分支（main）。

3. 配置應用：

• Digital Ocean 會自動檢測 Dockerfile。
• 也可以使用 .do/app.yaml 配置。

4. 設置環境變量：

• 轉到應用設置 → 環境變量。
• 添加以下作為加密變量：
  • DEPLOYHQ_EMAIL
  • DEPLOYHQ_API_KEY
  • DEPLOYHQ_ACCOUNT
• 添加以下作為普通變量：
  • NODE_ENV=production
  • PORT=8080
  • LOG_LEVEL=info

5. 部署：

• 點擊 "Next" 和 "Create Resources"。
• 等待部署完成。

6. 配置自定義域名（可選）：

• 轉到設置 → 域名。
• 添加 mcp.deployhq.com。
• 按照指示更新你的 DNS 記錄。

選項 2：使用 doctl CLI

1. 安裝 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

2. 進行身份驗證：

doctl auth init

3. 更新 .do/app.yaml：

• 編輯 github.repo 字段為你的倉庫。
• 根據需要審查和調整實例大小。

4. 創建應用：

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

5. 設置環境密鑰：

# 獲取你的應用 ID
doctl apps list

# 更新環境變量（替換 APP_ID）
doctl apps update APP_ID --spec .do/app.yaml

6. 查看日誌：

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             # 本文件

🤝 貢獻

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉倉庫。
2. 創建一個功能分支。
3. 進行更改。
4. 如有必要，添加測試。
5. 提交拉取請求。

維護者說明

有關創建版本併發布到 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

🔗 相關鏈接

• DeployHQ
• Model Context Protocol
• Digital Ocean App Platform
• Claude Desktop
• Claude Code CLI