使用说明

Jenkins 的 MCP 服务器插件

Jenkins的MCP（模型上下文协议）服务器插件实现了模型上下文协议的服务器端组件。此插件使Jenkins能够充当MCP服务器，为MCP客户端（如基于大型语言模型（LLM）的应用程序或集成开发环境（IDE））提供上下文、工具和功能。

特点/特性

MCP服务器实现实现了模型上下文协议的服务器端。
Jenkins 集成将Jenkins功能作为MCP工具和资源进行展示。
可扩展架构允许通过（某种方式）轻松扩展MCP（可能是指某种系统或模块，如“主控制处理器”或具体产品名称）的功能 McpServerExtension 接口。

关键组件

**终端（或终点）**MCP通信的主要入口点，负责处理MCP传输连接和消息路由。
默认MCP服务器实施（或实现） McpServerExtension提供用于与 Jenkins 作业和构建进行交互的默认工具。
**McpToolWrapper（可译为“MCP工具包装器”或根据具体上下文调整为更贴切的表述）**将Java方法封装为MCP工具，处理参数解析和结果格式化。
McpServerExtension（可译为）：MCP服务器扩展用于扩展MCP服务器功能的接口。

MCP SDK 版本

此MCP服务器基于MCP Java SDK版本0.13.1构建，实现了MCP规范版本2025-06-18。

入门指南

先决条件

Jenkins（版本2.479或更高）

配置

MCP Server 插件在安装时会自动设置必要的端点和工具，无需额外配置。

系统属性

以下系统属性可用于配置MCP服务器插件：

对返回的日志行数的最大值设置硬限制 io.jenkins.plugins.mcp.server.extensions.BuildLogsExtension.limit.max=10000 （默认 10000）

Origin头部验证

MCP规范标记为 MUST 验证 Origin 传入请求的头部信息。默认情况下，MCP Server 插件不会强制执行此验证，以便于那些不提供头部信息的 AI Agent 使用。您可以启用不同级别的验证，如果请求中包含头部信息，您可以使用（相应方法）来强制验证该头部信息系统属性 io.jenkins.plugins.mcp.server.Endpoint.requireOriginMatch=true 在执行验证时，头部值必须与配置的Jenkins根URL相匹配。

如果接收头部是必须的，那么系统属性 io.jenkins.plugins.mcp.server.Endpoint.requireOriginHeader=true 也将将其规定为强制性的。

使用方法

连接到MCP服务器

MCP客户端可以使用以下方式连接到服务器：

可流式传输的HTTP终端点： <jenkins-url>/mcp-server/mcp
SSE 端点： <jenkins-url>/mcp-server/sse
消息端点： <jenkins-url>/mcp-server/message

认证和凭据

MCP服务器插件需要与其运行所在的Jenkins实例相同的凭据。为了验证您的MCP查询：

Jenkins API令牌从您的 Jenkins 用户帐户生成 API 令牌。
基本认证在HTTP基本身份验证头中使用API令牌。

生成一个个人访问令牌

生成个人访问令牌：

登录到 Jenkins。
在右上角选择您的用户图标，然后选择 Security。
选择 Add new token。
输入一个名称以区分该令牌，然后选择 Generate.
复制该令牌并将其存放在安全的地方以备后续使用。

[!警告] 一旦您离开该页面，将无法再次查看或复制该令牌。

选择 Done 添加令牌。
选择 Save 保存您的更改。

为HTTP基本认证编码凭据

使用个人访问令牌对MCP代理进行基本HTTP身份验证编码。

在 Linux、macOS 或 Windows 上编码凭证：

打开一个终端并运行以下命令，替换 <username> 和 <token> 使用您在Jenkins中生成的实际用户名和个人访问令牌

Linux 或 macOS

echo -n "<username>:<token>" | base64

Windows（PowerShell）

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("<username>:<token>"))

如果成功，将输出Base64编码的凭据，格式如下所示：

dXNlcm5hbWU6dG9rZW4=

将编码后的凭证存储在安全位置，以便后续使用。

[!NOTE] （注：此标记通常用于指示后续内容为重要提示或注意事项） Base64编码并不是加密。任何能够访问该编码字符串的人都可以对其进行解码，并获取您的凭据。始终像对待原始用户名和令牌一样保护好编码后的凭据。

示例客户端配置

克利恩配置（或“渐变配置”，具体翻译取决于上下文，Cline可能指某种渐变或变化的概念）

{
  "mcpServers": {
    "jenkins": {
      "autoApprove": [
        
      ],
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://jenkins-host/mcp-server/mcp",
      "headers": {
        "Authorization": "Basic <user:token base64>"
      }
    }
  }
}

副驾驶配置

目前，Copilot 与 Streamable 传输方式配合不佳，我仍在调查相关问题。请继续使用 SSE 端点。

{
  "mcp": {
    "servers": {
      "jenkins": {
        "type": "sse",
        "url": "https://jenkins-host/mcp-server/sse",
        "headers": {
          "Authorization": "Basic <user:token base64>"
        }
      }
    }
  }
}

可流式传输的示例：

{
  "servers": {
    "jenkins": {
      "type": "http",
      "url": "http://jenkins-host/mcp-server/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Basic <user:token base64>"
        }
      }
    }
  }
}

风帆冲浪配置

{
  "servers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://jenkins-host/mcp-server/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Basic <user:token base64>"
      }
    }
  }
}

克劳德

claude mcp add http://jenkins-host/mcp-server/mcp --transport http --header "Authorization: Basic <user:token base64>"

鹅

