473 lines
19 KiB
Markdown
473 lines
19 KiB
Markdown
# 阿里云DevOps MCP服务
|
||
|
||
`MCP` `阿里云` `DevOps` `云效` `AI助手` `流水线`
|
||
|
||
<p align="center">English | <a href="README.zh-cn.md">中文</a><br></p>
|
||
|
||
# alibabacloud-devops-mcp-server
|
||
|
||
[阿里云云效 DevOps](https://www.aliyun.com/product/yunxiao) MCP Server 为 AI 助手提供与云效平台交互的能力，使其能够读取项目中的工作项内容、理解需求后自动编写代码，并提交代码合并请求。企业开发团队可借此辅助代码审查、优化任务管理、减少重复操作，从而专注于更重要的创新与产品交付。
|
||
|
||
## 功能特性
|
||
|
||
alibabacloud-devops-mcp-server 为 AI 助手提供以下能力：
|
||
|
||
- `organization-management`：组织管理工具（组织列表、组织详情、部门信息、组织角色、成员信息等）
|
||
- `code-management`：代码仓库管理工具（仓库管理、分支管理、合并请求管理、文件树等）
|
||
- `project-management`：项目管理工具（项目管理、工作项管理、工作项字段、工作项评论、工时记录等）
|
||
- `pipeline-management`：流水线管理工具（流水线列表、流水线配置、资源管理、标签管理、部署管理等）
|
||
- `application-delivery`：应用交付工具（部署单管理、应用管理、应用标签、变量组管理等）
|
||
- `packages-management`：制品仓库管理工具（制品仓库、制品列表等）
|
||
- `test-management`：测试管理工具（测试用例管理、测试用例目录、测试计划、测试结果等）
|
||
|
||
## 工具列表
|
||
|
||
alibabacloud-devops-mcp-server 集成了多种工具，包括：
|
||
|
||
### 组织管理
|
||
|
||
- `get_current_organization_Info`：获取当前用户的组织信息
|
||
- `get_user_organizations`：获取当前用户已加入的组织列表
|
||
- `get_organization_role`：获取组织角色信息
|
||
- `get_organization_departments`：获取组织的部门列表
|
||
- `get_organization_department_info`：获取组织中某个部门的信息
|
||
- `get_organization_department_ancestors`：获取组织中某个部门的上级部门
|
||
- `get_organization_members`：获取组织的成员列表
|
||
- `get_organization_member_info`：获取组织中某个成员的信息
|
||
- `get_organization_member_info_by_user_id`：通过用户 ID 获取组织成员信息
|
||
- `search_organization_members`：搜索组织成员
|
||
- `list_organization_roles`：列出组织角色
|
||
- `get_organization_role`：获取组织角色信息
|
||
|
||
### 代码管理工具
|
||
|
||
- `create_branch`：创建分支
|
||
- `delete_branch`：删除分支
|
||
- `get_branch`：获取分支信息
|
||
- `list_branches`：获取分支列表
|
||
- `create_file`：创建文件
|
||
- `delete_file`：删除文件
|
||
- `get_file_blobs`：获取文件内容
|
||
- `list_files`：查询文件树
|
||
- `update_file`：更新文件内容
|
||
- `create_change_request`：创建合并请求
|
||
- `create_change_request_comment`：在合并请求上创建评论
|
||
- `get_change_request`：查询合并请求
|
||
- `list_change_request_patch_sets`：查询合并请求版本列表
|
||
- `list_change_request`：查询合并请求列表
|
||
- `list_change_request_comments`：查询合并请求评论列表
|
||
- `get_compare`：比较代码差异
|
||
- `get_repository`：获取仓库详情
|
||
- `list_repositories`：获取仓库列表
|
||
|
||
### 项目管理工具
|
||
|
||
- `get_project`：获取项目详情
|
||
- `search_projects`：搜索项目
|
||
- `get_sprint`：获取迭代详情
|
||
- `list_sprints`：列出项目中的迭代
|
||
- `get_work_item`：获取工作项详情
|
||
- `search_workitems`：搜索工作项
|
||
- `get_work_item_types`：获取工作项类型
|
||
- `create_work_item`：创建工作项
|
||
- `list_all_work_item_types`：列出组织中所有工作项类型
|
||
- `list_work_item_types`：列出项目空间中的工作项类型
|
||
- `get_work_item_type`：获取特定工作项类型的详情
|
||
- `list_work_item_relation_work_item_types`：列出可与特定工作项关联的工作项类型
|
||
- `get_work_item_type_field_config`：获取特定工作项类型的字段配置
|
||
- `get_work_item_workflow`：获取特定工作项类型的工作流信息
|
||
- `list_work_item_comments`：列出特定工作项的评论
|
||
- `create_work_item_comment`：为特定工作项创建评论
|
||
- `list_current_user_effort_records`：【项目管理】获取用户的实际工时明细，结束时间和开始时间的间隔不能大于6个月
|
||
- `list_effort_records`：【项目管理】获取实际工时明细
|
||
- `create_effort_record`：【项目管理】登记实际工时
|
||
- `list_estimated_efforts`：【项目管理】获取预计工时明细
|
||
- `create_estimated_effort`：【项目管理】登记预计工时
|
||
- `update_effort_record`：【项目管理】更新登记实际工时
|
||
- `update_estimated_effort`：【项目管理】更新登记预计工时
|
||
|
||
### 流水线管理工具
|
||
|
||
- `get_pipeline`：获取流水线详情
|
||
- `list_pipelines`：获取流水线列表
|
||
- `smart_list_pipelines`：使用自然语言时间引用智能搜索流水线
|
||
- `create_pipeline_run`：创建流水线运行实例
|
||
- `get_latest_pipeline_run`：获取最新流水线运行实例
|
||
- `get_pipeline_run`：获取流水线运行详情
|
||
- `list_pipeline_runs`：获取流水线运行列表
|
||
- `list_pipeline_jobs_by_category`：按分类获取流水线执行任务
|
||
- `list_pipeline_job_historys`：获取流水线任务的执行历史
|
||
- `execute_pipeline_job_run`：手动运行流水线任务
|
||
- `get_pipeline_job_run_log`：获取流水线任务的执行日志
|
||
- `list_service_connections`：列出组织中的服务连接
|
||
- `create_pipeline_from_description`：自动生成 YAML 配置并创建流水线
|
||
- `update_pipeline`：通过 pipelineId 更新云效中现有的流水线（可更新 YAML、阶段、任务等）
|
||
- `create_resource_member`：创建资源成员
|
||
- `delete_resource_member`：删除资源成员
|
||
- `list_resource_members`：获取资源成员列表
|
||
- `update_resource_member`：更新资源成员
|
||
- `update_resource_owner`：转让资源所有者
|
||
- `create_tag`：创建标签
|
||
- `create_tag_group`：创建标签组
|
||
- `list_tag_groups`：获取标签组列表
|
||
- `delete_tag_group`：删除标签组
|
||
- `update_tag_group`：更新标签组
|
||
- `get_tag_group`：获取标签组
|
||
- `delete_tag`：删除标签
|
||
- `update_tag`：更新标签
|
||
- `stop_vm_deploy_order`：停止虚拟机部署单
|
||
- `skip_vm_deploy_machine`：跳过虚拟机部署机器
|
||
- `retry_vm_deploy_machine`：重试虚拟机部署机器
|
||
- `resume_vm_deploy_order`：恢复虚拟机部署单
|
||
- `get_vm_deploy_order`：获取虚拟机部署单详情
|
||
- `get_vm_deploy_machine_log`：获取虚拟机部署机器日志
|
||
|
||
### 应用交付工具
|
||
|
||
- `create_change_order`：【应用交付】创建部署单
|
||
- `list_change_order_versions`：【应用交付】查看部署单版本列表
|
||
- `get_change_order`：【应用交付】读取部署单使用的物料和工单状态
|
||
- `list_change_order_job_logs`：【应用交付】查询环境部署单日志
|
||
- `find_task_operation_log`：【应用交付】查询部署任务执行日志，其中通常包含下游部署引擎的调度细节信息
|
||
- `execute_job_action`：【应用交付】操作环境部署单
|
||
- `list_change_orders_by_origin`：【应用交付】根据创建来源查询部署单
|
||
- `create_appstack_change_request`：【应用交付】创建变更请求
|
||
- `get_appstack_change_request_audit_items`：【应用交付】获取变更请求的审批项
|
||
- `list_appstack_change_request_executions`：【应用交付】列出变更请求的执行记录
|
||
- `list_appstack_change_request_work_items`：【应用交付】列出变更请求的工作项
|
||
- `cancel_appstack_change_request`：【应用交付】取消变更请求
|
||
- `close_appstack_change_request`：【应用交付】关闭变更请求
|
||
- `list_applications`：【应用交付】分页列出组织中的应用
|
||
- `get_application`：【应用交付】通过名称获取应用详情
|
||
- `create_application`：【应用交付】创建新应用
|
||
- `update_application`：【应用交付】更新现有应用
|
||
- `get_latest_orchestration`：【应用交付】获取某环境的最新编排
|
||
- `list_app_orchestration`：【应用交付】列出应用编排
|
||
- `create_app_orchestration`：【应用交付】创建应用编排
|
||
- `delete_app_orchestration`：【应用交付】删除应用编排
|
||
- `get_app_orchestration`：【应用交付】获取应用编排
|
||
- `update_app_orchestration`：【应用交付】更新应用编排
|
||
- `get_env_variable_groups`：【应用交付】获取某环境的变量组
|
||
- `create_variable_group`：【应用交付】创建变量组
|
||
- `delete_variable_group`：【应用交付】删除变量组
|
||
- `get_variable_group`：【应用交付】获取变量组
|
||
- `update_variable_group`：【应用交付】更新变量组
|
||
- `get_app_variable_groups`：【应用交付】获取应用的变量组
|
||
- `get_app_variable_groups_revision`：【应用交付】获取应用变量组的版本
|
||
- `search_app_templates`：【应用交付】搜索应用模板
|
||
- `create_app_tag`：【应用交付】创建应用标签
|
||
- `update_app_tag`：【应用交付】更新应用标签
|
||
- `search_app_tags`：【应用交付】搜索应用标签
|
||
- `update_app_tag_bind`：【应用交付】更新应用标签绑定
|
||
- `create_global_var`：【应用交付】创建全局变量组
|
||
- `get_global_var`：【应用交付】获取全局变量组
|
||
- `update_global_var`：【应用交付】更新全局变量组
|
||
- `list_global_vars`：【应用交付】列出全局变量组
|
||
- `get_machine_deploy_log`：【应用交付】获取机器部署日志
|
||
- `add_host_list_to_host_group`：【应用交付】将主机列表添加到主机组
|
||
- `add_host_list_to_deploy_group`：【应用交付】将主机列表添加到部署组
|
||
- `list_app_release_workflows`：【应用交付】列出应用的所有发布流程
|
||
- `list_app_release_workflow_briefs`：【应用交付】列出应用的发布流程概要
|
||
- `get_app_release_workflow_stage`：【应用交付】获取发布流程阶段详情
|
||
- `list_app_release_stage_briefs`：【应用交付】列出发布阶段概要
|
||
- `update_app_release_stage`：【应用交付】更新应用发布流程阶段
|
||
- `list_app_release_stage_runs`：【应用交付】列出发布阶段执行记录
|
||
- `execute_app_release_stage`：【应用交付】为变更请求执行发布流程阶段
|
||
- `cancel_app_release_stage_execution`：【应用交付】取消发布流程阶段执行
|
||
- `retry_app_release_stage_pipeline`：【应用交付】重试发布流程阶段流水线
|
||
- `skip_app_release_stage_pipeline`：【应用交付】跳过发布流程阶段流水线
|
||
- `list_app_release_stage_execution_integrated_metadata`：【应用交付】列出阶段执行的集成元数据
|
||
- `get_app_release_stage_pipeline_run`：【应用交付】获取发布阶段流水线运行实例
|
||
- `pass_app_release_stage_pipeline_validate`：【应用交付】通过发布流程阶段校验
|
||
- `get_app_release_stage_execution_pipeline_job_log`：【应用交付】获取流水线任务执行日志
|
||
- `refuse_app_release_stage_pipeline_validate`：【应用交付】拒绝发布流程阶段校验
|
||
|
||
### 制品仓库管理工具
|
||
|
||
- `list_package_repositories`：获取制品仓库详情列表
|
||
- `list_artifacts`：获取制品详情列表
|
||
- `get_artifact`：获取单个制品详情
|
||
|
||
### 测试管理工具
|
||
|
||
- `list_testcase_directories`：【测试管理】获取测试用例目录列表
|
||
- `create_testcase_directory`：【测试管理】创建测试用例目录
|
||
- `get_testcase_field_config`：【测试管理】获取测试用例字段配置
|
||
- `create_testcase`：【测试管理】创建测试用例
|
||
- `search_testcases`：【测试管理】搜索测试用例
|
||
- `get_testcase`：【测试管理】获取测试用例信息
|
||
- `delete_testcase`：【测试管理】删除测试用例
|
||
- `list_test_plans`：【测试管理】获取测试计划列表
|
||
- `get_test_result_list`：【测试管理】获取测试计划中的测试用例列表
|
||
- `update_test_result`：【测试管理】更新测试结果
|
||
|
||
## 使用方式
|
||
|
||
### 前置条件
|
||
* Node.js 版本 >= 18.0.0
|
||
* [阿里云云效 DevOps](https://www.aliyun.com/product/yunxiao) 个人访问令牌，[点击此处获取](https://help.aliyun.com/zh/yunxiao/developer-reference/obtain-personal-access-token)。需授予组织管理、项目协作、代码管理、流水线管理、制品仓库管理、应用交付及测试管理下所有 API 的读写权限。
|
||
|
||
|
||
|
||
## 快速开始（推荐：使用 Stdio 模式）
|
||
|
||
**Stdio 模式**是最简单、最常用的方式，适用于大多数 MCP 客户端（如 Cursor、Claude Desktop、iFlow 等）。无需安装 Docker，通过 npx 即可运行。
|
||
|
||
### 方式一：通过 NPX 直接使用（最简单）
|
||
|
||
在您的 MCP 客户端配置文件中添加以下配置：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"command": "npx",
|
||
"args": [
|
||
"-y",
|
||
"alibabacloud-devops-mcp-server"
|
||
],
|
||
"env": {
|
||
"YUNXIAO_ACCESS_TOKEN": "<YOUR_TOKEN>"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **注意**：
|
||
> - 将 `<YOUR_TOKEN>` 替换为您的云效访问令牌
|
||
> - `-y` 标志可自动确认安装，无需手动确认
|
||
> - 此方式使用 **stdio 模式**，通过标准输入/输出与 MCP 客户端通信
|
||
|
||
### 方式二：通过 MCP 市场安装
|
||
|
||
通灵码（阿里云通义灵码）内置的 MCP 市场已提供阿里云 DevOps MCP 服务。安装时，只需在灵码中进入 MCP 市场，搜索"云效 DevOps"，点击安装即可。
|
||
|
||
---
|
||
|
||
## 使用 Docker（可选）
|
||
|
||
如需通过 Docker 运行 MCP Server，可选择 **stdio 模式**或 **SSE 模式**。
|
||
|
||
### Docker Stdio 模式
|
||
|
||
此方式与直接使用 npx 类似，但通过 Docker 容器运行。
|
||
|
||
#### 1. 获取 Docker 镜像
|
||
|
||
**方式一：使用官方镜像（推荐）**
|
||
|
||
```shell
|
||
docker pull build-steps-public-registry.cn-beijing.cr.aliyuncs.com/build-steps/alibabacloud-devops-mcp-server:v0.2.0
|
||
```
|
||
|
||
**方式二：自行构建镜像**
|
||
|
||
```shell
|
||
docker build -t alibabacloud/alibabacloud-devops-mcp-server .
|
||
```
|
||
|
||
#### 2. 配置 MCP 客户端
|
||
|
||
在您的 MCP 客户端配置文件中添加以下内容：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"command": "docker",
|
||
"args": [
|
||
"run",
|
||
"-i",
|
||
"--rm",
|
||
"-e",
|
||
"YUNXIAO_ACCESS_TOKEN",
|
||
"build-steps-public-registry.cn-beijing.cr.aliyuncs.com/build-steps/alibabacloud-devops-mcp-server:v0.2.0"
|
||
],
|
||
"env": {
|
||
"YUNXIAO_ACCESS_TOKEN": "<YOUR_TOKEN>"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **注意**：
|
||
> - 若使用自建镜像，请将镜像名称替换为 `alibabacloud/alibabacloud-devops-mcp-server`
|
||
> - 此方式使用 **stdio 模式**，容器通过标准输入/输出进行通信
|
||
|
||
### Docker SSE 模式
|
||
|
||
SSE 模式通过 HTTP 提供服务，适用于需要独立部署或支持多用户的场景。
|
||
|
||
#### 1. 启动 SSE 服务
|
||
|
||
**使用官方镜像：**
|
||
|
||
```shell
|
||
docker run -d --name yunxiao-mcp \
|
||
-p 3000:3000 \
|
||
-e YUNXIAO_ACCESS_TOKEN="your_token_here" \
|
||
-e PORT=3000 \
|
||
-e MCP_TRANSPORT=sse \
|
||
build-steps-public-registry.cn-beijing.cr.aliyuncs.com/build-steps/alibabacloud-devops-mcp-server:v0.2.0 \
|
||
node dist/index.js --sse
|
||
```
|
||
|
||
**使用自建镜像：**
|
||
|
||
```shell
|
||
docker run -d --name yunxiao-mcp \
|
||
-p 3000:3000 \
|
||
-e YUNXIAO_ACCESS_TOKEN="your_token_here" \
|
||
-e PORT=3000 \
|
||
-e MCP_TRANSPORT=sse \
|
||
alibabacloud/alibabacloud-devops-mcp-server \
|
||
node dist/index.js --sse
|
||
```
|
||
|
||
#### 2. 配置 MCP 客户端
|
||
|
||
在您的 MCP 客户端配置文件中添加以下内容：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"url": "http://localhost:3000/sse"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
如需在连接时传入自定义令牌（而非使用服务启动时的默认令牌）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"url": "http://localhost:3000/sse?yunxiao_access_token=YOUR_TOKEN_HERE"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 管理 SSE 服务
|
||
|
||
查看日志：
|
||
```shell
|
||
docker logs -f yunxiao-mcp
|
||
```
|
||
|
||
停止服务：
|
||
```shell
|
||
docker stop yunxiao-mcp
|
||
```
|
||
|
||
### 通过 Docker Compose 运行 SSE 模式
|
||
|
||
1. **环境配置**
|
||
```shell
|
||
cd alibabacloud-devops-mcp-server
|
||
cp .env.example .env
|
||
# 编辑 .env 文件并设置 YUNXIAO_ACCESS_TOKEN
|
||
```
|
||
|
||
2. **启动服务**
|
||
```shell
|
||
docker compose up -d
|
||
```
|
||
|
||
3. **配置 MCP 客户端**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"url": "http://localhost:3000/sse"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 高级 SSE 模式配置
|
||
|
||
### 使用自定义令牌
|
||
|
||
在 SSE 模式下，每个用户可通过以下方式传入自己的令牌：
|
||
|
||
1. **通过查询参数**（推荐）：
|
||
```
|
||
http://localhost:3000/sse?yunxiao_access_token=USER_SPECIFIC_TOKEN
|
||
```
|
||
|
||
2. **通过请求头**：
|
||
```
|
||
x-yunxiao-token: USER_SPECIFIC_TOKEN
|
||
```
|
||
|
||
这样多个用户可以共享同一个 SSE 服务，同时使用各自独立的令牌进行身份认证。
|
||
|
||
### 在 Codex 中配置 SSE 模式
|
||
|
||
如果您的云效 MCP Server 已在 `http://localhost:3000` 以 SSE 模式运行，可在 Codex 中按如下方式配置：
|
||
|
||
**使用默认令牌（服务启动时配置）：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"url": "http://localhost:3000/sse"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**在 URL 中传入令牌：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"yunxiao": {
|
||
"url": "http://localhost:3000/sse?yunxiao_access_token=YOUR_TOKEN_HERE"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 工具集
|
||
服务器现已支持工具集，允许您仅启用所需的工具，从而减少呈现给 AI 助手的工具数量，提升性能。
|
||
|
||
可用工具集：
|
||
- `organization-management`：组织管理工具（组织列表、组织详情、部门信息、组织角色、成员信息等）
|
||
- `code-management`：代码仓库管理工具（仓库管理、分支管理、合并请求管理、文件树等）
|
||
- `project-management`：项目管理工具（项目管理、工作项管理、工作项字段、工作项评论、工时记录等）
|
||
- `pipeline-management`：流水线管理工具（流水线列表、流水线配置、资源管理、标签管理、部署管理等）
|
||
- `packages-management`：制品仓库管理工具（制品仓库、制品列表等）
|
||
- `application-delivery`：应用交付工具（部署单管理、应用管理、应用标签、变量组管理等）
|
||
- `test-management`：测试管理工具（测试用例管理、测试用例目录、测试计划、测试结果等）
|
||
|
||
可通过命令行参数或环境变量指定工具集：
|
||
|
||
1. 通过命令行参数：
|
||
```bash
|
||
npx -y alibabacloud-devops-mcp-server --toolsets=code-management,project-management
|
||
```
|
||
|
||
2. 通过环境变量：
|
||
```bash
|
||
DEVOPS_TOOLSETS=code-management,project-management npx -y alibabacloud-devops-mcp-server
|
||
```
|
||
|
||
若未指定工具集，默认启用所有工具。
|
||
|
||
## 联系我们
|
||
|
||
如有任何问题，欢迎加入阿里云 DevOps 讨论群（134400004101）进行交流。
|
||
|
||
|
||
|
||
## 相关链接
|
||
- [阿里云云效 DevOps](https://www.aliyun.com/product/yunxiao)
|
||
- [MCP 市场](https://modelscope.cn/mcp/servers/@aliyun/alibabacloud-devops-mcp-server)
|
||
- [使用案例示例](https://mp.weixin.qq.com/s/KQsN6dQlnNeCNATC-QD7pg) |