jankins (Thecturner)

詹金斯

令牌优化的Jenkins MCP服务器，具有智能日志处理和故障分类功能

](https://pypi.org/project/jankins/) ](https://pypi.org/project/jankins/)       

jankins为Jenkins提供了符合MCP的访问权限，并具有专为AI编码助手设计的功能：

• 🎯 令牌感知格式：摘要/完整/差异输出模式可最大限度地减少上下文使用
• 📊 智能日志截断：使用字节偏移、正则表达式过滤和ANSI清理进行渐进式检索
• 🔍 故障分类：带假设和下一步的自动根本原因分析
• ⚡ 默认情况下高效：返回简洁的摘要，除非要求提供完整的详细信息
• 🛡️ 更好的错误处理：带有补救提示和关联ID的结构化错误
• 📝 内置提示：用于常见CI/CD任务的预构建工作流

快速开始

安装

pip install -e .

基本用法

# Set environment variables
export JENKINS_URL=https://jenkins.example.com
export JENKINS_USER=myuser
export JENKINS_API_TOKEN=11234567890abcdef1234567890abcdef

# Start the server
jankins

# Or use CLI flags
jankins --jenkins-url https://jenkins.example.com \
        --jenkins-user myuser \
        --jenkins-token $TOKEN \
        --bind 0.0.0.0:8080

生成Jenkins API令牌

1. 登录Jenkins
2. 点击您的用户名（右上角）→ 配置
3. 滚动至“API代币”部分
4. 点击“添加新令牌”
5. 为其命名并单击“生成”
6. 复制令牌（您将不会再看到它！）

配置

通过环境变量或CLI标志进行配置。CLI标志优先。

MCP工具

jankins提供25多种MCP工具，按类别组织：

工作

• list_jobs：列出带有前缀过滤和分页的作业
• get_job：获取详细的工作信息
• trigger_build：使用参数触发新的构建
• enable_job / disable_job：启用或禁用作业

建筑

• get_build：获取构建信息（支持 number 或 "last")
• get_build_changes：获取构建的SCM更改/提交
• get_build_artifacts：列出构建工件

日志

• get_build_log：通过智能截断和过滤获取日志

- 支持： filter_regex, redact, start 字节偏移， max_bytes - 默认情况下返回包含错误计数和失败阶段的摘要

• search_log：使用上下文窗口在日志中搜索模式

供应链管理和管道

• get_job_scm：获取作业SCM配置
• get_build_scm：获取构建的SCM信息（提交、分支）

健康与系统

• whoami：获取当前用户信息和权限
• get_status：Jenkins版本和队列深度
• summarize_queue：精简构建队列摘要

高级分析

• triage_failure：使用以下工具分析失败的构建：

- 根本原因假设 - 最常见的错误消息 - 失败阶段 - 嫌疑人犯罪 - 建议的后续步骤

• compare_runs：比较以下两个版本：

- 持续时间差异 - 结果更改 - 舞台级别差异（与蓝海）

• get_pipeline_graph：通过阶段、并行执行和计时实现管道可视化（蓝海）

• analyze_build_log：使用特定于构建工具的解析器（Maven、Gradle、NPM）分析日志，以进行详细的错误分析和建议

• retry_flaky_build：使用可配置的尝试和延迟重试不稳定的构建

测试结果

• get_test_report：获取测试结果摘要（JUnit、pytest等）
• get_failed_tests：列出失败的测试，包括错误详细信息和堆栈跟踪
• compare_test_results：比较不同版本之间的测试结果以进行回归检测
• detect_flaky_tests：识别多个版本中的不稳定测试

日志（增强型）

• tail_log_live：基于轮询的实时日志跟踪，具有渐进字节偏移

输出格式

所有工具支持 format 参数：

• summary （默认）：紧凑、令牌高效的视图
• full：所有字段的完整数据
• diff：仅差异（用于比较）
• ids：仅限ID和URL

例子：

{
  "name": "list_jobs",
  "arguments": {
    "format": "summary",
    "page_size": 20
  }
}

内置提示

jankins包括常见工作流的预构建提示：

• investigate_failure：完整的故障调查工作流程
• tail_errors：仅显示生成中的警告和错误
• compare_builds：比较两个版本以找出差异
• check_job_health：检查整体工作健康状况和稳定性
• trigger_with_params：在指导下触发参数化构建
• search_logs：在日志中搜索特定模式

客户示例

克劳德桌面（stdio模式-推荐）

添加到MCP设置中：

{
  "mcpServers": {
    "jankins": {
      "command": "jankins",
      "env": {
        "JENKINS_URL": "https://jenkins.example.com",
        "JENKINS_USER": "myuser",
        "JENKINS_API_TOKEN": "your-token-here"
      }
    }
  }
}

默认值 stdio 传输通过stdin/stdout进行通信，这是Claude Desktop等MCP客户端的标准。