点击 “添加自定义扩展”
给它起个有意义的名字
在“下拉选择”类型中，选择 “Streamable HTTP”翻译为中文是“可流式传输的HTTP”
输入终端点URL。它应该是类似这样的形式： http://jenkins-host/mcp-server/mcp
滚动到 “请求头”
在空白字段中，输入 Authorization （根据）名称。然后在值字段中，输入 “Basic <user:token base64>”
点击 “Add”翻译成中文是“添加”
点击 “Add Extension” 翻译成中文是：“添加扩展”

可用工具

该插件提供了以下内置工具来与 Jenkins 进行交互：

作业管理

getJob通过完整路径获取Jenkins作业。
getJobs获取按名称排序的Jenkins作业分页列表。
triggerBuild触发作业的构建。这个工具支持参数化构建。您可以提供一个JSON对象作为参数，其中每个键都是参数名。例如：
```
{
  "jobFullName": "my-job",
  "parameters": {
    "BRANCH": "main",
    "DEBUG_MODE": "true"
  }
}
```
参数说明：
- 核心Jenkins参数完全支持（字符串、布尔值、选择、文本、密码、运行）
- 插件参数自动检测并通过反射进行处理
- 文件参数不通过MCP支持（需要文件上传）
- 多选参数支持作为数组或列表使用
- 自定义插件参数自动尝试使用基于反射的检测方法
- 回退行为不支持的参数将回退到默认值，并记录日志

构建信息

getBuild检索Jenkins作业的特定构建或最后一个构建。
updateBuild更新构建显示名称和/或描述。
getBuildLog为特定构建或最后一个构建分页检索日志行。
searchBuildLog在构建日志中搜索符合特定模式（字符串或正则表达式）的日志行。

供应链管理（SCM）集成

getJobScm获取Jenkins作业的SCM配置。
getBuildScm获取特定构建的SCM（源代码管理）配置。
getBuildChangeSets获取特定构建的更改日志集。

管理信息

whoAmI获取当前用户的信息。
getStatus检查Jenkins实例的健康状况和准备就绪状态。使用此工具来评估Jenkins实例的健康状况，而不仅仅是判断其是启动还是停止状态。

每个工具都接受特定的参数以自定义其行为。有关详细使用说明和参数描述，请参阅API文档或使用MCP内省功能。

要使用这些工具，请连接到MCP服务器端点，并使用您的MCP客户端实现进行工具调用。

增强的参数支持

MCP服务器插件现在为Jenkins参数提供了全面支持：

支持的参数类型

字符串参数带有默认值的文本输入
布尔参数具有自动类型转换的真/假值
可选参数带有验证的下拉选择
文本参数多行文本输入
密码参数使用秘密处理确保输入安全
运行参数构建编号引用
插件参数自动检测并处理

参数处理特性

类型转换JSON类型与Jenkins参数类型之间的自动转换
验证选择参数用于验证输入是否符合可用选项
备用方案；回退方案不支持的参数将优雅地回退到默认值
反思插件参数类型自动检测并处理
记录日志全面记录日志以调试参数问题

示例用法

{
  "jobFullName": "my-parameterized-job",
  "parameters": {
    "BRANCH": "main",
    "DEBUG_MODE": true,
    "ENVIRONMENT": "production",
    "FEATURES": ["feature1", "feature2"],
    "NOTES": "Build triggered via MCP"
  }
}

扩展MCP功能

添加新的MCP工具或功能：

创建一个实现（某功能/接口）的类 McpServerExtension。
使用 @Tool 将方法作为MCP工具进行暴露。
使用 @ToolParam 定义和描述工具参数。

示例：

@Extension
public class MyCustomMcpExtension implements McpServerExtension {
	@Tool(description = "My custom tool")
	public String myCustomTool(@ToolParam(description = "Input parameter") String input) {
		// Tool implementation
	}
}

结果处理

MCP服务器插件采用以下方法处理各种结果类型：

列出结果列表中的每个元素都被转换为响应中的一个独立文本内容项。
单个对象整个对象被转换成一个单一的文本内容项。

对于序列化为文本内容：

@ExportedBean 注解如果结果对象被注解为 @ExportedBean （来自 org.kohsuke.stapler.export)，Jenkins'（詹金斯的） org.kohsuke.stapler.export.Flavor.JSON 使用了导出机制。
其他物体对于没有（某特性/属性）的物体 @ExportedBean 注解：Jackson 用于 JSON 序列化。

这种方法确保了对不同结果类型的灵活高效处理，既支持Jenkins特定的导出对象，也兼容标准的Java对象。这种灵活的方法确保了工具结果在MCP响应中能够一致且准确地呈现，无论其复杂程度如何。

与GitHub Copilot的集成

MCP服务器插件与GitHub Copilot无缝集成，通过在您的集成开发环境（IDE）中直接访问Jenkins信息，提升了您的开发体验。这种集成使您能够使用自然语言查询与Jenkins作业和构建进行交互。

如截图所示：

你可以使用自然语言向Copilot询问有关Jenkins作业的信息，例如，“列出根目录下的Jenkins作业”。
Copilot 使用 MCP 服务器来获取并显示 Jenkins 作业的信息，将根目录下的作业列出。
你也可以请求特定信息，比如“获取作业a的最后构建状态”，然后Copilot会提供包括构建编号、状态和URL在内的相关详细信息。

这种集成简化了您的工作流程，使您无需离开开发环境即可访问Jenkins信息。

贡献；做出贡献

欢迎为MCP服务器插件做出贡献。请参考 Jenkins 贡献指南如需更多信息。

许可证

这个项目采用MIT许可证授权——详见许可证文件中有详细信息。