zadig-mcp

v1.0.6

Published

2 days ago

Zadig MCP Server - Model Context Protocol integration for Zadig CI/CD platform

0High
0Medium
0Low

ranshaw

mcp zadig cicd deployment devops model-context-protocol

Zadig MCP Server

一个用于集成 Zadig CI/CD 平台的 Model Context Protocol (MCP) 服务器,让您可以在 Cursor AI 中直接操作 Zadig 进行发版、环境管理和服务监控。

✨ 功能特性

🚀 智能缓存 (新增)

✅ 自动预加载 - 启动时自动缓存所有项目、服务和工作流信息
✅ 快速查询 - 通过服务名直接查找所属项目和工作流,无需手动指定项目
✅ 模糊搜索 - 支持通过关键词搜索服务
✅ 缓存管理 - 手动刷新缓存或查看缓存状态

项目管理

✅ 列出项目 - 查看所有有权限的项目
✅ 项目详情 - 获取项目配置和统计信息

工作流管理

✅ 列出工作流 - 查看项目的所有可用工作流
✅ 触发工作流 - 一键启动构建和部署任务
✅ 查询任务状态 - 实时监控工作流执行进度
✅ 查看任务历史 - 获取发版历史记录

环境管理

✅ 列出环境 - 查看测试/生产环境列表
✅ 环境详情 - 查看环境配置和状态

服务管理

✅ 列出服务 - 查看项目中的所有服务
✅ 服务详情 - 查看服务信息

🚀 快速开始

1. 配置 Cursor MCP

方式一：使用 npx（推荐，无需安装）

在 Cursor 设置中添加 MCP 服务器配置：

{
  "mcpServers": {
    "zadig": {
      "command": "npx",
      "args": ["-y", "zadig-mcp"],
      "env": {
        "ZADIG_URL": "https://zadig.XXX.com",
        "ZADIG_TOKEN": "your-actual-token-here"
      }
    }
  }
}

方式二：本地安装后使用

npm install -g zadig-mcp

配置文件：

{
  "mcpServers": {
    "zadig": {
      "command": "zadig-mcp",
      "env": {
        "ZADIG_URL": "https://zadig.XXX.com",
        "ZADIG_TOKEN": "your-actual-token-here"
      }
    }
  }
}

方式三：从源码运行（开发者）

git clone <仓库地址>
cd zadig-mcp
npm install

配置文件（需指定完整路径）：

{
  "mcpServers": {
    "zadig": {
      "command": "node",
      "args": ["/绝对路径/zadig-mcp/index.js"],
      "env": {
        "ZADIG_URL": "https://zadig.XXX.com",
        "ZADIG_TOKEN": "your-actual-token-here"
      }
    }
  }
}

2. 获取 API Token

登录您的 Zadig 实例（将 XXX 替换为您的域名）
点击右上角用户头像
选择"账号设置"
复制 API Token
将 Token 粘贴到上方配置的 ZADIG_TOKEN 中

3. 重启 Cursor

配置完成后，重启 Cursor 使 MCP 服务器生效。

📚 使用示例

在 Cursor 中,您可以通过自然语言与 Zadig 交互:

🆕 示例 1: 智能查找服务所属项目

你: "调用zadig的mcp工具，查找项目 front-new 下有多少个服务?"

AI 会调用 zadig_find_service_info,自动从缓存中查找并返回:

所属项目名称
项目描述
相关的工作流列表

优势: 无需记住或指定项目名,直接通过服务名查询!

🆕 示例 2: 搜索服务

你: "调用zadig的mcp工具，搜索包含 front 的项目"

AI 会调用 zadig_search_services,返回所有匹配的服务及其所属项目。

🆕 示例 3: 查看缓存状态

你: "调用zadig的mcp工具，查看 Zadig 缓存状态"

AI 会调用 zadig_get_cache_stats,显示:

缓存的项目数、服务数、工作流数
缓存更新时间
缓存状态

