MCP Server for Ezone DevOps

MCP (Model Context Protocol) 服务器，用于对接简单云（Ezone）DevOps 平台，为 Cursor、Cherry Studio 等 AI 工具提供接口能力。

📋 功能特性

• ✅ 支持 Streamable HTTP 传输方式
• ✅ 11 个 MCP 工具，覆盖项目管理、代码库、流水线等核心功能
• ✅ 7 个 MCP 提示词，提供场景化的使用指南
• ✅ 14 个 MCP 资源，提供完整的 API 文档查询
• ✅ 完整的 Maven 项目配置
• ✅ 支持多种编程客户端接入

🏗️ 项目结构

mcp-server-devops/
├── pom.xml                                    # Maven 配置
├── README.md                                  # 项目说明文档
├── IFLOW.md                                   # 项目开发文档
├── src/
│   ├── main/
│   │   ├── java/cn/clenarch/mcp/
│   │   │   ├── McpServerApplication.java      # 启动类
│   │   │   ├── client/
│   │   │   │   ├── EzoneApiClient.java        # Ezone API 客户端
│   │   │   │   └── McpClientExample.java      # 客户端调用示例
│   │   │   ├── config/
│   │   │   │   └── EzoneApiConfig.java        # Ezone API 配置类
│   │   │   ├── controller/                    # 控制器
│   │   │   ├── dto/                           # 数据传输对象
│   │   │   │   ├── code/                      # 代码库相关 DTO
│   │   │   │   ├── pipeline/                  # 流水线相关 DTO
│   │   │   │   ├── project/                   # 项目相关 DTO
│   │   │   │   └── registry/                  # 镜像源相关 DTO
│   │   │   ├── prompts/
│   │   │   │   └── DevOpsPrompts.java         # DevOps 提示词工具
│   │   │   ├── resources/
│   │   │   │   └── ApiDocsResource.java       # API 文档资源
│   │   │   └── tools/                         # MCP 工具实现
│   │   │       ├── CodeTools.java             # 代码库管理工具
│   │   │       ├── PipelineTools.java         # 流水线管理工具
│   │   │       ├── ProjectTools.java          # 项目管理工具
│   │   │       └── RegistryTools.java         # 镜像源管理工具
│   │   └── resources/
│   │       └── application.yml                # 应用配置
│   └── test/
│       └── java/cn/clenarch/mcp/tools/
│           ├── PipelineToolsTest.java         # 流水线工具测试
│           └── ProjectToolsTest.java          # 项目工具测试
└── docs-api/                                  # Ezone 接口文档
    └── docs-api-1.0.0/
        ├── ezAdmin.md                         # 后台管理
        ├── ezBpm.md                           # 流程审批
        ├── ezCode.md                          # 代码库管理
        ├── ezDeploy.md                        # 主机部署
        ├── ezDoc.md                           # 文档管理
        ├── ezK8s.md                           # K8S 管理
        ├── ezPackage.md                       # 制品库管理
        ├── ezPipeline.md                      # 流水线管理
        ├── ezProject.md                       # 项目管理
        ├── ezResource-Manager.md              # 服务集成
        ├── ezScan.md                          # 代码扫描
        └── ezTest.md                          # 测试管理

📥 下载和安装

客户使用（推荐）

客户无需自己编译，直接下载发布包即可。

方式1：Docker 部署（推荐）

# 下载发布包
wget https://github.com/li7hai26/mcp-server-devops/releases/download/v1.0.0/mcp-server-devops-1.0.0-docker.tar.gz

# 解压
tar -xzf mcp-server-devops-1.0.0-docker.tar.gz
cd docker-release

# 启动服务
./start.sh

# 查看日志
docker logs -f mcp-server-devops

# 停止服务
./stop.sh

方式2：直接拉取镜像

# 拉取镜像
docker pull cleanarch/mcp-server-devops:1.0.0

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

方式3：二进制部署（备用）

# 下载发布包
wget https://github.com/li7hai26/mcp-server-devops/releases/download/v1.0.0/mcp-server-devops-1.0.0-binary.tar.gz

# 解压
tar -xzf mcp-server-devops-1.0.0-binary.tar.gz
cd mcp-server-devops-1.0.0-binary

# 启动服务
./scripts/start-binary.sh

# 查看日志
tail -f logs/mcp-server.log

# 停止服务
./scripts/stop-binary.sh

开发者使用

开发者需要克隆代码库并进行本地开发。

# 克隆代码库
git clone https://github.com/li7hai26/mcp-server-devops.git
cd mcp-server-devops

