DevOps MCP Server

DevOps MCP 服务

基于 FastMCP 构建的 MCP 服务，提供一套 DevOps 工具和集成。

此服务以只读方式运行，获取数据以供分析和展示，不会修改您的系统。它专为 DevOps 环境设计，注重安全性。

已通过 MCP Review 认证

功能

DevOps MCP 服务集成了多种必备的 DevOps 平台：

GitHub 集成

• 仓库管理：搜索并查看仓库详情。
• 文件访问：获取仓库中的文件内容。
• 问题跟踪：管理和跟踪问题。
• 代码搜索：执行针对性代码搜索。
• 提交历史：查看分支的提交历史。
• 公共版和企业版支持：自动检测并连接公共 GitHub 和 GitHub Enterprise 实例（可通过 GITHUB_API_URL 配置）。

Jenkins 集成

• 作业管理：列出并管理 Jenkins 作业。
• 构建日志：获取并分析构建日志。
• 视图管理：访问并管理 Jenkins 视图。
• 构建参数：检查构建所用的参数。
• 故障监控：识别并监控最近失败的构建。

Artifactory 集成

• 仓库浏览：列出 Artifactory 仓库中的项目（文件和目录）。
• 制品搜索：使用 Artifactory 查询语言（AQL），跨多个仓库按名称或路径搜索制品。
• 项目详情：获取特定文件和目录的元数据及属性。
• 身份验证：支持基于令牌和基于用户名/密码的身份验证。

安装

使用 pip 安装软件包：

pip install devops-mcps

用法

直接运行 MCP 服务：

devops-mcps

传输配置

此服务支持两种通信传输类型：

• stdio（默认）：标准输入/输出。
• stream_http：HTTP 流式传输。

本地用法：

# Default stdio transport
devops-mcps

# stream_http transport (runs HTTP server on 127.0.0.1:3721/mcp by default)
devops-mcps --transport stream_http

UVX 用法：

如果使用 UVX，请先安装工具：

uvx install

然后运行：

# Default stdio transport
uvx run devops-mcps

# stream_http transport
uvx run devops-mcps-stream-http

使用 Make

使用提供的 Makefile 简化常见任务：

# Discover available targets
make help

# Install dev dependencies (auto-detects uv, falls back to pip)
make install

# One-shot dev setup: install, format, and lint
make dev

# Run MCP server (stdio)
make run

# Run MCP server (stream_http) with optional mount path
make run-http MOUNT_PATH=/mcp

# Test and coverage
make test
make coverage

# Build and publish the package
make build
make publish

# Docker workflows
make docker-build
make docker-run
make docker-push REGISTRY=your.registry.example

配置

使用环境变量配置此服务：

必需：

# GitHub
export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_token"
# Optional: For GitHub Enterprise, set your API endpoint
# export GITHUB_API_URL="https://github.mycompany.com"

# Jenkins
export JENKINS_URL="your_jenkins_url"
export JENKINS_USER="your_jenkins_username"
export JENKINS_TOKEN="your_jenkins_api_token_or_password"

# Artifactory
export ARTIFACTORY_URL="https://your-artifactory-instance.example.com"
# Choose ONE authentication method:
export ARTIFACTORY_IDENTITY_TOKEN="your_artifactory_identity_token"
# OR
export ARTIFACTORY_USERNAME="your_artifactory_username"
export ARTIFACTORY_PASSWORD="your_artifactory_password"

可选：

# Jenkins Log Length (default: 5120 bytes)
export LOG_LENGTH=10240

# MCP Server Port for stream_http transport (default: 3721)
export MCP_PORT=3721

# Dynamic Prompts (optional)
export PROMPTS_FILE="example_prompts.json"

注意：LOG_LENGTH 控制获取的 Jenkins 日志数据量。请根据需要调整。

替代方式：使用 .env 文件

您也可以在项目根目录中创建 .env 文件，而不必手动设置环境变量：

# .env file
GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
PROMPTS_FILE=example_prompts.json
# Add other optional environment variables as needed

此服务启动时会自动从 .env 文件加载环境变量。

动态提示词

此服务支持从 JSON 文件加载自定义提示词。将 PROMPTS_FILE 环境变量设置为提示词配置文件的路径。

提示词文件格式：