HTTP模式（适用于基于HTTP的MCP客户端）

如果您的客户端需要HTTP传输：

{
  "mcp": {
    "servers": {
      "jankins": {
        "url": "http://localhost:8080/mcp",
        "headers": {
          "Content-Type": "application/json"
        }
      }
    }
  }
}

直接HTTP请求

以HTTP模式启动：

jankins --transport http

然后提出请求：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_build",
      "arguments": {
        "name": "my-job",
        "number": "last",
        "format": "summary"
      }
    }
  }'

示例工作流程

调查失败的构建

Use the "investigate_failure" prompt with job "backend-api"

这将：

1. 获取构建状态
2. 从日志中检索错误摘要
3. 执行故障分类
4. 显示可疑行为
5. 提供建议的后续步骤

比较两个建筑

{
  "name": "compare_runs",
  "arguments": {
    "name": "backend-api",
    "base": "100",
    "head": "101"
  }
}

在日志中搜索错误模式

{
  "name": "search_log",
  "arguments": {
    "name": "backend-api",
    "pattern": "OutOfMemoryError",
    "window_lines": 10
  }
}

仅获取上次构建的错误

{
  "name": "get_build_log",
  "arguments": {
    "name": "backend-api",
    "number": "last",
    "filter_regex": "ERROR|FATAL",
    "redact": true,
    "format": "summary"
  }
}

错误处理

jankins提供了结构化错误：

• 错误代码：JSON-RPC兼容错误代码
• 关联ID：跨日志跟踪请求
• 提示：人类可读的补救提示
• 下一步行动：解决问题的具体步骤
• 文档URL：故障排除指南链接

错误分类：

• InvalidParams （-32602）：刀具参数无效
• Unauthorized （-32001）：身份验证失败
• Forbidden （-32002）：权限不足
• NotFound （-32003）：找不到资源
• Timeout （-32007）：请求超时
• UpstreamError （-32006）：Jenkins服务器错误

令牌优化

jankins通过以下方式最大限度地减少了令牌的使用：

1. 默认摘要：默认摘要格式，根据要求提供完整摘要
2. 磁场限制：只有摘要模式下的基本字段
3. 智能截断：具有字节限制的渐进式日志检索
4. 代币估算：响应包括估计的令牌计数
5. 结构化数据：在冗长的文本上压缩表格和列表
6. 元数据分离：性能数据 _meta 章节

响应结构示例：

{
  "build_number": 42,
  "result": "FAILURE",
  "duration": "2m 15s",
  "_meta": {
    "correlation_id": "abc-123",
    "took_ms": 250,
    "format": "summary",
    "token_estimate": 180
  }
}

安全

• 显式配置：使用env变量或CLI标志（忽略工作目录中的.env文件）
• 基本认证：使用Jenkins API令牌（从不使用密码）
• 可选原产地验证：强制执行允许的来源
• 无秘密日志记录：凭据在日志中被编辑
• 秘密面具：詹金斯秘密面具被保留/编辑

备注：jankins忽略工作目录中的任何.env文件，只读取它需要的特定环境变量（JENKINS\_*，MCP\_*等等）。这可以防止与project.env文件发生冲突。

生成API令牌：

Jenkins → User → Configure → API Token → Add new Token

健康检查

• GET /_health：基本健康检查
• GET /_ready：准备状态检查（验证Jenkins连接）
• GET /_metrics：Prometheus指标占位符

发展

从源代码运行

# Install with dev dependencies
pip install -e ".[dev]"

# Run server
python -m jankins --jenkins-url $URL --jenkins-user $USER --jenkins-token $TOKEN

# With debug logging
python -m jankins --log-level DEBUG --debug-http

测试

pytest tests/

码头工人

看 docker-compose.yml 用于本地Jenkins+jankins设置。

docker-compose up

这将开始：

• 8081端口上的Jenkins LTS
• 端口8080上的jankins MCP服务器

功能对比

故障排除

“未经授权”错误

• 验证 JENKINS_USER 和 JENKINS_API_TOKEN 是正确的
• 从Jenkins用户设置中重新生成API令牌
• 检查Jenkins服务器是否可访问

“超时”错误

• 增加 --timeout 价值
• 检查Jenkins服务器响应
• 验证网络连接

“找不到工具”错误

• 确保服务器已成功启动
• 检查MCP客户端配置
• 验证工具名称拼写

大日志超时

• 使用 max_bytes 限制检索的参数
• 使用 filter_regex 减小日志大小
• 使用 format=summary 先进行概述

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

1. 为新功能添加测试
2. 遵循现有代码样式
3. 更新文档
4. 添加类型提示

致谢

构建于：

• 蟒蛇詹金斯 为Jenkins API
• 模型上下文协议 规格
• 斯塔莱特 用于传输层