# 构建项目
./scripts/build/build-dev.sh

# 启动服务
./scripts/start/start-dev.sh

🚀 快速开始

1. 环境要求

• JDK 17+
• Maven 3.6+

2. 配置 Ezone API（可选）

注意: Ezone API 认证信息现在通过 MCP 客户端传递，无需在服务器端配置。

方式 1: 环境变量（默认值，可选）

export EZONE_BASE_URL=https://srih.ezone.work
export EZONE_ACCESS_TOKEN=default_token
export EZONE_COMPANY_NAME=default
export EZONE_TIMEOUT=30000

方式 2: 配置文件（默认值，可选）

修改 application.yml：

ezone:
  api:
    base-url: https://srih.ezone.work
    access-token: default_token
    company-name: default
    timeout: 30000

详细配置说明请参考: CONFIG.md

3. 配置 MCP 客户端认证（必填）

MCP 客户端（如 Cursor、Cherry Studio）需要传递认证信息。

详细认证说明请参考: AUTH.md

3. 编译运行

# 编译项目
mvn clean package

# 运行服务
mvn spring-boot:run

4. Docker 部署（推荐）

使用 Docker 构建

# 构建镜像
docker build -t mcp-server-devops:1.0.0 .

# 运行容器
docker run -d \
  --name mcp-server-devops \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  mcp-server-devops:1.0.0

使用 Docker Compose（推荐）

方式1：直接拉取镜像

# 拉取镜像
docker pull cleanarch/mcp-server-devops:1.0.0

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

方式2：使用发布包（推荐）

# 下载发布包
wget https://github.com/li7hai26/mcp-server-devops/releases/download/v1.0.0/mcp-server-devops-1.0.0-docker.tar.gz

# 解压
tar -xzf mcp-server-devops-1.0.0-docker.tar.gz
cd docker-release

# 启动服务
./start.sh

# 查看日志
docker logs -f mcp-server-devops

# 停止服务
./stop.sh

Docker 镜像优化特性

• 多阶段构建: 分离构建环境和运行环境，减小镜像体积
• 轻量级基础镜像: 使用 amazoncorretto:17-alpine3.19，镜像大小约 581MB
• JVM 参数优化: 自动适配容器内存限制，使用 G1GC
• 健康检查: 内置健康检查，自动监控服务状态
• 非 root 用户: 使用 spring 用户运行，提高安全性
• 时区配置: 默认使用 Asia/Shanghai 时区

多镜像仓库推送

项目支持同时推送 Docker 镜像到多个镜像仓库，方便不同环境的部署。

支持的镜像仓库:

镜像仓库	地址	用户名
Docker Hub	docker.io/cleanarch/mcp-server-devops	cleanarch
GitHub Container Registry	ghcr.io/li7hai26/mcp-server-devops	li7hai26
Quay.io	quay.io/cleanarch/mcp-server-devops	cleanarch

客户拉取镜像:

# Docker Hub
docker pull cleanarch/mcp-server-devops:1.0.0

# GitHub Container Registry
docker pull ghcr.io/li7hai26/mcp-server-devops:1.0.0

# Quay.io
docker pull quay.io/cleanarch/mcp-server-devops:1.0.0

开发者推送镜像:

# 推送到所有镜像仓库
./scripts/build/push-docker.sh

登录镜像仓库:

# Docker Hub
docker login

# GitHub Container Registry
echo "YOUR_GITHUB_TOKEN" | docker login ghcr.io -u li7hai26 --password-stdin

# Quay.io
docker login quay.io

Docker 环境变量

# Spring 配置
SPRING_PROFILES_ACTIVE=prod          # 运行环境（dev/test/prod）
SERVER_PORT=8080                      # 服务端口

# JVM 参数（可选）
JAVA_OPTS=-Xmx512m -Xms256m          # JVM 内存配置

# 日志配置
LOGGING_LEVEL_ROOT=INFO               # 根日志级别
LOGGING_LEVEL_CN_CLENARCH_MCP=DEBUG   # 应用日志级别

# Ezone API 默认配置（可选，用于降级场景）
# 注意：生产环境中认证信息应该由 MCP 客户端通过 HTTP 头部传递
EZONE_BASE_URL=https://srih.ezone.work
EZONE_ACCESS_TOKEN=your_token_here
EZONE_COMPANY_NAME=default
EZONE_TIMEOUT=30000

5. 访问服务

服务启动后，访问以下地址：

• MCP 端点: http://localhost:8080/mcp
• 健康检查: http://localhost:8080/mcp

📦 MCP 组件

Tools（11 个）

项目管理工具

