# mcp-server-devops

**Repository Path**: cleanarch/mcp-server-devops

## Basic Information

- **Project Name**: mcp-server-devops
- **Description**: 简单云-MCP SERVER(基于 SASS 版以及总院内网版本调试)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 部署（推荐）

```bash
# 下载发布包
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：直接拉取镜像

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

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

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

```bash
# 下载发布包
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
```

### 开发者使用

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

```bash
# 克隆代码库
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: 环境变量（默认值，可选）

```bash
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`：

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

**详细配置说明请参考**: [CONFIG.md](./CONFIG.md)

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

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

**详细认证说明请参考**: [AUTH.md](./AUTH.md)

### 3. 编译运行

```bash
# 编译项目
mvn clean package

# 运行服务
mvn spring-boot:run
```

### 4. Docker 部署（推荐）

#### 使用 Docker 构建

```bash
# 构建镜像
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：直接拉取镜像**

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

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

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

```bash
# 下载发布包
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 |

**客户拉取镜像**:

```bash
# 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
```

**开发者推送镜像**:

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

**登录镜像仓库**:

```bash
# 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 环境变量

```yaml
# 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 客户端

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

### 方式 2: HTTP POST 调用

```bash
# 调用项目列表工具
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 客户端

```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

```yaml
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 |

## 🧪 测试

### 运行集成测试

```bash
# 运行所有测试
mvn test

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

### 测试规范

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

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

## 📚 参考资料

- [Spring AI 官方文档](https://spring.io/projects/spring-ai)
- [MCP 协议规范](https://modelcontextprotocol.io)
- [简单云 Ezone 平台](https://ezone.work)
- [完整开发文档](./IFLOW.md)
- [构建和部署脚本](./scripts/README.md)

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

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