{
  "prompts": [
    {
      "name": "github_repo_analysis",
      "description": "Analyze a GitHub repository for DevOps insights",
      "template": "Please analyze the GitHub repository {{owner}}/{{repo}} and provide insights on:\n\n1. Repository structure and organization\n2. CI/CD pipeline configuration\n3. Code quality indicators\n4. Security considerations\n5. Documentation quality\n\n{{#include_issues}}Also include analysis of recent issues and their resolution patterns.{{/include_issues}}",
      "arguments": [
        {
          "name": "owner",
          "description": "GitHub repository owner",
          "required": true
        },
        {
          "name": "repo",
          "description": "GitHub repository name",
          "required": true
        },
        {
          "name": "include_issues",
          "description": "Include analysis of repository issues",
          "required": false
        }
      ]
    }
  ]
}

使用提示词

DevOps MCP 服务提供动态提示词，帮助您执行常见的 DevOps 任务。以下是可用提示词的使用方法：

可用提示词

1. quick_repo_check - 全面的仓库健康评估和安全分析
2. daily_check - 完整的 DevOps 监控，包括 Jenkins 作业分析和基础设施状态
3. build_troubleshoot - 高级构建故障调查和根因分析

使用 daily_check 提示词

用途： 全面的 DevOps 监控和基础设施状态报告，并分析 Jenkins 任务。

参数：

参数	类型	必填	描述
time_range	string	❌ 否	分析的时间范围（例如，“24h”、“7d”、“1w”）
include_infrastructure	boolean	❌ 否	在报告中包含基础设施状态
focus_area	string	❌ 否	要重点关注的特定领域（例如，“builds”、“deployments”、“security”）

使用示例：

# Basic daily monitoring
Prompt: daily_check

# Weekly infrastructure review
Prompt: daily_check
Parameters:
- time_range: "7d"
- include_infrastructure: true

# Focus on build failures
Prompt: daily_check
Parameters:
- time_range: "24h"
- focus_area: "builds"

功能：

1. 🔍 Jenkins 任务分析：全面检查任务状态和近期故障
2. 🔧 根本原因调查：深入分析故障模式和趋势
3. 🏗️ 基础设施状态：检查关键基础设施组件的健康状况
4. 📋 可执行建议：按优先级排列的操作项，并提供实施指导
5. 📊 执行摘要：概述关键指标和趋势

使用 build_troubleshoot 提示词

用途： 深入调查构建失败，全面分析根本原因并提供可执行建议。

参数：

参数	类型	必填	描述
job_name	string	✅ 是	Jenkins 任务名称
build_number	string	❌ 否	要分析的构建编号（使用 -1 表示最新构建）
include_logs	boolean	❌ 否	是否在分析中包含构建日志

使用示例：

# Basic usage (latest build)
Prompt: build_troubleshoot
Parameters:
- job_name: "my-application-build"

# Specific build number
Prompt: build_troubleshoot
Parameters:
- job_name: "my-application-build"
- build_number: "42"

# With build logs
Prompt: build_troubleshoot
Parameters:
- job_name: "my-application-build"
- build_number: "42"
- include_logs: true

功能：

1. 获取指定任务的构建状态和基本信息
2. 获取并分析构建日志（如果 include_logs 为 true）
3. 根据构建数据确定潜在的故障原因
4. 提供故障排查步骤和可执行建议

使用 quick_repo_check 提示词

用途： 全面的代码仓库健康状况评估，包括安全分析和 DevOps 最佳实践评估。

参数：

参数	类型	必填	描述
repo_name	string	✅ 是	代码仓库名称，格式为 'owner/repo'
include_security	boolean	❌ 否	在评估中包含安全分析
check_ci_cd	boolean	❌ 否	分析 CI/CD 工作流配置

使用示例：

# Basic repository check
Prompt: quick_repo_check
Parameters:
- repo_name: "facebook/react"

# Comprehensive security assessment
Prompt: quick_repo_check
Parameters:
- repo_name: "myorg/myproject"
- include_security: true
- check_ci_cd: true

功能：

1. 📊 代码仓库健康状况评估：全面评估代码仓库状态和指标
2. 🔒 安全分析：审查安全配置并评估漏洞
3. 🏗️ CI/CD 工作流评估：分析构建和部署配置
4. 📋 可执行建议：按优先级排列的改进建议，并提供实施指导
5. 📈 执行摘要：概述关键发现和战略建议

自然语言支持

DevOps MCP 服务支持通过结构化和自然语言两种方式调用提示词：

结构化格式（显式）：

Use prompt: build_troubleshoot
Parameters:
- job_name: "creole-Automerge-main"
- build_number: 29
- include_logs: true

自然语言格式（推荐）：