示例 4: 查看项目列表

你: "调用zadig的mcp工具，列出我有权限的所有 Zadig 项目"

AI 会调用 zadig_list_projects 并返回项目列表。

示例 5: 查看工作流

你: "调用zadig的mcp工具，查看 front-new 项目的所有工作流"

AI 会调用 zadig_list_workflows 并显示工作流列表。

示例 6: 触发发版

你: "调用zadig的mcp工具，agent-call的master分支部署到国内测试环境"

AI 会:

调用 zadig_trigger_workflow
返回任务 ID 和状态

示例 7: 查看环境

你: "调用zadig的mcp工具，查看 voice-realtime 项目的所有环境"

AI 会调用 zadig_list_environments 并显示环境列表。

示例 8: 查看服务列表

你: "调用zadig的mcp工具，列出 voice-realtime 项目中的所有服务"

AI 会调用 zadig_list_services 并显示服务列表。

🆕 示例 9: 首次发布后保存发布信息

你: "调用zadig的mcp工具，将 agent-call 发布到香港环境，分支 master"

# 发布成功后
你: "保存发布信息"

AI 会：

调用 zadig_trigger_workflow 触发发布，成功后提示可保存
调用 zadig_save_deploy_preset，以 agent-call 为 key，将工作流名、项目、环境、服务列表、分支等参数持久化到本地

💡 支持的保存指令："保存发布信息"、"保存一下"、"记住这次发布"、"把发布参数存起来"

🆕 示例 10: 下次直接快速发布（无需重新收集参数）

你: "调用zadig的mcp工具，发布 agent-call"

AI 检测到已有预设，直接调用 zadig_quick_deploy，沿用上次保存的分支和环境，无需再次询问工作流名、项目等信息。

若需要换分支：

你: "发布 agent-call，分支换成 release/1.2.0"

AI 会用新分支触发发布，并自动更新预设中的默认分支。

🆕 示例 11: 查看所有已保存的发布预设

你: "查看所有发布预设"
你: "有哪些服务保存了发布信息"

AI 会调用 zadig_list_deploy_presets，列出所有已保存的服务及其工作流、环境、分支信息。

🆕 示例 12: 删除发布预设

你: "删除 agent-call 的发布预设"

AI 会调用 zadig_delete_deploy_preset 移除该预设。

🆕 示例 13: 获取工作流的 targets 配置

你: "获取 front-new-publish 工作流在 hk 环境的 targets"

AI 会调用 zadig_get_workflow_targets，返回该工作流的所有服务构建和部署配置，包括：

服务名、镜像名
构建仓库信息（repo_owner, repo_name, branch 等）
部署环境配置
环境变量

该接口支持缓存，重复查询会优先从缓存返回，提升性能。

🌍 环境映射说明

为方便自然语言交互，系统支持智能环境映射：

环境代码对照表

| 环境代码 | 环境名称 | 自然语言描述 | |---------|---------|------------| | hk | 香港环境 | 香港环境、香港、hk环境 | | load | 压测环境 | 压测环境、压测、性能测试 | | ten-test | 腾讯云测试环境 | 测试环境(默认)、测试、腾讯云测试 | | ali-test | 阿里云测试环境 | 阿里云测试、阿里云、阿里测试 |

智能映射规则

⭐ 重要: 当您说"测试环境"且未明确指定云厂商时，系统自动使用 ten-test（腾讯云测试环境）

使用示例：

# 默认测试环境
你: "发布 front-new 到测试环境"
→ 自动使用: ten-test

# 香港环境
你: "发布 front-new 到香港环境"
→ 使用: hk

# 阿里云测试
你: "发布 front-new 到阿里云测试"
→ 使用: ali-test

# 压测环境
你: "发布 front-new 到压测环境"
→ 使用: load

🛠️ 可用工具

智能缓存工具 (新增 🆕)

