AI导哈

Jenkins故障诊断服务器

一个帮助AI助手高效调试Jenkins CI作业失败的模型上下文协议服务器，通过过滤冗长的API响应，仅返回关键错误信息、提交消息和失败的测试。

  • by omrisaba
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 omrisaba/Jenkins-Investigator-MCP-Server

使用说明

Jenkins调查员MCP服务器

A. 模型上下文协议 该服务器可帮助AI助手高效调试失败的Jenkins CI作业，而无需打开上下文窗口。

注： 这个代码库是在人工智能的帮助下生成的（Claude/Cursor），并由人类进行审查、测试和验证。

运作原理

原始的Jenkins API响应是巨大的。此服务器充当过滤器：它获取详细数据，去除噪声，只返回重要的内容——错误片段、提交消息、失败的测试。

工具

Bundles——从这里开始

捆绑将多个API调用合并为一个工具调用，从而节省了令牌和延迟。

捆绑 它做什么
investigate_build_failure 主要入口点。 在一次调用中返回构建信息、阶段、错误、测试、提交、参数和趋势。
compare_failing_vs_passing 区分上次失败与上次通过的构建：参数更改、代理、触发器、累积提交。
deep_dive_test_failures 通过最近的构建追溯每个失败的测试，以找到回归点和可疑提交。如果可用，则丰富JUnitXML工件（故障分类、爆炸半径检测、扩展的stdout/stderr）。
analyze_flaky_job 按节点、阶段和一天中的时间对片状和集群故障进行评分。
diagnose_infrastructure_issue 检查节点健康状况和每个节点的故障相关性，以确定故障是否与基础设施有关。
search_across_jobs 在文件夹中的所有作业的控制台日志中搜索特定的错误模式。并发，具有状态过滤和提前终止功能。
triage_folder 扫描文件夹中连续失败计数的中断作业——团队健康仪表板。

个人工具

在捆绑包为您提供大局后，使用这些进行有针对性的跟进。

工具 何时使用
get_last_build_info 从作业名称中发现最新（或最新失败）的内部版本号。
list_jobs 浏览Jenkins文件夹中的作业。
get_build_summary 快速构建概述：状态、运行时、代理、触发器。
get_pipeline_stages 带有状态和持续时间的舞台表。
get_build_parameters 请参阅构建参数（分支、环境、标志）。
get_build_history 最近的构建结果和趋势分析。
get_scm_changes 在此版本中提交（Git、SVN、Mercurial）。
get_error_logs 从控制台日志中提取优先级错误（≤250行）。
get_stage_logs 从特定管道阶段的日志中提取错误。
search_console_log 使用上下文行在控制台日志中查找字符串或正则表达式。
get_test_failures 测试失败，出现错误消息和堆栈跟踪。
get_build_artifacts 列出工件或获取特定工件的内容。
get_job_config 解析的作业配置：SCM、触发器、代理标签、管道定义。
get_build_environment CI相关环境变量（需要EnvInject插件）。
get_queue_info 构建队列，说明构建等待的原因。
compare_builds 区分任意两个构建（参数、代理、触发器、提交）。
get_upstream_downstream_builds 构建的上游触发链。
get_node_status 代理联机状态和磁盘空间。
get_node_list 所有带有标签、执行器和磁盘空间的代理。
get_pipeline_flow_nodes 阶段内的并行分支和步骤级细节。

设置

1.安装依赖项

pip install uv
uv pip install -e .

或者用普通pip：

pip install fastmcp>=3.0.0 requests>=2.31 pydantic>=2.0 python-dotenv>=1.0

2.配置凭据

cp .env.example .env

编辑 .env:

JENKINS_URL=http://your-jenkins:8080
JENKINS_USER=your-username
JENKINS_TOKEN=your-api-token

您的API令牌可以从Jenkins生成→ 用户→ 配置→ API令牌。

3.运行服务器

python server.py

默认情况下，服务器以Streamable HTTP传输启动 0.0.0.0:8000。您将在启动时看到打印的本地和网络URL。

4.从Cursor/Claude桌面连接

HTTP传输（默认）：

{
  "mcpServers": {
    "jenkins-investigator": {
      "url": "http://192.168.1.42:8000/mcp"
    }
  }
}

将IP替换为服务器启动时打印的网络URL。

标准运输 （套 MCP_TRANSPORT=stdio 在 .env):

{
  "mcpServers": {
    "jenkins-investigator": {
      "command": "python",
      "args": ["/absolute/path/to/jenkins-mcp/server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "JENKINS_URL": "http://your-jenkins:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_TOKEN": "your-api-token"
      }
    }
  }
}

职位名称

对于简单作业，直接使用作业名称： my-job.

对于文件夹或多分支管道中的作业，请使用斜线分隔的路径：

my-org/my-repo/main

服务器自动将其转换为正确的Jenkins API路径(/job/my-org/job/my-repo/job/main/).

配置

环境变量

