内容
# Jenkins MCP 服务器
用于与受 Cloudflare Access 保护的 Jenkins 实例交互的 MCP（模型上下文协议）服务器。为与 Kiro 和其他 MCP 兼容的 AI 编码工具一起使用而构建。
## 先决条件
- [Node.js](https://nodejs.org/)（v18+）
- 已安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) CLI
- Jenkins API token（从 Jenkins → {您的用户} → 安全 → API Token 生成）
## 安装
1. 克隆此仓库：
```bash
git clone https://github.com/kmlarso6/jenkins-mcp-server.git
cd jenkins-mcp-server
```
2. 安装依赖项：
```bash
npm install
```
## MCP 配置
在 `~/.kiro/settings/mcp.json`（或工作区 `.kiro/settings/mcp.json`）中添加以下内容到您的 Kiro MCP 配置中：
```json
{
"mcpServers": {
"Jenkins": {
"command": "node",
"args": ["/path/to/jenkins-mcp-server/index.mjs"],
"env": {
"JENKINS_URL": "https://jenkins.devops.asu.edu",
"JENKINS_USER": "{您的用户 ID}",
"JENKINS_TOKEN": "{您的 API 密钥}"
},
"disabled": false,
"autoApprove": [
"get_build",
"get_build_log",
"get_job",
"list_builds",
"get_test_results",
"get_artifact",
"download_test_results",
"list_stages",
"get_stage_log",
"get_failed_tests",
"compare_builds"
]
}
}
}
```
替换：
- `/path/to/jenkins-mcp-server/index.mjs` 为您克隆副本的绝对路径
- `{您的用户 ID}` 为您的 Jenkins 用户名（通常是异常 ASURITE 或电子邮件地址）
- `{您的 API 密钥}` 为您的 Jenkins API token
### PoP（证明存在）实例
PoP 实例在不同的 URL（例如 `jenkins-{product}.devops.asu.edu`）上运行，通常需要单独的凭证。为每个 PoP 实例添加一个 MCP 服务器条目：
```json
{
"mcpServers": {
"Jenkins": {
"command": "node",
"args": ["/path/to/jenkins-mcp-server/index.mjs"],
"env": {
"JENKINS_URL": "https://jenkins.devops.asu.edu",
"JENKINS_USER": "{您的用户 ID}",
"JENKINS_TOKEN": "{您的 API 密钥}"
},
"disabled": false,
"autoApprove": ["get_build", "get_build_log", "get_job", "list_builds", "get_test_results", "get_artifact", "download_test_results", "list_stages", "get_stage_log", "get_failed_tests", "compare_builds"]
},
"Jenkins-PoP": {
"command": "node",
"args": ["/path/to/jenkins-mcp-server/index.mjs"],
"env": {
"JENKINS_URL": "{您的 PoP URL}",
"JENKINS_USER": "{您的 PoP 用户 ID}",
"JENKINS_TOKEN": "{您的 PoP API 密钥}"
},
"disabled": false,
"autoApprove": ["get_build", "get_build_log", "get_job", "list_builds", "get_test_results", "get_artifact", "download_test_results", "list_stages", "get_stage_log", "get_failed_tests", "compare_builds"]
},
...
}
}
```
每个实例都需要自己的 Cloudflare Access 登录（参见下文）和自己的 Jenkins API token。如果您的凭证在实例之间共享，您可以在任何工具调用上使用 `baseUrl` 参数来覆盖默认的 Jenkins URL。
> **注意：** 用户名格式在实例之间可能有所不同。例如，主实例可能使用您的异常 ASURITE（`ex_asurite`），而 PoP 实例可能需要您的异常 ASURITE 电子邮件地址（`ex_asurite@asu.edu`）。请在每个 Jenkins 实例上检查您的用户配置文件以确认。
## Cloudflare Access 身份验证
每个 Jenkins 实例都位于 Cloudflare Access 后面。您需要为连接的每个实例获取有效的令牌。
### 初始登录
```bash
# 主实例
cloudflared access login "https://jenkins.devops.asu.edu"
# PoP 实例（为每个使用的 PoP URL 重复）
cloudflared access login "https://jenkins-{product}.devops.asu.edu"
```
此命令将自动打开一个浏览器标签页 **并在终端中打印授权 URL**。由于 Jenkins 访问通常授予您的异常 ASURITE，因此您可能需要在您登录为异常 ID 的浏览器会话中进行身份验证。
**推荐流程：**
1. 关闭自动打开的浏览器标签页
2. 复制终端中打印的 URL
3. 在隐身/私人窗口或您可以登录异常 ASURITE 凭证的浏览器配置文件中打开它
4. 完成 ASU SSO 登录
5. 终端命令将检测到成功并自动在 `~/.cloudflared/` 中缓存令牌
### 令牌验证
```bash
cloudflared access token -app=https://jenkins.devops.asu.edu
cloudflared access token -app=https://jenkins-{product}.devops.asu.edu
```
如果这返回一个 JWT 字符串，则您已身份验证。
### 令牌过期
令牌在几个小时后过期。如果 MCP 工具调用开始因 Cloudflare 错误而失败，请为受影响的实例重新运行登录命令。
## 安装 Kiro 技能
此仓库包含一个 Kiro 技能，帮助 AI 代理自动管理 Cloudflare 身份验证流程。
要安装它，请将技能复制到您的 Kiro 技能目录中：
```bash
cp -r skills/jenkins-access ~/.kiro/skills/
```
安装后，Kiro 将在需要 Jenkins 访问或发生身份验证错误时激活该技能。
## 实例映射（转向文件）
如果您配置了多个 Jenkins 实例，您可以创建一个转向文件，以帮助 AI 代理确定为给定仓库查询哪个实例，而无需反复试验。
将示例复制到您的全局转向目录：
```bash
cp steering/jenkins-instances.example.md ~/.kiro/steering/jenkins-instances.md
```
编辑它以将您的仓库映射到其各自的实例。当提供转向文件作为上下文（通过 `#jenkins-instances.md`）时，代理将使用它来选择正确的实例。当仓库未映射时，代理将并行尝试所有已配置的实例。
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `get_build` | 获取特定构建的信息 |
| `get_build_log` | 获取构建的控制台输出 |
| `get_job` | 获取作业信息和最近的构建列表 |
| `list_builds` | 列出最近的构建结果 |
| `get_test_results` | 获取构建的测试报告 |
| `get_artifact` | 内联读取文本工件 |
| `download_test_results` | 将 Playwright 工件下载到本地临时目录 |
| `list_stages` | 列出具有状态和持续时间的流水线阶段 |
| `get_stage_log` | 获取特定流水线阶段的控制台日志 |
| `get_failed_tests` | 获取仅失败的测试用例和错误消息 |
| `compare_builds` | 比较两个构建之间的测试结果 |
## 作业路径格式
Jenkins 作业路径遵循以下模式：`<GitHub-Org>/<repo-name>/<branch>`
例如：`MyOrg/my-repo/main`
### 包含斜线的分支
如果分支名称包含斜线（例如 `feat/my-feature`），请在作业路径中将斜线编码为 `%2F`：
```
MyOrg/my-repo/feat%2Fmy-feature
```
服务器将正确地将此编码为 Jenkins URL 格式。您可以通过调用 `get_job` 仓库路径（不带分支）来找到确切的分支名称 - 响应列出了所有具有其编码名称的分支。
### PoP 作业路径模式
PoP 实例可能使用与主实例不同的 GitHub 组织前缀。使用 `get_job` 组织文件夹来发现可用的仓库，然后使用 `get_job` 仓库来发现分支。