| 工具名称 | 功能描述 | 必填参数 | 说明 | |---------|---------|----------|------| | zadig_find_service_info | 通过服务名快速查找所属项目和工作流 | serviceName | 无需指定项目名 | | zadig_search_services | 搜索服务(支持模糊匹配) | keyword | 返回匹配服务及所属项目 | | zadig_refresh_cache | 手动刷新缓存 | 无 | 重新加载所有数据 | | zadig_get_cache_stats | 获取缓存统计信息 | 无 | 查看缓存状态和数据量 |

发布预设工具 (新增 🆕)

| 工具名称 | 功能描述 | 必填参数 | 说明 | |---------|---------|----------|------| | zadig_save_deploy_preset | 保存发布预设参数 | key, workflowName, projectName, namespace, branch | 持久化存储，不过期 | | zadig_quick_deploy | 使用预设快速触发发布 | key | branch 可选，覆盖预设默认分支 | | zadig_list_deploy_presets | 列出所有发布预设 | 无 | 查看已保存的服务发布参数 | | zadig_delete_deploy_preset | 删除发布预设 | key | 移除指定服务的预设 |

项目管理

| 工具名称 | 功能描述 | 必填参数 | |---------|---------|----------| | zadig_list_projects | 列出所有有权限的项目 | 无 | | zadig_get_project_detail | 获取项目详情 | projectName |

工作流管理

| 工具名称 | 功能描述 | 必填参数 | |---------|---------|----------| | zadig_list_workflows | 列出项目的工作流 | projectName | | zadig_trigger_workflow | 触发工作流（需明确指定分支/Tag） | workflowName, projectName, namespace, branch | | zadig_quick_deploy | 使用预设快速发布（已保存参数时推荐） | key | | zadig_list_workflow_tasks | 获取工作流任务列表 | workflowName, projectName | | zadig_get_workflow_task_status | 获取任务状态 | workflowName, taskId, projectName | | zadig_get_workflow_targets | 🆕 获取工作流的 targets 配置 | workflowName, namespace, projectName |

环境管理

| 工具名称 | 功能描述 | 必填参数 | |---------|---------|----------| | zadig_list_environments | 列出环境 | projectName | | zadig_get_environment_detail | 获取环境详情 | envName, projectName |

服务管理

| 工具名称 | 功能描述 | 必填参数 | |---------|---------|----------| | zadig_list_services | 列出服务 | projectName |

📁 项目结构

zadig-mcp/
├── index.js                          # MCP 服务器入口
├── package.json                      # 项目配置
├── test.js                           # 集成测试脚本
├── src/
│   ├── zadig-client.js              # Zadig API 客户端
│   ├── tools/                        # 工具实现
│   │   ├── project.js               # 项目工具
│   │   ├── workflow.js              # 工作流工具
│   │   ├── environment.js           # 环境工具
│   │   ├── service.js               # 服务工具
│   │   └── cache.js                 # 🆕 缓存工具
│   └── utils/                        # 工具类
│       ├── config.js                 # 配置管理
│       ├── logger.js                 # 日志工具
│       └── cache.js                  # 🆕 缓存管理器
├── mcp-config/                       # MCP 配置
│   ├── SERVER_METADATA.json          # 服务器元数据
│   ├── STATUS.md                     # 服务器状态说明
│   ├── INSTRUCTIONS.md               # 使用说明
│   └── tools/                        # 工具定义 (JSON Schema)
│       ├── list_projects.json
│       ├── list_workflows.json
│       ├── trigger_workflow.json
│       ├── get_workflow_targets.json # 🆕
│       ├── find_service_info.json    # 🆕
│       ├── search_services.json      # 🆕
│       ├── refresh_cache.json        # 🆕
│       ├── get_cache_stats.json      # 🆕
│       └── ...
├── config/
│   └── default.json                  # 默认配置
├── .env.example                      # 环境变量示例
├── docs/                             # 📚 完整文档（见下方「文档」章节）
└── README.md                         # 项目说明