工具名称	描述
list_projects	查询有权限的项目列表
list_project_repositories	查询指定项目关联的代码库列表

代码库管理工具

工具名称	描述
list_repositories	查询有权限的代码库列表

流水线管理工具

工具名称	描述
list_pipelines	查询指定代码库下有权限的流水线列表
get_pipeline_detail	获取指定流水线的详细信息
create_pipeline	创建新的流水线
copy_pipeline	复制指定的流水线到新的流水线
update_pipeline	更新指定流水线的配置
list_branches	查询指定代码库的分支列表
list_build_images	查询指定作业类型的构建环境镜像列表

镜像源管理工具

工具名称	描述
list_docker_registries	查询所有公用的 Docker 镜像源

Prompts（7 个）

提示词名称	描述
query_project_pipelines	查询项目到流水线的完整流程指南
quick_query_pipelines	快速查询代码库流水线的指南
devops_tools_guide	DevOps 工具使用指南
pipeline_lifecycle_guide	流水线生命周期管理指南
build_image_selection_guide	构建环境镜像选择指南
branch_selection_guide	分支选择指南
api_docs_query_guide	API 文档查询指南

Resources（14 个）

资源名称	描述
api_docs_index	所有 API 文档的索引
pipeline_api_docs	流水线管理 API 文档
project_api_docs	项目管理 API 文档
code_api_docs	代码库管理 API 文档
test_api_docs	测试管理 API 文档
deploy_api_docs	部署管理 API 文档
package_api_docs	制品库管理 API 文档
k8s_api_docs	K8S 管理相关 API 文档
doc_api_docs	文档管理 API 文档
wiki_api_docs	Wiki 管理 API 文档
scan_api_docs	代码扫描 API 文档
bpm_api_docs	流程审批 API 文档
resource_manager_api_docs	服务集成 API 文档
admin_api_docs	后台管理 API 文档

🔌 客户端接入方式

方式 1: MCP Streamable HTTP 客户端

// Spring AI 客户端配置
spring:
  mcp:
    client:
      streamable-http:
        connections:
          ezone-devops:
            url: http://localhost:8080/mcp

方式 2: HTTP POST 调用

# 调用项目列表工具
curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "list_projects",
         "arguments": {
           "keyword": "",
           "pageNumber": 1,
           "pageSize": 10
         }
       }
     }'

方式 3: Python 客户端

import requests

# 调用 MCP 工具
url = "http://localhost:8080/mcp"
payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "list_projects",
        "arguments": {
            "keyword": "",
            "pageNumber": 1,
            "pageSize": 10
        }
    }
}

response = requests.post(url, json=payload)
print(response.json())

📝 配置说明

application.yml

spring:
  application:
    name: mcp-server-devops
  ai:
    mcp:
      server:
        protocol: STREAMABLE              # 使用 Streamable HTTP 协议
        name: mcp-server-devops
        version: 1.0.0
        type: SYNC
        instructions: "MCP 服务器用于对接简单云（Ezone）DevOps 平台"
        capabilities:
          tool: true                      # 启用工具功能
          resource: true                  # 启用资源功能
          prompt: true                    # 启用提示词功能
          completion: false
        streamable-http:
          mcp-endpoint: /mcp              # MCP 端点路径
          keep-alive-interval: 20s        # 保活间隔

ezone:
  api:
    base-url: https://srih.ezone.work
    access-token: c0c880d402d94dcdb168d4dd97e7a5471758640484560
    company-name: default
    timeout: 30000

🔧 依赖版本

组件	版本
Spring Boot	3.4.0
Spring AI	1.1.0-M3
JDK	17+
MCP 协议	STREAMABLE HTTP

🧪 测试

运行集成测试

# 运行所有测试
mvn test

# 运行集成测试（需要 API 访问权限）
mvn test -D INTEGRATION_TEST_ENABLED=true

测试规范

1. 先测试 HTTP API 调用

   • 使用集成测试直接调用 EzoneApiClient
   • 确认 HTTP 请求格式、参数、响应格式正确
   • 验证 JSON 反序列化无错误

2. 再测试 MCP 工具

   • 通过 MCP 协议调用工具
   • 确认工具返回格式符合 MCP 规范
   • 验证 MCP 响应与 HTTP 响应的差异已被正确处理

📚 参考资料

• Spring AI 官方文档
• MCP 协议规范
• 简单云 Ezone 平台
• 完整开发文档
• 构建和部署脚本

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系方式

• 项目主页: https://gitee.com/cleanarch/mcp-server-devops
• 主域名: clenarch.cn