"Perform daily DevOps monitoring check for the last 24 hours"

"Troubleshoot the Jenkins build failure for job 'creole-Automerge-main' build #29 with detailed logs"

"Check the GitHub repository facebook/react with security analysis"

"Analyze the failed build for my-app-build job number 42 including logs"

"Run weekly infrastructure review with comprehensive monitoring"

"Assess repository health for myorg/myproject including CI/CD pipeline analysis"

自然语言处理的工作原理：

1. 意图识别：AI 助手识别与你的请求相匹配的提示词
2. 参数提取：从你的消息中提取具体值（作业名称、构建编号、仓库名称）
3. 自动映射：将你的自然语言映射到结构化提示词格式
4. 上下文感知：利用对话历史和工作区上下文补全缺失的参数

提高自然语言识别准确性的提示：

• 使用关键词：包含“排查故障”“分析”“检查仓库”“构建失败”等词语
• 具体说明：提及准确的作业名称、构建编号和仓库名称
• 使用引号：用引号括起具体值，以便清晰识别（例如，“my-job-name”）
• 提供上下文：说明你希望进行哪种类型的分析

自然语言示例模式：

意图	自然语言示例
每日监控	“每日 DevOps 检查”“运行每日监控”“基础设施状态报告”
仓库分析	“使用安全检查仓库 owner/name”“对 GitHub 仓库 X 进行 CI/CD 分析”
构建故障排查	“调试构建失败”“排查作业 X 的构建 Y”“调查构建问题”
包含日志	“包含日志”“包括详细日志”“显示构建日志”
最新构建	“最新构建”“最近一次构建”“当前构建”
时间范围	“过去 24 小时”“过去一周”“7 天”“每周回顾”
关注领域	“重点关注构建”“安全分析”“基础设施审查”

前置条件

要使用 build_troubleshoot 等 Jenkins 相关提示词，请确保你具备：

# Required Jenkins environment variables
export JENKINS_URL="https://your-jenkins-server.com"
export JENKINS_USER="your-username"
export JENKINS_TOKEN="your-api-token"

要使用 quick_repo_check 等 GitHub 相关提示词，请确保你具备：

# Required GitHub environment variable
export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_token"

模板变量：

