# @znmin/jenkins-mcp-server

通过 `npx` 启动的 Jenkins MCP，支持任务查询、构建、日志、队列、节点配置及 **Pipeline Replay**。
直接连接现有 Jenkins，不需要安装 Jenkins MCP Server 插件或升级 Jenkins 核心。

基于 MIT 许可的 [mcpland/jenkins-mcp](https://github.com/mcpland/jenkins-mcp) 维护，版权声明保留在 LICENSE / THIRD_PARTY_NOTICES.md。

## 安装与启动

需要 Node.js **20.19 或更新版本**，推荐当前 Node.js LTS。MCP 客户端使用 **stdio**：

```json
{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["-y", "@znmin/jenkins-mcp-server@1.0.0"],
      "env": {
        "JENKINS_URL": "http://jenkins.example.internal",
        "JENKINS_USERNAME": "your-account",
        "JENKINS_PASSWORD": "your-password"
      }
    }
  }
}
```

支持密码认证，也支持 API Token：将 `JENKINS_PASSWORD` 换成 `JENKINS_API_TOKEN`。
环境变量只需在 MCP 配置中填写一次，AI 每次调用工具时无需再次提供服务器地址和密码。
修改配置后重启 MCP 并刷新工具列表；必要时新建对话。

## 全部环境变量

| 参数 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `JENKINS_URL` | 是 | 无 | Jenkins 根地址，支持 `/jenkins` 等上下文路径 |
| `JENKINS_USERNAME` | 是 | 无 | Jenkins 用户名 |
| `JENKINS_PASSWORD` | 二选一 | 无 | 登录密码，也可填 API Token |
| `JENKINS_API_TOKEN` | 二选一 | 无 | API Token；同时设置时优先于环境中的密码 |
| `JENKINS_VERIFY_SSL` | 否 | `true` | `false` 时仅本 Jenkins 客户端跳过 HTTPS 证书校验 |
| `JENKINS_TIMEOUT` | 否 | `30` | 单次请求等待响应头的超时秒数，必须为正数 |
| `JENKINS_SESSION_SINGLETON` | 否 | `true` | 复用连接、crumb 和会话 Cookie |
| `JENKINS_READ_ONLY` | 否 | `false` | `true` 时不注册所有写工具，包括 Replay |

兼容原包的 `jenkins_url`、`jenkins_username`、`jenkins_password`、`jenkins_verify_ssl`、
`jenkins_timeout`、`jenkins_session_singleton`、`jenkins_read_only` 小写变量；同名大写变量优先。
程序不会自动读取 `.env` 文件。

兼容启动选项：`--jenkins-url`、`--jenkins-username`、`--jenkins-password`、
`--jenkins-timeout`、`--jenkins-verify-ssl`、`--no-jenkins-verify-ssl`、
`--jenkins-session-singleton`、`--no-jenkins-session-singleton`、`--read-only`、
`--allow-full-console-output`。显式 CLI 值优先。此版本只启动 stdio，不开放 HTTP/SSE 监听端口。

默认开放已实现的读写工具；实际操作仍受 Jenkins 账号权限控制。

## Replay

先读取指定构建的原始脚本：

```json
{"fullname":"folder/pipeline-job","number":123}
```

调用工具 `get_replay_scripts`，返回 `mainScript`、`mainScriptSha256`、`loadedScripts` 和源构建号。
`loadedScripts` 的键来自 Replay 表单的脚本名称，例如 `org.example.Script1`。

调用工具 `replay_build`：

```json
{
  "fullname":"folder/pipeline-job",
  "number":123,
  "mainScript":"node { echo 'updated pipeline' }",
  "loadedScripts":{"org.example.Script1":"return 'updated helper'"}
}
```

`number` 可省略，工具会先解析为确定的最近一次构建号。`mainScript` 必填，
`loadedScripts` 可省略；未修改的加载脚本保持原样，名称错误时在提交前拒绝。
内部按照 Jenkins Replay 表单协议发送 `json` 字段，正确处理点号到下划线的字段映射。

Replay 是对已有运行脚本的重放，不修改任务配置或仓库中的 Jenkinsfile。
此操作会调度真实构建，可能包含部署。Jenkins 接受后通常重定向回任务页面，不返回队列 ID，
所以结果中的 `queueId` 和 `buildNumber` 为 `null`；需要继续查询队列和构建历史来定位新运行。
不猜测下一次构建号，也不把“已接受调度”解释成“构建成功”。

提交遇到超时或异常响应时不会自动重试；请先检查队列和构建历史，避免重复部署。
账号需要任务读取、构建以及 **Run/Replay** 权限；非沙箱脚本还受 Jenkins 管理员权限和脚本审批规则约束。
仅有 Rebuild 权限、非 Pipeline 任务或不存在可编辑 Replay 表单时，工具会返回错误。
这些限制由 Jenkins 自身执行，此包不会绕过。

## 工具

| 类别 | 工具 |
| --- | --- |
| Replay | `get_replay_scripts`、`replay_build` |
| 任务 | `get_all_items`、`get_item`、`query_items`、`get_item_config`、`set_item_config`、`build_item` |
| 构建 | `get_build`、`get_running_builds`、`get_build_scripts`、`stop_build`、`get_build_test_report` |
| 日志 | `get_build_console_tail`、`get_build_console_chunk`、`search_build_console`、`get_build_failure_excerpt` |
| 节点 | `get_all_nodes`、`get_node`、`get_node_config`、`set_node_config` |
| 队列 | `get_all_queue_items`、`get_queue_item`、`cancel_queue_item` |

`get_build_scripts` 保留原包兼容接口。需要完整的主脚本和加载脚本名称时使用 `get_replay_scripts`。
`build_item` 的 `build_type` 为 `build` 或 `buildWithParameters`；参数化构建通过 `params` 提供键值。
`fullname` 使用实际任务名称和文件夹路径，如 `folder/job`；普通路径分隔符表示文件夹层级。

日志优先用 tail / search / chunk；这些工具对返回字节数设有上限。
`get_build_console_output` 默认不注册，只有显式加 `--allow-full-console-output` 才启用，以免完整大日志占满上下文。

密码认证时自动获取 crumb 并保留同一会话的 Cookie。API Token 也支持；服务没有 crumbIssuer 时兼容其 404 响应。
不会自动跟随认证请求的重定向，也不会把凭据发送到其他域名。

## 验证范围

- 自动测试覆盖原包常用能力、Replay 表单读取、加载脚本保留/替换、密码会话 Cookie、crumb、只读模式、异常重定向与不自动重试。
- 在 Jenkins **2.462.1** 实例完成登录、任务列表、Replay 脚本读取及日志读取联调。
- 未在真实业务任务上提交 Replay 或触发部署；写入路径通过本地 HTTP 模拟服务验证。
- 无需安装 Jenkins MCP Server 插件。Pipeline Replay 需要现有 Pipeline/Groovy 插件提供 Replay 页面。

## 开发

```sh
npm ci
npm run check
```

CI 在 Windows / Ubuntu、Node.js 20 / 24 上运行检查。