部署中心-mcp服务器

Name: 部署中心-mcp服务器
Author: deployhq

作者：deployhq10 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

DeployHQ MCP Server

适用于DeployHQ的模型上下文协议（MCP）服务器，使AI助手如Claude Desktop和Claude Code能够与您的DeployHQ部署进行交互。

🚀 特性

完整的DeployHQ API集成：访问项目、服务器和部署
简易安装：直接使用npx安装，无需额外安装步骤
兼容Claude Desktop & Claude Code：支持两种MCP客户端的stdio传输
安全：凭据通过环境变量传递，不会存储
类型安全：使用TypeScript和Zod验证构建
多种传输方式：主要使用stdio，同时支持SSE和HTTP（可选，用于托管）
生产就绪：全面的错误处理和日志记录

📋 可用工具

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 (字符串，可选)：使用最新部署的提交作为开始

🚀 快速入门

使用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, 或 DEBUG)
      }
    }
  }
}

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

开始使用

配置完成后，您可以请求Claude与DeployHQ互动：

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

💡 常见使用示例

检查部署状态

用户：我的应用的最新部署状态是什么？
Claude：[使用list_deployments → get_deployment → 显示状态]

调试失败的部署

用户：为什么我的应用的最后一次部署失败了？
Claude：[使用list_deployments → get_deployment_log → 分析日志]

部署最新更改

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

完整工作流程示例

用户：我想将我的应用部署到生产环境，并使用最新的更改

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

🔧 配置选项

环境变量

必需

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

🐛 故障排除

服务器无法启动

问题：服务器启动后立即退出

解决方案：

检查是否设置了所有必需的环境变量
验证Node.js版本是否为18或更高：node --version
在Claude Desktop/Code中检查日志以获取错误消息
尝试设置LOG_LEVEL=DEBUG以获取更多详细信息

认证错误

问题："认证失败"或401/403错误

解决方案：

验证您的邮箱和API密钥是否正确
检查您的API密钥是否已过期
确保您的账户启用了API访问
尝试使用相同的凭证登录DeployHQ网页界面

项目未找到

问题："项目未找到"或404错误

解决方案：

使用list_projects查看确切的永久链接格式
项目永久链接区分大小写
检查您是否有权限访问DeployHQ中的项目

部署创建被阻止

问题：尝试创建部署时出现"服务器处于只读模式"错误

解决方案：

默认情况下，只读模式是禁用的，但您可能已启用它
要禁用只读模式，请在环境变量中设置DEPLOYHQ_READ_ONLY=false
或者使用CLI标志--read-only=false
查看安全性部分以获取关于只读模式的详细说明

部署失败

问题：部署创建但立即失败

解决方案：

使用get_deployment_log查看详细的错误日志
使用list_servers验证服务器UUID是否正确
检查起始和结束修订是否存在于仓库中
确保服务器已正确配置部署密钥

连接超时

问题："请求超时"错误

解决方案：

检查您的互联网连接
验证DeployHQ API是否可访问：curl https://YOUR_ACCOUNT.deployhq.com
大量部署列表可能需要时间 - 使用分页
如果DeployHQ出现问题，请稍后再试

日志未显示

问题：看不到任何日志输出

解决方案：

日志发送到stderr，而不是stdout（对于stdio传输）
检查Claude Desktop/Code日志位置：
- macOS：~/Library/Logs/Claude/
- Windows：%APPDATA%\Claude\logs\
设置LOG_LEVEL=DEBUG以获取详细输出
对于托管模式，请检查Digital Ocean日志

获取您的DeployHQ凭证

用户名：您的DeployHQ登录邮箱
密码：您的DeployHQ密码
账户：您的DeployHQ账户名称（可见于URL：https://ACCOUNT.deployhq.com）

🏗️ 架构

┌─────────────────┐                    ┌─────────────┐
│  Claude Desktop │    stdio/JSON-RPC  │  DeployHQ   │
│  或 Claude Code │◄──────────────────►│  API        │
│                 │    (通过npx)       │             │
│  环境变量 ─────┼───────────────────►│ 基本认证    │
└─────────────────┘                    └─────────────┘

Claude Desktop/Code：通过npx启动服务器的MCP客户端
MCP服务器：从环境变量读取凭据，通过stdio通信
DeployHQ API：带有HTTP基本认证的REST API

📦 先决条件

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

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

🔧 本地开发

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. 本地测试stdio传输

# 先构建
npm run build

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

服务器将以stdio模式启动，并等待stdin上的JSON-RPC消息。

6. 使用Claude Code测试

配置您的本地.claude.json以使用构建版本：

{
  "mcpServers": {
    "deployhq": {
      "command": "node",
      "args": ["/path/to/deployhq-ms-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 "初始提交"
git push origin main

创建新应用：
- 转到 Digital Ocean Apps
- 单击“创建应用”
- 选择您的GitHub仓库
- 选择分支（main）
配置应用：
- Digital Ocean会自动检测Dockerfile
- 或使用.do/app.yaml配置
设置环境变量：
- 转到应用设置 → 环境变量
- 添加以下加密变量：
  - DEPLOYHQ_EMAIL
  - DEPLOYHQ_API_KEY
  - DEPLOYHQ_ACCOUNT
- 添加这些常规变量：
  - NODE_ENV=production
  - PORT=8080
  - LOG_LEVEL=info
部署：
- 单击“下一步”和“创建资源”
- 等待部署完成
**配置自定义域名