⚙️ 配置说明

环境变量

| 变量名 | 必填 | 说明 | 示例 | |--------|-----|------|------| | ZADIG_URL | ✅ | Zadig 实例地址 | https://zadig.XXX.com（将 XXX 替换为您的域名） | | ZADIG_TOKEN | ✅ | Zadig API Token | your-token-here | | LOG_LEVEL | ❌ | 日志级别 | info, debug, warn, error |

注意: 不再需要配置默认项目名称。当需要项目名称时，系统会通过智能缓存自动查找或询问用户。

配置文件 (config/default.json)

{
  "zadig": {
    "url": "https://zadig.XXX.com",
    "apiVersion": "v1.15.0",
    "timeout": 30000,
    "retryAttempts": 3
  },
  "server": {
    "name": "Zadig MCP",
    "version": "1.0.0"
  }
}

仅源码开发时需要，通过 npx 或全局安装使用时无需修改此文件。

说明:

timeout: API 请求超时时间（毫秒）
retryAttempts: 失败重试次数
不再包含 defaultProject 配置，系统会智能识别项目

🔧 故障排查

问题: 无法连接到 Zadig

解决方案:

检查 ZADIG_URL 是否正确
确认 Zadig 实例可访问
检查网络连接

问题: 认证失败

解决方案:

验证 ZADIG_TOKEN 是否正确
检查 Token 是否过期
确认 Token 有项目访问权限

问题: 工具调用失败

解决方案:

查看日志获取详细错误信息
确认项目名称正确
检查 API 版本兼容性(需要 v1.15.0+)

查看日志

设置更详细的日志级别:

LOG_LEVEL=debug npm start

📖 API 文档

详细的 Zadig API 接口说明请参考 docs/api/reference.md。

🔐 安全建议

⚠️ 不要将 .env 文件提交到代码仓库
🔒 定期轮换 API Token
🔐 限制 Token 的权限范围
⚡ 触发工作流前请确认目标环境

🆕 更新日志

v1.0.0 (2026-02-27)

✨ 修复所有 API 接口路径,适配 Zadig v1.15.0
✅ 新增项目管理功能
✅ 优化工作流触发逻辑
✅ 完善错误处理和日志记录
✅ 更新所有工具定义
✅ 完整的测试验证

📄 许可证

MIT

🙏 致谢

感谢 Zadig 团队提供的优秀 CI/CD 平台!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Zadig MCP Server

✨ 功能特性

🚀 智能缓存 (新增)

项目管理

工作流管理

环境管理

服务管理

🚀 快速开始

1. 配置 Cursor MCP

2. 获取 API Token

3. 重启 Cursor

📚 使用示例

🆕 示例 1: 智能查找服务所属项目

🆕 示例 2: 搜索服务

🆕 示例 3: 查看缓存状态

示例 4: 查看项目列表

示例 5: 查看工作流

示例 6: 触发发版

示例 7: 查看环境

示例 8: 查看服务列表

🆕 示例 9: 首次发布后保存发布信息

🆕 示例 10: 下次直接快速发布（无需重新收集参数）

🆕 示例 11: 查看所有已保存的发布预设

🆕 示例 12: 删除发布预设

🆕 示例 13: 获取工作流的 targets 配置

🌍 环境映射说明

环境代码对照表

智能映射规则

🛠️ 可用工具

智能缓存工具 (新增 🆕)

发布预设工具 (新增 🆕)

项目管理

工作流管理

环境管理

服务管理

📁 项目结构

⚙️ 配置说明

环境变量

配置文件 (config/default.json)

🔧 故障排查

问题: 无法连接到 Zadig

问题: 认证失败

问题: 工具调用失败

查看日志

📖 API 文档

🔐 安全建议

🆕 更新日志

v1.0.0 (2026-02-27)

📄 许可证

🙏 致谢