变量 必填 默认 描述
JENKINS_URL 是 -- Jenkins实例的基本URL
JENKINS_USER 没有* -- Jenkins用户名（没有每个请求头时回退）
JENKINS_TOKEN 没有* - Jenkins API令牌（当没有per-request头时回退）
JENKINS_VERIFY_SSL 没有 true 设置为 false 适用于具有自签名或内部CA证书的Jenkins
REQUESTS_CA_BUNDLE 否 -- 公司/内部CA的CA证书文件路径
MCP_TRANSPORT 没有 http 传输协议： http （流式HTTP）或 stdio
MCP_HOST 没有 0.0.0.0 绑定HTTP传输地址
MCP_PORT 没有 8000 HTTP传输端口
TOOL_DELAY_SECONDS 没有 2 工具调用之间的延迟，以避免达到AI提供商TPM限制

*不使用按请求身份验证标头时需要。

每用户身份验证（HTTP标头）

当部署为共享服务器时，每个用户通过其Cursor MCP配置中的HTTP标头提供自己的Jenkins凭据：

标题 描述
X-Jenkins-User Jenkins用户名
X-Jenkins-Token Jenkins API令牌

每请求标头的优先级高于服务器范围 JENKINS_USER / JENKINS_TOKEN env变量。

文档

看 建筑学 用于系统设计、层职责和弹性策略。

看 刀具流 用于决策树、捆绑内部和每个工具的快速参考。

项目结构

jenkins-mcp/
├── server.py          # FastMCP server — 20 individual tools + 7 bundles
├── utils/
│   ├── __init__.py
│   ├── jenkins_api.py # Jenkins REST wrappers with retry/backoff
│   ├── junit_parser.py# JUnit XML parser (assertion vs exception classification, blast radius)
│   ├── log_parser.py  # Priority-budgeted error extraction
│   └── scm.py         # changeSet/changeSets normalization across SCMs
├── docs/
│   ├── architecture.md # System design and layer diagrams
│   └── tool-flow.md    # Decision trees and bundle internals
├── tests/             # pytest suite (162 tests)
├── .env               # Your credentials (gitignored)
├── .env.example       # Template
├── .gitignore
└── pyproject.toml

OpenShift部署

先决条件

  • oc CLI已登录到集群
  • 可从集群访问的容器注册表（例如。 images.paas.redhat.com)
  • Jenkins CA证书文件(jenkins-ca.pem)

1.建立和推广形象

IMAGE=images.paas.redhat.com/your-org/jenkins-investigator:latest

podman build -t $IMAGE .
podman push $IMAGE

2.创建命名空间资源

NAMESPACE=your-namespace

# Create the secret with Jenkins credentials
oc create secret generic jenkins-investigator-credentials \
  --from-literal=JENKINS_URL="https://jenkins-csb-ant-main.dno.corp.redhat.com/" \
  --from-literal=JENKINS_USER="your-username" \
  --from-literal=JENKINS_TOKEN="your-api-token" \
  -n $NAMESPACE

# Create the CA certificate ConfigMap
oc create configmap jenkins-investigator-ca \
  --from-file=jenkins-ca.pem=/path/to/jenkins-ca.pem \
  -n $NAMESPACE

3.部署

更新 IMAGE_REGISTRY/jenkins-investigator:latest 在 k8s/deployment.yaml 到您的实际图像，然后：

oc apply -f k8s/deployment.yaml -n $NAMESPACE
oc apply -f k8s/service.yaml -n $NAMESPACE
oc apply -f k8s/route.yaml -n $NAMESPACE

4.从游标连接（根据用户设置）

获取路由URL:

oc get route jenkins-investigator -n $NAMESPACE -o jsonpath='{.spec.host}'

每个用户都会将此添加到他们的 ~/.cursor/mcp.json，使用他们 拥有 Jenkins API令牌：

{
  "mcpServers": {
    "jenkins-investigator": {
      "url": "https://<route-host>/mcp",
      "headers": {
        "X-Jenkins-User": "your-jenkins-username",
        "X-Jenkins-Token": "your-jenkins-api-token"
      }
    }
  }
}

生成Jenkins API令牌：Jenkins→ 您的个人资料（右上角）→ 配置→ API代币→ 添加新令牌。

无标题： 如果 JENKINS_USER 和 JENKINS_TOKEN 在服务器Secret中设置，没有标头的请求将回退到这些凭据。如果既没有设置headers也没有设置env变量，服务器将返回错误。

清单参考

文件 目的
k8s/secret.yaml Jenkins凭据模板（使用 oc create secret 而是用于实际部署）
k8s/configmap-ca.yaml Jenkins CA证书模板
k8s/deployment.yaml 使用证书装载和健康检查进行部署
k8s/service.yaml 8000端口上的集群IP服务
k8s/route.yaml 带TLS边缘终止的OpenShift路由

安全

  • 凭据仅从环境变量中读取，从不进行硬编码。
  • 服务器是 只读：没有工具可以删除作业、擦除工作区或触发构建。
  • 这个 .env 默认情况下，文件为gitignore。
  • 控制台日志的上限为10 MB，以防止大型构建中的内存耗尽。

相关 MCP