• 使用 {{variable_name}} 进行简单的变量替换
• 使用 {{#variable_name}}...{{/variable_name}} 编写条件块（当变量有值时显示）
• 使用 {{^variable_name}}...{{/variable_name}} 编写否定条件块（当变量为空或为 null 时显示）

提示词可用工具： 提示词可以引用任何可用的 MCP 工具：

• GitHub 工具：search_repositories、get_file_contents、list_commits、list_issues 等
• Jenkins 工具：get_jenkins_jobs、get_jenkins_build_log、get_recent_failed_jenkins_builds 等
• Azure 工具：get_azure_subscriptions、list_azure_vms、list_aks_clusters 等
• Artifactory 工具：list_artifactory_items、search_artifactory_items、get_artifactory_item_info 等

Docker

构建 Docker 镜像：

docker build -t devops-mcps .

运行容器：

# Stdio transport (interactive)
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN="..." \
  -e JENKINS_URL="..." \
  -e JENKINS_USER="..." \
  -e JENKINS_TOKEN="..." \
  -e ARTIFACTORY_URL="..." \
  -e ARTIFACTORY_IDENTITY_TOKEN="..." \
  devops-mcps

# stream_http transport (background, HTTP server on 127.0.0.1:3721/mcp by default)
docker run -d -p 3721:3721 --rm \
  -e TRANSPORT_TYPE=stream_http \
  -e MCP_PORT=3721 \
  -e GITHUB_PERSONAL_ACCESS_TOKEN="..." \
  -e JENKINS_URL="..." \
  -e JENKINS_USER="..." \
  -e JENKINS_TOKEN="..." \
  -e ARTIFACTORY_URL="..." \
  -e ARTIFACTORY_IDENTITY_TOKEN="..." \
  devops-mcps

将 ... 替换为你的实际凭据。

VSCode 集成

在 VSCode 的 settings.json 中配置 MCP 服务：

示例（使用 stdio 的 UVX）：

"devops-mcps": {
  "type": "stdio",
  "command": "uvx",
  "args": ["devops-mcps"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_...",
    "GITHUB_API_URL": "https://github.mycompany.com", // Optional for GHE
    "JENKINS_URL": "...",
    "JENKINS_USER": "...",
    "JENKINS_TOKEN": "...",
    "ARTIFACTORY_URL": "...",
    "ARTIFACTORY_IDENTITY_TOKEN": "cm..." // Or USERNAME/PASSWORD
  }
}

示例（使用 stream_http 的 Docker）：

确保 Docker 容器已启用 stream_http 并正在运行（参见 Docker 部分）。

{
  "type": "stream_http",
  "url": "http://127.0.0.1:3721/mcp", // Adjust if Docker host is remote or if MCP_PORT is set differently
  "env": {
    // Environment variables are set in the container,
    // but can be overridden here if needed.
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

其他传输方式／运行器组合（UVX/stream_http、Docker/stdio）请参阅 README.md 开头的各节。

开发

设置开发环境：

# Install dependencies (using uv)
uv pip install -e ".[dev]"
# Or sync with lock file
# uv sync --all-extras --group dev

代码检查与格式化（Ruff）：

# Check code style
uvx ruff check .

# Format code
uvx ruff format .

测试（Pytest）：

# Run tests with coverage using the provided script
./test.sh

# Or run manually
pytest --cov=src/devops_mcps --cov-report=html:coverage/html --cov-report=xml --cov-fail-under=80 tests/

测试脚本功能：

项目包含全面的 test.sh 脚本，该脚本会：

• 自动检查是否已安装 uv
• 同步开发依赖项
• 使用 pytest 运行所有测试
• 生成 HTML 和 XML 覆盖率报告
• 在浏览器中自动打开 HTML 覆盖率报告（在 CI 中跳过）
• 要求测试覆盖率至少达到 80%（项目会保持较高的覆盖率）

覆盖率报告：

• HTML 报告：coverage/html/index.html（自动打开）
• XML 报告：coverage.xml（用于 CI/CD 集成）

使用 MCP Inspector 调试：

# Basic run
npx @modelcontextprotocol/inspector uvx run devops-mcps

# Run with specific environment variables
npx @modelcontextprotocol/inspector uvx run devops-mcps -e GITHUB_PERSONAL_ACCESS_TOKEN=... -e JENKINS_URL=... # Add other vars

检查过时的软件包依赖项

uv pip list --outdated

更新软件包依赖项

uv lock --upgrade

CI/CD

GitHub Actions 工作流（.github/workflows/ci.yml）负责：

1. 代码检查与测试：在推送和拉取请求时运行 Ruff 和 Pytest。
2. 发布：在推送到 main 分支时，将 Python 软件包构建并发布到 PyPI，并将 Docker 镜像发布到 Docker Hub。

必需的仓库机密：

• PYPI_API_TOKEN：用于发布软件包的 PyPI 令牌。
• DOCKER_HUB_USERNAME：Docker Hub 用户名。
• DOCKER_HUB_TOKEN：Docker Hub 访问令牌。

打包和发布（手动）

确保已安装 build 和 twine：

pip install -U build twine

1. 更新版本：递增 pyproject.toml 中的版本号。
2. 构建：python -m build
3. 上传：twine upload dist/*（需要配置 ~/.pypirc 或输入令牌）。

附录：GitHub 搜索查询语法

在 MCP 工具中使用 GitHub 强大的搜索语法：

仓库搜索（gh_search_repositories）：

• in:name,description,readme：搜索指定字段。 示例：fastapi in:name
• user:USERNAME 或 org:ORGNAME：将搜索范围限定到用户或组织。 示例：user:tiangolo fastapi
• language:LANGUAGE：按语言筛选。 示例：http client language:python
• stars:>N、forks:<N、created:YYYY-MM-DD、pushed:>YYYY-MM-DD：按指标和日期筛选。 示例：language:javascript stars:>1000 pushed:>2024-01-01
• topic:TOPIC-NAME：按主题筛选。 示例：topic:docker topic:python
• license:LICENSE-KEYWORD：按许可证筛选（例如，mit、apache-2.0）。 示例：language:go license:mit

代码搜索（gh_search_code）：

• in:file,path：搜索文件内容（默认）或路径。 示例："import requests" in:file
• repo:OWNER/REPO：将搜索范围限定到指定仓库。 示例："JenkinsAPIException" repo:your-org/your-repo
• language:LANGUAGE：按文件语言筛选。 示例：def main language:python
• path:PATH/TO/DIR、filename:FILENAME.EXT、extension:EXT：按路径、文件名或扩展名筛选。 示例："GithubException" path:src/devops_mcps extension:py

参考：

• 在 GitHub 上搜索
• 搜索代码
• 搜索仓库

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。